2
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@yosei_ikegami(耀星)

MkDocsで仕様書を読みやすくする。構成・Mermaid・公開手順

2
Last updated at Posted at 2026-02-02

1. はじめに

Markdownの仕様書は、ページが増えると読む順序が分かりづらくなります。
概要・機能・画面・APIを別ファイルにしても、読む順序や関係が伝わらなければ、初めて見る人は迷います。

MkDocsを使うと、Markdownを目次・検索付きのWebサイトにできます。
タスク管理システムの仕様書を例に、導入、ページの整理、図・表の追加、GitHub Pagesでの公開を説明します。

この記事で扱うこと 作れるもの
MkDocsの導入 手元で確認できるドキュメントサイト
ページと目次の整理 概要から詳細へ進める仕様書
MaterialとMermaidの設定 検索・表・画面遷移図があるサイト
GitHub Actionsでの公開 更新内容を自動反映する公開サイト

完成イメージはタスク管理システムの仕様書サンプルです。
これは仕様書の構成例で、タスク管理アプリの操作デモではありません。
PythonとGitを使える環境が前提です。公開にはGitHubアカウントも必要です。

2. MkDocsの仕組みと用途

MkDocsは、MarkdownからHTMLを生成するPython製のツールです。
文章や図の元データをGitで管理し、生成したサイトをブラウザで読めます。

ファイル・フォルダ 役割 普段の作業
docs/ ページの元になるMarkdown 文章・表・図を編集
mkdocs.yml サイト名・テーマ・目次などの設定 ページを追加したら目次も更新
requirements.txt 必要なPythonパッケージ 手元と公開処理で同じ依存定義を使用
site/ ビルドしたサイト 生成物として扱い、直接編集しない

2.1 仕様書の管理でできること

整理前の困りごと MkDocsでの整理後
長い1ファイルから目的の仕様を探す 概要・機能・画面・APIをページに分ける
ファイル名だけでは読む順序が分からない navで表示名と順序を決める
編集後の表示が分からない mkdocs serveで保存後の表示を確認する
仕様の変更理由を追いづらい Gitの差分・履歴とレビューで確認する

検索機能はMkDocs標準テーマでも利用できます。
Material for MkDocsを使うと、ナビゲーションやコード表示を整えやすく、Mermaidの図も組み込めます。

2.2 他の方法との使い分け

方法 合う場面 考慮すること
GitHub上でMarkdownを読む 少数ページをコードと一緒に管理 読む順序や案内を自分で整理
Wiki・共同編集サービス ブラウザで複数人が文章を編集 権限・履歴・運用方法はサービスごとに確認
MkDocs 複数ページの技術文書をGitでレビュー Python環境とビルド・配信の設定が必要

MarkdownとGitで仕様を管理するチームなら、MkDocsを選びやすいです。
非エンジニアが頻繁に共同編集する場合は、編集方法も含めて比較するとよいと思います。

3. 導入とローカルプレビュー

3.1 仮想環境にインストールする

既存のPython環境と分けるため、仮想環境を使います。
次のコマンドで作業用フォルダと仮想環境を作ります。

# 作業フォルダと仮想環境を作る
mkdir my-spec
cd my-spec
python -m venv .venv

仮想環境を有効にするコマンドはOSによって異なります。

macOS / Linux

# 仮想環境を有効にする
source .venv/bin/activate

Windows PowerShell

# 仮想環境を有効にする
.\.venv\Scripts\Activate.ps1

環境によっては、pythonをmacOS / Linuxではpython3、Windowsではpyに読み替えてください。

次に、requirements.txtを作成します。

# MkDocs本体とMaterialテーマ
mkdocs>=1.6,<2
mkdocs-material>=9,<10

# 依存パッケージを入れ、現在のフォルダに雛形を作る
python -m pip install -r requirements.txt
python -m mkdocs new .
python -m mkdocs serve

http://127.0.0.1:8000を開きます。
docs/index.mdを編集・保存して表示が変われば、導入は完了です。

プレビューを終了するときは、実行中のターミナルで Ctrl+C を押します。
後のビルドコマンドも同じターミナルで実行できます。

この依存定義はバージョン範囲を指定する例です。
同一バージョンでの再現が必要な運用では、動作確認したバージョンを固定します。

3.2 トップページの設定

mkdocs.ymlを次の内容に置き換えます。
この時点では、雛形で作られたindex.mdだけを目次に載せます。

# まずは存在するトップページだけを設定する
site_name: タスク管理システム 仕様書
theme:
  name: material
  language: ja
  features:
    - navigation.footer
    - search.highlight
    - content.code.copy
nav:
  - はじめに・読み方: index.md

