びびっと！

MkDocs / Material for MkDocs の揺れと Zensical 最新動向から見る、枯れたドキュメントサイト技術の変遷

16 min read

MkDocs / Material for MkDocs の揺れと Zensical 最新動向から見る、枯れたドキュメントサイト技術の変遷

要旨

MkDocs と Material for MkDocs は、長く「枯れた」ドキュメントサイト基盤として使われてきた。 しかし2025年末から2026年春にかけて、MkDocs 1.x の停滞、MkDocs 2.0 の非互換方針、Material for MkDocs のメンテナンスモード化、Zensical の登場、GitHub Discussions閉鎖、PyPI権限騒動が重なり、エコシステムの緊張が一気に表面化した。 これは単なる「コミュニティのいざこざ」ではなく、ドキュメントサイトが成熟した結果、テーマ、プラグイン、検索、APIリファレンス、バージョン管理、スポンサー制度、メンテナンス権限まで含む大きなドキュメント基盤になったことの副作用である。 2026-05-03時点では、Zensicalはalphaだが急速に更新されており、Material for MkDocs互換を優先しながら、Rustランタイム、差分ビルド、モジュールシステム、検索、コンポーネント化へ進もうとしている。

背景・動機

前回の調査では、Quartz、Cloudflare Pages、GitHub Pages、Netlify、Vercel などを、ブログ・ホームページ・ナレッジ共有・ドキュメント公開の観点で整理した。 その中で、ドキュメントサイト向けの「枯れた選択肢」として MkDocs / Material for MkDocs / Docusaurus / Sphinx / Read the Docs などが見えてきた。

しかし、MkDocs周辺は2025年末から2026年にかけて急に安定感が揺らいだ。 一見すると「有名OSSの人間関係トラブル」に見えるが、実際には次の問題が絡んでいる。

  • MkDocs 1.x のメンテナンス停滞
  • MkDocs 2.0 が既存プラグイン・テーマと非互換になり得ること
  • Material for MkDocs がMkDocs本体に強く依存していたこと
  • Material for MkDocsの巨大なユーザー基盤が、MkDocs本体より大きな実質的エコシステムになっていたこと
  • GitHub Discussionsが大規模ユーザーサポートに向かなかったこと
  • スポンサー、サポート、ロードマップ決定をどう持続可能にするかというOSSガバナンス問題

本稿は、最新情報を整理しながら、ドキュメントサイト技術の歴史と「枯れているように見える技術」の見方を更新する。

調査内容

何が起きたのか

2026-05-03時点で確認できる範囲では、主要な出来事は次のように整理できる。

日付出来事意味
2008-03Sphinx 0.1が公開Python圏の本格的なドキュメント生成基盤が広がる
2010頃Read the Docs が登場Git連携・自動ビルド・バージョン別公開が一般化
2014MkDocs が登場Markdownで簡単にドキュメントサイトを作る流れが強まる
2016Material for MkDocs が成長開始MkDocsを現代的なUI・検索・拡張込みの実用基盤に押し上げる
2017Docusaurus 公開React/Markdown/OSSドキュメントの統合基盤が登場
2024-08-30MkDocs 1.6.1リリース2026年春時点で1.x系の最新安定リリースとして参照される
2025-11-05Zensical発表Material for MkDocsチームが次世代SSGへ移行開始
2025-11-11Material for MkDocs 9.7.0 / Insiders無料化Material for MkDocsはメンテナンスモードへ
2025-11-18GitHub Discussions read-only化サポートと開発の分離問題が明文化される
2026-02-18MkDocs 2.0影響分析公開MkDocs 2.0の非互換リスクが広く共有される
2026-03-09MkDocsのPyPI権限騒動パッケージ配布権限とガバナンス問題が表面化
2026-04-14Zensical 0.0.33がPyPIに公開Zensicalはalphaながら継続更新中

ここで重要なのは、MkDocsやMaterial for MkDocsが「失敗した」という単純な話ではないこと。 むしろ、長く成功した結果、利用者・プラグイン・テーマ・検索・API文書・スポンサー・サポートの規模が膨らみ、単一の古いアーキテクチャと少数メンテナ体制では支えきれない段階に入ったと見る方がよい。

「コミュニティのいざこざ」の中身

Material for MkDocsチームの公式発信では、GitHub Discussionsをread-onlyにした理由として、サポート依頼、質問、バグ報告、上流プロジェクト由来の問題が一つの場に流れ込み、メンテナの負荷と通知疲れが増えたことが説明されている。 GitHub Discussionsは、少人数のプロジェクトでは便利でも、大規模ユーザー基盤を持つOSSのサポート窓口としては構造的に厳しい、という判断である。

