環境
- Windows10 Pro バージョン1909
- Python 3.8.5
  - Pythonのインストール記録はこちら
- pip 20.2.3

mkdocsをインストールする

# インストールする
> 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が設定ファイルになる

# 「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

ビルドしてブラウザで表示してみる

# プロジェクトのディレクトリに移動して
> 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」はいらない。

> 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/]をブラウザで表示するとこんな感じ

materialテーマをインストールする

参考 : カンタンにドキュメントが作れるmkdocsをはじめてみよう - Qiita

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

> 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にテーマを設定する

プロジェクト作成時に作成されたmkdocs.ymlを開く
「theme: 'material'」を追記する
他の部分はカンタンにドキュメントが作れるmkdocsをはじめてみよう - Qiita を参考に・・・というかコピペ

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

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

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

また、サーバを起動してブラウザで表示してみる

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

困った

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

はじめてのMkDocsの使い方