--- title: "MkDocsの使い方｜インストールからMaterialテーマ・日本語対応・GitHub Pages公開まで【2026年版】" url: "https://www.issoh.co.jp/tech/details/3675/" published: 2024-09-27 updated: 2026-07-16 categories: ["プラットフォーム"] publisher: "株式会社一創" --- # 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.yml`1枚に集約**：サイト名・テーマ・ナビゲーション（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が基盤です。 | ツール | 記法 | 基盤 | 向いている場面 | | ---------- | ------------ | ------------- | --------------- | | MkDocs | Markdown | Python | 整った技術ドキュメント | | Sphinx | reST中心 | Python | 大規模な仕様書 | | Docusaurus | Markdown/MDX | Node.js/React | 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.yml`1枚で決まります。ここでサイト名、入出力フォルダ、テーマ、ナビゲーション、プラグインを指定します。 ### 主要な設定項目とフォルダの役割 入力フォルダは`docs_dir`（既定`docs`）、出力フォルダは`site_dir`（既定`site`）で指定します。既定のままで問題ないことがほとんどですが、モノレポでフォルダ構成を変えたいときにこれらを明示します。 | キー | 役割 | 既定値 | | ---------- | --------------- | ------- | | site\_name | サイトのタイトル | My Docs | | docs\_dir | Markdownの入力フォルダ | docs | | site\_dir | ビルド出力フォルダ | site | | theme | 使用テーマ | mkdocs | | nav | メニュー構成 | 自動生成 | `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とは？できること・使い方・料金をわかりやすく解説](/tech/details/5875/)で詳しく整理しています。 ### 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構築方法](/tech/details/4397/)も参考になります。 ### 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とは？できること・使い方・料金をわかりやすく解説](/tech/details/5875/) - [静的サイトジェネレーターを活用したGitHub Pages構築方法](/tech/details/4397/) --- 出典: [MkDocsの使い方｜インストールからMaterialテーマ・日本語対応・GitHub Pages公開まで【2026年版】]()（株式会社一創）