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

運営者による日本語サンプルを GitHub によるソース付で公開しています。

🎈 mkdocs.balloon.net.eu.org
🎈 GitHub fu-sen/mkdocs.balloon.net.eu.org - ソース

目次

公式サイト

•  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

pip を動作させるようにするため、PATH の追加が必要です。
Windows 10 の場合、 + Pause|Break で「設定 - 詳細情報」を表示し、
システムの詳細設定 を選ぶと「システムのプロパティ」が開きます。
環境変数… を選び、「ユーザー環境変数」の Path を選び、新規 で追加します。

pip install mkdocs

ただし、Python の更新で mkdocs がエラーになります。
Python の更新後、 pip および mkdocs などを再インストールします。

python -m pip install --upgrade --force-reinstall pip
pip install --upgrade --force-reinstall mkdocs

MkDocs の更新

次のコマンドで MkDocs を更新します。

pip install -U mkdocs

mkdocs や mkdocs --version で更新された事を確認して下さい。

新規サイトの作成

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

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
 mkdocs themes 検索結果 | GitHub

多くの場合は pip でインストールします。

pip install mkdocs-bootswatch

一部テーマは pip パッケージに含めていない場合があります。
GitHub の README.md などにインストール方法が記載されています。

環境によってが Python を更新した後、再度インストールが必要な場合があります。

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

theme:
    name: yeti

日本語ページの場合、または日本語と英語のページであれば、
MkDocs 1.2 より日本語検索に対応しているため、
locale: ja を加えて下さい。

theme:
    name: yeti
    locale: ja

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 です。
テーマ独自でのカスタマイズが豊富な事など、特徴があります。
日本語で解説しているサイトがあるので、ここでは現在のところ触れていません。

Kilsbergen

 ruuda/kilsbergen | GitHub

なんとテーマ構成ファイルは main.html のみです。
リポジトリを kilsbergen フォルダとして MkDocs フォルダに入れ、
mkdocs.yml では custom_dir で場所を指定します。

theme:
  name: null
  custom_dir: kilsbergen/

検索フォーム

MkDocs 1.2 より Material 以外のテーマでも日本語検索に対応しています。

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

Pull request が入り、改修の上で merge された事で、動作可能になりました。

日本語検索に対応させるために、theme: 内で locale: ja を指定して下さい。

theme:
    name: yeti
    locale: ja

Material for MkDocs

Material for MkDocs は検索フォームが独自対応されているため、
MkDocs 1.1 系以前でも正常に動作します。

検索フォームを削除する

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

plugins: []

ページの生成

通常は 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

Git のコミットになるので、コミットメッセージを入れておくと良いでしょう。

mkdocs gh-deploy -m "コミットメッセージ"

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

mkdocs gh-deploy -b 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 で自動的にデプロイされます。

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

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

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

 kubilus1/mkdocs-paginate-plugin | GitHub

ページを一覧表示するプラグインも開発されています。
対応テーマが増えると、まともにブログ用途で MkDocs を使えるようになります。

これについては短期間で進捗がありますので、
GitHub 内を探してみると良いかもしれません。

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

 byrnereese/mkdocs-minify-plugin | GitHub

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