MKDocs – 拡張プラグイン集(2)

MKDocs – 拡張プラグイン集(2)

Material for MkDocs をベースにタブ付きコンテンツや Web アイコンフォント、絵文字といった MKDocs で使用できる拡張プラグインを紹介します。
#MkDocs
くにきち

くにきち

facebook logohatena logotwitter logo
Clock Icon2021.04.20

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

はじめに

しがないOLくにきちです。 前回に引き続き、MKDocs の拡張プラグインについてまとめています。 今回はタブ付きコンテンツや Web アイコンフォント、絵文字などを使用するための設定を紹介していきます。

前回のブログはこちら。 ファビコン・アイコン設定や PlantUML 表示、アラート装飾など 8 つの設定を紹介しています。

本ブログ内の手順における前提

次の設定でドキュメントを生成します。

  • Python Version: 3.8.5
  • mkdocs Version: 1.1.2
  • mkdocs-material Version: 7.1.2 (このテーマを使用します)

事前準備として次の手順を完了してください。

ドキュメントの構造

mkdocs-test\
    |_ docs\
        |_ index.md
        |_ test-plugin.md
    |_ mkdocs.yml

拡張プラグイン集

タブ付きコンテンツ (Markdown 拡張)

コンテンツを切り替え表示できる設定です。情報をコンパクトにまとめられるので、ドキュメントを見やすくすっきりさせるのに便利です。 タブ内では文字だけでなく、テーブルやリスト、コードブロック、アラート装飾なども表示できます。 ただし、前回のブログで紹介したアラート装飾と同様に、デフォルトではタブ内のネストされたブロックを考慮しないため、複数行のコードブロックを 1 行で表示してしまいます。 複数行のコードブロックを正しく表示するには、アラート修飾内にネストを考慮する設定(スーパーフェンス機能)を追加します。

※ コードハイライトやアラート装飾は別途設定が必要です。詳細については前回のブログを参照してください。

設定方法

  1. 設定ファイルにタブ付きコンテンツの設定を記述します。 タブのコンテンツにコードブロックを埋め込まない場合は、スーパーフェンス機能を設定しなくて大丈夫です。

    # タブ付きコンテンツ
- pymdownx.tabbed
# スーパーフェンス機能
- pymdownx.superfences
# アラート装飾
- admonition
  2. markdown には次のように=== "{タブ名}"で記述します。 タブの内容は、スペース 4 つでインデントしてから始めてください。 

    ## タブ付きコンテンツ

コンテンツを切り替え表示し、情報をコンパクトにまとめます。
タブ内では文字やテーブル、リスト、コードブロック、アラート装飾などを表示できます。

=== "タブ 1"
    タブ 1 の内容を書く。 

    | カラム
    | :------
    | aaa
    
    ```java
    public class HelloWorld{
        public static void main(String[] args){
            System.out.println("Hello World!!");
        }
    }
    ```

=== "タブ 2"
    タブ 2 の内容を書く。

    - リスト 1
    - リスト 2
    
    !!! note
        これはノートです。

Webアイコンフォント・絵文字 (Markdown 拡張)

:{icon_shortcode}: の形式で記述し、文字と同じように表示できるアイコンと絵文字です。ページの装飾として使用できます。 アイコンのサイズや色は文字と同じ設定になるため、簡単に統一感のあるページを作成できます。

mkdocs-material では、次のアイコン群がバンドルされているため、設定を入れるだけですぐに使用できます。リンクはそれぞれのサービスで使用できるアイコン一覧ページへ遷移します。

設定方法

  1. Web アイコンフォントを使用するための設定を追加します。 
    markdown_extensions:
    # アイコン・絵文字の設定
    - pymdownx.emoji:
        emoji_index: !!python/name:materialx.emoji.twemoji
        emoji_generator: !!python/name:materialx.emoji.to_svg
  2. Material For MKDocs ドキュメントの「Icons + Emojis -Search」でキーワードを入力し、使用したいアイコンのショートコードをコピーします。キーワードがわからない場合は、各サービスのアイコン一覧を参照するとよいですが、各サービスで表示されるアイコンのコードと使用するショートコードは異なりますのでご注意ください。たとえば、Octicons の alert 16px を使用したい場合、:octicons-alert-16:と指定する必要があります。
  3. markdown にコピーしたショートコードをペーストして使用します。 
    ## :material-arrow-right-circle: Webアイコンフォント + 絵文字

