この記事は公開されてから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
orslate
) を指定します。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
orslate
) を指定します。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
おわりに
今回はドキュメントの基本的な配色設定について紹介しました。 簡単な設定でモードや色を切り替えできるのが良いですね。 次回以降ではスタイルシートを利用したカスタムカラー設定方法について紹介できればと思います。
ではまた。