MkDocs入門

入門チュートリアル！

---

インストール

MkDocsをインストールするには、コマンドラインから次のコマンドを実行します。

pip install mkdocs

詳細は、インストールガイドを参照してください。

新規プロジェクトの作成

すぐに始められます。 新しいプロジェクトを作成するには、コマンドラインから次のコマンドを実行します。

mkdocs new my-project
cd my-project

作成された初期プロジェクトを確認してください。

mkdocs.ymlという設定ファイルと、ドキュメントのソースファイルを含むdocsというフォルダがあります（docsはdocs_dir設定のデフォルト値です）。 現在、docsフォルダには、index.mdというドキュメントページが1つだけ含まれています。

MkDocsには、作業中にドキュメントをプレビューできる組み込みの開発サーバーが付属しています。 mkdocs.yml設定ファイルと同じディレクトリにいることを確認し、mkdocs serveコマンドを実行してサーバーを起動します。

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.22 seconds
INFO    -  [15:50:43] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [15:50:43] Serving on http://127.0.0.1:8000/

ブラウザでhttp://127.0.0.1:8000/を開くと、デフォルトのホームページが表示されます。

開発サーバーは自動リロードもサポートしており、設定ファイル、ドキュメントディレクトリ、またはテーマディレクトリの内容が変更されるたびにドキュメントを再構築します。

好みのテキストエディタでdocs/index.mdドキュメントを開き、最初の見出しをMkLorumに変更して変更を保存します。 ブラウザが自動的にリロードされ、更新されたドキュメントがすぐに表示されます。

次に、設定ファイル：mkdocs.ymlを編集してみましょう。 site_name設定をMkLorumに変更してファイルを保存します。

site_name: MkLorum

ブラウザがすぐにリロードされ、新しいサイト名が反映されます。

ページの追加

次に、ドキュメントに2番目のページを追加します。

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

ドキュメントサイトにはナビゲーションヘッダーが含まれるため、nav設定を追加して、設定ファイルを編集し、ナビゲーションヘッダーの各ページの順序、タイトル、およびネストに関する情報を追加することができます。

site_name: MkLorum
nav:
  - Home: index.md
  - About: about.md

変更を保存すると、左側にホームとAboutの項目、右側に検索、前へ、次への項目を含むナビゲーションバーが表示されます。

メニュー項目を試して、ページ間を前後に移動します。 次に、[検索]をクリックします。 検索ダイアログが表示され、任意のページの任意のテキストを検索できます。 検索結果には、サイト上の検索語のすべての出現箇所が含まれており、検索語が表示されているページのセクションに直接リンクされていることに注意してください。 すべての手間をかけずに、すべてが手に入ります！

ドキュメントのテーマ設定

次に、テーマを変更して、ドキュメントの表示方法を変更する設定ファイルを変更します。 mkdocs.ymlファイルを編集し、theme設定を追加します。

site_name: MkLorum
nav:
  - Home: index.md
  - About: about.md
theme: readthedocs

変更を保存すると、ReadTheDocsテーマが使用されていることがわかります。

ファビコンアイコンの変更

デフォルトでは、MkDocsはMkDocsファビコンアイコンを使用します。 別のアイコンを使用するには、`docs`ディレクトリに`img`サブディレクトリを作成し、カスタム`favicon.ico`ファイルをそのディレクトリにコピーします。 MkDocsは、そのファイルをファビコンアイコンとして自動的に検出して使用します。

サイトのビルド

良さそうです。 `MkLorum`ドキュメントの最初のパスをデプロイする準備ができました。最初にドキュメントをビルドします

mkdocs build

これにより、`site`という名前の新しいディレクトリが作成されます。ディレクトリ内を見てください

$ ls site
about  fonts  index.html  license  search.html
css    img    js          mkdocs   sitemap.xml

ソースドキュメントは、`index.html`と`about / index.html`という名前の2つのHTMLファイルとして出力されていることに注意してください。また、ドキュメントテーマの一部として`site`ディレクトリにコピーされた他のさまざまなメディアもあります。 `sitemap.xml`ファイルと`mkdocs / search_index.json`もあります。

`git`などのソースコード管理を使用している場合、ドキュメントのビルドをリポジトリにチェックインしたくない場合があります。 `.gitignore`ファイルに`site /`を含む行を追加します。

echo "site/" >> .gitignore

別のソースコード管理ツールを使用している場合は、特定のディレクトリを無視する方法について、そのドキュメントを確認してください。

その他のコマンドとオプション

他にもさまざまなコマンドとオプションがあります。コマンドの完全なリストを表示するには、`--help`フラグを使用します

mkdocs --help

特定のコマンドで使用可能なオプションのリストを表示するには、そのコマンドで`--help`フラグを使用します。たとえば、`build`コマンドで使用可能なすべてのオプションのリストを取得するには、次を実行します

mkdocs build --help

デプロイ

作成したドキュメントサイトは静的ファイルのみを使用するため、ほぼどこからでもホストできます。 `site`ディレクトリの内容全体をWebサイトをホストしている場所にアップロードするだけです。一般的なホストの数に関する具体的な手順については、ドキュメントのデプロイページを参照してください。

ヘルプの表示

MkDocsのすべての機能のより完全なドキュメントについては、ユーザーガイドを参照してください。

MkDocsに関するヘルプが必要な場合は、GitHubディスカッションまたはGitHubの問題を使用してください。