Material for MkDocs のインストール

MkDocsではサイトの外観を変更できます。
MkDocs Themes にサンプルがあります。
本サイトでは見栄えがよくマテリアルデザインにも対応する人気テーマのMaterial for MkDocs を紹介します。 本サイトもMaterialを使用しています。

mkdocs-materialのインストール

Mkdocsと同じように pip install mkdocs-material でインストールします。

 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
29
30
31
32
33
C:\Python\MkDocsSample>pip install mkdocs-material
Collecting mkdocs-material
  Downloading https://files.pythonhosted.org/packages/5b/22/cd9acf99048b82bfe9adab00284ed632a4885f5176a06c709cf8a8296360/mkdocs_material-4.4.2-py2.py3-none-any.whl (711kB)
     |████████████████████████████████| 716kB 6.8MB/s
Collecting pymdown-extensions>=4.11 (from mkdocs-material)
  Downloading https://files.pythonhosted.org/packages/87/dd/b099881058d0e1a5f80389ff4528e7e796e7ad3d5d430f36c086dde8c824/pymdown_extensions-6.1-py2.py3-none-any.whl (219kB)
     |████████████████████████████████| 225kB 6.4MB/s
Requirement already satisfied: mkdocs>=1 in c:\python\python37\lib\site-packages (from mkdocs-material) (1.0.4)
Collecting Pygments>=2.2 (from mkdocs-material)
  Downloading https://files.pythonhosted.org/packages/5c/73/1dfa428150e3ccb0fa3e68db406e5be48698f2a979ccbcec795f28f44048/Pygments-2.4.2-py2.py3-none-any.whl (883kB)
     |████████████████████████████████| 890kB 6.8MB/s
Collecting mkdocs-minify-plugin>=0.2 (from mkdocs-material)
  Downloading https://files.pythonhosted.org/packages/66/fe/47e0acd1df33a289a075af252f3d7d65fb8acec425f5fac12493669c6828/mkdocs-minify-plugin-0.2.1.tar.gz
Collecting pep562 (from pymdown-extensions>=4.11->mkdocs-material)
  Downloading https://files.pythonhosted.org/packages/f5/31/2c8475b148c8a0c8cae39300f4346068e21909d44e0659f104ce76c3a7ef/pep562-1.0-py2.py3-none-any.whl
Requirement already satisfied: Markdown>=3.0.1 in c:\python\python37\lib\site-packages (from pymdown-extensions>=4.11->mkdocs-material) (3.1.1)
Requirement already satisfied: PyYAML>=3.10 in c:\python\python37\lib\site-packages (from mkdocs>=1->mkdocs-material) (5.1.2)
Requirement already satisfied: Jinja2>=2.7.1 in c:\python\python37\lib\site-packages (from mkdocs>=1->mkdocs-material) (2.10.1)
Requirement already satisfied: livereload>=2.5.1 in c:\python\python37\lib\site-packages (from mkdocs>=1->mkdocs-material) (2.6.1)
Requirement already satisfied: tornado>=5.0 in c:\python\python37\lib\site-packages (from mkdocs>=1->mkdocs-material) (6.0.3)
Requirement already satisfied: click>=3.3 in c:\python\python37\lib\site-packages (from mkdocs>=1->mkdocs-material) (7.0)
Collecting htmlmin>=0.1.4 (from mkdocs-minify-plugin>=0.2->mkdocs-material)
  Downloading https://files.pythonhosted.org/packages/b3/e7/fcd59e12169de19f0131ff2812077f964c6b960e7c09804d30a7bf2ab461/htmlmin-0.1.12.tar.gz
Collecting jsmin>=2.2.2 (from mkdocs-minify-plugin>=0.2->mkdocs-material)
  Downloading https://files.pythonhosted.org/packages/17/73/615d1267a82ed26cd7c124108c3c61169d8e40c36d393883eaee3a561852/jsmin-2.2.2.tar.gz
Requirement already satisfied: setuptools>=36 in c:\python\python37\lib\site-packages (from Markdown>=3.0.1->pymdown-extensions>=4.11->mkdocs-material) (40.8.0)
Requirement already satisfied: MarkupSafe>=0.23 in c:\python\python37\lib\site-packages (from Jinja2>=2.7.1->mkdocs>=1->mkdocs-material) (1.1.1)
Requirement already satisfied: six in c:\python\python37\lib\site-packages (from livereload>=2.5.1->mkdocs>=1->mkdocs-material) (1.12.0)
Installing collected packages: pep562, pymdown-extensions, Pygments, htmlmin, jsmin, mkdocs-minify-plugin, mkdocs-material
  Running setup.py install for htmlmin ... done
  Running setup.py install for jsmin ... done
  Running setup.py install for mkdocs-minify-plugin ... done
Successfully installed Pygments-2.4.2 htmlmin-0.1.12 jsmin-2.2.2 mkdocs-material-4.4.2 mkdocs-minify-plugin-0.2.1 pep562-1.0 pymdown-extensions-6.1

mkdocs.ymlへの適用

mkdocs.ymlファイルに以下の内容を追記します。

1
2
theme:
    name: 'material'

ビルドすることでデザインが変化します。

MkDocs index.html MkDocs-Material index.html

Materialの拡張設定

Materialテーマは他にも設定変更ができます。 本サイトではmkdocs.ymlの設定例について利用頻度の高いものを日本語のコメントにて紹介します。
詳細は公式サイトのGetting started - Material for 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
theme:
    # 使用するテーマ名
    name: 'material'
    # 標準言語。日本語の場合は'ja'(jpではない)
    language: 'ja'
    # サイトヘッダー画像
    logo: 'images/logo.svg'
    # サイトアイコン画像
    favicon: 'assets/images/favicon.ico'
    # 使用可能色は定義された21色
    #    red, pink, purple, deep purple, indigo, blue, light blue, cyan,
    #    teal,  green, light green, lime, yellow, amber, orange,
    #    deep orange,   brown, grey, blue grey, white
    palette:
        # ヘッダーの色。標準は'indigo'
        primary: 'indigo'
        # ハイライト文字の色。標準は'indigo'。
        accent: 'indigo'
    # フォント。'font: false'にするとGoogleフォントを使用しなくなる
    font:
        text: 'Roboto'
        code: 'Roboto Mono'

extra:
    # Materialデザインのアイコン拡張
    logo:
        # 利用可能なアイコンは以下を参照
        # https://material.io/resources/icons/?icon=description&style=baseline
        icon: 'developer_board'
    # ウェブアプリマニフェストを有効化
    # Web App Manifestについては他サイトを参照
    manifest: 'manifest.webmanifest'

markdown_extensions:
    # !!! を使って文書内に見やすいスタイルを使う(Markdownのサンプルを参照)
    - admonition
    # [^1] を使って注釈を使う(Markdownのサンプルを参照)
    - footnotes
    # コードハイライトを使う
    - codehilite:
        # 言語を表記する
        guess_lang: true
        # 行数を表示
        linenums: true