目次
はじめに
本書を手に取ってくださり、ありがとうございます。本書は静的サイトジェネレータMkDocsの入門書として書かれました。さまざまなドキュメントや個人的なウェブサイトの構築などの用途で、静的サイトジェネレータは広く使われています。静的サイトジェネレータの有名どころとしてはHugoやGatsby、Jekyllなどがありますが、MkDocsもまた、選択肢のひとつとなるでしょう。
MkDocsは、Markdownをソースとしてコンテンツを生成する静的サイトジェネレータです。MkDocsでは、拡張機能やプラグインを利用することで、純粋なMarkdownを超えた豊かな表現を行えます。
しかし、MkDocsについて、日本語で体系的にまとめられた文献はあまりありません。特に、書籍の形でまとめられているものは言語を問わず、ほぼ存在しません。
本文中でも具体的な例を示しますが、MkDocsは多くのOSSのドキュメント作成に使われています。本書を通して、ドキュメントサイトや簡単なウェブサイトを構築するにあたって、MkDocsがその選択肢となる一助となれば幸いです。
対象読者
本書は、主に次のような方を対象としています。
・静的サイトジェネレータに興味のある人
・MarkdownをベースにドキュメントやマニュアルのWebサイトを構築したい人
・OSSで使われているようなドキュメントを作成したい人
MkDocsは、Pythonベースの静的サイトジェネレータです。本書ではPython、並びにMarkdownに関する基本的な内容については、詳しく解説しません。これらについて馴染みのない方は、必要に応じて適宜検索等を用いて対応していただく必要があります。
本書の読み方
本書は全9章で構成されています。ハンズオンを交えて順序立てて解説を行っているので、MkDocsをはじめて使う方は、第1章から順番に読み進めてください。
第1章では、MkDocsの特徴や実際の利用例について、OSSドキュメントでの例を交えて紹介し、MkDocsを通してどのようなことができるのかを紹介します。
第2章では、クイックスタートとしてMkDocs CLIのコマンドの利用方法を通して、ドキュメントを作り始める手順について解説します。
第3章では、MkDocsで作成する静的サイトの設定を記述する設定ファイルmkdocs.ymlの主要な設定値について紹介します。本章は設定項目についてのリファレンスとしても活用いただけます。第4章ではハンズオンとして、ここまで説明した内容を用いて簡単なドキュメントサイトを作成します。
第5章、第6章では、MkDocsの拡張機能・プラグインの利用方法を紹介するとともに、便利な拡張機能・プラグイン・テーマについて紹介します。第7章ではハンズオンとして、コミュニティ製のプラグインやテーマを用いて、ブログサイトを作成します。
第8章、第9章では、MkDocsで作成したサイトをインターネット上に公開する方法をGitHub Pages、Netlifyでの例を通して紹介します。
動作確認バージョン
本書の執筆には、それぞれ次のバージョンを使用しました。
・Python: 3.13.1
・MkDocs: 1.6.1
表記関係について
本書に記載されている会社名、製品名などは、一般に各社の登録商標または商標、商品名です。会社名、製品名については、本文中では©、®、™マークなどは表示していません。
免責事項
本書に記載された内容は、情報の提供のみを目的としています。本書を用いた開発、製作、運用は、必ずご自身の責任と判断によって行ってください。これらの情報による開発、製作、運用の結果について、著者はいかなる責任も負いません。
底本について
本書は、同人誌即売会「技術書典」並びに「コミックマーケット」にて頒布されたものを底本としています。
第1章 MkDocsとは
MkDocs（https://www.mkdocs.org/）は、Python製の静的サイトジェネレータです。2014年から開発が続けられており、2025年現在もメンテナンスされているプロジェクトです。本章では、MkDocsの概要として、その特徴やOSSでの利用例を紹介します。
1.1 MkDocsの特徴
MkDocsの主な特徴としては、次の点が挙げられます。
・Markdownをベースにサイトを生成できる
─ドキュメントソースの可読性が高い
─開発ドキュメントはMarkdownで書かれることが多いため、READMEなどの既存のドキュメントから移行しやすい
─新規に利用を開始する場合でもキャッチアップコストが低い
・Python-Markdown拡張やMkDocsプラグインを利用し、機能を拡張できる
─拡張を通して、本来のMarkdown以上に多彩な表現が可能
─コミュニティ製のプラグインやテーマを通して、リッチなサイトデザインや便利な機能を手軽に利用できる
・MkDocs CLIのWebサーバー機能によって、リアルタイムプレビューが可能
─ローカル環境で手軽に実際のサイトの生成結果を確認しながらドキュメントを書ける
・YAMLファイルでサイトの設定を記述でき、管理がしやすい
─基本的には1つのサイトに1つのYAMLファイルが対応している
─ファイルを分けることで開発環境と本番環境など、複数の環境にも対応できる
1.1.1 なぜMkDocsか
静的サイトジェネレータとしては、JekyllやHugoがユーザーも多く人気です。MkDocsはこれらの静的サイトジェネレータに比べて、そのシンプルさが特徴です。JekyllやHugoもまた非常に多くの機能を備えており、実際MkDocsよりも多くのことができますが、その分、設定や構築が複雑になりがちです。MkDocsは、シンプルな設定で手軽にサイトを構築でき、コンテンツの記述に注力しやすいため、OSSのドキュメントやツールのマニュアルといった、比較的構成がシンプルなサイトの構築に向いています。
1.2 OSSでの利用例
MkDocsは、OSSのドキュメントでもしばしば利用されています。ここでは、そのいくつかの例を紹介します。
1.2.1 MkDocsでの例
MkDocsの公式ドキュメント1は、MkDocsで作成されています。このドキュメントは、MkDocs本体にあらかじめ含まれているmkdocsテーマを使用して作成されています。サイトの設定ファイルも他の例に比べてシンプルなので、実際のサイトがどのように作られているかを知る際に参考にしやすいでしょう。サイトのソースコードは、https://github.com/mkdocs/mkdocsから確認できます。
1.2.2 Django REST frameworkでの例
Django REST frameworkのドキュメント2は、MkDocsで作成されています。こちらもビルトインのmkdocsテーマから作成されていますが、MkDocsのドキュメントとは色などのデザインが異なります。後に紹介しますが、MkDocsは既存のテーマを任意のhtmlファイルやcssファイルでオーバーライドする機能が備わっています。Django REST frameworkのドキュメントでは、この機能を使って既存のテーマのデザインを変更しています。本書は入門書として位置づけているため、本書ではテーマのオーバーライドは設定方法の説明にとどめ、具体的なオーバーライドの方法などの詳しい説明はしませんが、このソースコードはhttps://github.com/encode/django-rest-frameworkから見ることができます。リポジトリのdocs_theme/フォルダー配下にオーバーライド用のファイルが格納されていますので、興味がある方は確認してみてもよいでしょう。
1.2.3 Trivyでの例
これまで紹介したものとは異なる、コミュニティ製のテーマの使用例を紹介します。脆弱性スキャンツールTrivy3のドキュメントです。
Trivyのドキュメントでは、コミュニティ製のテーマであるMaterial for MkDocsを採用しています。本書でも後に説明しますが、Material for MkDocsはもっとも人気のあるコミュニティ製のテーマのひとつです。マテリアルデザインをベースとしたテーマで、Trivy以外にもRenovate4やArgo Workflows5など、多くのOSSドキュメントで採用されています。
