はじめに
YAMLファイルを解析し、読みやすいHTMLドキュメントに変換するCLIツール 「YamlDocDock」 を開発しました。
npmパッケージとして公開しましたので、主な機能や使い方、そして開発の背景について紹介させていただきます。
作ったもの：YamlDocDock
YamlDocDock (ヤムルドックドック)
https://github.com/wavecre8/YamlDocDock
既存のYAMLファイルを解析し、モダンでインタラクティブなHTMLドキュメントを生成するツールです。
名前に込めた意味は "Document Docking"。
ソースとなる「YAMLファイル（構造）」に、「ガイドファイル（説明）」や「エイリアスファイル（表示名）」を ドッキング（結合） させて、一つのリッチなドキュメントを作り上げるイメージです。
デモ
※ サンプルページはこちらからも体験できます。
汎用的なYAMLファイル・CFnテンプレート・AWS CLIの取得結果などが、こんな感じの見やすいHTMLドキュメントへと爆速で変換できます。
主な特徴は以下の通りです。
- 🔒 セキュア: 解析はすべてローカルで行われ、ネットワーク上に情報を持ち出しません。
- ✨ 非破壊: ソースとなるYAMLファイルに手を加える必要はありません。
- 📝 ガイド機能: ソースYAMLとは別に、説明書き専用のYAMLファイル（ガイドファイル）を用意することで、詳細なドキュメントを付加できます。
- 🧩 モード駆動: 用途に合わせて解析ロジック（モード）を切り替えられます（例: cfnモード）。
なぜ作ったのか？（開発の背景）
すべては「Excel方眼紙によるパラメータ管理」へのアンチテーゼから始まりました。
現在のプロジェクトでは、AWSリソースの設定値を「Excel方眼紙のパラメータシート」で管理しています。
しかし、この運用には3つの大きな課題がありました。
- 本質的でない作業: 「設定値の管理」よりも、Excelの「見栄え（セル結合やレイアウト）」の調整に時間を奪われてしまう。
- 実態との乖離: Excelの更新を忘れると、即座に「嘘のドキュメント」と化す。
- AI活用への壁: Excel方眼紙は機械可読性が低く、今後のAI協業時代において資産として活用しにくい。
「ならば、正本であるYAMLファイル（ AWS CLIの出力やIaCコード）に直接コメントを書けばいいのでは？」
当初はそう考えましたが、これも本質的な解決にはなりませんでした。
正本ファイルに直接説明を書き込むと、以下の新たな問題が発生するからです。
- AWS CLIで再取得すると、書いたコメントが消えてしまう
- 詳細な説明を書くほどファイルが肥大化し、全体像が把握しづらくなる
- 「値の変更」と「説明の変更」が混ざり、Gitの履歴がノイズで汚れてしまう
「Excelのような管理はしたくない。でも、ソースコードも汚したくない。」
このジレンマを解消するために辿り着いたのが、
「ソースには一切手を加えず、説明（ドキュメント）だけを外付けしてドッキングさせる」
というアプローチでした。
機能紹介
1. ガイド（解説）ドッキング機能
ソースYAMLと同じ構造を持つ「ガイドファイル」を用意するだけで、自動的に説明文がドッキングされます。
- 部分定義でOK: すべてのキーを網羅する必要はありません。説明が必要な箇所だけを記述した「ミニマムなYAML」で動作します。
-
リンク機能:
[表示名](URL)記法により、ドキュメント内の他パラメータへの相互リンクや、外部資料への誘導も可能です。
2. エイリアス（別名）ドッキング機能
システムが出力した設定ファイルや、YAMLの英語キー名は、直感的に意味を把握しづらいことがあります。
YamlDocDockでは、別途エイリアスファイルを定義することで、任意のキー名を表示することもできるようになっています。
難解な英語キーを馴染みのある日本語に置き換えることで、チーム全員が理解できるドキュメントにつながります。
# aliases/config_alias.yml
Resources:
MyVPC:
_alias: メインVPC 👈 ドキュメント上ではこう表示される
3. 複数ファイルのマージ
巨大なシステム定義は、機能ごとにファイルを分割して管理するのが一般的です。
しかし、ドキュメントまでバラバラでは一覧性が損なわれます。
YamlDocDockでは、複数のYAMLファイルをマージして1つのHTMLドキュメントとして出力できます。
「管理は分割、閲覧は統合」
これも開発時に重視したポイントです。
4. モード切り替え機能
YamlDocDockは、対象のYAMLファイルの種類に応じて最適な解析ロジックを切り替える「モード」という概念を持っています。
現在は以下の2つのモードを提供しています。
- generic (デフォルト): 標準的なYAMLファイル用
- cfn: AWS CloudFormationテンプレート用
cfn モードを指定すると、CloudFormation固有のタグ（!Ref や !Sub など）を認識し、関数やリソース参照をドキュメント上で自然な形で表示できるようになります。
使い方 (Quick Start)
Node.jsさえあれば、インストール不要ですぐに試せます。
1. プロジェクトで初期化
ドキュメント化したいYAMLがあるディレクトリで以下を実行します。
npx yamldocdock init
これで設定ファイル setting.config.yml が生成されます。
2. 設定ファイルの編集
setting.config.yml を編集して、対象のYAMLファイルを指定します。
lang: ja
index:
output: docs/index.html
title: ドキュメント一覧
pages:
- title: インフラ仕様書
mode: cfn # CloudFormationなら cfn, 通常なら generic
sources:
- ./cloudformation/vpc.yml
- ./cloudformation/ec2.yml
guideDir: guides
aliasDir: aliases
output: ./docs/infra.html
ここで指定した guideDir と aliasDir に配置したファイルは、ソースファイル名に基づいて自動的に関連付けられます。
-
ガイドファイル:
{ソースファイル名}_guide.yml(例:vpc_guide.yml) -
エイリアスファイル:
{ソースファイル名}_alias.yml(例:vpc_alias.yml)
3. ビルド
npx yamldocdock build
設定ファイルを明示的に指定する場合は -c オプションを使います。
npx yamldocdock build -c setting.config.yml
これだけで ./docs/infra.html と、それらをまとめたポータルページ ./docs/index.html が生成されます！
--watch オプションを付ければ、編集しながらリアルタイムプレビューも可能です。
おわりに
「Excel方眼紙の呪縛」 や 「ドキュメントのないYAML」 に苦しんでいる方がいましたら、ぜひ一度試してみてください。
もし気に入っていただけたら、GitHubでスター⭐️をいただけると開発の励みになります！
バグ報告や機能要望もIssueでお待ちしています。
使ってみた感想もコメントしていただけると今後の開発の参考になります。
Happy YAML Life!