MKDocs – 基本のドキュメント配色設定方法

Material for MkDocs をベースに基本的なドキュメント配色設定方法について紹介します。

#MkDocs

#初心者向け

くにきち

2021.05.20

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

はじめに

しがないOLくにきちです。今回は MKDocs 製ドキュメントの配色設定方法についてまとめています。ここでは「Material for MkDocs」でサポートされているカラースキームや基本色・アクセント色の変更方法を紹介します。

⚠️ 本ブログでは設定ファイル (mkdocs.yaml) でおこなう基本的な配色設定を対象としており、スタイルシートを使用したカスタムカラー設定方法は本ブログの対象外です。

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

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

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

事前準備

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

「プロジェクトドキュメント構築向け静的サイトジェネレータ『MkDocs』及び『Material for MkDocs』の個人的導入＆設定まとめ」を参照して、ドキュメントを生成できる状態にする。

設定ファイル (mkdocs.yaml)に次のような設定を追加する。(ここに画面のカラーパレット設定を追加していきます)

site_name: ドキュメントテスト
theme:
    name: material
    # サイトの言語設定
    language: ja
    features:
        # トップに戻るボタン
        - navigation.top
# Markdown拡張
markdown_extensions:
    # アイコン・絵文字の設定
    - pymdownx.emoji:
        emoji_index: !!python/name:materialx.emoji.twemoji
        emoji_generator: !!python/name:materialx.emoji.to_svg
   # ボタン表示
    - attr_list

次のようなカラー設定確認用のファイル (sample.md) を作成する。

# サンプル

## ボタン

基本色

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

カーソルをあてた時の色

