静的サイトジェネレータ MkDocs についてまとめています。

---

目次

---

公式サイト

•  Mkdocs
•  GitHub mkdocs
  •  Wiki
  •  Discussions

コミュニティは Google グループ が使われていましたが、
2021年3月より GitHub Discussions に移行しています。

---

インストール

Mkdocs は Python で作られています。
インストールされていなければ Python をインストールします。
Python をインストールすると pip が使えるようになるので、
これで mkdocs をインストールします。

pip install mkdocs

mkdocs や mkdocs --version でインストールを確認して下さい。

Scoop を用いた Python 経由のインストール

Windows で 🎈 Scoop を使用している場合は
次のコマンドで Python をインストールできます。

scoop install python

 Updating Python cause PIP Packages Removed! #2180 | GitHub lukesampson/scoop issues

しかし Scoop では普通に pip パッケージをインストールすると、
Scoop フォルダ内の Python パッケージ内に作成してしまうため、
Python の更新で pip パッケージを失ってしまいます。
そこで pip install に --user を付けて、
Windows のユーザーフォルダ下にインストールするようにします。

pip install --user mkdocs

これにより Python 3.9 系の場合、ユーザー フォルダ 内の
AppData\Roaming\Python\Python39\Scripts\ に実行ファイルが入ります。
（半角 ＼ ＝ 半角 ￥ 。日本語の Windows に限り ￥ です）
この Scripts フォルダを PATH に加えます。具体的には次の操作です。

ただし、これでも Python の更新で mkdocs がエラーになります。
Python の更新後、 mkdocs も再インストールして下さい。

pip uninstall mkdocs
pip install --no-cache-dir --user mkdocs

テーマパッケージは Python のミラーアップデートであれば更新せずに動作します。

---

新規サイトの作成

次のコマンドで新規サイトのファイルを生成します。

mkdocs new フォルダ

フォルダは . で現在居るフォルダ（カレントフォルダ）を指定する事もできます。

---

動作確認

動作確認しながらのサイト構築がおすすめです。次をコマンド実行して下さい。

mkdocs serve

Web ブラウザより http://127.0.0.1:8000/ で参照できます。
そのまま構成ファイルを編集し保存すると、Web サイトが自動更新されます。
わざわざ Web ブラウザの更新を押す必要はありません。

---

mkdocs.yml

 Configuration | MkDocs

サイト全体の設定は mkdocs.yml で行います。
通常使用するのは次の項目でしょう。

更に次の項目があります。必要に応じて追加して下さい。

他にも項目が存在します。公式サイトを参照して下さい。

---

テーマ

 Wiki - MkDocs Themes | mkdocs/mkdocs

デフォルトでは Mkdocs のテーマが適用されています。
公式 GitHub プロジェクトの Wiki で一部紹介されていますが、
実際には豊富にテーマが存在しています。

 mkdocs.themes | Wheelodex

左側が pip のパッケージ名ですので、pip でインストールします。

pip install mkdocs-bootswatch

Python を Scoop でインストールしている場合は --user を必ず付けて下さい。

pip install --user mkdocs-bootswatch

