公開2024.09.27更新2026.10.25 21 人が閲覧（直近 30 日）開発

MkDocsとは？使い方とMaterial for MkDocsの設定・日本語検索・GitHub Pages公開【2026年版】

Q: MkDocsとは無料のツールですか？商用利用はできますか？

MkDocsとは、Markdownからドキュメントサイトを作るPython製の静的サイトジェネレーターで、無料のオープンソースです。MkDocs本体はBSD-2-Clause、Material for MkDocsとZensicalはMITライセンスで、商用を含めて無償で使えます。公開先にGitHub Pagesの無料枠を使えば、ホスティング費用もかかりません。条文は導入時に各リポジトリで確認してください。

Q: MkDocsの代替ツールは何がありますか？

Python系ならSphinx、Node.js/React系ならDocusaurusが代表です。相互参照やAPIドキュメントの自動生成を重視するならSphinx、Reactコンポーネントを埋め込むならDocusaurusが向きます。Material for MkDocsの後継としては、同じ開発チームのZensicalがあり、既存の mkdocs.yml をそのまま読み込めます。

Q: Material for MkDocsはいつまで使えますか？

重大なバグ修正とセキュリティ更新は2027年5月5日まで提供されると公式のchangelogに明記されています。それ以降もインストール済みの版は動き続けますが、新たに見つかった脆弱性は修正されません。長く運用するサイトは、この日付までにZensicalなどへの移行を検討してください。

Q: MkDocs 2.0にアップグレードできますか？

2026年10月時点ではアップグレードできない状態です。2.0は開発版（2.0.dev6）の段階で、 mkdocs.yml があるフォルダでは起動を拒否し、プラグインとMaterialテーマも使えません。 mkdocs-material 経由で入れていれば、依存が mkdocs<2 に固定されているので誤って2.0が入ることはありません。

Q: mkdocs serveとmkdocs buildの違いは何ですか？

mkdocs serve は執筆中のプレビュー用で、開発用サーバーを立ち上げてファイルを保存するたびに再ビルドします。 mkdocs build は公開用で、HTML一式を site フォルダに書き出します。 mkdocs gh-deploy は内部でbuildを実行してから gh-pages ブランチへ反映するので、公開時にbuildを別に打つ必要はありません。

MkDocsとは？使い方とMaterial for MkDocsの設定・日本語検索・GitHub Pages公開【2026年版】

MkDocsとは、Markdownで書いた文書を検索つきの静的なドキュメントサイトに変換するPython製のツールです。使い方の骨格は、pip install mkdocs-materialで入れ、mkdocs new .で雛形を作り、mkdocs serveで書きながら確認し、mkdocs gh-deployでGitHub Pagesへ公開する、の4段階です。この記事では、MkDocsの仕組みとメリット・デメリットを整理したうえで、テーマにMaterial for MkDocsを使い、その設定、日本語の全文検索、GitHub Actionsでの自動公開までを、2026年10月16日に手元で実行した結果つきで説明します。あわせて、Materialが2027年5月5日にサポート終了を迎えること、MkDocs 2.0の開発版と後継のZensicalをどう扱うべきかも整理します。

まとめ：MkDocsとは何かと使い方、Material for MkDocsの要点

MkDocsとは：Markdownの原稿とmkdocs.yml1枚から、HTML・CSS・JavaScriptだけのサイトを書き出す静的サイトジェネレーター。データベースもサーバー側の処理も持たず、生成物を静的ホスティングに置くだけで公開できる。
最短4コマンド：pip install mkdocs-material → mkdocs new . → mkdocs serve → mkdocs gh-deploy。MkDocs本体（1.6.1）は依存として一緒に入る。
設定はmkdocs.yml1枚：theme・nav・plugins・markdown_extensionsを書き足していく。Materialの見た目と機能はtheme.featuresとmarkdown_extensionsで決まる。
日本語検索は2行：searchプラグインのlang: jaで日本語の分割処理が有効になり、theme.language: jaで区切り文字に「、」「。」が加わる。追加ライブラリは不要。
2026年10月時点の前提：Material for MkDocsは9.7系で新機能が止まり、2027年5月5日に保守が終わる。MkDocs 2.0の開発版はmkdocs.ymlを読まず、Materialも動かない。今の構成で書き始め、Zensicalへの移行は自分のプラグイン構成が対応しているかを確かめてから行う。