一方で、MkDocs本体側ではより深い摩擦があった。 Material for MkDocs側は、MkDocs 1.xが長く更新されず、MkDocs 2.0が既存テーマ・プラグインと非互換になる可能性を強く警告している。 外部記事「The Slow Collapse of MkDocs」は、個人間の摩擦、メンテナンス権限、PyPI権限、MkDocs 2.0の方向性、後継プロジェクトの分裂を時系列でまとめている。

ただし、個人攻撃的な読み方は避けたい。 この件の本質は、次のような構造問題にある。

  • 成功したOSSでは、ユーザーサポートと開発作業が混ざりやすい
  • テーマが本体より大きな実質的ユーザー基盤を持つと、責任境界が曖昧になる
  • プラグインエコシステムは便利だが、本体の内部実装に強く依存しやすい
  • パッケージ配布権限、GitHub権限、プロジェクト方針の合意がずれると、技術的互換性より先に信頼が揺らぐ
  • 「枯れた技術」は、コードが安定しているだけでは足りず、メンテナンス体制も安定していなければならない

MkDocs 2.0の争点

Material for MkDocsチームの2026-02-18記事によると、MkDocs 2.0の争点は大きく次の通り。

  • Material for MkDocsとの非互換
  • プラグインシステムの扱い
  • テーマシステムの再設計
  • mkdocs.yml からTOML系設定への変更
  • コントリビューションモデルの変化
  • ライセンスや公開形態への懸念

もちろん、これはMaterial for MkDocs側から見た分析であり、MkDocs 2.0側の狙いは「より単純で整理された新しいMkDocs」を作ることだと思われる。 しかし既存ユーザーから見ると、MkDocsの価値は本体だけではなく、テーマ、プラグイン、Python Markdown拡張、mkdocstrings、mike、Material for MkDocsなどの周辺資産込みで成立している。

したがって、MkDocs 2.0が本体をきれいに作り直しても、既存の拡張資産が使えなくなるなら、多くのドキュメントサイトにとっては「アップグレード」ではなく「移行プロジェクト」になる。

Zensicalの最新状況

Zensical は、Material for MkDocsの作者・チームが作る次世代の静的サイトジェネレーター。 2026-05-03時点で、公式サイトではalphaと説明されている。 PyPIでは 2026-04-14 に 0.0.33 が公開されており、Python 3.10以上、Rust/Python構成、MITライセンス、Development StatusはAlphaとして確認できる。

Zensicalの方針は、「Material for MkDocs互換を保ちながら、MkDocsの制約を越える」こと。 公式のCompatibilityページでは、既存の mkdocs.yml、Markdown、frontmatter、プロジェクト構造、URL、テンプレート、CSS/JSカスタマイズとの互換性を重視している。 一方で、新規プロジェクトでは zensical.toml を推奨しつつ、mkdocs.yml は移行メカニズムとして長期的に扱う方針が説明されている。

ロードマップ上の焦点は次の通り。

  • Rustベースの次世代ランタイム
  • 差分ビルド
  • タスク依存関係を明示するモジュールシステム
  • Material for MkDocs互換のclassic themeと新しいmodern theme
  • Python Markdown互換からCommonMark / component systemへの段階的移行
  • 検索エンジン、APIドキュメント、バージョン管理、i18n、サブプロジェクト対応
  • Zensical Sparkによるプロ向けサポートとロードマップ参加

現時点では「今すぐ全サイトを移すべき安定版」ではなく、「Material for MkDocsの将来不安を見越して検証を始めるべき次世代候補」と見るのが妥当である。

「枯れた技術」としてのドキュメントサイト史

ドキュメントサイト技術は、Webフロントエンドの派手な変化に比べると地味に見える。 しかし歴史を見ると、実は何度も中心課題が変わっている。

1. Sphinx時代: 文書構造と複数出力

2008年公開のSphinxは、reStructuredTextを中心に、HTML、PDF、ePub、man pageなど複数形式へ出力できる。 Python公式ドキュメントのために育ったため、API参照、索引、相互参照、拡張機構に強い。

この時代の主題は「きちんと構造化された技術文書を、長期的に保守する」ことだった。 reStructuredTextはMarkdownより学習コストが高いが、参照・ディレクティブ・出力形式の幅では強い。

2. Read the Docs時代: Docs as Codeと自動公開

Read the Docs は、Gitにpushするとドキュメントが自動ビルド・公開され、バージョン別に読める体験を一般化した。 ここでDocs as Codeの実務感が強くなる。

