生成AI時代のドキュメント基盤¶

生成AI時代におけるドキュメント基盤のテンプレート。

Markdown文書を静的サイトジェネレーターでHTMLに変換・公開することで、次を実現する。

Markdownによる文書記述
Mermaidによる図表作成
Draw.ioによるSVG図表作成
GitHub Pages*1 もしくは Azure Static Web Apps（以降SWA）による正式文書公開
Pull Request時にSWAでのプレビュー
GitHubリポジトリの権限に応じたセキュリティ管理*1
GitHub Discussionsを通じた新規ユーザーへの招待・承認フロー*2

1: GitHub Pagesでリポジトリ権限に応じた閲覧制御を行うには、GitHub Enterpriseプランが必要 2: SWAへのアクセス権限はGitHub Discussionsの招待を承認することで付与される

技術スタック¶

技術	用途
Python + uv	MkDocs の実行環境と依存関係管理
MkDocs + Material for MkDocs	静的サイトジェネレーター
MkDocs プラグイン群	Mermaid の SVG/PNG 変換、PDF 出力、表読込
Node.js + pnpm	Marp と textlint の実行基盤
Mermaid	Markdown内での図表作成
Draw.io	SVG図表作成
Marp	Markdownスライド作成
Playwright	Mermaid 変換時のブラウザ自動化
WeasyPrint	PDF生成
textlint	ドキュメント品質チェック

外部リソース¶

技術スタック¶

Markdown
MkDocs(Material for MkDocs): 静的サイトジェネレーター
Mermaid: 図表作成ライブラリ
Draw.io（diagrams.net）: SVG描画ツール
Marp: Markdownプレゼンテーションツール

利用サービス・ツール¶

Coding Agent（Codex CLI, Claude Code, GitHub Copilotなど）
GitHub
GitHub Actions
Azure Static Web Apps
swa-github-repo-auth
Visual Studio Code
Draw.io Integration
テキスト校正くん
MkDocs
Python
uv
mkdocs-mermaid-to-svg
mkdocs-svg-to-png
mkdocs-to-pdf
mkdocs-table-reader-plugin
Marp
Node.js
Excel
CopyToMarkdownAddIn

以下、T.B.D

🚀 セットアップ¶

前提条件¶

Windows 10/11
PowerShell 5.1 以上
インターネット接続（パッケージダウンロード用）

自動セットアップ¶

管理者権限でPowerShellを起動し、以下のコマンドを実行してください：

.\scripts\Setup-Environments.ps1

このスクリプトは以下を自動でインストール・セットアップする：

Python 3.13
uv（Python環境管理）
Node.js
Mermaid CLI
GTK+ Runtime（PDF生成用）
プロジェクト依存関係

手動セットアップ¶

リポジトリのクローン

git clone <repository-url>
cd DocumentationStrategy

Python環境のセットアップ
```
uv sync
```
開発サーバーの起動
```
uv run mkdocs serve
```
ブラウザでアクセス
```
http://localhost:8000
```

📝 使用方法¶

ローカル開発¶

# 開発サーバー起動
uv run mkdocs serve

# 本番ビルド
uv run mkdocs build

# PDF生成
uv run mkdocs build --config-file mkdocs.yml

ドキュメント編集¶

docs/ ディレクトリ内のMarkdownファイルを編集
Mermaid図表は、コードブロック内で mermaid 言語を指定
変更は自動的にライブリロードで反映

新しい図表の追加¶

```mermaid
graph TD
    A[開始] --> B[処理]
    B --> C[終了]
```

📁 プロジェクト構造¶

DocumentationStrategy/
├── docs/                          # ドキュメントソース
│   ├── 01.システム設計/           # システム設計関連
│   ├── プロセス・フロー/          # プロセス図表
│   ├── プロジェクト管理/          # プロジェクト管理図表
│   ├── stylesheets/               # カスタムCSS
│   └── index.md                   # トップページ
├── scripts/                       # セットアップスクリプト
├── mkdocs.yml                     # MkDocs設定
├── pyproject.toml                 # Python依存関係
└── README.md                      # このファイル

🔧 設定¶

MkDocs設定（mkdocs.yml）¶

主要な設定項目：

テーマ: Material for MkDocs（日本語対応）
プラグイン:
mermaid-to-image: PDF出力用の図表変換
to-pdf: PDF生成機能
拡張機能: Mermaid図表サポート、コードハイライト

Python依存関係（pyproject.toml）¶

MkDocs関連パッケージ
PDF生成用ライブラリ（WeasyPrint）
Mermaid図表処理プラグイン

📄 PDF出力¶

ビルド時に自動的にPDFが生成される：

uv run mkdocs build

生成されたPDF: site/pdf/ドキュメンテーション戦略.pdf

🤝 コントリビューション¶

このリポジトリをフォーク
フィーチャーブランチを作成
変更をコミット
プルリクエストを送信

🆘 トラブルシューティング¶

よくある問題¶

PDF生成エラー
GTK+ Runtimeがインストールされているか確認
WeasyPrintの依存関係を確認
Mermaid図表が表示されない
ブラウザのキャッシュをクリア
JavaScriptが有効になっているか確認
セットアップスクリプトが動作しない
PowerShellを管理者権限で実行
ExecutionPolicyを確認

サポート¶

問題が発生した場合は、GitHubのIssuesで報告すること。