以降は、MkDocsとは何かを仕組みから確認し、インストールから公開までを順に追い、最後に「今どの組み合わせを選ぶか」を判断材料つきで述べます。

MkDocsとは：Markdownと設定1枚でドキュメントサイトを作るPython製ツール

MkDocsは、公式サイトが「Project documentation with Markdown」と掲げるとおり、プロジェクトのドキュメント作りに的を絞った静的サイトジェネレーターです。原稿はMarkdownで書き、設定はYAML形式の設定ファイル1枚で済ませる、という2点が設計の中心にあります（MkDocs公式サイト）。PyPIで確認できる最も古い公開版は2014年1月21日の0.2で、10年以上続くツールです。2026年10月時点の安定版は1.6.1、要件はPython 3.8以上、ソースはGitHubのmkdocs/mkdocsで公開されています（PyPIのmkdocs）。

静的サイトジェネレーター（SSG）全般の仕組みや、企業サイトにSSGを採用するときの判断基準はSSGとは？静的サイトジェネレーターの仕組みと企業サイト採用の判断基準で扱っています。MkDocsはそのSSGの中でも、ブログや製品サイトではなく、手順書・API仕様・設計資料のような「章立てのある文書」に機能を寄せた位置づけです。

Python-MarkdownとJinja2によるMkDocsの静的HTML生成

MkDocsの処理は、設定の読み込み → Markdownの変換 → テンプレートへの流し込み → ファイル書き出し、の順に進みます。Markdownの変換にはPython-Markdownライブラリを使うと公式ドキュメントに明記されています（MkDocs公式：Writing your docs）。PyPIに登録された1.6.1の依存を見ると、各工程を担う部品が分かります。

工程	担う依存ライブラリ	役割
設定の読み込み	pyyaml	mkdocs.ymlの解析
本文の変換	markdown	MarkdownからHTMLへ
ページの組み立て	jinja2	テーマのテンプレート描画
執筆中の再ビルド	watchdog	ファイル変更の監視
GitHub Pages公開	ghp-import	gh-pagesブランチへの反映

最小のプロジェクトは、設定ファイルとdocsフォルダの組み合わせです。トップページは慣例としてindex.mdにし、同じフォルダにREADME.mdしか無ければそれをトップとして扱います。両方あればindex.mdが優先されます。

my-project/
├── mkdocs.yml        # site_name などの設定
└── docs/
    ├── index.md      # トップページ（index.html になる）
    └── guide/
        └── install.md  # guide/install/index.html になる

プラグインは、このビルドの途中に処理を差し込む仕組みです。mkdocs.plugins.BasePluginを継承したクラスにon_pre_buildのようなイベント名のメソッドを書くと、その時点で呼ばれます（MkDocs公式：Plugins）。Materialの検索や更新日の表示も、この仕組みの上に乗っています。

MkDocsの特徴：組み込みテーマ2種とプラグイン、静的ホスティングでの公開

本体にはmkdocsとreadthedocsの2つのテーマが同梱され、ほかにサードパーティ製のテーマを選べます（MkDocs公式：Choosing your Theme）。本記事で使うMaterial for MkDocsは、そのサードパーティテーマの代表格です。プラグインとテーマの一覧は、MkDocsのGitHub組織が運営するmkdocs/catalogにまとまっています。

公開先も選択肢が広く、公式の公開ガイドはGitHub Pagesに加えてRead the Docsを挙げ、静的ファイルを配信できるホスティングならどこでも使えると書いています（MkDocs公式：Deploying your docs）。社内向けなら、社内のWebサーバーやオブジェクトストレージにsiteフォルダを置くだけで済みます。

MkDocsのメリットとデメリット：採用前に押さえる長所と制約

長所と制約を、技術文書の運用目線で並べます。

観点	メリット	デメリット
書き方	Markdownだけで書ける	独自記法は拡張頼み
管理	テキストなのでGitで差分管理	非エンジニアには敷居
公開	DB不要で静的に配信	コメントや認証は持たない
検索	ブラウザ内の全文検索つき	日本語の精度に限界
版管理	設定が1ファイルで単純	文書の版切替は本体に無い
将来性	1系は安定して動く	2.0とMaterial保守終了が控える

