コンテンツにスキップ

MkDocsのインストール

インストール

コマンドプロンプトから py -m pip install mkdocs を実行します。 環境変数PATHにPythonを登録せず、Pythonランチャー(py.exe)を利用している場合、コマンドプロンプトからの実行は py -m を付けます。

py -m pip install mkdocs
(処理省略)

バージョンを確認します。

C:\Users\NAME>py -m mkdocs -V
python -m mkdocs, version 1.3.1 from C:\Python\Python310\lib\site-packages\mkdocs (Python 3.10)

バージョンが表示されればインストール完了です。

プロジェクトの新規作成

Pythonフォルダ直下に例として MkDocsSample プロジェクトを新規作成します。 プロジェクトフォルダが作成されて、中に mkdocs.yml ファイルと docs フォルダが作成されます。 docs フォルダには index.md ファイルが作成されます。

C:\Users\NAME>cd C:\python
C:\python>py -m mkdocs new MkDocsSample
INFO    -  Creating project directory: MkDocsSample
INFO    -  Writing config file: MkDocsSample\mkdocs.yml
INFO    -  Writing initial docs: MkDocsSample\docs\index.md

index.mdはMarkdown形式のテキストファイルです。

プロジェクトのビルド

プロジェクトをビルドするにはプロジェクトフォルダに cd で移動し、 mkdocs build コマンドでビルドします。 ビルドが成功すれば新規作成された site フォルダにファイル一式が出力されます。

C:\Python>cd MkDocsSample
C:\Python\MkDocsSample>py -m mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\Python\MkDocsSample\site
INFO    -  Documentation built in 0.22 seconds

MkDocs index.html ブラウザ表示

mdファイルの修正や作成とbuildを繰り返して作業します。

ローカルサーバーの起動

HTMLファイルのサイト内リンクはディレクトリパスを参照するため、リンク移動すると下記のようなディレクトリ画面が表示されてしまうため、サイト内の移動がやや面倒です。

MkDocs ディレクトリ表示

mkdocs serve コマンドを使うとローカルでHTTPサーバサービスが起動します。 アドレスが表示される(下記では http://127.0.0.1:8000 )のでWebブラウザで表示します。
HTTPサーバサービスでは本来の挙動(サイト内リンクでindex.htmlが表示など)になります。
また、サービス起動中はファイルの変更が自動的に反映されるため毎回ビルドしなくて済みます。

C:\Python\MkDocsSample>mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 190901 12:34:56 server:296] Serving on http://127.0.0.1:8000
[I 190901 12:34:56 handlers:62] Start watching changes
[I 190901 12:34:56 handlers:64] Start detecting changes

終了させる場合はコマンドプロンプトを閉じるか、 Ctrl+C を押します。

[I 190901 12:35:00 server:318] Shutting down...

文字コードについて

MkDocsのファイルはUTF-8で作成します。
Windows標準のメモ帳でテキストが空、もしくは半角英数字で書かれたファイルに全角文字を追加して保存した場合、Shift_JISで保存されてしまうことがあります。 この状態でビルドするとUnicodeDecodeErrorとなってしまいます。 その場合は保存時に文字コードをUTF-8に変更して上書き保存してください。

C:\Python\MkDocsSample>mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\Python\MkDocsSample\site
ERROR   -  Encoding error reading file: index.md
ERROR   -  Error reading page 'index.md': 'utf-8' codec can't decode byte 0x82 in position 8: invalid start byte
(省略)
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x82 in position 8: invalid start byte