ドキュメントは手元のファイルで書き、Gitでレビューし、CI/CDで公開する。 この流れは現在のCloudflare Pages、GitHub Pages、Netlify、Vercel、Quartz運用にもつながっている。

3. MkDocs時代: Markdownで手軽に書く

MkDocs は、MarkdownとYAML設定でドキュメントサイトを作れる手軽さが強みだった。 Sphinxより軽く、プロジェクト文書を始めやすい。 2016年以降、Material for MkDocs が見た目、検索、ナビゲーション、Admonition、タブ、コード注釈、ブログ、タグなどを強化し、MkDocsは多くのチームにとって「これで十分」な選択肢になった。

ここでの主題は「開発者がMarkdownで、きれいなドキュメントを素早く出す」ことだった。

4. Docusaurus / Starlight時代: ドキュメントとWebアプリの接近

Docusaurus は、React、Markdown、ブログ、バージョン、i18n、検索を組み合わせ、OSSプロジェクトのWebサイトを標準化する方向へ進んだ。 Astro系のStarlightも同様に、ドキュメントサイトをフロントエンドコンポーネントと統合する。

この時代の主題は「ドキュメントもWebプロダクトの一部として扱う」こと。 ランディングページ、ブログ、API文書、チュートリアル、バージョン管理が一つのサイトにまとまる。

5. Zensical以後: 巨大ドキュメントと持続可能性

Zensical が掲げる課題は、単に「MkDocsを速くする」ことではない。 数万ページ規模、差分ビルド、検索、APIドキュメント、モジュール、コンポーネント、i18n、サブプロジェクト、プロ向けサポートまで含めた、ドキュメント基盤全体の再設計である。

ここでの主題は「ドキュメントサイトを小さな静的サイトではなく、長期運用される知識プロダクトとして扱う」ことに移っている。

いま使うならどう判断するか

2026-05-03時点の実務的な判断は次のようになる。

状況判断
既存のMaterial for MkDocsサイトが安定稼働中すぐ壊れるわけではない。依存バージョンを固定し、MkDocs <2 を維持する
新規で小規模な社内ドキュメントを作るMkDocs Materialはまだ使えるが、Zensical / Docusaurus / Starlightも比較対象に入れる
長期運用の大型ドキュメントを新規構築MkDocs 1.x依存を避け、Zensicalの成熟待ち、Docusaurus、Starlight、Sphinxなどを慎重に比較
Python API文書が中心Sphinx / mkdocstrings / ZensicalのAPI文書計画を比較
「枯れた技術」を最優先Sphinx + Read the Docsが最も保守的。MkDocs Materialは現在の移行期リスクを理解して使う
Obsidian的な調査アーカイブQuartz が別軸で有力。ドキュメントサイトというより知識網公開ツール

特に重要なのは、ドキュメントツールを「今の見た目」だけで選ばないこと。 次の観点を必ず見る必要がある。

  • 本体とテーマの責任境界
  • プラグインエコシステムの安定性
  • パッケージ配布権限とメンテナンス体制
  • 互換性ポリシー
  • バージョン固定のしやすさ
  • 代替ツールへの移行容易性
  • ドキュメントのソース形式が標準的か

結論

MkDocs / Material for MkDocs周辺の騒動は、表面だけ見ると人間関係やコミュニティ運営の揉め事に見える。 しかし、より深く見ると、ドキュメントサイト技術が成熟し、単なるMarkdown変換ツールではなく、検索、API、バージョン、プラグイン、テーマ、サポートを含む巨大な基盤になったことの帰結である。

「枯れた技術」とは、古い技術という意味ではない。 安定した仕様、十分な利用実績、読めるソース形式、予測可能なメンテナンス、移行可能性が揃っている技術のこと。 その意味では、MkDocs Materialは技術的には非常に成熟しているが、2026年現在はガバナンスと将来互換性の面で移行期にある。

Zensicalはまだalphaだが、Material for MkDocsの経験を引き継ぎ、互換性を重視しながら次世代のドキュメント基盤を作ろうとしている。 ただし、現時点では「本番標準」ではなく「有力な次世代候補」として検証するのが安全である。

このリポジトリの文脈では、Quartz は調査アーカイブやデジタルガーデンに向き、MkDocs / Zensical / Docusaurus / Sphinx は体系的な製品ドキュメントに向く。 両者は競合というより、公開したい知識の形が違う。 ノートの網を育てるならQuartz、手順とリファレンスを安定配布するならドキュメントサイト専用ツール、という切り分けがよい。

関連

出典

Graph View

Backlinks