採用してよいのは、書き手がエンジニア中心で、原稿をGitのプルリクエストでレビューし、公開物は誰でも読める静的ページで足りる場合です。逆に、編集者がブラウザ上で原稿を直したい、ページごとに閲覧権限を分けたい、製品の版ごとに文書を切り替えたいという要件が先にあるなら、MkDocs単体では満たせません。版の切り替えを標準で持つDocusaurusや、ヘッドレスCMSなど別の手段を比べます。Markdownでサイトを作る方法同士の比較はMarkdownでWebサイトを作る3つの方法【2026年版】が参考になります。

MkDocs・MaterialとSphinx・Docusaurusの役割と選定基準

MkDocsは、docsフォルダのMarkdownと設定ファイルmkdocs.ymlを入力に、HTML・CSS・JavaScriptだけでできたサイトをsiteフォルダへ書き出す静的サイトジェネレーターです。データベースを持たないので生成物を静的ホスティングに置くだけで公開でき、ソースがテキストなのでGitで差分を管理できます。APIリファレンス・社内の技術文書・手順書のように文章中心で更新が多い用途に向き、記事一覧やコメント欄が主役のメディアサイトには向きません。

MkDocs本体とMaterialテーマの役割分担と設定項目の違い

MkDocs本体が担うのはMarkdownの変換とナビゲーションの組み立てまでで、見た目・検索UI・ダークモード・コードのコピーボタンといった機能の大半はテーマのMaterial for MkDocsが提供します。本記事では、配色・ナビゲーション・コード表示をまとめて設定できるMaterialを使用します。ライセンスはMkDocs本体がBSD-2-Clause、Material for MkDocsがMITで、どちらも商用利用できます（PyPIのmkdocs）。

SphinxやDocusaurusとの比較：文書形式と必要機能の違い

ドキュメント生成ツールは、記法と基盤の技術で選び分けます。

ツール	記法	基盤	向いている場面
MkDocs	Markdown	Python	Markdownだけで書く技術文書
Sphinx	reST中心（Markdownも可）	Python	相互参照・API自動生成の多い仕様書
Docusaurus	Markdown／MDX	Node.js／React	Reactで拡張する製品サイト

Markdownだけで完結させ、Python環境で手早く始めたいならMkDocsです。docstringからのAPIドキュメント生成や相互参照を多用するならSphinx、ページにReactコンポーネントを埋め込みたいならDocusaurusを選びます。C++やJavaのソースコメントから文書を作りたい場合は、Doxygenとは？読み方・インストールから使い方・VS Code連携まで解説【1.18.0対応】で扱っているDoxygenの守備範囲です。

MkDocsのインストールからローカル表示までの環境準備と実行手順

ここからは実際の操作です。mkdocsとmkdocs-materialの要件はどちらもPython 3.8以上ですが、依存のpymdown-extensions 12.3は3.10以上を要求するため、3.10未満では古い版の依存が入ります。新しく環境を作るなら3.10以上を使います。

pipでmkdocs-materialを導入する仮想環境の準備と手順

以下はmacOS・Linuxのbash／zsh向けです。仮想環境を作り、テーマごと一括で入れます。WindowsのPowerShellでは、有効化の行を.venv\Scripts\Activate.ps1に置き換えてください。mkdocs-materialは依存にmkdocs<2,>=1.6を持つので、pip install mkdocsを別に打つ必要はなく、MkDocs 2.0の開発版が誤って入ることもありません。

python -m venv .venv
source .venv/bin/activate
pip install mkdocs-material
mkdocs --version

2026年10月16日にmacOS・Python 3.12で実行したところ、mkdocs 1.6.1・mkdocs-material 9.7.7・pymdown-extensions 12.3が入りました。mkdocs --versionで1.6系が表示されれば準備完了です。MkDocs本体の最新安定版は2024年8月30日公開の1.6.1のまま、1系の新版は出ていません（PyPI）。

mkdocs newで雛形を作りmkdocs serveで確認する

mkdocs new .を実行すると、カレントディレクトリにmkdocs.yml（中身はsite_name: My Docsの1行）とdocs/index.mdが作られます。続けてmkdocs serveを起動すると、http://127.0.0.1:8000/で開発用サーバーが立ち上がり、docsとmkdocs.ymlの変更を監視して保存のたびに再ビルドします。

mkdocs new .
mkdocs serve