`mkdocs.yml に使用するテーマを指定します。

theme:
    name: yeti

pip に含まれていない場合はそのテーマを公開しているところ
（通常 GitHub プロジェクト）に導入方法が記載されていますので、
その記載に合わせてテーマをインストールして下さい。

mkdocs・readthedocs

 Styling your docs | MkDocs

MkDocs に標準で含まれているテーマです。
pip でのインストールする事なく、テーマを指定できます。

mkdocs-bootswatch

 mkdocs/mkdocs-bootswatch | GitHub

Bootswatch 公開の Bootstrap テーマです。

 Bootswatch

mkdocs テーマを継承しているため、mkdocs と同じレイアウトになります。

Material for MkDocs

 Material for MkDocs

Mkdocs を検索した時、多く紹介されているのが Material です。
テーマ独自でのカスタマイズが豊富な事と、
日本語を含める英語以外の検索を独自に完全対応させている特徴があります。
日本語で解説しているサイトがあるので、ここでは現在のところ触れていません。

---

検索フォームを削除する

Material 以外のテーマでは現在のところ英語以外の検索が結果として表示できません。
そこで検索フォームを削除する事で、この問題を回避して、
他のテーマも使えるようにします。

Mkdocs はプラグインとしてデフォルトで search を読み込んでいます。
これを削除する事で、検索フォームを非表示にする事ができます。
他に読み込む plugin がない場合、 mkdocs.yml を次の表記にします。

plugins: []

MkDocs の日本語検索対応

 Fix an error when the lang of node prebuild_index is ja or jp. #2178 | GitHub mkdocs/mkdocs Pull request

日本語関連の検索は Pull request が入り、改修の上で merge されました。
後に公開される Mkdocs 1.2 で日本語検索が改善されます。

---

ページの生成

通常は docs/ 内に .md ファイルを加えていきます。
これがビルドされて .html ファイルとなります。
他のファイルは docs/ 内に置く事で、そのまま公開されます。

.md ファイル

index は index.md で index.html を生成しますが、
ない場合は代わりに README.md を参照し生成します。

自動的にメニューへ追加されていきますが、ABC 順になります。
mkdocs.yml で nav を用いて、メニューを指定できます。

nav:
    - index.md
    - mogmog.md

インテントを付けて、下層も生成できます。
また、ここにタイトルを付与する事もできます。

nav:
    - ホーム: 'index.md'
    - 'もぐもぐ':
        - 'もぐもぐとは？': 'whats-mogmog.md'
        - 'もぐもぐの使い方': 'uses-momog.md'
    - 'もぐもぐについて':
        - 'ライセンス': 'license.md'
        - '履歴': 'release-notes.md'

MkDocs では Makedown の本文をいきなり開始しても問題ありませんが、
他の静的サイトジェネータのように Front Matter を使用することもできます。
ただし mkdocs.yml の nav でタイトルがある場合は、 nav が優先されます。
どちらもない場合は Markdown の # （HTML の <h1>）をタイトルに使用し、
これもなければ、ファイル名を元にタイトルを決めます。

---
title: もぐもぐについて
---

**(・～・)mog?** ←ここから本文

テーマにより、具体的な Front Matter の項目が存在している場合があります。

Favicon アイコン

mkdocs や mkdocs-bootswatch などのテーマでは
docs/ の ime/ 内に favicon.ico を入れます。
他のところに favicon.ico を入れる場合、
mkdocs.yml の項目 site_favicon で場所を指定する事が可能です。

テーマにより実装が異なり、他にも必要とする場合や
mkdocs.yml の項目として設定する場合があります。

他のファイル

docs 内の .md ファイルはビルド動作で .html ファイルへ変換されますが、
他のファイルはその構成のままコピーされます。
画像グァイル、.css .js ファイル、robots.txt などは
docs/ 内に、必要に応じて更にフォルダ・ディレクトリを作成して入れて下さい。

mkdocs build で生成される site/ 内に入れた場合、
Web サービスによっては出力先が異なったり、ビルド前に消去したりするため、
そのファイルが出力されなくなる可能性があるため、
ビルド先の site/ などに入れる事はおすすめしません。

カスタム CSS を適用する

mkdocs.yml に次を追加します。
ここでは css/custom.css が追加する CSS とした場合次となります。
URL を含める事もできます。

extra_css:
    - css/custom.css

テーマのカスタマイズ

mkdocs.yml の theme 下層に custom_dir を設定します。
通常 name を設定しているので、その下に入れる事になります。

theme:
    name: mkdocs
    custom_dir: custom/

mkdocs.yml があるところに設定した値のフォルダを生成します。
ここでは custom/ です。この下層で生成された内容はテーマを上書きできます。

下は custom/main.html で次を追加する事で
🎈 Open Graph protocal と Twitter Card を追加します。
説明・画像は Front Matter に description・image があればその画像、
画像がなければ img/ogp.png です。

{% extends "base.html" %}
{% block extrahead %}
  {% set title = config.site_name %}
  {% if page and page.title and not page.is_homepage %}
    {% set title = page.title ~ " - " ~ config.site_name | striptags %}
  {% endif %}
  {% set description = config.site_description %}
  {% if page and page.meta.description %}
    {% set description = page.meta.description %}
  {% endif %}
  {% set image = config.site_url ~ 'img/ogp.png' %}
  {% if page and page.meta.image %}
    {% set image = config.site_url ~ page.meta.image %}
  {% endif %}
  <meta property="og:type" content="website">
  <meta name="twitter:card" content="summary_large_image">
  <meta property="og:title" content="{{ title }}">
  <meta name="twitter:title" content="{{ title }}">
  <meta property="og:description" content="{{ description }}">
  <meta name="twitter:description" content="{{ description }}">
  <meta property="og:image" content="{{ image }}">
  <meta name="twitter:image" content="{{ image }}">
  <meta property="og:url" content="{{ page.canonical_url }}">
{% endblock %}

テーマによっては {% block extrahead %} を定義していない場合があるため、
その場合は代用できる部分をテーマの base.html を参照して探して下さい。

---

ビルド

次のコマンドで HTML ファイルを生成します。デフォルトは site フォルダ内です。

mkdocs build

---

Web サービスで使用する

 Mkdocs Deployments | GitHub mkdocs/mkdocs Wiki

ここに紹介している以外にも
MkDocs を容易にビルド・デプロイできる Web サービスがあります。

GitHub Pages

 GitHub Pages
 GitHub Pages について | GitHub ヘルプ
🎈 GitHub Pages | ふうせん🎈 FU-SEN

 Deploying your docs | Mkdocs\

Mkdocs ではコマンドで簡単に GitHub Pages へ公開できます。
デフォルトでは gh-pages ブランチになります。

mkdocs gh-deploy

main ブランチを使用している場合は次となります。

mkdocs gh-deploy --remote-branch main

Cloudflare Pages

 Cloudflare Pages
 Pages - Build configuration | Cloudflare Docs
🎈 Cloudflare Pages | ふうせん🎈 FU-SEN

ビルド構成のフレームワーク プリセットとして Mkdocs が含まれていますが、
まともに使用するには、テーマやプラグインを
pip パッケージからダウンロードする必要があるため、現状では記載不足です。
そこで、最小限のプロジェクトをページ運営者が公開しています。

🎈  fu-sen/CloudflarePages-MkDocs | GitHub

Cloudflare Pages で動作するために追加が必要なのは
requirements.txt および runtime.txt です。
requirements.txt にテーマ・プラグインの pip パッケージを追加して下さい。

Cloudflare Pages は GitHub 連動必須なので、
まず GitHub に git push しておきます。プロジェクトは Private でも使用可能です。

 Cloudflare へログインし、ページ を選択した後、
プロジェクトを作成 を選び、GitHub プロジェクト を選択します。
「ビルドとデプロイをセットアップ」で次を入力・選択します。

保存してデプロイする を選択します。
1 分ほど待った後、デプロイが完了し、公開されます。

その後は GitHub プロジェクトへのコミット git push で自動的にデプロイされます。

DOM Cloud Hosting

 DOM Cloud Hosting
🎈 DOM Cloud Hosting | ふうせん🎈 FU-SEN

テンプレート機能を用いて .zip または Git リポジトリからの git clone で展開し、
ビルドはサーバ側で行う事が可能です。

最小限のプロジェクトをページ運営者が公開しています。

🎈  fu-sen/DOMCloud-MkDocs | GitHub

source: .zip ファイルの URL または .git リポジトリ
directory: 展開するディレクトリ
root: public_html/site
nginx:
  ssl: enforce
  error_pages:
  - 404 /404.html
commands:
- pip install --user -r requirements.txt
- mkdocs build

Vercel

▲ Vercel
🎈 Vercel | ふうせん🎈 FU-SEN

Vercel の公式としては用意されていませんが、簡単に MkDocs を動作できます。
最小限のプロジェクトをページ運営者が公開しています。

🎈  fu-sen/Vercel-MkDocs | GitHub

Vercel で動作するために追加が必要なのは package.json と requirements.txt です。
requirements.txt にテーマ・プラグインの pip パッケージを追加して下さい。

はじめてのビルド・デプロイで、初期状態から設定を変更する必要はありません。

vercel dev でローカル動作できますが、 yarn が必要です。
Windows の場合 🎈 Scoop に含まれています。

scoop install yarn

vercel で仮の URL でデプロイ、vercel --prod で公開となります。
代わりに GitHub・GitLab・BitBucket と連携し git push でデプロイも可能です。

---

Q&A

Sitemap は生成されますか？

自動的に sitemap.xml と sitemap.xml.gz が生成されます。

mkdocs.yml の site_url を必要としますので、忘れずに入れて下さい。

Not Found ページは生成されますか？

 mkdocs/themes/mkdocs/404.html | GitHub mkdocs/mkdocs

多くのテーマで 404.html を生成しています。
404.html を表示するようになっていれば、正常に表示されます。

この 404.html を改修したい場合は、
 テーマのカスタマイズ の方法で 404.html を上書きして下さい。

ページの目次は削除できますか？

 MkDocs Recipes  Remove the “Table of Contents” sidebar from the mkdocs theme. | GitHub mkdocs/mkdocs Wiki

公式 Wiki では  テーマのカスタマイズ の方法を用いて
{% block content %} 内を content.html のみにする事で削除する方法が紹介されています。

フッターの表示は変更できますか？

mkdocs および mkdocs-bootswatch は次になっています。

        <footer class="col-md-12">
          {%- block footer %}
            <hr>
            {%- if config.copyright %}
                <p>{{ config.copyright }}</p>
            {%- endif %}
            <p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p>
          {%- endblock %}
        </footer>

mkdocs.yml の copyright で記載した内容がそのまま追加されますが、
下の部分も変更したい場合は  テーマのカスタマイズ の方法で
{% block footer %} ～ {% endblock %} を作成し、上書きして下さい。

サイドバーに任意の表示を行えますか？

 midnightprioriem/mkdocs-toc-sidebar-plugin | GitHub

そのためのプラグインが存在しています。
 テーマのカスタマイズ にある方法を用いて追加して下さい。

ブログを作る事はできますか？

 fmaida/mkdocs-blog-plugin | GitHub
 andyoakley/mkdocs-blog | GitHub

ブログ構成を実現するプラグインが存在しています。

このプラグインを使わず、記事として通常のページを追加して、
一覧は手でリンクを追加しているようにしているケースも見られます。

空白などをなくす処理はできますか？

 byrnereese/mkdocs-minify-plugin | GitHub

Minify と言われます。プラグインが存在します。