navigation.footerは前後のページへのリンク、content.code.copyはコードのコピーボタンを有効にします。
複数ページに分けた後も、読む順番を追いやすくなります。

4. ページ構成と内部リンク

最初のページでは、何のシステムか、誰が使うか、どの順に読むかを説明します。
詳細を読む前に、トップページで全体像を確認できるようにします。

ページ 答える問い タスク管理の例
はじめに・読み方 このサイトは何か。どこから読むか 仕様書のサンプル、読者別の案内
目的と対象範囲 何を解決し、何を含めるか 作業の共有。添付・コメントは対象外
用語とステータス 言葉の意味は何か タスク、担当者、未着手・進行中・完了
機能一覧 何ができるか 一覧・登録・編集・検索
画面仕様 どう操作するか 画面遷移、入力項目、保存後の動き
API仕様 どんなデータを送受信するか 呼び出し先、JSON、応答

次の構成で、各Markdownファイルに見出しと本文を用意します。

my-spec/
├── mkdocs.yml
├── requirements.txt
└── docs/
    ├── index.md
    ├── overview.md
    ├── glossary.md
    ├── api.md
    └── features/
        ├── list.md
        └── screens.md

たとえば、docs/overview.mdにはサンプルの目的と対象範囲を短く書きます。
Markdownの # はページの見出し、## はページ内の小見出しです。

<!-- docs/overview.mdの記入例 -->
# 目的と対象範囲

チーム内の作業を一覧に集め、担当者・期限・進捗を共有するシステムです。

## 対象に含めるもの

- タスクの登録・編集・ステータス変更・削除
- 一覧・フィルタ・検索・ソート

## 対象外

- ファイル添付・コメント

他のページも、表の「答える問い」に沿って見出しと本文を用意します。

ファイルを作った後、mkdocs.ymlのnavを次に置き換えます。

# パスはdocs/を基準に指定する
nav:
  - はじめに・読み方: index.md
  - 1. 全体像をつかむ:
      - 目的と対象範囲: overview.md
      - 用語とステータス: glossary.md
  - 2. 操作を理解する:
      - 機能一覧と確認観点: features/list.md
      - 画面遷移と入力項目: features/screens.md
  - 3. APIを確認する: api.md

navを省略すると、MkDocsがMarkdownファイルから目次を自動生成します。
navを指定した場合、そこに書かなかったページは目次に出ませんが、通常はビルドされます。
目次から外すことは、非公開にすることではありません。

画面仕様からAPIの入力項目へ、機能一覧から該当画面へリンクすると、関連情報も探しやすくなります。
docs/features/list.mdからリンクを書く例です。