注意点が1つあります。mkdocs.ymlにsite_url: https://example.github.io/docs/のようなサブパス付きのURLを書くと、開発用サーバーもそのパス（http://127.0.0.1:8000/docs/）で配信し、ルートへのアクセスは302で転送されます。GitHub Pagesのプロジェクトサイト向けにsite_urlを設定した後に「ルートを開いても表示が変わらない」と感じたら、ログのServing onの行で実際のURLを確かめてください。

mkdocs buildによる公開用の静的ファイル出力と確認手順

公開用のファイルはmkdocs buildでsiteフォルダに書き出します。serveは執筆中のプレビュー、buildは公開物の出力という分担です。文書内の相対リンク先ファイルやnavに書いたファイルの欠落を、既定の警告設定でエラーとして止めたいときはmkdocs build --strictを使い、CIでもこちらを回します。siteはビルドのたびに作り直すので、.gitignoreにsite/を入れてGitの管理から外します。

Material 9.7.2（2026年2月18日）で警告が追加され、9.7.3（2026年2月24日）で出力先が標準エラー出力に変わりました。2026年10月16日に9.7.7でbuildしたときの表示は次のとおりです。

⚠  Warning from the Material for MkDocs team
MkDocs 2.0, the underlying framework of Material for MkDocs,
will introduce backward-incompatible changes, including:
× All plugins will stop working – the plugin system has been removed
× All theme overrides will break – the theming system has been rewritten
× No migration path exists – existing projects cannot be upgraded
× Closed contribution model – community members can't report bugs
× Currently unlicensed – unsuitable for production use

ビルド自体は成功しています。CIのログから消したい場合は環境変数NO_MKDOCS_2_WARNING=1を付けて実行すると表示されなくなります（9.7.7のmaterial/templates/__init__.pyで判定）。-qオプションでは消えませんでした。

mkdocs.ymlの基本設定：nav・docs_dir・site_url

MkDocsの挙動はmkdocs.ymlで決まります。最初に触るのは次のキーです（MkDocs公式の設定リファレンス）。

キー	役割	既定値
site_name	サイトのタイトル（必須）	なし
site_url	公開URL（正規URL・サイトマップに使用）	なし
docs_dir	Markdownの入力フォルダ	docs
site_dir	ビルドの出力フォルダ	site
nav	メニューの構成と順序	ファイルから自動生成

navを書かなければdocs内のファイル構成からメニューが自動で作られます。ページ名に使われるのは、メタデータのtitleや本文の先頭見出しなどです。表示順とラベルを明示したいときは、docs_dirからの相対パスで明示します。

site_name: 製品ドキュメント
site_url: https://example.github.io/docs/
theme:
  name: material
nav:
  - はじめに: index.md
  - 使い方:
      - インストール: guide/install.md
      - 設定: guide/config.md
  - FAQ: faq.md

この設定を--strictでビルドすると、site/guide/install/のようにページごとのディレクトリが作られます。navに書いたファイルが無いとビルドが止まるので、ページの追加とnavの更新は同じコミットで行うと事故が減ります。

Material for MkDocsの見た目と機能を設定する

Materialはthemeのnameをmaterialにするだけで適用されます。そこから先は、テーマ側の機能をtheme.featuresで、本文の記法をmarkdown_extensionsで足していきます。以下のコード例はどれも設定の抜粋なので、複数を使うときは同じthemeキーの下へ項目をまとめてください。theme:を2回書くと後の方だけが有効になり、--strictでもエラーになりません。

Materialの配色とダークモード切り替えの設定項目と記述例

配色はpaletteで指定します。明暗2つのpaletteを配列で並べ、それぞれにtoggleを付けると、ヘッダーに切り替えボタンが出ます。scheme: slateが暗色側です（公式：Changing the colors）。

theme:
  name: material
  language: ja
  palette:
    - scheme: default
      primary: indigo
      toggle:
        icon: material/brightness-7
        name: ダークモードに切り替え
    - scheme: slate
      primary: indigo
      toggle:
        icon: material/brightness-4
        name: ライトモードに切り替え

language: jaを入れると、検索欄の案内や「目次」などUIの文言が日本語になります。ロゴはlogoにdocsからの相対パスで画像を指定し、細かな色や余白はextra_cssで読み込むCSSでCSS変数を上書きします。テーマのテンプレートを直接書き換える方法（custom_dir）もありますが、後述のとおりMkDocs 2.0ではテーマの仕組みが作り直されるため、手を入れる範囲はCSSにとどめた方が移行時に困りません。

