「Material for MkDocs」で利用可能な”リスト”の記法を色々試してみる

#MkDocs

しんや

2021.05.31

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

ロジェクトドキュメント構築向け静的サイトジェネレータ「Material for MkDocs」では、シンプル且つ分かりやすい構成・設定で見栄えの良いドキュメントを作成することが可能です。

当エントリでは、その中からドキュメント上に「リスト」を表現するための幾つかの方法について、設定手順とその内容を紹介します。

Lists - Material for MkDocs

リスト表記

番号無しのリストに関しては、-,+,*を使用可能です。以下のような形で記載をした場合、

- Classmethod Leadership Principle（CLP）は、クラスメソッド社員の行動指針や価値観を示したものです。社員として採用時や評価時の基準になります。 
    * リーダーシップ – Leadership –
    * パートナーシップ – Partnership –
    * ダイバーシティ – Diversity –
    * プロフェッショナル – Professionalism –
        + aaaaa
        + bbbbb
        + ccccc
    * 感謝 – Appreciation –
    * 顧客視点 – Customer Obsession –
    * フィードバック – Feedback –
    * 情報発信 – Output –
    * やってみる – Start small –
        + XXXXXXXX
        + YYYYYYYY
        + ZZZZZZZZ
    * 楽しむ - Enjoyment -

表示は以下のような内容となります。

数字リスト表記

数字.の表記形式で記載をした場合、番号付きのリストを展開することが出来ます。上記内容の先頭部分を数字表記に置き換えると、

1. Classmethod Leadership Principle（CLP）は、クラスメソッド社員の行動指針や価値観を示したものです。社員として採用時や評価時の基準になります。

    1. リーダーシップ – Leadership –
    2. パートナーシップ – Partnership –
    3. ダイバーシティ – Diversity –
    4. プロフェッショナル – Professionalism –
        1. aaaaa
        2. bbbbb
        3. ccccc
    5. 感謝 – Appreciation –
    6. 顧客視点 – Customer Obsession –
    7. フィードバック – Feedback –
    8. 情報発信 – Output –
    9. やってみる – Start small –
        1. XXXXXXXX
        2. YYYYYYYY
        3. ZZZZZZZZ
    10. 楽しむ - Enjoyment -

以下のように、行毎に採番された形でリストが表示されました。インデントの深さに応じて、数字の表示タイプが変わっていることも確認出来ます。

定義リスト

用語とその用語の定義のペアとなる記法、HTMLコードで言うとdl,dt,ddタグに相当する内容をMarkdownで記載することが出来ます。

この記法を使う場合は、mkdocs.ymlに以下の定義を追加します。

markdown_extensions:
  - def_list

追加した上で以下のコンテンツを記載。dtタグに相当する部分は行頭スペース無しで書き始め、ddタグに相当する部分は: (コロン＋半角空白3桁)を先頭に付与する形で書き始めます。

リーダーシップ – Leadership –
:   全ての社員がリーダーであるという考えのもとで、指示待ちや他責にならず自ら進んで前向きに行動し、周囲を巻き込み協力しあいながら、妥協せずに最高の結果が出るように尽力します。

パートナーシップ – Partnership –
:   雇用（社員・アルバイト・業務委託）、会社（親会社・子会社）、役割（上司・部下）、職務（エンジニア・バックオフィス）など、立場に関係なく、全て共に働くパートナーとして等しく接し、
互いを尊重します。

ダイバーシティ – Diversity –
:   年齢・性別・国籍・人種・宗教・性的指向・障害の有無など、多様な価値観があることを学びます。また、出産・育児・介護などのライフステージに寄り添い、互いに助け合い、これを強みとしま
す。

以下のような内容で表示されました。ただ内容的にはシンプルで素っ気ない感じもしますね。

生成されたHTMLコードを確認してみます。シンプルにHTMLコードとしてdl,dt,ddタグが吐き出されているだけなので、CSSで装飾したいと思います。

<dl>
<dt>リーダーシップ – Leadership –</dt>
<dd>全ての社員がリーダーであるという考えのもとで、指示待ちや他責にならず自ら進んで前向きに行動し、周囲を巻き込み協力しあいながら、妥協せずに最高の結果が出るように尽力します。</dd>
<dt>パートナーシップ – Partnership –</dt>
<dd>雇用（社員・アルバイト・業務委託）、会社（親会社・子会社）、役割（上司・部下）、職務（エンジニア・バックオフィス）など、立場に関係なく、全て共に働くパートナーとして等しく接し、互いを尊重します。</dd>
<dt>ダイバーシティ – Diversity –</dt>
<dd>年齢・性別・国籍・人種・宗教・性的指向・障害の有無など、多様な価値観があることを学びます。また、出産・育児・介護などのライフステージに寄り添い、互いに助け合い、これを強みとします。</dd>
</dl>

カスタムCSSを展開した上で以下設定を追加し、

dt {
  font-size: 1.15em;
  font-weight: bold;
  font-family: font-family: monospace, serif;
  color: #996666;
}

dd {
  font-size: 0.9em; 
}

ちょろっと見栄えを変えてみました。

タスクリスト

markdown_extensionsでタスクリストの定義を有効にしていると、チェックボックスのリストを使うことが出来ます。

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true
      ##clickable_checkbox: true

Markdownでチェックボックスを含めたリストを記載しておくと、

- [x] aaaaaaa
- [ ] ccccccc
    * [x] XXXXXXX
    * [x] YYYYYYY
    * [ ] ZZZZZZZ

以下のような形でチェックボックス付きのリストを表現出来ました。ちなみにclickable_checkbox: trueについては有効にすると「チェックボックスのOn/Offが操作出来る」ようになるのですが、正味のところ公開専門のドキュメントですし"現状の対応状況など"をチェックボックスの選択有無で確認することはあっても、参照用ドキュメントの上のチェックボックスを操作することも無さそうなのでここは記載無しでも良いかな、と思いました。