<!-- 元のMarkdownファイルへの相対パスでリンクする -->
[タスク登録の画面仕様](screens.md#タスク登録)
[登録API](../api.md#タスク登録)

日本語の見出しをそのままリンク先に使う場合は、mkdocs.ymlに次も追加します。
後からmarkdown_extensionsを追加するときは、このtoc設定も同じ一覧に残してください。

# 日本語の見出しからリンク用IDを生成する
markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

5. 表とMermaidの図

表は項目の比較、図は順序や関係の説明に使います。
図の直後に何を示す図かを一文添えると、読み取り方が伝わります。

説明する内容 向いている表現
入力項目・必須・制約・初期値 表
画面の移動、処理の分岐 フローチャート
状態の変化 状態遷移図
APIの呼び出しと応答の順序 シーケンス図

5.1 Mermaidの設定

mkdocs.ymlの markdown_extensions を次の内容に置き換えます。
4章の日本語見出し用の設定も含めています。同じ名前の設定をもう1つ追加しないでください。
Material for MkDocsのMermaid連携を使う設定です。

# Mermaidコードブロックを図として表示する
markdown_extensions:
  - tables
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

この設定では、Materialが必要なJavaScriptを読み込むため、Mermaid用のスクリプトを別途追加する必要はありません。
詳細はMaterial公式の図の設定を参照してください。

5.2 画面遷移図

Markdownファイルに次のように書きます。

<!-- 一覧から登録・編集へ進む流れ -->
```mermaid
flowchart TD
    A["タスク一覧"] -->|新規登録| B["タスク登録"]
    B -->|登録成功| A
    A -->|行をクリック| C["タスク編集"]
```

表示される図は次のとおりです。

この図は、一覧画面から登録・編集へ移動する流れを示しています。
更新後・削除後の遷移先も決まっているなら、図と文章の両方に追記します。

5.3 入力項目の表

「タイトルは必須、担当者も必須、期限は任意」と文章で並べるより、列をそろえると確認しやすくなります。

項目 必須 制約 初期値
タイトル 必須 最大100文字 要確認
担当者 必須 ユーザーを選択 要確認
期限 任意 日付 要確認
優先度 任意 高・中・低 中

未確定の値を例から推測して埋めると、実装者が確定仕様として扱うおそれがあります。
決まっていないことは「要確認」と書き、何を決める必要があるかを残します。

サンプルでは、画面の更新・削除に対する公開APIが未定義であることや、検索対象の記載の違いも明記しています。
図や表を増やすときは、関連ページで同じ項目や条件を書いているかも確認します。

5.4 完成したmkdocs.yml

ここまでの設定と、次章で使うリンク検査をまとめると次のようになります。
設定の追加先に迷った場合は、この内容で mkdocs.yml を置き換えてください。
navに指定したMarkdownファイルを作成済みであることが前提です。

# ページの目次・テーマ・図・リンク検査をまとめた設定
site_name: タスク管理システム 仕様書

theme:
  name: material
  language: ja
  features:
    - navigation.footer
    - search.highlight
    - content.code.copy

nav:
  - はじめに・読み方: index.md
  - 1. 全体像をつかむ:
      - 目的と対象範囲: overview.md
      - 用語とステータス: glossary.md
  - 2. 操作を理解する:
      - 機能一覧と確認観点: features/list.md
      - 画面遷移と入力項目: features/screens.md
  - 3. APIを確認する: api.md

markdown_extensions:
  - tables
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

validation:
  links:
    anchors: warn

6. GitHub Pagesへの公開

ここではサンプルと同じ、ビルド結果をgh-pagesブランチへ配置する方法を使います。
GitHubにリポジトリを用意し、docs/・設定・依存定義を管理している前提です。

6.1 公開前のビルド確認

# 警告があれば失敗させ、公開前に問題を見つける
python -m mkdocs build --strict

リンクの見出しまで確認したい場合は、mkdocs.ymlに次を追加します。
この設定はMkDocs 1.6以降を前提にしています。

# 存在しない見出しへのリンクを警告にする
validation:
  links:
    anchors: warn

--strictは、MkDocsが出した警告をエラーとして扱う指定です。
Mermaidの描画はブラウザで行うため、ビルド成功後も図を開いて確認します。

6.2 公開ワークフローとPagesの設定

.github/workflows/deploy.ymlを作ります。
次はサンプルリポジトリの公開方法に合わせた例です。

# mainの更新をビルドし、生成したサイトをgh-pagesへ配置する
name: Deploy MkDocs to GitHub Pages
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: python -m pip install -r requirements.txt
      - run: python -m mkdocs build --strict
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

requirements.txtもリポジトリに含めてください。
GITHUB_TOKENはGitHub Actionsが用意するトークンです。

  1. ワークフローを含む変更をmainへpushする。
  2. Actionsでワークフローの成功と、gh-pagesブランチの作成を確認する。
  3. Settings → Pages → Build and deploymentを開く。
  4. SourceでDeploy from a branchを選ぶ。
  5. Branchをgh-pages、フォルダを/ (root)にして保存する。
  6. Pages側の公開処理も成功したら、Visit siteから開く。

gh-pagesをまだ作っていないと選択できないため、初回のワークフロー成功後に設定します。
この手順は、PagesのSourceを「GitHub Actions」にする方式とは設定が異なります。
プロジェクトサイトのURLは、通常https://<ユーザー名>.github.io/<リポジトリ名>/です。

生成物のsite/と仮想環境の.venv/は、通常Gitの管理対象から外します。

6.3 非公開情報の取り扱い

GitHub Freeでは、GitHub Pagesは公開リポジトリで利用できます。
GitHub Pro・Teamなどでは非公開リポジトリでも利用できますが、リポジトリの非公開設定とサイトの閲覧制限は別です。

GitHub公式の注意事項でも、非公開リポジトリから作ったPagesサイトが公開される点が説明されています。
社内仕様書には、組織の閲覧制限や認証付きの配信先を確認してから使ってください。

7. 表示・公開トラブルの確認先

症状 確認すること
ページが目次に出ない navの記載、docs/からの相対パス、ファイル名
--strictでビルドに失敗する 最初に出た警告、存在しないページ・見出しへのリンク
Mermaidがコードのまま表示される custom_fencesの設定とコードブロックの言語名mermaid
図だけ表示されない 図の構文、ブラウザのエラー、必要なJavaScriptを読み込めるか
gh-pagesへ配置できない Actionsのログ、contents: write、組織側の制限
公開URLが404になる Pagesの公開元、Pages側の処理結果、プロジェクト名を含むURL
手元と公開先で表示が異なる 依存バージョン、ビルド結果、公開処理の完了

動作確認では、トップページからの読み順、内部リンク、検索、図の表示を確認します。
スマートフォンの幅で表と図が読めるかも見ると、公開後の迷いを減らせます。

参考文献

2
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?