この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
はじめに
おひさしぶりです。しがないOLくにきちです。久々のブログ投稿になりました。 最近はドキュメント整備を主な仕事にしてまして(たまにリファクタリングやテスト)新しくドキュメント環境作ってみたりドキュメント書いたりして過ごしてます。
その中で、これまでドキュメント作成に使用していた GitBook CLI の開発が止まってしまったため、新しいドキュメント生成ツールを導入しよう!ということになりました。 導入の条件は色々ありましたが、今回導入に至ったのは「MKDocs」です。 簡単で、プラグインの豊富さやモダンな見ため、既存のドキュメントよりも見やすくなったのが決め手でした。
MkDocs の導入については、すでに弊社しんや (shinyaa31) による導入手順ブログ「プロジェクトドキュメント構築向け静的サイトジェネレータ『MkDocs』及び『Material for MkDocs』の個人的導入&設定まとめ」があります。 導入手順はそちらをご覧ください。私もお世話になりました。
本ブログでは、MKDocs の拡張プラグインについて書いていきます。 上記導入手順でも拡張プラグインについていくつか書いており重複するものもありますが、自分の備忘録としてこちらにまとめて書いておきます。 ※ 1ページですべてまとめたかったのですが、量が多くなってしまったのでページをわけます。
本ブログ内の手順における前提
次の設定でドキュメントを生成します。
- Python Version:
3.8.5
- mkdocs Version:
1.1.2
- mkdocs-material Version:
6.2.5
(このテーマを使用します)
事前準備として次の手順を完了してください。
- 「プロジェクトドキュメント構築向け静的サイトジェネレータ『MkDocs』及び『Material for MkDocs』の個人的導入&設定まとめ」を参照して、ドキュメントを生成できる状態にする。
- プラグインテスト用のファイル (
test-plugin.md
) を作成する。docs\
内に格納すればmkdocs.yml
(以降は「設定ファイル」と呼びます)の編集は不要です。- ここで各種プラグインの表示をテストします。
ドキュメントの構造
mkdocs-test\
|_ docs\
|_ index.md
|_ test-plugin.md
|_ mkdocs.yml
拡張プラグイン集
ここでは、MKDocs の拡張プラグインから私が有用だと感じたものを紹介します。
(MKDocs で使用できるすべてのプラグインを書いているわけではありません)
ここで紹介する拡張プラグインは、mkdocs-material
のみ対応しているものもありますので、「本ブログ内の手順における前提」でも書いたとおり、mkdocs-material
テーマを使用して試してください。
ファビコン変更
ファビコンを任意の画像に変更できます。 今回はこの画像を使用します。
状態 | イメージ |
---|---|
デフォルト | |
設定後 |
設定方法
- 画像用ディレクトリ (
images
) を作成し、ファビコンとして表示したい画像を格納します。# 画像追加時のドキュメント構造 mkdocs-test/ |_ docs/ |_ index.md |_ test-plugin.md |_ images/ |_ image1.png |_ mkdocs.yml
-
設定ファイルに画像のパスを指定します。 このとき、
docs
またはdocs_dir
で指定したディレクトリを起点にパスを記述します。mkdocs.yml
theme: # ファビコンの設定 favicon: images/image1.png
アイコン変更
ファビコンと同様にドキュメントのヘッダーで表示するアイコンを任意の画像に変更できます。 ここではファビコンで使用したものと同じ画像を使用しますので、画像を格納する手順は割愛します。
状態 | イメージ |
---|---|
デフォルト | |
設定後 |
設定方法
設定ファイルに画像のパスを指定します。 このとき、docs
または docs_dir
で指定したディレクトリを起点にパスを記述します。
mkdocs.yml
theme:
# アイコンの設定
logo: images/image1.png
日本語検索の設定
material
は、サイトの設定言語に基づいて検索言語を自動的に設定します。
設定ファイルの言語設定で language: ja
と記述していれば日本語検索が可能です。
設定方法
mkdocs.yml
theme:
# サイトの言語設定
language: ja
検索インデックスの単語区切り文字設定
設定ファイルで検索インデックス作成時の単語区切り文字をカスタマイズできます。
単語区切り文字をカスタマイズすることで、空白とハイフン (-
) 以外の文字で区切られた単語にインデックスを付与できます。
デフォルト(未設定時)の単語区切り文字は、[\s\-]+
(空白とハイフン)です。
状態 | イメージ |
---|---|
デフォルト | |
設定後 |
設定後のイメージは、デフォルトの空白とハイフン (-
)に単語区切り文字としてドット (.
) を追加した例です。
ドット (.
) で区切られた単語 hoge
にインデックスがついています。
設定方法
デフォルトの空白とハイフン (-
)に単語区切り文字としてドット (.
) を追加する場合、separator: '[\s\-\.]+'
と記述します。
mkdocs.yml
plugins:
- search:
# 検索インデックスの単語区切り文字設定
separator: '[\s\-\.]+'
さらに単語区切り文字を追加したい場合は、[]
内に \
で区切って単語区切りに使用する文字を追加していきます。たとえば、ドット (.
) に加え、さらにアンダースコア (_
) を追加したい場合は [\s\-\.\_]+
のように指定します。
コードハイライト (Markdown 拡張)
codehilite
を使用してコードブロックの構文を強調表示します。
コードハイライトには次のようなオプションを用意しています。
use_pygments
: Pygmentsを使用してコードブロックを表示する設定 (Default: true) ※使用する場合は記述不要noclasses
: インラインスタイル (HTMLタグに直接スタイルを付与する方法)の設定 (Default: false)pygments_style
: Pygments スタイルの設定 (Default: default テーマ)- スタイルは「pygments/pygments/styles」から指定できます。
linenums
: コードブロックの行番号表示 (Default: false)
状態 | イメージ |
---|---|
デフォルト | |
設定後 |
設定後のイメージは、noclasses
, pygments_style: colorful
, linenums
を指定した場合の例です。
設定方法
- 設定ファイルにコードハイライトの設定を記述します。
mkdocs.yml
markdown_extensions: # コードハイライトの設定 - codehilite: noclasses: true pygments_style: colorful linenums: true
-
markdown には次のように記述します。
test-plugin.md
```java #ブロック内の言語を指定 public class HelloWorld { public static void main(String[] args){ System.out.println("Hello World!!"); } } ```
PlantUML 表示設定 (Markdown 拡張)
PlantUMLを表示するための Markdown 拡張設定です。
状態 | イメージ |
---|---|
デフォルト | |
設定後 |
設定方法
plantuml-markdown
をインストールします。pip install plantuml-markdown
- PlantUML を描画するために「 plantuml-server 」の Docker イメージをダウンロードします。 (コマンドを実行するには Docker のインストールが必要です)
docker pull plantuml/plantuml-server
-
設定ファイルに PlantUML の設定を記述します。
mkdocs.yml
markdown_extensions: # PlantUMLの表示設定 - plantuml_markdown: server: http://www.plantuml.com/plantuml
アラート修飾 (Markdown 拡張)
注意や警告を目立たせるために装飾する設定です。 インフォメーションや警告、ヒントなどをアイコンやカラーを使用して目立つように装飾します。 アラート修飾内では文字だけではなく、テーブルやリスト、コードブロックを表示できます。アラート装飾内にさらにアラート装飾を設定することも可能です。 ただし、デフォルトではアラート修飾内のネストされたブロックを考慮しないため、複数行のコードブロックを 1 行で表示してしまいます。 複数行のコードブロックを正しく表示するには、アラート修飾内にネストを考慮する設定(スーパーフェンス機能)を追加します。
※ コードブロックは、必要に応じて前述のコードハイライト設定をしてください。
設定方法
- 設定ファイルにアラート修飾の設定を記述します。
アラートの内容にコードブロックを埋め込まない場合は、スーパーフェンス機能を設定しなくて大丈夫です。
mkdocs.yml
markdown_extensions: # アラート修飾の設定 - admonition # スーパーフェンス機能の設定 - pymdownx.superfences
-
markdown には
!!! {ラベル名}
で記述します。 独自のタイトルを付けたい場合は!!! {ラベル名} "{タイトル}"
とし、タイトルを削除する場合は!!! {ラベル名} " "
と記述します。 アラートの内容は、スペース 4 つでインデントしてから始めてください。test-plugin.md
!!! note これはノートです。 * aaa * bbb | aaa | :--- | hoge ```java public class HelloWorld{ public static void main(String[] args){ System.out.println("Hello World!!"); } } ```
装飾の種類
アラート装飾は指定するラベルによってアイコンやカラーが変わります。 指定できるラベルと装飾のイメージは次のとおりです。
ラベル名 | イメージ |
---|---|
note , seealso |
|
abstract , summary , tldr |
|
info , todo |
|
tip , hint , important |
|
success , check , done |
|
question , help , faq |
|
warning , caution , attention |
|
failure , fail , missing |
|
danger , error |
|
bug |
|
example |
|
quote , cite |
コンテンツの折りたたみ (Markdown 拡張)
コンテンツを折りたたんだ状態で表示します。アラート修飾と同様の表現ができます。 ドキュメント内をすっきりさせたい場合に便利です。
設定方法
- 設定ファイルにコンテンツの折りたたみ設定を記述します。
mkdocs.yml
markdown_extensions: # コンテンツの折りたたみ設定 - pymdownx.details
- markdown には次のように
??? {ラベル名}
で記述します。内容は、アラート装飾と同様にスペース 4 つでインデントしてから始めてください。 読み込み時に折りたたみコンテンツを開いた状態で表示する場合は、???+ {ラベル名}
と記述してください。 これらを組み合わせてネストしたコンテンツも作成できます。test-plugin.md
??? note これはノートです。 ??? note "ネストされた詳細 1" このように詳細のネストが可能です。 ???+ note "ネストされた詳細 2" このように詳細のネストが可能です。
まとめ
今回紹介した設定や拡張プラグインを記述した設定ファイルと Markdown (test-plugin.md
) はこのような感じです。
これらを適切に表示するにはライブラリのインストールなど別途操作を必要とするものがあり、この内容をコピーするだけではエラーになります。
各プラグイン紹介の「設定方法」を確認してください。
mkdocs.yml
site_name: ドキュメントテスト
theme:
name: material
# サイトの言語設定
language: ja
# ファビコンの設定
favicon: images/image1.png
# アイコンの設定
logo: images/image1.png
plugins:
- search:
# 検索インデックスの単語区切り文字設定
separator: '[\s\-\.]+'
markdown_extensions:
# コードハイライトの設定
- codehilite:
noclasses: true
pygments_style: colorful
linenums: true
# PlantUMLの表示設定
- plantuml_markdown:
server: http://www.plantuml.com/plantuml
# アラート修飾の設定
- admonition
# スーパーフェンス機能の設定
- pymdownx.superfences
# コンテンツの折りたたみ
- pymdownx.details
test-plugin.md
# プラグインのテスト
## 検索テスト
検索のテストです。
| param | name | type
| :------- | :----------------- | :-----
| path | `{customer_code}` | string
| body | `.customer_name` | string
| body | `.hoge[].hoge1` | string
## コードハイライトのテスト
``` java
public class HelloWorld{
public static void main(String[] args){
System.out.println("Hello World!!");
}
}
```
## PlantUMLのテスト
```plantuml
Bob->Alice : hello
```
## アラート装飾のテスト
!!! note
これはノートです。
* aaa
* bbb
| aaa
| :---
| hoge
```java
public class HelloWorld{
public static void main(String[] args){
System.out.println("Hello World!!");
}
}
```
!!! note
`note`, `seealso` ラベルで使用できる装飾です。
!!! abstract
`abstract`, `summary`, `tldr` ラベルで使用できる装飾です。
!!! info
`info`, `todo` ラベルで使用できる装飾です。
!!! tip
`tip`, `hint`, `important` ラベルで使用できる装飾です。
!!! success
`success`, `check`, `done` ラベルで使用できる装飾です。
!!! question
`question`, `help`, `faq` ラベルで使用できる装飾です。
!!! warning
`warning`, `caution`, `attention` ラベルで使用できる装飾です。
!!! failure
`failure`, `fail`, `missing` ラベルで使用できる装飾です。
!!! danger
`danger`, `error` ラベルで使用できる装飾です。
!!! bug
`bug` ラベルで使用できる装飾です。
!!! example
`example` ラベルで使用できる装飾です。
!!! quote
`quote`, `cite` ラベルで使用できる装飾です。
## コンテンツの折りたたみテスト
??? note
これはノートです。
??? note "ネストされた詳細 1"
このように詳細のネストが可能です。
???+ note "ネストされた詳細 2"
このように詳細のネストが可能です。
おわりに
今回は MKocs の拡張プラグインをいくつか紹介しました。 特に Markdown 拡張プラグインを使うと、きれいでスッキリとした見やすいドキュメントを作成できるので大変助かってます。 少し長くなってしまったので今回はここまでにして、次回この続きを書きたいと思います。 次は「Web アイコンフォント」や「タブ付きコンテンツ」などを紹介します。
ではまた。