MkDocsの使い方｜インストールからMaterialテーマ・日本語対応・GitHub Pages公開まで【2026年版】

MkDocsは、Markdownで書いた文書をそのまま静的なドキュメントサイトに変換するPython製のツールです。最短の流れはpip install mkdocs-materialでインストールし、mkdocs new .で雛形を作り、mkdocs serveで書きながらプレビューし、mkdocs gh-deployでGitHub Pagesへ公開する、という4段階に集約できます。この記事ではこの一連の手順に加え、Materialテーマのカスタマイズ、日本語の全文検索設定、そして2026年時点で判断が分かれるMaterialの保守モード入りと後継Zensicalの選び方までを、公式ドキュメントの実際の設定に沿って解説します。

まとめ：MkDocsの使い方の要点（先に結論）

• 最短4コマンド：pip install mkdocs-material → mkdocs new . → mkdocs serve → mkdocs gh-deploy。これだけで公開まで届く。
• 設定はmkdocs.yml1枚に集約：サイト名・テーマ・ナビゲーション（nav）・プラグインをここで指定する。データベースもCMSも不要。
• 日本語検索は1行：searchプラグインにlang: jaを指定するだけ。中国語で使うjiebaは日本語には不要。
• 2026年の注意点：Material for MkDocsは2025年11月に保守モードへ入り、新機能追加は止まった。開発チームは後継として静的サイトジェネレーターZensicalを公開している。新規採用時はこの動向を踏まえて選ぶ。

以降で各コマンドの意味、mkdocs.ymlの書き方、Materialの見た目調整、そして「今から始めるならどれを選ぶか」までを具体的に見ていきます。

MkDocsとは：Markdownを静的サイトに変換するドキュメント生成ツール

MkDocsは、Markdownファイル群を1つの検索可能なWebサイト（HTML/CSS/JavaScript）へビルドする静的サイトジェネレーターです。書き手はMarkdownの執筆に専念でき、サイトの体裁・ナビゲーション・全文検索はMkDocs側が生成します。WordPressのようなCMSと違いサーバーサイドの処理やデータベースを持たないため、生成物をそのままGitHub Pagesなどの静的ホスティングに置くだけで公開が完結します。

MkDocsの仕組みと向いている用途

入力はdocsフォルダ内のMarkdown、設定はmkdocs.yml、出力はビルドされたsiteフォルダという構成です。ソースがすべてテキストなのでGitでバージョン管理でき、変更差分がレビューしやすい点が実務上の利点です。向いているのはAPIリファレンス、社内の技術ドキュメント、OSSのマニュアル、手順書といった「文章中心で更新頻度が高い」用途です。逆に、記事一覧や日付ソート、コメント欄が主役のブログ／メディアサイトには、後述の理由から必ずしも適しません。

SphinxやDocusaurusとの違い

ドキュメント生成ツールは他にもあり、書式と技術スタックで選び分けます。MkDocsはMarkdown＋Python、SphinxはreStructuredText（Markdownも可）＋Python、DocusaurusはMarkdown/MDX＋Reactが基盤です。

Markdownだけで完結させたい、Python環境で導入コストを抑えたい場合はMkDocsが有力です。相互参照や自動APIドキュメント（docstring取り込み）を多用するならSphinx、Reactコンポーネントをドキュメントに埋め込みたいならDocusaurusが向きます。「mkdocs 代替」を検討する際は、この記法と基盤の違いが最初の判断軸になります。

【2026年の最新動向】Material保守モード入り・後継Zensical・MkDocs 2.0

MkDocsを新規採用するなら、2025年末に起きた開発体制の変化を知らずに始めるべきではありません。事実関係を整理します（変動が速い領域のため、採用前に公式の最新状況を確認してください）。

Material for MkDocsの保守モード入り（2025年11月5日）