Materialのナビゲーションタブとコードのコピーボタンの設定

Material固有の機能はtheme.featuresに名前を並べて有効にします。よく使うのは次の3つです（公式：Setting up navigation、Code blocks）。

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.top
    - content.code.copy

navigation.tabsはnavの最上位項目をヘッダー下のタブにし、navigation.topは上方向へスクロールしたときに「トップへ戻る」ボタンを出し、content.code.copyはすべてのコードブロックにコピーボタンを付けます。タブはnavの最上位項目の数だけ並ぶので、タブ化する前に最上位を少数の大分類にまとめておくと、ヘッダーが横にあふれません。

Markdown拡張による注記・コードのタブ・Mermaid図の記述例

本文の表現力はmarkdown_extensionsで決まります。技術文書で効くのは、注意書きのボックス（admonition）、OSや手段ごとに切り替えるタブ、テキストで書ける図（Mermaid）の3つです（公式：Admonitions）。

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.highlight
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true

Markdown側は次のように書きます。!!! noteの下を4文字下げると注記の本文になり、=== "pip"の並びがタブに、mermaidを指定したコードブロックが図になります。

!!! note "注意"
    これは注記です。

=== "pip"

    ```bash
    pip install mkdocs-material
    ```

=== "uv"

    ```bash
    uv add mkdocs-material
    ```

```mermaid
graph LR
  A[Markdown] --> B[mkdocs build] --> C[site]
```

この設定と本文をmkdocs build --strictでビルドし、出力HTMLにadmonition note・tabbed-set・class="mermaid"の要素が生成されることを確認しました。pymdownx.superfencesのformat行は、YAMLのタグ!!python/name:を含むため一字でも崩れると読み込みに失敗します。公式ドキュメントからそのままコピーするのが安全です。

日本語サイト向けの全文検索の言語指定と表示フォントの設定方法

Materialの検索はブラウザ内で動くクライアント側検索で、lunrとlunr-languagesで実装されています（公式：Built-in search plugin）。日本語は単語の間に空白が無いため、言語を指定しないと語の区切りを正しく判定できません。

searchプラグインの日本語設定と区切り文字による検索範囲の違い

検索の言語はsearchプラグインのlangで、区切り文字の既定値はテーマのlanguageで決まります。両方に記述する値はjaです。英語のページも混ざるならlang: [ja, en]のように並べます。

theme:
  name: material
  language: ja
plugins:
  - search:
      lang: ja

ビルド後のsite/search/search_index.jsonを開くと、"lang": ["ja"]に加え、区切り文字separatorに空白・ハイフン・全角スペース・「、」「。」「，」「．」が入っていました。theme.languageだけをenに戻して同じビルドをすると、separatorは空白とハイフンだけになり、句読点では区切られなくなります。日本語の分割にはlunr-languagesのlunr.ja.js（TinySegmenter）が読み込まれます。中国語で必要なjiebaのような追加ライブラリは日本語には要りません。

限界も知っておくべきです。TinySegmenterは統計的に文字列を区切る方式で、日本語用の語幹処理（stemmer）は入力をそのまま返す実装です。そのため「インストール」と「インストールする」のような語形の違いや、長い複合語の一部では当たらないことがあります。社内規程のように語の揺れが多い文書を数百ページ載せるなら、検索精度の要件を先に決め、満たせなければ外部の検索サービスを組み合わせる判断が必要です。

Materialの日本語フォント指定と外部通信を避ける場合の設定

Materialは既定でGoogle FontsのRobotoを読み込みます。日本語の字形をそろえたい場合はfontで指定します（公式：Changing the fonts）。

theme:
  name: material
  font:
    text: Noto Sans JP
    code: Roboto Mono

社内ネットワークなどでGoogle Fontsへの通信を避けたい場合はfont: falseにしてOS標準のフォントに任せるか、extra_cssで自前のWebフォントを読み込みます。

GitHub Pagesへの公開方法と手動・自動デプロイの設定

ビルドしたサイトはGitHub Pagesで公開できます。GitHub Freeで利用する場合、公開元のリポジトリはpublicであることが条件です。容量や帯域の上限、商用利用の可否はGitHub Pagesとは？料金と無料の範囲・容量制限・商用利用とSEO設定【2026年】にまとめています。

