はじめてのMkDocsの使い方

- 環境
    - Windows10 Pro バージョン1909
    - Python 3.8.5
        - [Pythonのインストール記録はこちら](https://ponsuke-tarou.hatenablog.com/entry/2020/09/24/180503)
    - pip 20.2.3


# mkdocsをインストールする
参考 : [MkDocsによるドキュメント作成 - Zenn](https://zenn.dev/mebiusbox/articles/81d977a72cee01)

```bash
# インストールする
> pip install mkdocs
Collecting mkdocs
  Downloading mkdocs-1.1.2-py3-none-any.whl (6.4 MB)
     |████████████████████████████████| 6.4 MB 726 kB/s
# ...省略...
Successfully installed Jinja2-2.11.2 Markdown-3.2.2 MarkupSafe-1.1.1 PyYAML-5.3.1 click-7.1.2 joblib-0.17.0 livereload-2.6.3 lunr-0.5.8 mkdocs-1.1.2 nltk-3.5 regex-2020.9.27 tornado-6.0.4 tqdm-4.50.0

# バージョンを確認する
> mkdocs -V
mkdocs, version 1.1.2 from c:\path\to\venv\lib\site-packages\mkdocs (Python 3.8)
```

# プロジェクトを作成する
プロジェクトを作成すると作成される`mkdocs.yml`が設定ファイルになる

```bash
# 「docs」というプロジェクト名でプロジェクトを作成すると
> mkdocs new docs
INFO    -  Creating project directory: docs
INFO    -  Writing config file: docs\mkdocs.yml
INFO    -  Writing initial docs: docs\docs\index.md

# プロジェクト名のディレクトリが作成されて
> ls -la | grep docs
drwxr-xr-x 1 ponsuke 1049089        0 10月  5 12:55 docs/

# index.mdとmkdocs.ymlが作成される
> find docs/ -type f
docs/docs/index.md
docs/mkdocs.yml
```



## ビルドしてブラウザで表示してみる
```bash
# プロジェクトのディレクトリに移動して
> cd docs

# ビルドして
> mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\path\to\docs\site
INFO    -  Documentation built in 0.11 seconds

# サーバを起動して
> mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.12 seconds
[I 201005 13:00:32 server:335] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000
[I 201005 13:00:32 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 201005 13:00:32 handlers:64] Start detecting changes
INFO    -  Start detecting changes
[I 201005 13:00:41 handlers:135] Browser Connected: http://127.0.0.1:8000/
INFO    -  Browser Connected: http://127.0.0.1:8000/
# サーバを停止したいときはCrtl + C
```

注意 : サーバの起動は`mkdocs server`ではなく`mkdocs serve`。「r」はいらない。

```bash
> mkdocs server
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...
Try 'mkdocs -h' for help.

Error: No such command 'server'.
```


`mkdocs serve`で出力される[http://127.0.0.1:8000/]をブラウザで表示するとこんな感じ

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/159761/dd9d8da5-2655-6228-bd13-c38fc9090f06.png)


## materialテーマをインストールする
- 参考 : [カンタンにドキュメントが作れるmkdocsをはじめてみよう - Qiita](https://qiita.com/wamisnet/items/ed725d74f945f7c06b91)

外観を設定してくれるテーマをインストールする。
今回は、ほかのサイトで紹介されている`material`を使ってみる。
インストール中に`Requirement already satisfied: ...`が表示されるのは「もうインストールされてるよ」的なものなので気にしない。

```bash
> pip install mkdocs-material
Collecting mkdocs-material
  Downloading mkdocs_material-6.0.2-py2.py3-none-any.whl (3.9 MB)
     |████████████████████████████████| 3.9 MB 86 kB/s
# ...省略...
Requirement already satisfied: regex in c:\path\to\venv\lib\site-packages (from nltk>=3.2.5; python_version > "2.7" and extra == "languages"->lunr[languages]==0.5.8->mkdocs>=1.1->mkdocs-material) (2020.9.27)
Installing collected packages: Pygments, pymdown-extensions, mkdocs-material-extensions, mkdocs-material
Successfully installed Pygments-2.7.1 mkdocs-material-6.0.2 mkdocs-material-extensions-1.0.1 pymdown-extensions-8.0.1

> pip list
Package                    Version
-------------------------- ---------
...
mkdocs                     1.1.2
mkdocs-material            6.0.2
mkdocs-material-extensions 1.0.1
...
Pygments                   2.7.1
```

### mkdocs.ymlにテーマを設定する
1. プロジェクト作成時に作成されたmkdocs.ymlを開く
1. 「theme: 'material'」を追記する
1. 他の部分は [カンタンにドキュメントが作れるmkdocsをはじめてみよう - Qiita](https://qiita.com/wamisnet/items/ed725d74f945f7c06b91#%E3%81%9B%E3%81%A3%E3%81%8B%E3%81%8F%E3%81%AA%E3%81%AE%E3%81%A7mkdocs%E3%82%92material-design%E3%81%AB%E3%81%97%E3%81%A6%E3%81%BF%E3%82%88%E3%81%86) を参考に・・・というかコピペ

```yml
# Project information
site_name: 'サイトの名前'

# Documentation and theme
docs_dir: 'docs'
theme: 'material'

# Extensions
markdown_extensions:
  - admonition
  - toc:
      permalink: '#'
```

### また、サーバを起動してブラウザで表示してみる
1. `mkdocs serve`でサーバを起動する
1. サーバを起動時に出力されるURLでブラウザで表示してみるとこんな感じに変わった

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/159761/6d26baef-f722-5585-a938-de912e5a18a0.png)

# 困った
- [Config value: 'pages'. Warning: The 'pages' configuration option has been deprecated and will be removed in a future release of MkDocs. Use 'nav' instead. - Qiita](https://qiita.com/ponsuke0531/items/6305341f03693952213a)