もっとも普及しているテーマMaterial for MkDocsは、2025年11月5日に保守モード入りを宣言しました。開発チームによれば、最低12か月は重大なバグ・セキュリティ問題の修正を続けるものの、新機能は追加されません。現行の安定版はバージョン9.7系（PyPIで9.7.6を確認）で、既存プロジェクトが動かなくなるわけではありませんが、今後の機能拡張は期待できないという前提で採用を判断する必要があります。

後継の静的サイトジェネレーターZensical

同じ開発チーム（squidfunk）は同日、後継となる静的サイトジェネレーターZensicalを発表しました。ZensicalはMITライセンスで商用利用も可能、既存のmkdocs.ymlをそのまま読み込める後方互換を掲げています。ただし2026年7月時点ではバージョン0.0.x系のプレリリース段階（PyPIで0.0.50を確認）で、本番の大規模サイトに全面採用するには早い状況です。従来のスポンサーウェア方式は廃止され、プロ向けにZensical Sparkが用意されています。

MkDocs 2.0の破壊的変更点とプレリリース状況

MkDocs本体は1.6.1が最新の安定版で、2024年以降1.x系の新リリースは出ていません（2026年7月時点）。次期の2.0はゼロから書き直すプレリリースとして進行中で、設定ファイルがYAMLからTOMLへ変わる、プラグイン機構を廃止する、既存のMaterialテーマとは互換性がない、といった破壊的変更が予告されています。リリース日は未定です。

判断の指針：安定して動く実績を優先するなら、現時点では従来のMkDocs 1.6系＋Material 9.7系の組み合わせが最も無難です。新機能が止まる点を許容できない、または新規に長期運用するプロジェクトなら、Zensicalの成熟度を追いながら移行を検討する価値があります。逆に、2.0のプレリリースを本番採用するのは互換性が固まるまで避けるべきです。既存プロジェクトを今すぐ乗り換える必要はありません。

MkDocsのインストールと最短の使い方

ここからは実際の操作です。Materialテーマを最初から使う前提で、依存関係をまとめて入れます。

pipでのインストール手順

Python 3.8以上が必要です（Zensicalを使う場合は3.10以上）。仮想環境を作ってから、テーマ込みで一括インストールします。mkdocs-materialを入れるとMkDocs本体も依存として同時に入るため、別途pip install mkdocsは不要です。

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

最後のmkdocs --versionでバージョン（例：mkdocs 1.6.1）が表示されればインストール成功です。「mkdocs version」を確認したいときもこのコマンドを使います。

プロジェクト作成からローカルプレビューまで

カレントディレクトリに雛形を作るにはmkdocs new .を実行します。docs/index.mdとmkdocs.ymlが生成されます。続けてmkdocs serveを起動すると、ローカルサーバー（既定でhttp://127.0.0.1:8000）が立ち上がり、Markdownを保存するたび自動で再ビルド・ブラウザ更新されます。書きながら結果を確認できるのがMkDocsの使い勝手の中心です。

mkdocs new .
mkdocs serve

生成される最小構成は次のとおりです。

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

静的ファイルのビルドと公開準備

プレビューではなく、公開用のHTMLを書き出すにはmkdocs buildを実行します。既定でsiteフォルダに完成物一式が生成され、これをそのまま任意のWebサーバーやホスティングへ配置すれば公開できます。mkdocs serveが開発用（メモリ上で配信）、mkdocs buildが本番用（ファイル出力）という役割分担です。壊れたリンクなどをビルド時に検知して失敗させたい場合はmkdocs build --strictを使います。

mkdocs.ymlの設定とファイル構成（docs_dir・site_dir・nav）

MkDocsの挙動はmkdocs.yml1枚で決まります。ここでサイト名、入出力フォルダ、テーマ、ナビゲーション、プラグインを指定します。

主要な設定項目とフォルダの役割

入力フォルダはdocs_dir（既定docs）、出力フォルダはsite_dir（既定site）で指定します。既定のままで問題ないことがほとんどですが、モノレポでフォルダ構成を変えたいときにこれらを明示します。

