mkdocs等ドキュメントサイト生成

docs-as-code という考え方

ドキュメントサイト生成ツール(mkdocs・Docusaurus・Sphinx・VitePress など)は、リポジトリ内の Markdown をそのままWebサイトへ変換します。共通する前提は「文書をコードと同じ流儀で扱う」ことです。

従来の文書管理docs-as-code
共有ドライブに Word/Excelリポジトリ内の .md
更新履歴が追えない[[Git]] の履歴で誰がいつ何を変えたか分かる
レビューは口頭かメール[[コードレビュー]] と同じ仕組みで差分レビュー
公開は手作業でアップロード[[CI/CD]] が変更のたびに自動公開

コードと文書が同じPRに入ることが最大の利点です。仕様を変えた人が同じ変更で文書も直せるため、実装と説明のずれが起きにくくなります。

mkdocsの構成

設定は1つのYAMLに集約されます。

site_name: TerraSketch Docs
theme:
  name: material
nav:
  - はじめに: index.md
  - 使い方:
      - 基本操作: guide/basic.md
      - 応用: guide/advanced.md

nav に書いた順序がそのままサイトの目次になります。ファイルを置いただけでは目次に出ない(設定によっては自動収集もできる)ため、追加したのに見つからないときはここを疑います。

主要テーマは全文検索を標準で備えており、Markdown から抽出した索引をブラウザ側で引きます。サーバーを用意せずに検索が効くのは、静的サイトとして配布できることの利点です。

何を選ぶか

  • mkdocs — 設定がYAML1枚。Python製。手順書・社内文書に向く
  • Docusaurus — Reactベース。バージョン別文書や多言語([[国際化(i18n)]])の仕組みが標準
  • Sphinx — Pythonのdocstringから API リファレンスを生成できる
  • VitePress — Vueベース。ライブラリのドキュメントで採用が多い

選定基準は誰が書くかです。書き手が非エンジニアを含むなら設定の少ないものを選び、開発者だけならフレームワークに合わせるのが自然です。

公開と運用

生成物は静的ファイルなので、[[ホスティングとレンタルサーバー]] の選択肢はほぼ何でも使えます。GitHub Pages への公開を [[CI/CD]] に載せるのが定番です。

  • リンク切れを検査する — 文書が増えるほど内部リンクが壊れます。ビルド時に検出する設定を入れます
  • [[SEOの技術基礎]] を意識する — 検索から直接来る読者が多い媒体です。ページタイトルと見出し構造が入口になります
  • 公開範囲を確認する — 社内向けの内容が入っていないかを、公開の自動化を入れる前に確認します

初学者向けポイント

  • まず docs/ にある既存の Markdown をそのまま出すところから始めます。書き直しは後で構いません
  • 画像やリンクの相対パスはサイト上の階層で解決されます。リポジトリ上で正しくてもサイトで壊れることがあるため、ビルドしたものを実際に見て確認します
  • [[ドキュメンテーション]] は書く量より探せることが価値を決めます。目次と検索が効いているかを最初に確かめます

関連技術とのつながり

  • [[ドキュメンテーション]] — 何を書くかの指針。ツールはそれを届ける手段
  • [[Git]] — 文書の変更履歴とレビューの土台
  • [[CI/CD]] — 変更のたびにビルドして公開する自動化
  • [[ホスティングとレンタルサーバー]] — 静的ファイルなので配布先を選ばない
  • [[SEOの技術基礎]] — 検索から直接訪れる読者への入口設計
Q: docs-as-code の利点として正しいのはどれ?
- [ ] 文書を書く量が減る
- [x] コードと文書を同じPRで変更でき、実装と説明のずれが起きにくい
- [ ] Markdownを書かなくてよくなる
解説: 同じリポジトリ・同じレビュー経路に載せることで、仕様を変えた人が同じ変更で文書も直せます。

Q: mkdocsで追加したページが目次に出ないとき、まず確認する場所はどれ?
- [ ] テーマのCSS
- [x] 設定ファイルの `nav`
- [ ] ホスティング先の設定
解説: `nav` に書いた順序がそのまま目次になります。ファイルを置いただけでは並びません。

Q: ドキュメントサイト生成ツールを選ぶ基準として妥当なのはどれ?
- [ ] 生成が最も速いもの
- [x] 誰が書くか(非エンジニアを含むなら設定の少ないもの)
- [ ] 一番新しいもの
解説: 書き手が継続して更新できるかが文書の価値を決めます。