生成AI時代のドキュメント基盤¶
このリポジトリは、以下の2つをサンプルとして提供する。
- ドキュメントを記述する基盤（Markdown + Mermaid + Draw.io + textlint + MkDocs）
- 記述した文書を公開する仕組み（GitHub Pages / Azure Blob Storage静的サイト）
採用している技術の一覧は 技術スタック を参照する。
3つの実行環境¶
用途に応じて、次の3形態でドキュメント執筆環境を利用できる。
| 形態 | 想定用途 | 前提 |
|---|---|---|
| ローカル（Linux / WSL） | 普段の執筆・プレビュー | miseでツールを揃える |
| DevContainer | VS Code で隔離環境を使いたい | Docker + VS Code + Dev Containers拡張 |
| code-server | ブラウザだけでハンズオンしたい | Docker（ローカル）または Azure（配布） |
ローカル環境（Linux / WSL）¶
mise.tomlでPython / uv / Node.js / pnpmのバージョンを固定している。以下の手順でツールを揃える。
1.mise のインストール¶
curl https://mise.run | sh
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
exec "$SHELL"
2.依存関係のインストール¶
Debian / Ubuntu系ではまずWeasyPrintやPlaywrightのネイティブ依存（Chromium、Pango、Cairo、日本語フォントなど）をaptで導入する。sudoが必要で、初回のみ実行する。
mise run setup-system
続いてランタイムとPython / Nodeの依存関係をまとめて取得する。
mise run setup # mise install / uv sync / Playwright / pnpm install をまとめて実行
macOSやWindows、その他のディストリビューションでは setup-systemは対象外である。該当環境ではネイティブ依存を個別に導入する必要があるため、DevContainerまたはcode-serverの利用を推奨する。
3.ドキュメントのプレビュー¶
pnpm mkdocs # http://127.0.0.1:8000 でライブプレビュー
DevContainer¶
VS CodeのDev Containers拡張を導入し、リポジトリを開いた際に表示される「Reopen in Container」を選ぶと、.devcontainer/devcontainer.jsonが .devcontainer/Dockerfileをビルドして起動する。
当DockerfileはGHCRに公開済みの下記ハンズオンイメージをベースにしており、ビルドはベースイメージのpullのみで完了するためホスト側にmiseやPythonを入れずに同じツール構成で作業できる。
- ghcr.io/genai-docs/genai-docs-env:latest
ポート8000は自動フォワードされ、MkDocsライブプレビューにブラウザでアクセスできる。
code-server（ブラウザ版 VS Code）¶
ハンズオン配布や、ローカルに開発ツールを入れたくない場合に使う。実行環境（Dockerイメージ定義、起動・ Azureデプロイスクリプト、Bicep、CI）は別リポジトリ genai-docs/genai-docs-env に切り出している。該当リポジトリで nr run:local / nr run:remote / nr azure:deploy を実行する。
当リポジトリのDevContainerは同イメージ ghcr.io/genai-docs/genai-docs-env:latest をベースとして使うため、イメージ更新はenvリポジトリ側で完結する。
Azure上に共有ハンズオン環境を展開する手順は実行環境にまとめている。