「 [Icons + Emojis -Search :octicons-link-external-16:](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search) 」から Web アイコンフォントや絵文字を検索できます。

* 「 :fontawesome-solid-user: User 」のように統一感のある表示ができ、色やサイズは文字の設定に準拠します。
* :warning: :beginner: のようなカラフルな絵文字も使用できます。

ボタン (Markdown 拡張)

ページ内にボタンを表示する設定です。 表示したボタンにカーソルを合わせると色が変化し、ボタンをクリックすると指定したリンク先に遷移します。ボタンに表示する文言にはアイコンや絵文字も使用できます。※アイコンや絵文字も使用する場合には「 Webアイコンフォント・絵文字 (Markdown 拡張)」で紹介している設定が必要です。

ボタンの色はドキュメントのテーマに準拠しています。ここではテーマに material のデフォルトカラーを指定しているため、落ち着いたブルーカラーで表示しています。カラーを変更したい場合は、「カスタム CSS の設定」のように独自の CSS 設定ファイルを作成してカスタマイズするか、ドキュメント自体のテーマカラーを変更してください。（ドキュメントのテーマカラー変更については、また後日紹介したいと思います。）

カラー変更

設定方法

  1. 設定ファイルにボタンを使用するための設定を追加します。今回はアイコンや絵文字を使用するため、アイコン・絵文字設定も追加しています。アイコンや絵文字を使用しない場合は、アイコン・絵文字設定は不要です。 
    markdown_extensions:
    # アイコン・絵文字の設定
    - pymdownx.emoji:
        emoji_index: !!python/name:materialx.emoji.twemoji
        emoji_generator: !!python/name:materialx.emoji.to_svg
    # ボタン表示
    - attr_list
  2. markdown には次のように [{ボタンに表示する文言}]({ボタンクリック時のリンク先}){: .md-button } で記述します。イメージ図右側のように塗りつぶしボタンを使用する場合は、[{ボタンに表示する文言}]({ボタンクリック時のリンク先}){: .md-button .md-button--primary} と記述してください。 
    ## ボタン

アイコンや絵文字を指定してボタンを作成できます。

