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

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

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

目次

• 初期環境設定とコンテンツの準備
• 「Material for MkDocs」で利用可能な主な設定
  • ヘッダー部分の表示を隠す
  • ヘッダー上部の「アナウンスバー」をカスタマイズ
• mkdocs.ymlテンプレートファイル(設定追記済)
• まとめ

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

初期環境設定とコンテンツの準備については、下記エントリの同見出し部分の内容をご参照ください。

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

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

ここからは、下記ドキュメントの内容のものを検証してみます。

• Setting up the header - Material for MkDocs

ヘッダー部分の表示を隠す

この値を有効にしていると、ユーザーが画面を(縦)スクロールさせた際に一定のしきい値を超えたタイミングで自動でヘッダー部分が非表示となります。

theme:
  features:
    - header.autohide

設定が有効となっていない場合はページのコンテンツ最下部に行ってもヘッダー部分は表示されたままですが、

上記設定を追加した場合、途中からこの様にヘッダー部分が表示されなくなってきます。

ヘッダー上部の「アナウンスバー」をカスタマイズ

Material for MkDocsでは、プロジェクトのニュースやその他重要な情報をユーザーに表示するのに最適な場所として「アナウンスバー」を活用することが出来ます。この部分は画面スクロール時には消える挙動となります。

アナウンスバーを追加するには幾つかの手順が必要です。まずはmkdocs.ymlにcustom_dir: overridesの行を追加。

• Customization - Material for MkDocs

theme:
  name: material
  custom_dir: overrides

overrirdesフォルダ及びmain.htmlファイルを下記構成で追加。

├── docs
:
:
├── mkdocs.yml
└── overrides
    └── main.html

作成したmain.htmlの内容を以下の形で記載します。ちなみにここで紹介した手法の他にも「Overriding partials」というものがあるのですが、公式的にはここで紹介した「Overriding blocks」に倣う形で進めています。

• Overriding blocks / Customization - Material for MkDocs

overrides/main.html

{% extends "base.html" %}

{% block announce %}
  <strong><img src="https://www.google.com/s2/favicons?domain=dev.classmethod.jp" /> DevelopersIO</strong> はクラスメソッド株式会社が運営しています。 
{% endblock %}

上記設定が完了したらページをリロード。すると以下のようにヘッダー部分に表示エリアが現れ、記載した文言が表示されるようになりました。

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

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

注)設定内容は下記エントリの内容を経たものとなっています。

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

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      # Material for MkDocsを利用
  custom_dir: overrides      ## 設定ファイルを上書き

  features:
    #---- 各種機能カスタマイズ(ナビゲーション関連)
    - navigation.instant     ## mkdocs for MaterialのSPA対応
    - navigation.tabs        ## トップレベル項目を画面上部メニューにタブ表示
    ##- navigation.sections  ## 項目のセクション表示 
    ##- navigation.expand    ## 初期表示で全てのページ展開を有効化
    - navigation.top         ## ページTOP遷移ボタンを有効化
    - toc.integrate          ## 画面左右のメニューを統合

    #---- 各種機能カスタマイズ(ヘッダー関連)
    - header.autohide        ## ヘッダー部分を一定量スクロールしたら隠すようにする


  palette:            # 色に関する設定
    #---- 基本的な色設定 ----
    scheme: default      ## カラースキーム設定(default:ライトモード、slate:ダークモード)
    ##primary: orange  ## プライマリーカラー設定(ヘッダー背景色、サイドバー背景色、テキストリンク等)
    ##accent: green    ## アクセントカラー設定(ホバーされたリンクやボタン、スクロールバー等)

    #---- カラースキーム切替設定 ----
    ##- scheme: default   ## カラースキーム切替設定(ライトモード時)
    ##  primary: yellow
    ##  accent: red
    ##  toggle:
    ##    icon: material/weather-sunny
    ##    name: Switch to dark mode
    ##- scheme: slate     ## カラースキーム切替設定(ダークモード時)
    ##  primary: cyan
    ##  accent: light green
    ##  toggle:
    ##    icon: material/weather-night
    ##    name: Switch to light mode



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

まとめ

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

• MkDocs の記事一覧 | DevelopersIO