コンテンツにスキップ

MkDocs拡張機能

MkDocsは拡張機能(Extension)を有効にすることによって、様々な機能を追加することができる。

公式サポート拡張(Officially Supported Extensions)

公式でサポートされている拡張機能。MkDocsに最初から含まれており、追加インストールしなくても使用することができる。

公式拡張機能のリスト

導入方法

mkdocs.yml内でmarkdown_extensions:に拡張機能の名前を追加する。

例:Attribute Listsの場合

1
2
3
markdown_extensions:
    - attr_list
    - 拡張機能名

Attribute Lists

生成されるHTMLの要素に任意の属性を追加することができる拡張機能。例えば見出しに対してid属性を指定したい場合次のように書く

1
### カスタムクエリ {: #Custom-queries}

すると以下のようなHTMLが生成される

1
<h3 id="Custom-queries">カスタムクエリ</h3>

Attribute Listsを使用した画像の中心揃え

extra_cssに以下のタグを追加する

1
2
3
4
.center {
  display: block; /*ブロック要素にする*/
  margin: 0 auto; /*中心揃え*/
}

画像を中心揃えで挿入する

1
![image](image.png){: .center}

サードパーティー拡張機能

CodeHilite

コードをハイライトする。300言語対応している。
https://squidfunk.github.io/mkdocs-material/extensions/codehilite/

インストール

1
pip install pygments

mkdocs.ymlに以下を追加

1
2
markdown_extensions:
    - codehilite

行番号を追加する場合

1
2
3
markdown_extensions:
    - codehilite:
        linenums: true

Houdini Vex言語に対応する

1
pip install houdini-lexers

でインストールする。コードブロックでvexを指定することによってvexのハイライトが可能。

Material for MkDocsで打ち消し線が動作しない。

以下の拡張機能を有効にする。

1
2
markdown_extensions:
    - pymdownx.tilde

その他、PyMdown Extensionsの拡張機能一覧

https://squidfunk.github.io/mkdocs-material/extensions/pymdown/

フォルダの名前を書き換える (Awesome-Pages)

通常、サイドメニューのフォルダのタイトルは元のフォルダ名で作られてしまう。そのため日本語にしたい場合にはフォルダ名を日本語にしなくてはならないためURLが汚れてしまう。Awesome-Pagesを使用するとこの問題を解決できる。

インストール

pipでインストール

1
pip install mkdocs-awesome-pages-plugin

mkdocs.ymlに以下を追加

1
2
plugins:
    - awesome-pages

使い方

後は、改名したいディレクトリ直下に.pagesというファイルを作り以下のようにタイトルを設定する。

1
title : タイトル

すると、フォルダのタイトル名が.pagesで設定したものになる。