プロジェクトドキュメント構築向け静的サイトジェネレータ「Material for MkDocs」の色々な設定を試してみる(ナビゲーション編)

下記エントリで紹介したプロジェクトドキュメント構築向け静的サイトジェネレータ「Material for MkDocs」。日々アップデートが行われており、便利な機能や設定が利用出来るようになっています。

このエントリでは「現時点での最新バージョンではどんなことが出来るのか」という観点で、Material for MkDocsの「ナビゲーション」に関する項目を色々試してみた内容を紹介します。

目次

• 初期環境設定とコンテンツの準備
• 「Material for MkDocs」で利用可能な主な設定
  • インスタントローディング
  • ナビゲーションタブ設定
  • ナビゲーションのセクション表示
  • ページ内容を初期表示で全て「展開済み」の状態に
  • 「ページTOPに戻る」ボタンを表示
  • ナビゲーションの情報を左右統合
• mkdocs.ymlテンプレートファイル(設定内容追記済)
• まとめ

初期環境設定とコンテンツの準備

今回の検証は、下記のPython及びMaterial for MkDocsのライブラリバージョンで行っています。

• Python: 3.8.6
• mkdocs: 1.1.2
• mkdocs-material: 7.1.5

% python --version
Python 3.8.6

% pip install mkdocs-material
% pip freeze | grep mkdocs
mkdocs==1.1.2
mkdocs-material==7.1.5
mkdocs-material-extensions==1.0.1

そして、下記エントリの内容を参考に、任意のフォルダかつ複数個のmdファイルで構成されるmkdocsプロジェクトを用意しました。

• クラスメソッド株式会社のブログ『Developers.IO 』で”ジョインブログ”を書く人が最初に読むエントリ | DevelopersIO

mkdocs new プロジェクト名でmkdocsプロジェクトを作成。

% mkdocs new doc-developers-io
INFO    -  Creating project directory: doc-developers-io 
INFO    -  Writing config file: doc-developers-io/mkdocs.yml 
INFO    -  Writing initial docs: doc-developers-io/docs/index.md

% cd doc-developers-io 
% tree
.
├── docs
│   ├── index.md
│   ├── join-blog-flow
│   │   ├── account.md
│   │   ├── login.md
│   │   ├── notation.md
│   │   ├── topics.md
│   │   └── writing-flow.md
│   └── overview
│       └── overview.md
└── mkdocs.yml

Material for MkDocsを利用するためのname: materialをtheme配下に追加し、必要最低限の構成となる設定ファイルを記載します。

mkdocs.yml

## Overview Settings.
site_name: "DevelopersIO Mkdocs Site."

## Contents Navigation
nav:

- はじめに:
    - はじめに: index.md
    - 環境設定: settings.md
- 概要:
    - DevelopersIOについて: overview/overview.md
- ジョインブログ執筆:
    - ログイン: join-blog-flow/login.md
    - アカウントの確認と設定: join-blog-flow/account.md
    - ジョインブログに書く内容: join-blog-flow/topics.md
    - 記法: join-blog-flow/notation.md
    - 執筆フロー: join-blog-flow/writing-flow.md

## Basic Configuration
theme:
  name: material

mkdocs serveコマンドでサーバを起動。

## ポート番号:8000で起動
% mkdocs serve

ブラウザでhttp://localhost:8000/にアクセスし、以下のような形でページが表示されれば検証用環境の準備は完了です。

「Material for MkDocs」で利用可能な主な設定

ここからは、下記ドキュメントの内容から主だったものを幾つかピックアップして検証してみます。

• Setting up navigation - Material for MkDocs

インスタントローディング

navigation.instantの設定を有効にすると、全ての内部リンクのクリックがインターセプトされ、ページを完全にリロードすること無くXHR経由でディスパッチされるようになります。出来上がったページは解析及びインジェクションされ、全てのイベントハンドラとコンポーネントは自動的にリバウンドされます。

これによりmkdocsはシングルページアプリケーション(SPA)にように動作します。膨大な検索インデックスを備えた大規模ドキュメントサイトでは有効に働き、ドキュメント切り替えの間も検索インデックスはそのまま維持されます。以下の設定を追加することで有効となります。

