Material for MkDocsのタイトルテキストをリンクテキストにする

たかやま

2023.10.24

こんにちは。たかやまです。

Material for Mkdocsではヘッダーにサイトアイコンとタイトルテキストを表示することができます。こちらのアイコンとテキストですが、トップページリンクとして機能するのはアイコンのみで、タイトルテキストはリンクになっていません。

直感的にはタイトルテキストからもトップページに戻りたいと思っています。

今回はこちらのMaterial for Mkdocsのタイトルテキストをトップページリンクにする方法を紹介します。

さきにまとめ

CustomizationのOverriding partialsを利用し、元のheader.htmlのタイトルテキスト部分にリンクを付与する

Customization - Material for MkDocs

やってみる

検証環境

以下の手順に沿って環境を用意します。

# (必要に応じて)仮想環境作成
python3 -m venv .venv && source .venv/bin/activat

# Material for Mkdocs環境作成
pip3 install mkdocs-material
mkdocs new .
echo -e "\ntheme:\n  name: material" >> mkdocs.yml
mkdocs serve

mkdocs serveを実行するとlocalhost:8000でサイトが表示されます。

ヘッダーカスタマイズ

検証環境作成段階でのディレクトリ構成は以下のようになっています。

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

では、ここからヘッダーのタイトルテキストへ設定を行っていきます。
Material for Mkdocsではネイティブにタイトルテキストへのリンク機能はサポートされていないためカスタマイズが必要になります。

Material for MkdocsではカスタマイズとしてCSSやJavaScript,利用しているテーマの拡張を行うことができます。

Customization - Material for MkDocs

今回はテーマで利用されているヘッダー部分を上書きする処理を行います。

まずは、上書きするテーマを配置するoverrides/partialsディレクトリを作成し、ディレクトリ配下にMaterial for Mkdocsのテーマで利用されているheader.htmlを配置します。

.
├─ docs/
│  └─ index.md
├── overrides/
│   └── partials/
│       └── header.html
└─ mkdocs.yml

ブログ執筆時点(2023/10/24)ではMaterial for Mkdocsの以下のパスからheader.htmlを確認することができます。

mkdocs-material/src/templates/partials/header.html at master - squidfunk/mkdocs-material

header.html(クリックで展開) 
<!--
  Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to
  deal in the Software without restriction, including without limitation the
  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  sell copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  IN THE SOFTWARE.
-->

<!-- Determine classes -->
{% set class = "md-header" %}
{% if "navigation.tabs.sticky" in features %}
  {% set class = class ~ " md-header--shadow md-header--lifted" %}
{% elif "navigation.tabs" not in features %}
  {% set class = class ~ " md-header--shadow" %}
{% endif %}

<!-- Header -->
<header class="{{ class }}" data-md-component="header">
  <nav
    class="md-header__inner md-grid"
    aria-label="{{ lang.t('header') }}"
  >

    <!-- Link to home -->
    <a
      href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
      title="{{ config.site_name | e }}"
      class="md-header__button md-logo"
      aria-label="{{ config.site_name }}"
      data-md-component="logo"
    >
      {% include "partials/logo.html" %}
    </a>

    <!-- Button to open drawer -->
    <label class="md-header__button md-icon" for="__drawer">
      {% set icon = config.theme.icon.menu or "material/menu" %}
      {% include ".icons/" ~ icon ~ ".svg" %}
    </label>

    <!-- Header title -->
    <div class="md-header__title" data-md-component="header-title">
      <div class="md-header__ellipsis">
        <div class="md-header__topic">
          <span class="md-ellipsis">
            {{ config.site_name }}
          </span>
        </div>
        <div class="md-header__topic" data-md-component="header-topic">
          <span class="md-ellipsis">
            {% if page.meta and page.meta.title %}
              {{ page.meta.title }}
            {% else %}
              {{ page.title }}
            {% endif %}
          </span>
        </div>
      </div>
    </div>

    <!-- Color palette toggle -->
    {% if config.theme.palette %}
      {% if not config.theme.palette is mapping %}
        {% include "partials/palette.html" %}
      {% endif %}
    {% endif %}

    <!-- Site language selector -->
    {% if config.extra.alternate %}
      {% include "partials/alternate.html" %}
    {% endif %}

    <!-- Button to open search modal -->
    {% if "material/search" in config.plugins %}
      <label class="md-header__button md-icon" for="__search">
        {% set icon = config.theme.icon.search or "material/magnify" %}
        {% include ".icons/" ~ icon ~ ".svg" %}
      </label>

      <!-- Search interface -->
      {% include "partials/search.html" %}
    {% endif %}

    <!-- Repository information -->
    {% if config.repo_url %}
      <div class="md-header__source">
        {% include "partials/source.html" %}
      </div>
    {% endif %}
  </nav>

  <!-- Navigation tabs (sticky) -->
  {% if "navigation.tabs.sticky" in features %}
    {% if "navigation.tabs" in features %}
      {% include "partials/tabs.html" %}
    {% endif %}
  {% endif %}
