MkDocsのインストール

pipのアップデート

MkDocsのインストールはPythonのパッケージ管理システムである pip を使用します。 インストールの前にpipのアップデートを実施します。

pip更新前にバージョンを確認します。

1
2
C:\Users\NAME>pip -V
pip 19.0.3 from c:\python\python37\lib\site-packages\pip (python 3.7)

pip install -U pip --user コマンドでpipを更新します。

1
2
3
4
5
6
7
8
C:\Users\NAME>pip install -U pip --user
Collecting pip
  Downloading https://files.pythonhosted.org/packages/30/db/9e38760b32e3e7f40cce46dd5fb107b8c73840df38f0046d8e6514e675a1/pip-19.2.3-py2.py3-none-any.whl (1.4MB)
    100% |████████████████████████████████| 1.4MB 4.0MB/s
Installing collected packages: pip
Successfully installed pip-19.2.3
You are using pip version 19.0.3, however version 19.2.3 is available.
You should consider upgrading via the 'python -m pip install --upgrade pip' command.

Tip

--user を付けなかった場合はアクセスエラーが表示されますが更新されています。

1
2
3
4
5
6
7
8
9
C:\Users\NAME>pip install -U pip
Collecting pip
  Using cached https://files.pythonhosted.org/packages/30/db/9e38760b32e3e7f40cce46dd5fb107b8c73840df38f0046d8e6514e675a1/pip-19.2.3-py2.py3-none-any.whl
Installing collected packages: pip
  Found existing installation: pip 19.0.3
    Uninstalling pip-19.0.3:
      Successfully uninstalled pip-19.0.3
Could not install packages due to an EnvironmentError: [WinError 5] アクセスが拒否されました。: 'C:\\Users\\NAME\\AppData\\Local\\Temp\\pip-uninstall-t8mc6klx\\pip.exe'
Consider using the `--user` option or check the permissions.

pip更新後にバージョンを確認します。

1
2
C:\Users\NAME>pip -V
pip 19.2.3 from c:\python\python37\lib\site-packages\pip (python 3.7)

バージョンが更新されていれば成功です。

MkDocsのインストール

コマンドプロンプトから pip install mkdocs を実行します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
C:\Users\NAME>pip install mkdocs
Collecting mkdocs
  Downloading https://files.pythonhosted.org/packages/db/f9/b0179afee0db21943120ea606eb68bda1257b96420df74b775280eb5850b/mkdocs-1.0.4-py2.py3-none-any.whl (1.2MB)
     |████████████████████████████████|1.2MB 6.8MB/s
Collecting Markdown>=2.3.1 (from mkdocs)
  Downloading https://files.pythonhosted.org/packages/c0/4e/fd492e91abdc2d2fcb70ef453064d980688762079397f779758e055f6575/Markdown-3.1.1-py2.py3-none-any.whl (87kB)
     |████████████████████████████████| 92kB 6.1MB/s
Collecting click>=3.3 (from mkdocs)
  Downloading https://files.pythonhosted.org/packages/fa/37/45185cb5abbc30d7257104c434fe0b07e5a195a6847506c074527aa599ec/Click-7.0-py2.py3-none-any.whl (81kB)
     |████████████████████████████████| 81kB 5.1MB/s
Collecting PyYAML>=3.10 (from mkdocs)
  Downloading https://files.pythonhosted.org/packages/bc/3f/4f733cd0b1b675f34beb290d465a65e0f06b492c00b111d1b75125062de1/PyYAML-5.1.2-cp37-cp37m-win_amd64.whl (215kB)
     |████████████████████████████████| 225kB 6.4MB/s
Collecting tornado>=5.0 (from mkdocs)
  Downloading https://files.pythonhosted.org/packages/4e/f8/86ab848da5c79715f901e22bc23d2dc467b8672fe1eda8d3e1f48cba130c/tornado-6.0.3-cp37-cp37m-win_amd64.whl (415kB)
     |████████████████████████████████| 419kB 6.4MB/s
Collecting Jinja2>=2.7.1 (from mkdocs)
  Downloading https://files.pythonhosted.org/packages/1d/e7/fd8b501e7a6dfe492a433deb7b9d833d39ca74916fa8bc63dd1a4947a671/Jinja2-2.10.1-py2.py3-none-any.whl (124kB)
     |████████████████████████████████| 133kB 6.4MB/s
Collecting livereload>=2.5.1 (from mkdocs)
  Downloading https://files.pythonhosted.org/packages/12/4d/30cfe74402d2e962d66d35da29bf8850b0557b559ce84d09967c8ade859e/livereload-2.6.1-py2.py3-none-any.whl
Requirement already satisfied: setuptools>=36 in c:\python\python37\lib\site-packages (from Markdown>=2.3.1->mkdocs) (40.8.0)
Collecting MarkupSafe>=0.23 (from Jinja2>=2.7.1->mkdocs)
  Downloading https://files.pythonhosted.org/packages/65/c6/2399700d236d1dd681af8aebff1725558cddfd6e43d7a5184a675f4711f5/MarkupSafe-1.1.1-cp37-cp37m-win_amd64.whl
Collecting six (from livereload>=2.5.1->mkdocs)
  Downloading https://files.pythonhosted.org/packages/73/fb/00a976f728d0d1fecfe898238ce23f502a721c0ac0ecfedb80e0d88c64e9/six-1.12.0-py2.py3-none-any.whl
Installing collected packages: Markdown, click, PyYAML, tornado, MarkupSafe, Jinja2, six, livereload, mkdocs
Successfully installed Jinja2-2.10.1 Markdown-3.1.1 MarkupSafe-1.1.1 PyYAML-5.1.2 click-7.0 livereload-2.6.1 mkdocs-1.0.4 six-1.12.0 tornado-6.0.3

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

1
2
C:\Users\NAME>mkdocs -V
mkdocs, version 1.0.4 from c:\python\python37\lib\site-packages\mkdocs (Python 3.7)

インストール完了です。

プロジェクトの新規作成

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

1
2
3
4
5
C:\Users\NAME>cd C:\python
C:\python>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形式のテキストファイルです。

MkDocs index.md

プロジェクトのビルド

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

1
2
3
C:\Python\MkDocsSample>mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\Python\MkDocsSample\site

MkDocs index.html ブラウザ表示

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

ローカルサーバーの起動

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

MkDocs ディレクトリ表示

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

1
2
3
4
5
6
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 を押します。

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

文字コードについて

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

1
2
3
4
5
6
7
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