site_dirはGitの管理対象から外す（.gitignoreにsite/を追加する）のが定石です。ビルド生成物をリポジトリに含めると差分が肥大化するためです。

ナビゲーション（nav）の組み方

navを書かない場合、MkDocsはdocs内のファイルからメニューを自動生成します。表示順やページ名を制御したいときは、次のように明示します。ページのパスはdocs_dirからの相対で書きます。

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

階層はインデントで表現し、上位項目にセクション名、下位にページを割り当てます。ファイル名をそのまま出したくない場合は、このnavで日本語のラベルを付けます。

Material for MkDocsの導入とカスタマイズ

既定テーマでも公開はできますが、検索UI・レスポンシブ対応・ダークモードが整うMaterialが実質の標準です。前掲のとおりmkdocs-materialを入れておけば、あとはmkdocs.ymlでテーマ名を切り替えるだけです。

Materialテーマの有効化

themeのnameをmaterialにすると適用されます。既定テーマから切り替える場合もこの1行の変更で済みます。

theme:
  name: material

カラー・ロゴ・フォントのカスタマイズ

ブランドカラーはpaletteで指定します。ダークモード切り替えを付けるには、明暗2つのpaletteを配列で並べ、toggleを設定します。ロゴはlogoに画像パスを、独自のCSS・JavaScriptはextra_css・extra_javascriptで読み込みます。画像やCSSはdocs配下（例：docs/assets/）に置き、そこからの相対パスで参照します。

theme:
  name: material
  logo: assets/logo.png
  palette:
    primary: indigo
    accent: indigo
extra_css:
  - stylesheets/extra.css
extra_javascript:
  - javascripts/extra.js

細かな配色や余白の調整はextra.cssでCSS変数を上書きするのが基本方針です。テーマ本体のテンプレートを直接書き換える方法もありますが、更新時に追従が難しくなるため、まずはCSS変数とmkdocs.ymlの範囲で収める方が保守が楽です。

画像・SVGアイコンの扱い

本文への画像挿入は通常のMarkdown記法（![代替テキスト](assets/figure.png)）で行います。「mkdocs svg」で調べられるSVGの扱いは2通りあり、用途で使い分けます。ロゴや装飾のように拡大しても劣化させたくない画像はSVGファイルとしてdocs配下に置き画像として参照します。一方、Materialが備えるアイコン（:material-home:のような記法）を使う場合は、テーマに同梱のSVGアイコンセットがそのまま使え、追加ファイルは不要です。ボタンやリンクにアイコンを添えるだけなら後者が手軽です。

日本語対応：全文検索とフォントの設定

MkDocsの全文検索はクライアント側（ブラウザ内）で動くため、日本語を正しく分割できるよう言語を明示します。既定のままだと日本語がうまくヒットしないことがあります。

日本語の全文検索設定（lang: ja）

設定はsearchプラグインのlangにjaを指定するだけです。日本語はクライアント側で分割処理されるため、中国語で使うjiebaのような追加ライブラリは不要です（jiebaは中国語専用）。英語と併用するならjaとenを並べます。

plugins:
  - search:
      lang: ja

検索がまだ弱いと感じる場合でも、まずはこの1行が入っているかを確認します。区切り文字（separator）はサイト言語から自動計算されるため、日本語では通常そのままで動きます。ただし日本語はブラウザ側のTinySegmenterで分割する仕組み上、複合語や連続する日本語の検索精度には既知の限界があり、lang: jaを入れれば英語並みに効くとは限らない点は理解しておくとよいでしょう。

日本語フォントの指定

Materialは既定でGoogle FontsのRobotoを読み込みますが、日本語見出しの字形を整えたい場合はfontで日本語フォントを指定します。指定したフォントファミリーはGoogle Fontsから読み込まれます。

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

社内ネットワークで外部フォントの読み込みを避けたい環境では、font: falseにしてブラウザ標準フォントに任せる、またはextra_cssで自前のWebフォントを指定する方針にします。

