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

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

この記事は公開されてから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)に次のような設定を追加する。(ここに画面のカラーパレット設定を追加していきます)

    mkdocs.yml

    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) を作成する。

    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 を使用します。 カラー設定については、後述の「基本色とアクセント色の設定」を参照してください。

mkdocs.yml

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

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

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

  • ライトモード (default)

  • ダークモード (slate)

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

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

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

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

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

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

mkdocs.yml

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 を指定します。

mkdocs.yml

# ライトモードの場合
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) については、「事前準備」に記載していますので割愛します)

mkdocs.yml

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

おわりに

今回はドキュメントの基本的な配色設定について紹介しました。 簡単な設定でモードや色を切り替えできるのが良いですね。 次回以降ではスタイルシートを利用したカスタムカラー設定方法について紹介できればと思います。

ではまた。