「Material for MkDocs」で利用可能な”テーブル”の記法を色々試してみる

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

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

• Data tables - Material for MkDocs

目次

• テーブル表示の基本形
• テーブルセルの「寄せ」に関する設定
• 並べ替え可能なテーブルの実装
• HTMLとCSSで個別に記述する
• まとめ

テーブル表示の基本形

MkDocsでは記法としてMarkdownに対応しているため、インラインコードブロック、アイコンや絵文字などを使ってテーブルを表現することが可能です。

• Extended Syntax | Markdown Guide

以下のような記述を行うことで、

| Method      | Description                          |
| ----------- | ------------------------------------ |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

このような形式のテーブルが表示されます。

テーブルセルの「寄せ」に関する設定

テーブルセルの「左寄せ/真ん中寄せ/右寄せ」についても、Markdownでの記法を使って表現することが可能です。下記のように、列毎に指定する形を採用します。ヘッダー行とデータ行の間に1行、「寄せ」に関する設定行を追加することで対応出来ます。

| Syntax      | Description | Test Text     |
| :---        |    :----:   |          ---: |
| Header      | Title       | Here's this   |
| Paragraph   | Text        | And more      |
|　左寄せテキスト | 真ん中寄せテキスト | 右寄せテキスト |

表示内容がこちら。

並べ替え可能なテーブルの実装

定義とライブラリの追加でひと手間加えると、Markdownで記載したテーブルの内容を「項目で並べ替え」することが可能になります。

任意のパス(下記例ではdocs/javascripts/tables.jsに以下のJavascriptファイルを配置。

docs/javascripts/tables.js

document$.subscribe(function() {
  var tables = document.querySelectorAll("article table")
  tables.forEach(function(table) {
    new Tablesort(table)
  })
})

更に、mkdocs.ymlに以下の定義を追加。

mkdocs.yml

extra_javascript:
  - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
  - javascripts/tables.js

この状態で、Markdownで記載したテーブルの内容を確認(リロード)してみます。すると、テーブルヘッダーのセル部分をクリックするとデータが並び替え表示されるようになりました。

HTMLとCSSで個別に記述する

上記は全てMarkdown記法での内容でしたが、Markdownでの表現には限界もあります。また、Material for MkdocsはHTMLにも対応しているので『HTML書けるんなら別にHTMLでも良いんじゃね？』というのもあります。ここでは普段仕事で使ってる「HTMLとCSSで構成する設定」を備忘録として残しておきたいと思います。

まずはHTMLでテーブルを記述。

<table class="devio">
<tr><th>METHOD</th><th>Description</th></tr>
<tr><td>GET</td><td>Fetch resource</td></tr>
<tr><td>PUT</td><td>Update resource</td></tr>
<tr><td>DELETE</td><td>Delete resource</td></tr>
</table>

mkdocs.ymlに以下の設定を追加し、

mkdocs.yml

extra_css:  ## CSS追加設定定
    - stylesheets/custom.css

対応するファイルとテーブルに関する定義を追加します。

docs/stylesheets/custom.css

/** テーブル装飾. */
table.devio {
  background-color:black !important;
  width: 100%;
}
table.devio th {
  background-color:#ffc699 !important;
  border-collapse: collapse !important;
  border:1px solid #333 !important;
  padding: 3px 8px;
  margin: 3px 8px;
  font-weight: bold;
}
table.devio td {
  background-color:#ffffff !important;
  border-collapse: collapse !important;
  border:1px solid #333 !important;
  padding: 3px 8px;
  margin: 3px 8px;
}

以下のように、任意のテーブルを表現することが出来ました。

まとめ

という訳で、プロジェクトドキュメント構築向け静的サイトジェネレータ「Material for MkDocs」のテーブル表現に関する内容の紹介でした。引き続き色々な設定を試してみたいと思います。

• MkDocs の記事一覧 | DevelopersIO