コンテンツにスキップ

mkdocs.yml 設定

mkdocs.yml で設定を変更することでさまざまな機能を付加して便利に使用することができます。 個人的にこれはと思った設定項目を紹介します。

Material テーマ前提とします

紹介するものの中には Material テーマ以外で対応していないものもあるかもしれませんので注意願います。

nav を設定していない場合 MkDocs は自動的に docs 以下の .md ファイルを探索して自動的にインデックスを構成します。 しかしこれだと意図しない並びや名前になったりすることがあると思います。 その場合 nav で定義することにより自分でリンク名や並び順を決めることができます。 追加する度に記述するのが多少面倒ですが、致し方ないかなと思います。

nav:
  - index.md
  - MkDocs:
    - mkdocs/001.md  # この記述の場合対象ドキュメントの <h1> が自動的に使用される
    - ほげふが: mkdocs/002.md  # 題名「ほげふが」を明示的に指定する

theme

テーマを設定します。 ロゴや favicon, 更に Material テーマだと色やフォント、タブなども設定できて便利です。 このあたりは 公式ドキュメント にいろいろ書いてありますので、一通り見てみるのが良いでしょう。

この中で注意すべきなのが features: の部分です:

navigation.tabs
トップレベル階層をタブとして表示します。好みによるかと思いますが、カテゴリがタブとして明確に表示されるので悪くないと思います。
navigation.top
下にスクロールして上に戻る時に画面トップに戻るためのボタンが表示されます。ちょっと便利です。
toc.integrate
通常は左にページ一覧、右に目次が表示され、中央にコンテンツが表示されて領域が狭いのですが、この設定を付与すると左にページ一覧と目次が合体して表示されます。 個人的にはこの方が見やすい気がします。

クラスメソッド様の記事 が大変参考になりました。 私は最終的に以下のような設定に落ち着きました:

theme:
  name: 'material'
  language: 'ja'
  logo: assets/logo.png
  favicon: assets/favicon.png
  palette:
    primary: 'light blue'
    accent: 'orange'
  font:
    text: 'BIZ UDPGothic'
    code: 'JetBrains Mono'
  features:
    - navigation.tabs
    - navigation.top
    - toc.integrate

extra_css,extra_javascript

見た目や挙動をカスタマイズするために別途 CSS や JavaScript ファイルを追加することができます。 例えば以下のように指定して対象ディレクトリにファイルを配置します:

# 拡張 CSS
extra_css:
  - assets/extra.css

# 拡張 JavaScript
extra_javascript:
  - assets/extra.js

plugin

使用するプラグインを指定します。 Material テーマでは日本語での検索ができるのですが、それを使用するためにここで以下のように指定します:

plugins:
  - search:
      lang: ja

markdown_extensions

その他 Markdown 拡張記法の追加を行い便利に利用できるようにします。 概要だけ書きます。

admonition
メモ、ヒント、警告などを目立つように表示してくれる拡張機能です。見た目が良いのでおすすめです。
!!! Note "Admonition テスト"

    こんな感じです。

こう書くと以下のように表示されます:

Admonition テスト

こんな感じです。

footnotes
注釈を書いて文末にまとめることができます。独特な感じです1。
codehilite
コードブロックをハイライト表示してくれます。
public static void main(String... args) {
    System.out.println("こんな感じです");
}
def_list
定義リスト、要は <dl><dt><dd> 構造を使用して定義を列挙することができます。 まさにここの項目で使用している通りです。
pymdownx.tasklist
タスクリストを定義することができます。タスク管理を行う場合に便利なのではないかと思います。
  • やっていないこと
  • やったこと
    • 入れ子
    • 入れ子 2
attr_list
Markdown に対して属性を追加することが出来ます。例えば ![image](image.png){: .center} のような記法をすることで生成される <img> タグに class="center" 属性を付加することができます。
md_in_list
HTML 記法の中でも Markdown を利用できるようになるとのことです。

結果的に以下のような指定に落ち着きました:

markdown_extensions:
- admonition
- footnotes
- codehilite
- def_list
- pymdownx.tasklist:
  custom_checkbox: true
- attr_list
- md_in_html

尚、このサイトで最終的に使用している指定は GitHub のリポジトリ から参照できますので、参考になるかと思います。

  1. ここが注釈の概要です ↩

コメント