[申し込みフォーム :octicons-link-external-16:](#){: .md-button .md-button--primary }

## リンク

**[リンク :octicons-link-external-16:](#)**

ドキュメントの構造

事前準備を終えた時点では、このようなドキュメント構造をしています。

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

生成したドキュメントを確認する場合は、mkdocs.yml が存在するディレクトリで mkdocs serve を実行してください。ドキュメントサーバ起動後、http://localhost:8000/ にアクセスするとドキュメントを確認できます。

カラースキームの設定

mkdocs-material は、カラースキームとしてライトモード (default) とダークモード (slate) の 2 種類をサポートしています。カラースキームの設定をしない場合は、ライトモードで表示します。

カラースキーム設定例

設定ファイルにカラースキーム設定を追加します。ここでは基本色やアクセント色の設定をしていないため、基本色やアクセント色ともにデフォルト設定の indeigo を使用します。カラー設定については、後述の「基本色とアクセント色の設定」を参照してください。


# ライトモードの場合
theme:
    palette:
        scheme: default

# ダークモードの場合
theme:
    palette:
        scheme: slate

カラースキーム設定イメージ

ライトモード (default)

ダークモード (slate)

カラースキームの切り替え設定

ヘッダーに切り替えスイッチを配置し、ユーザーが任意にライトモードとダークモードを切り替えできるようにします。ライトモードとダークモードで基本色やアクセント色を変えたい場合は、それぞれのカラースキーム設定で基本色とアクセント色の設定を追加します。基本色やアクセント色の指定がない場合は、indigo を使用します。

カラースキーム切り替え設定例

設定ファイルにカラースキーム切り替え設定を追加します。

scheme: 設定するカラースキーム (default or slate) を指定します。
icon: 切り替えスイッチとして表示するアイコンを指定します。詳細は後述の「切り替えスイッチに使用できるアイコン」を参照してください。
name: トグルスイッチにカーソルを合わせた時に表示するメッセージを指定します。ライトモードのアイコン表示時は「ダークモードに切り替えます。」などにすると良いでしょう。

ここでは、ライトモードにデフォルト設定 (indigo)、ダークモードは色を変えるために red を指定します。スイッチはトグルボタンを使用します。使用可能色は後述の「使用可能な色」を参照してください。

theme:
    palette:
        - scheme: default
          toggle:
              icon: material/toggle-switch-off-outline
              name: ダークモードに切り替えます。
        - scheme: slate
          primary: red
          accent: red
          toggle:
              icon: material/toggle-switch
              name: ライトモードに切り替えます。

切り替えスイッチに使用できるアイコン

切り替えスイッチとして表示するアイコンは、mkdocs-material でバンドルされているアイコンを使用できます。バンドルされているアイコンセットは、前回のブログ「MKDocs – 拡張プラグイン集(2)」で紹介したものと同様です。

アイコンを指定する場合、前回のブログで紹介したアイコンのショートコードではなく、material/toggle-switch-off-outline のようにアイコンを参照するパスを指定する必要があります。アイコンのパスは、ショートコードの : を削除し、アイコンセット名とアイコン名の間にある - を / にすれば大丈夫そうです。たとえば、:octicons-sun-16: のアイコンを使用したい場合は、アイコンパスは octicons/sun-16 と指定します。

カラースキーム切り替え設定イメージ

最初のイメージと異なり、ライトモードとダークモードとで基本色とアクセント色を変更できました。

基本色とアクセント色の設定

ヘッダーやボタン、テキストリンクなどで使用する基本色とカーソルをあてた時に使用するアクセント色を変更できます。基本色とアクセント色とで同じ色名のものがありますが、前述の「カラースキーム設定イメージ」でもわかるように、大体は同じ色名を指定しても違いがわかるようになっています。

基本色とアクセント色の設定例

設定ファイルに基本色とアクセント色の設定を追加します。カラースキーム切り替え設定時の配色については、前述の「カラースキーム切り替え設定例」を参照してください。

scheme: 設定するカラースキーム (default or slate) を指定します。default の場合は省略可能です。
primary: ヘッダーやボタン、テキストリンクなどの基本色を指定します。未指定の場合は indigo で表示します。
accent: ボタンやテキストリンクにカーソルをあてた時のアクセント色を指定します。未指定の場合は indigo で表示します。

ここでは、基本色に red, アクセント色に orange を指定します。

# ライトモードの場合
theme:
    palette:
        primary: red
        accent: orange

# ダークモードの場合
theme:
    palette:
        scheme: slate
        primary: red
        accent: orange

基本色とアクセント色の設定イメージ

ライトモード

ダークモード

使用可能な色

現在、基本色は 21 色、アクセント色は 16 色用意されています。自社のブランドカラーを使用したいなどサポート外の色を指定する場合は、独自のスタイルシートを追加して色を定義する必要があります。カスタムカラーの指定については、また別途ご紹介したいと思います。

使用可能な色名とイメージ

イメージではボタンとテキストリンクを表示しています。カラースキームと色の相性が良いもの、悪いものがありますので、イメージ一覧を参考にしてみてください。

※アクセント色は deep orange までの 16 色しかサポートしていないため、brown 以降のイメージはボタンとテキストリンクのみのイメージを掲載しています。

色名	ライトモード	ダークモード
`indigo` (デフォルト)
`red`
`pink`
`purple`
`deep purple`
`blue`
`light blue`
`cyan`
`teal`
`green`
`light green`
`lime`
`yellow`
`amber`
`orange`
`deep orange`
`brown`
`grey`
`blue grey`
`black`
`white`

まとめ

今回紹介した設定ファイルはこのような感じです。(カラー設定確認用のファイル (sample.md) については、「事前準備」に記載していますので割愛します)

site_name: ドキュメントテスト
theme:
    name: material
    # サイトの言語設定
    language: ja
    features:
        # トップに戻るボタン
        - navigation.top
    # 配色設定
    palette:
        - scheme: default
          toggle:
              icon: material/toggle-switch-off-outline
              name: ダークモードに切り替えます。
        - scheme: slate
          primary: red
          accent: red
          toggle:
              icon: material/toggle-switch
              name: ライトモードに切り替えます。
# Markdown拡張
markdown_extensions:
    # アイコン・絵文字の設定
    - pymdownx.emoji:
        emoji_index: !!python/name:materialx.emoji.twemoji
        emoji_generator: !!python/name:materialx.emoji.to_svg
    # ボタン表示
    - attr_list