MkDocs をインストールする

静的サイトジェネレーターである MkDocs に関して、日本語の情報源としては Mebiusbox さんがお書きになっている MkDocsによるドキュメント作成が最強なのでは無いかと思います。余談ですが「動かして学ぶ！Rust入門」の執筆によると Mebiusbox さんはさんは動かして学ぶ！Rust入門の著者でもあるそうです (すごい)。

以前に HBFM (Markdown 拡張) を追加した MkDocs の Docker イメージというメモを書きました。このはハートビーツさんが作成されたプラグインを取り込んだ MkDocs の Docker イメージを利用する前提になっています。今回は Docker コンテナは利用せず、ローカルに MkDocs をインストールする手順をメモしておきます。

仮想環境の作成¶

MkDocs をグローバルにインストールするのであれば不要ですが、Python 仮想環境内へインストールするのであれば venv で仮想環境を作成します。 rye 使いたい…

mkdir sample
cd sample/
python3 -m venv .venv
echo 'source .venv/bin/activate' > .envrc
direnv allow
python3 -m pip install --upgrade pip

MkDocs のインストール¶

MkDocs をインストールします。テーマには material を利用するので、mkdocs-material をインストールしておきます。

python3 -m pip install mkdocs mkdocs-material

プロジェクトの作成¶

MkDocs を利用するには初めに mkdocs new [PROJECT] を実行し、プロジェクトディレクトリ/スケルトンを作成します。

$ mkdocs new my-first-pj
INFO    -  Creating project directory: my-first-pj
INFO    -  Writing config file: my-first-pj/mkdocs.yml
INFO    -  Writing initial docs: my-first-pj/docs/index.md

この時点でディレクトリ構造は以下になっていました。更新元となるドキュメントは docs 配下に格納します。

$ tree my-first-pj/
my-first-pj/
├── docs
│   └── index.md
└── mkdocs.yml

今後の作業はこの「プロジェクトディレクトリ」で行うことになります。 mkdocs new . することで現在のディレクトリをプロジェクトディレクトリにすることも出来ます。

ドキュメントのビルド¶

コンテンツの更新を行った場合はドキュメントをビルドし直す必要があります。

cd my-first-pj/
mkdocs build

初回ビルド直後のプロジェクトディレクトリ構造は以下になっていました。前述の通り、更新元となるドキュメントは docs 配下に格納しますが、「docs のドキュメントから生成された公開用コンテンツ」は site ディレクトリ配下に格納されます。外部にドキュメントを更新したい場合は (docs 配下のファイルは不要で) site 配下のファイルを Web サーバから参照出来るディレクトリへアップロードすることになります。

$ tree my-first-pj/
my-first-pj/
├── docs
│   └── index.md
├── mkdocs.yml
└── site
    ├── 404.html
    ├── css
    │   ├── base.css
    │   ├── bootstrap.min.css
    │   └── font-awesome.min.css
    ├── fonts
    │   ├── fontawesome-webfont.eot
    │   ├── fontawesome-webfont.svg
    │   ├── fontawesome-webfont.ttf
    │   ├── fontawesome-webfont.woff
    │   └── fontawesome-webfont.woff2
    ├── img
    │   ├── favicon.ico
    │   └── grid.png
    ├── index.html
    ├── js
    │   ├── base.js
    │   ├── bootstrap.min.js
    │   └── jquery-3.6.0.min.js
    ├── search
    │   ├── lunr.js
    │   ├── main.js
    │   ├── search_index.json
    │   └── worker.js
    ├── sitemap.xml
    └── sitemap.xml.gz

MkDocs 内蔵サーバを使ったドキュメントチェック¶

MkDocs は Web サーバを内蔵しています。 mkdocs serve で起動することが出来ます。この内臓サーバを起動している間はファイルの追加・変更などが発生する度に自動的にドキュメントが再ビルドされます。

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

ブラウザで http://127.0.0.1:8000 へアクセスすると以下のように表示されます。

01a

テーマの変更¶

テーマや言語など、全体に関わる設定は mkdocs.yml ファイルで行います。デフォルトでは以下になっていました。

$ cat mkdocs.yml
site_name: My Docs

material テーマを利用する為、以下のように書き換えます。

site_name: My Docs
theme:
  name: material

mkdocs.yml を更新した場合はサーバを再起動する必要があるので、mkdocs serve を停止・再実行します。ブラウザで http://127.0.0.1:8000 へアクセスし直すと以下のように表示されます。テーマが変更されたことが分かります。

02a