[:beginner: 新規会員登録](#){: .md-button }
[申し込みフォーム :octicons-link-external-16:](#){: .md-button .md-button--primary }

テーブルの並び替え設定

「tablesort」を利用して、作成したテーブルの並び替えをできるようにする設定です。 作成したテーブルのカラムをクリックすると、データを昇順・降順に並び替えます。複数のカラムを指定した複雑な並び替えはできません。文字の最初に絵文字を使用している場合、絵文字は無視して絵文字の後に記述している文字列を対象に並び替えを行います。

デフォルト

「Name」 でソート

「Emoji + Name」 でソート

絵文字後の文字をベースにソートしています。 絵文字のショートコードは :banana: など、絵文字後に記述している文字と一致しますが、絵文字のみのデータをソートした場合、並び順は ?(banana) -> ?(strawberry) -> ?(melon) の順になり、絵文字のショートコードを基準にソートしていないことがわかります。

設定方法

  1. docs/javascripts/というディレクトリを作成し、tables.js ファイルを作成します。 ディレクトリ名やファイル名は別の名前でもかまいません。後述の設定ファイル記述部分でこのファイルを指定する必要がありますので、名前を変更する場合は変更後の名前に置き換えてください。 ファイル作成後のドキュメント構造は次のとおりです。

    mkdocs-test\
    |_ docs\
        |_ index.md
        |_ test-plugin.md
        |_ javascripts\
            |_ tables.js
    |_ mkdocs.yml
  2. 作成した tables.js ファイルには次のように記述します。 
    document$.subscribe(function() {
  var tables = document.querySelectorAll("article table")
  tables.forEach(function(table) {
    new Tablesort(table)
  })
})
  3. 設定ファイルにテーブル並び替えの設定を追加します。 extra_javascript: に tablesort と先ほど作成した tables.js を指定し、デフォルトのテーマをカスタマイズします。tablesort は、ブログ執筆時の最新バージョン 5.2.1 を指定しています。バージョンについては、「tablesort」のリリース情報を確認してください。

    # 追加のJavaScript
extra_javascript:
    # テーブル並べ替え設定
    - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
    - javascripts/tables.js
  4. markdown にテーブルを追加します。 
    カラムをクリックすると、データを昇順・降順に並び替えます。

| No. | Name      | Emoji + Name
| :-- | :-------- | :------------------------
| 1   | バナナ     | :banana: banana
| 2   | いちご     | :strawberry: strawberry
| 3   | メロン     | :melon: melon

まとめ

今回紹介した設定や拡張プラグインを記述した設定ファイルと Markdown (test-plugin.md) はこのような感じです。作成した markdown を適切に表示するには、以下のファイルをコピーするだけではなく、javascripts/tables.js の作成を忘れずにおこなってください。

site_name: ドキュメントテスト
theme:
    name: material
    # サイトの言語設定
    language: ja

# Markdown拡張
markdown_extensions:
    # タブ付きコンテンツ
    - pymdownx.tabbed
    # スーパーフェンス機能
    - pymdownx.superfences
    # アラート装飾
    - admonition
    # アイコン・絵文字の設定
    - pymdownx.emoji:
        emoji_index: !!python/name:materialx.emoji.twemoji
        emoji_generator: !!python/name:materialx.emoji.to_svg
   # ボタン表示
    - attr_list
# 追加のJavaScript
extra_javascript:
    # テーブル並べ替え設定
    - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
    - javascripts/tables.js

# プラグインのテスト

## タブ付きコンテンツ

コンテンツを切り替え表示し、情報をコンパクトにまとめます。
タブ内では文字やテーブル、リスト、コードブロック、アラート装飾などを表示できます。

=== "タブ 1"
    タブ 1 の内容を書く。 

    | カラム
    | :------
    | aaa
    
    ```java
    public class HelloWorld{
        public static void main(String[] args){
            System.out.println("Hello World!!");
        }
    }
    ```

=== "タブ 2"
    タブ 2 の内容を書く。

    - リスト 1
    - リスト 2
    
    !!! note
        これはノートです。

## :material-arrow-right-circle: Webアイコンフォント + 絵文字

「 [Icons + Emojis -Search :octicons-link-external-16:](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search) 」から Web アイコンフォントや絵文字を検索できます。

* 「 :fontawesome-solid-user: User 」のように統一感のある表示ができ、色やサイズは文字の設定に準拠します。
* :warning: :beginner: のようなカラフルな絵文字も使用できます。


## ボタン

アイコンや絵文字を指定してボタンを作成できます。

[:beginner: 新規会員登録](#){: .md-button }
[申し込みフォーム :octicons-link-external-16:](#){: .md-button .md-button--primary }

## テーブルの並び替え

カラムをクリックすると、データを昇順・降順に並び替えます。

| No. | Name      | Emoji + Name
| :-- | :-------- | :------------------------
| 1   | バナナ     | :banana: banana
| 2   | いちご      | :strawberry: strawberry
| 3   | メロン      | :melon: melon

おわりに

今回は前回に引き続き、MKDocs 使用できる拡張プラグインなどを紹介しました。 私は特にWebアイコンフォント・絵文字が気に入っていて、アイコンを挿入するだけでメリハリがある見やすいドキュメントになるなーと思いました。 また、Material for MkDocs はリリース頻度も高く、開発や機能改善が活発なのが嬉しいです。 これからも MKDocs や Material for MkDocs について書いていければと思います。

ではまた。

Share this article

facebook logohatena logotwitter logo

関連記事

いちナレッジサイトにおける MkDocs および Material for MkDocs の 設定まとめ【静的サイトジェネレータ】

いちナレッジサイトにおける MkDocs および Material for MkDocs の 設定まとめ【静的サイトジェネレータ】

User avatar
川原征大
2024.10.10
Material for MkdocsにCustomizationを使ってサイト分析ツールを導入してみた

Material for MkdocsにCustomizationを使ってサイト分析ツールを導入してみた

User avatar
たかやま
2023.10.30
Material for MkDocsのタイトルテキストをリンクテキストにする

Material for MkDocsのタイトルテキストをリンクテキストにする

User avatar
たかやま
2023.10.24
ドキュメントの文法(シンタックス)【CCG執筆者向け】

ドキュメントの文法(シンタックス)【CCG執筆者向け】

User avatar
川原征大
2023.09.11
Classmethod's white logo
Facebook's logo
X's logo
YouTube's logo

© Classmethod, Inc. All rights reserved.