theme:
  features:
    - navigation.instant

ナビゲーションタブ設定

navigation.tabsの設定を有効にすることで、ドキュメントのトップレベルにあるセクションを、横のナビにではなく「画面上部のヘッダー部分」に横に並べる形で表示させることが出来ます。

設定記載がない場合はこのような表示になっていますが、

以下のような設定を追加すると、

theme:
  features:
    - navigation.tabs

このように表示がを切り替えることが出来ます。ドキュメント構成的に大きなトピックが存在するような場合は、この表示方法を使うことで構成的にもより分かりやすく案内出来ると思います。

ナビゲーションのセクション表示

navigation.sectionsをの設定を有効にすると、トップレベルのセクションがサイドバーのグループとしてレンダリングされるようになります。

設定内容：

theme:
  features:
    - navigation.sections

設定変更前：

設定変更後：

ページ内容を初期表示で全て「展開済み」の状態に

navigation.expandの設定を有効にすると、左サイドバーの要素が全て展開された状態をデフォルト表示とします。

通常であれば、表示したページが存在するセクションの部分だけがこういう感じで表示されますが、

以下のように設定を有効にすると、

theme:
  features:
    - navigation.expand

全てのページが展開された状態で初期表示されるようになります。

「ページTOPに戻る」ボタンを表示

navigation.topの設定を有効にすると、ページのTOPに戻るためのボタンを使えるようになります。

theme:
  features:
    - navigation.top

ナビゲーションの情報を左右統合

toc.integrateの設定を有効にすると、左右に分散されているページメニューをひとまとめにすることが出来ます。従来であればページ毎の構成に関するメニューは左側に、ページ配下の見出しレベルに関するメニューは右側に表示される形となっていますが、

下記のように設定を有効にすると、

theme:
  features:
    - toc.integrate

これら2つのメニュー情報をひとまとめにすることが出来ます。統合される分、本文領域となる部分がより広く使えるようになるのでこれは嬉しい設定ですね。

mkdocs.ymlテンプレートファイル(設定追記済)

このエントリで紹介した設定内容を追記したmkdocs.ymlファイルの記載例は以下の通りです。個人的な好みから有効化したもの、コメントアウトしたものがありますが、実際にご利用される際はカスタマイズして頂けますと幸いです。

mkdocs.yml

site_name: "DevelopersIO Mkdocs Site."


## Contents Navigation
nav:

- はじめに:
    - はじめに: index.md
    - 環境設定: settings.md
- 概要:
    - DevelopersIOについて: overview/overview.md
- ジョインブログ執筆:
    - ログイン: join-blog-flow/login.md
    - アカウントの確認と設定: join-blog-flow/account.md
    - ジョインブログに書く内容: join-blog-flow/topics.md
    - 記法: join-blog-flow/notation.md
    - 執筆フロー: join-blog-flow/writing-flow.md

theme:
  name: material
  features:
    - navigation.instant     ## mkdocs for MaterialのSPA対応
    - navigation.tabs        ## トップレベル項目を画面上部メニューにタブ表示
    ##- navigation.sections  ## 項目のセクション表示 
    ##- navigation.expand    ## 初期表示で全てのページ展開を有効化
    - navigation.top       ## ページTOP遷移ボタンを有効化
    - toc.integrate        ## 画面左右のメニューを統

ちなみに紹介されている機能の中には「Insiders only」という記載のあるものも幾つかありました。今回のエントリでは紹介していません。

これに関しては、どうやらスポンサーシップ登録・連携を行うことで優先的に利用可能になるもののようです。内容的に興味深いものも幾つかありますが、(興味のある方はこちらのスポンサーシップ提携、試してみてはいかがでしょうか)

まとめ

という訳で、プロジェクトドキュメント構築向け静的サイトジェネレータ「Material for MkDocs」の設定カスタマイズ「ナビゲーション編」に関する検証内容の紹介でした。引き続き色々な設定を試してみたいと思います。

• MkDocs の記事一覧 | DevelopersIO