</header>

次に配置したheader.htmlを編集していきます。

以下のように、タイトルテキスト部分となる<div class="md-header__topic">に<a>タグを追加し、href属性にトップページのURLを指定するようにします。

@@ -55,11 +55,11 @@
     <!-- Header title -->
     <div class="md-header__title" data-md-component="header-title">
       <div class="md-header__ellipsis">
-        <div class="md-header__topic">
+        <a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" class="md-header__topic">
           <span class="md-ellipsis">
             {{ config.site_name }}
           </span>
-        </div>
+        </a>
         <div class="md-header__topic" data-md-component="header-topic">
           <span class="md-ellipsis">
             {% if page.meta and page.meta.title %}
修正後のheaser.html(クリックで展開) 
<!--
  Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to
  deal in the Software without restriction, including without limitation the
  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  sell copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  IN THE SOFTWARE.
-->

<!-- Determine classes -->
{% set class = "md-header" %}
{% if "navigation.tabs.sticky" in features %}
  {% set class = class ~ " md-header--shadow md-header--lifted" %}
{% elif "navigation.tabs" not in features %}
  {% set class = class ~ " md-header--shadow" %}
{% endif %}

<!-- Header -->
<header class="{{ class }}" data-md-component="header">
  <nav
    class="md-header__inner md-grid"
    aria-label="{{ lang.t('header') }}"
  >

    <!-- Link to home -->
    <a
      href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
      title="{{ config.site_name | e }}"
      class="md-header__button md-logo"
      aria-label="{{ config.site_name }}"
      data-md-component="logo"
    >
      {% include "partials/logo.html" %}
    </a>

    <!-- Button to open drawer -->
    <label class="md-header__button md-icon" for="__drawer">
      {% set icon = config.theme.icon.menu or "material/menu" %}
      {% include ".icons/" ~ icon ~ ".svg" %}
    </label>

    <!-- Header title -->
    <div class="md-header__title" data-md-component="header-title">
      <div class="md-header__ellipsis">
        <a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" class="md-header__topic">
          <span class="md-ellipsis">
            {{ config.site_name }}
          </span>
        </a>
        <div class="md-header__topic" data-md-component="header-topic">
          <span class="md-ellipsis">
            {% if page.meta and page.meta.title %}
              {{ page.meta.title }}
            {% else %}
              {{ page.title }}
            {% endif %}
          </span>
        </div>
      </div>
    </div>

    <!-- Color palette toggle -->
    {% if config.theme.palette %}
      {% if not config.theme.palette is mapping %}
        {% include "partials/palette.html" %}
      {% endif %}
    {% endif %}

    <!-- Site language selector -->
    {% if config.extra.alternate %}
      {% include "partials/alternate.html" %}
    {% endif %}

    <!-- Button to open search modal -->
    {% if "material/search" in config.plugins %}
      <label class="md-header__button md-icon" for="__search">
        {% set icon = config.theme.icon.search or "material/magnify" %}
        {% include ".icons/" ~ icon ~ ".svg" %}
      </label>

      <!-- Search interface -->
      {% include "partials/search.html" %}
    {% endif %}

    <!-- Repository information -->
    {% if config.repo_url %}
      <div class="md-header__source">
        {% include "partials/source.html" %}
      </div>
    {% endif %}
  </nav>

  <!-- Navigation tabs (sticky) -->
  {% if "navigation.tabs.sticky" in features %}
    {% if "navigation.tabs" in features %}
      {% include "partials/tabs.html" %}
    {% endif %}
  {% endif %}
</header>

最後に、カスタマイズ機能を有効にするためにmkdocs.ymlに以下の設定を追加します。

site_name: My Docs

theme:
  name: material
  custom_dir: overrides

動作確認

カスタマイズができたら、mkdocs serveを実行して動作確認を行います。

タイトルテキストにhref属性がつきトップページに戻ることができれば設定完了です。

最後に

今回はMaterial for Mkdocsのタイトルテキストをトップページリンクにする方法を紹介しました。

テーマでネイティブにサポートされていない機能についても、カスタマイズ機能を利用することで実現することができます。

こちらの記事が同様の悩みを持っている方への助けになれば幸いです。

以上、たかやま(@nyan_kotaroo)でした。

AWS

関連記事

Material for MkdocsにCustomizationを使ってサイト分析ツールを導入してみた

たかやま

2023.10.30

ドキュメントの文法(シンタックス)【CCG執筆者向け】

川原征大

2023.09.11

「Classmethod Cloud Guidebookの裏側」というビデオセッションで話しました #devio2023

たかやま

2023.08.02

DevelopersIO 2023 大阪 – 勉強会「S3 + MkDocs でナレッジサイトをお手軽に構築・運用する話」 #devio2023

川原征大

2023.07.19