mkdocs gh-deployによる一括公開の手順と公開先の設定

GitHub側のリポジトリを用意し、ローカルのGitリポジトリに接続先originとpush用の認証を設定します。そのリポジトリのルートでmkdocs gh-deployを実行すると、ビルドしてgh-pagesブランチにコミットし、GitHubへpushするところまで自動で進みます（MkDocs公式：Deploying your docs）。リポジトリの設定でPagesの公開元をgh-pagesブランチにすれば、https://<ユーザー名>.github.io/<リポジトリ名>/で公開されます。

mkdocs gh-deploy

公開後に404になるときは、公開元のブランチがgh-pagesになっているか、サブパスで公開しているのにsite_urlが未設定でないかを確認します。公開URLの形式と404の切り分けはGitHub PagesのURLはどこで確認する？形式・変わる条件・404の切り分けで詳しく扱っています。

GitHub Actionsによる自動デプロイの設定と書き込み権限

mainブランチへのpushをきっかけに自動で公開するなら、Materialの公式ドキュメントが示すワークフローを.github/workflows/ci.ymlに置きます（公式：Publishing your site）。次はその要点を抜き出したものです。

name: ci
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

gh-deployはgh-pagesブランチへpushするので、permissionsにcontents: writeが必要です。これが無いと、既定のトークン権限が読み取りのみのリポジトリでpushが403で失敗します。権限の既定値と絞り方はGitHub Actionsのpermissions｜GITHUB_TOKENの既定権限と最小権限の設計を参照してください。依存のバージョンを固定したい場合はpip install mkdocs-material==9.7.7のように版を指定し、requirements.txtで管理します。ドキュメントのビルドを既存のCI/CDやレビュー手順に組み込む設計を外部に任せたい場合は、DevOps・CI/CD導入支援でも相談を受けています。

2026年10月時点のMaterial保守終了とMkDocs 2.0・Zensical

MkDocsをこれから採用するなら、2025年11月以降の3つの変化を前提に置く必要があります。一次情報の記載と、手元で実行した結果を並べます。

Material for MkDocsの9.7系新機能停止と2027年5月5日保守終了

Material for MkDocsは2025年11月11日公開の9.7.0で保守モードに入りました。CHANGELOGには「新機能を受け取る最後のリリース」とあり、重大なバグ修正とセキュリティ更新を少なくとも12か月続けると書かれています（CHANGELOG）。その後の更新は修正だけで、最新の9.7.7（2026年7月17日）は検索候補のDOMベースのXSSを直したリリースです。9.7.5（2026年3月10日）ではMkDocs本体の版を<2に固定しました。

さらに公式のchangelogページは、2026年10月時点で「Material for MkDocs reaches end of life on May 5, 2027」と明記しています。重大なバグ修正とセキュリティ更新はこの日まで続き、その後は開発元による保守が終わります。インストール済みの版はそのまま使えますが、以降に見つかった脆弱性は直りません（公式changelog）。

MkDocs 2.0開発版のmkdocs.yml検出時の起動拒否

MkDocs 2.0は、2026年8月28日の2.0.dev0から9月15日の2.0.dev6まで開発版がPyPIに出ています（開発ステータスはBeta、Python 3.10以上）。公式サイトはpip install mkdocs --preで開発版を入れる方法を案内しています（encode.io/mkdocs）。--preを付けない通常のpip installでは1.6.1が入ります。

2.0.dev6を別の仮想環境に入れ、ここまでのmkdocs.ymlがあるフォルダでmkdocs buildを実行すると、Exception: Found mkdocs.yml config, but mkdocs 2.0 pre-release is installedで即座に止まりました。サブコマンドはbuildとserveの2つだけで、new・gh-deploy・--versionはありません。mkdocs.ymlを消すとビルドは通りますが、生成されたのは最小限のHTMLで、Materialテーマもプラグインも使えません。公式の手順も、トップページをdocs/README.mdとして作る前提に変わっています。

なお警告の「Currently unlicensed」は古くなっており、2026年10月時点の公式サイトにはMITライセンスと同じ文面の許諾条項が載っています（encode.io/mkdocs/license）。ただし1系のプロジェクトをそのまま2.0へ上げる道が無い点は変わりません。

Zensicalのmkdocs.yml互換性と未対応プラグインの扱い