GitHub Pagesで公開する（mkdocs gh-deploy）

ビルドした静的サイトは無料のGitHub Pagesで手軽に公開できます。MkDocsには公開まで一括で行う専用コマンドが用意されています。GitHub Pages自体の料金や制約はGitHub Pagesとは？できること・使い方・料金をわかりやすく解説で詳しく整理しています。

gh-deployコマンドで一括公開

リポジトリのルートでmkdocs gh-deployを実行すると、サイトをビルドしてgh-pagesブランチにコミットし、GitHubへpushするところまで自動で行われます。あとはリポジトリ設定でPagesの公開元をgh-pagesブランチにすれば公開されます。公開URLはhttps://<ユーザー名>.github.io/<リポジトリ名>/の形になります。

mkdocs gh-deploy

公開後に404になる典型原因は、Pagesの公開元ブランチがgh-pagesになっていない、またはプロジェクト配下URL（サブパス）でmkdocs.ymlのsite_urlが未設定でリンクがずれる、の2つです。site_urlに本番URLを明記しておくと相対リンクの崩れを防げます。静的サイトジェネレーターからGitHub Pagesへ公開する全体像は静的サイトジェネレーターを活用したGitHub Pages構築方法も参考になります。

GitHub Actionsで自動デプロイ

手元からgh-deployする代わりに、mainブランチへのpushをトリガーに自動公開する構成が実務では一般的です。.github/workflows/にワークフローを置き、依存をインストールしてmkdocs gh-deploy --forceを走らせます。

name: docs
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

この構成なら、ドキュメントの更新をコミットするだけで公開まで自動化でき、手元環境の差異による公開ミスを避けられます。

よくある質問（FAQ）

MkDocsは無料で商用利用できますか？

できます。MkDocs本体はBSDライセンス、Material for MkDocsとZensicalはMITライセンスで、いずれも商用を含め無償で利用できます。公開先にGitHub Pagesの無料枠を使えば、ホスティング費用もかけずに運用できます。ライセンス条項は導入時に各公式リポジトリで確認してください。

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

Python系ではSphinx、Node.js/React系ではDocusaurusが主な代替です。reStructuredTextでの相互参照やAPIドキュメント自動生成を重視するならSphinx、Reactコンポーネントを埋め込みたいならDocusaurusが向きます。加えて2025年以降は、Material開発チームの後継Zensicalも選択肢に入ります。

今から始めるならMaterial for MkDocsとZensicalのどちらを使うべきですか？

2026年7月時点では、実績と安定性を求めるならMkDocs 1.6系＋Material 9.7系が無難です。Materialは保守モードで新機能は増えませんが、既存機能は十分に成熟しています。長期運用で最新機能を追いたい新規プロジェクトは、まだ0.x系のZensicalを試験導入しつつ成熟を待つ進め方が現実的です。なおZensicalはPython 3.10以上が必須で、旧いPython環境ではそのまま動かない点も選定時の判断材料になります。

日本語の全文検索が効かないときはどうすればよいですか？

まずmkdocs.ymlのsearchプラグインにlang: jaが入っているかを確認します。設定後はmkdocs buildで検索インデックスを作り直す必要があります。それでも精度が不足する場合は、英語混在のページでjaとenを併記します。日本語にjieba等の追加ライブラリは不要です。

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

mkdocs serveは執筆中のプレビュー用で、ローカルサーバーを立ち上げMarkdown保存のたびに自動で再ビルドします。mkdocs buildは公開用で、完成したHTML一式をsiteフォルダに書き出します。なおmkdocs gh-deployは内部でこのbuildを実行してからgh-pagesブランチへ反映するため、公開時はbuildを個別に打つ必要はありません。日々の編集はserve、公開はgh-deployという使い分けです。

関連記事

• GitHub Pagesとは？できること・使い方・料金をわかりやすく解説
• 静的サイトジェネレーターを活用したGitHub Pages構築方法