ZensicalはMaterialの開発チームが作っている後継の静的サイトジェネレーターです。2026年10月12日公開の0.0.70が最新で、PyPIの開発ステータスは「3 – Alpha」、Python 3.11以上が必要、ライセンスはMITです（PyPIのzensical）。

上の配色・タブ・注記・Mermaidを含むmkdocs.ymlを変更せずにzensical buildへ渡すと、約1秒で「No issues found」と出てビルドが終わり、出力HTMLには注記・タブ・Mermaidの要素が生成されていました。zensical newで新規に作ると、設定はzensical.toml（TOML形式）になり、GitHub Pagesへ公開するワークフローも.github/workflows/に作られます。

落とし穴は、対応表に無いプラグインの扱いです。公式の互換性ページは「対応一覧に無いプラグインの設定は黙って無視し、インポートも実行もしない」と書いています（Zensical：MkDocs plugins）。試しに、インストールしていないgit-revision-date-localizedをpluginsに足すと、MkDocs 1.6.1は「Aborted with a configuration error!」で止まり、Zensicalは「No issues found」でビルドを終えました。更新日の表示が消えていても、ビルドのログでは気づけません。同ページでは、このプラグインはgit-authors・git-committers・privacyとともに「Planned（対応予定）」の扱いで、gen-filesは未対応と明記されています。

MkDocs・Material・Zensicalの運用期間に応じた構成選定

判断は次のとおりです。

既存サイト・今すぐ公開したい新規サイト：MkDocs 1.6.1＋Material 9.7系で始める。2027年5月5日までは重大な不具合と脆弱性の修正が出る。設定はmkdocs.ymlとCSSにとどめ、テンプレートの上書きを増やさない。
2027年5月以降も運用する予定のサイト：同じmkdocs.ymlでZensicalのビルドを試し、使っているプラグインがすべて対応一覧に載っているかを確認してから移す。対応予定のプラグインに依存しているなら、その対応を待つ。
MkDocs 2.0開発版：本番には使わない。Materialが動かず、1系の設定も読まないため、試すなら空のフォルダで新しく作る。

避けるべきなのは、Zensicalの「No issues found」だけを見て本番を切り替えることです。切り替え前に、MkDocsとZensicalの両方で出力したsiteを比べ、更新日・タグ・リダイレクトなどプラグインに頼る表示が残っているかを目で確かめてください。

よくある質問

MkDocsとは無料のツールですか？商用利用はできますか？

MkDocsとは、Markdownからドキュメントサイトを作るPython製の静的サイトジェネレーターで、無料のオープンソースです。MkDocs本体はBSD-2-Clause、Material for MkDocsとZensicalはMITライセンスで、商用を含めて無償で使えます。公開先にGitHub Pagesの無料枠を使えば、ホスティング費用もかかりません。条文は導入時に各リポジトリで確認してください。

MkDocsの代替ツールは何がありますか？

Python系ならSphinx、Node.js/React系ならDocusaurusが代表です。相互参照やAPIドキュメントの自動生成を重視するならSphinx、Reactコンポーネントを埋め込むならDocusaurusが向きます。Material for MkDocsの後継としては、同じ開発チームのZensicalがあり、既存のmkdocs.ymlをそのまま読み込めます。

Material for MkDocsはいつまで使えますか？

重大なバグ修正とセキュリティ更新は2027年5月5日まで提供されると公式のchangelogに明記されています。それ以降もインストール済みの版は動き続けますが、新たに見つかった脆弱性は修正されません。長く運用するサイトは、この日付までにZensicalなどへの移行を検討してください。

MkDocs 2.0にアップグレードできますか？

2026年10月時点ではアップグレードできない状態です。2.0は開発版（2.0.dev6）の段階で、mkdocs.ymlがあるフォルダでは起動を拒否し、プラグインとMaterialテーマも使えません。mkdocs-material経由で入れていれば、依存がmkdocs<2に固定されているので誤って2.0が入ることはありません。

mkdocs serveとmkdocs buildの違いは何ですか？

mkdocs serveは執筆中のプレビュー用で、開発用サーバーを立ち上げてファイルを保存するたびに再ビルドします。mkdocs buildは公開用で、HTML一式をsiteフォルダに書き出します。mkdocs gh-deployは内部でbuildを実行してからgh-pagesブランチへ反映するので、公開時にbuildを別に打つ必要はありません。