ドキュメントの値を変数で管理するCLIツール「docvars」を作ってみた！

こんにちは、リテールアプリ共創部の戸田駿太です。

ドキュメントの値を変数で管理するCLIツール「docvars」を作りました。この記事ではツールの紹介と開発の背景についてお話しします。

https://github.com/ShuntaToda/docvars

docvarsとは

docvarsは、ドキュメントテンプレート内の{{変数}}をYAMLファイルの値で管理するCLIツールです。Markdown、HTML、TXT, CSVなど、あらゆるテキストベースのファイルに対応しています。
このツールを使うとドキュメントがコードのように変数管理できるようになります。

基本的な使い方

npx docvars ./templates ./output

たったこれだけで、templatesディレクトリ内のテンプレートファイルが処理され、outputディレクトリに出力されます。

テンプレート例

テンプレート（templates/proposal.md）

# {{project.name}} ご提案書

クライアント: {{client.name}} 様
担当者: {{client.contact}}
提出日: {{date}}

変数ファイル（variables.yaml）

project:
  name: 新規Webサイト制作

client:
  name: 株式会社ABC
  contact: 田中太郎

date: 2026年1月28日

出力結果（output/proposal.md）

# 新規Webサイト制作 ご提案書

クライアント: 株式会社ABC 様
担当者: 田中太郎
提出日: 2026年1月28日

ネストしたオブジェクトはドット記法（project.name）でアクセスできます。配列を使う場合はインデックス記法（items.0、items.1）でアクセスします。

なぜ作ったのか

課題：ドキュメント内の値の重複管理

まとまったドキュメントを書くときに同じ値や名前を複数のファイルにまたがって記載することがよくあります。

• 提案書・企画書: 概要、詳細仕様、見積もり、スケジュールにクライアント名やプロジェクト名
• イベント資料: 招待状、プログラム、参加者ガイドにイベント名や日時、会場
• 設計書: 各ドキュメントにシステム名やバージョン、担当者名

これらの値が変更になるたび、全てのファイルを手動で更新する必要があります。更新漏れが発生しやすく、ドキュメント間で情報が不整合になるリスクがあります。

実体験としてチームメンバーのレビューで値が違うことに気づくこともありました。

課題：AIでドキュメントを書くときの影響範囲

最近はAIでドキュメントを書くシーンも増えました。しかし、AIが修正を加えたとき、どこを変更してどこに影響が出たのかが分かりづらいことがあります。

変数として値を管理しておけば、この変数がどのファイルで使われているかが明確になります。AIに修正を依頼するときも、変数ファイルを変更するだけで済むため、意図しない箇所が書き換わるリスクを減らせます。

既存ツールとの違い

似たようなツールは存在しますが、以下の点で不満がありました。

• 特定形式専用: Markdown以外（HTMLやTXTなど）に対応していない
• 複雑すぎる: 単純な変数置換をしたいだけなのに、大きなツールを導入するのは過剰
• 設定が面倒: 設定ファイルの記述量が多い
• 依存関係が分かりづらい: どの変数がどのファイルで使われているか把握しにくい

docvarsは「変数の置換と管理をする」ということだけをシンプルにするツールとして作りました。

何が解決できるのか

一元管理で更新漏れを防ぐ

変数をYAMLファイルに一元管理することで、値の重複を排除できます。

# variables.yaml - ここだけ更新すればOK
project:
  name: 新規Webサイト制作
client:
  name: 株式会社ABC
  contact: 田中太郎

クライアント名や担当者が変わっても、このファイルを1箇所変更するだけで全てのドキュメントに反映されます。

主な機能

変数ファイルの指定

デフォルトではvariables.yamlを参照しますが、--vars（-v）オプションで別のファイルを指定できます。

# A社向け
npx docvars ./templates ./output --vars client-a.yaml

# B社向け
npx docvars ./templates ./output --vars client-b.yaml

ファイルのフィルタリング

--only（-o）と--exclude（-e）オプションでファイルを選択できます。

# Markdownファイルのみ処理
npx docvars ./templates ./output --only "**/*.md"

# ドラフトファイルを除外
npx docvars ./templates ./output --exclude "draft-*.md"

ウォッチモード

--watch（-w）オプションでファイルの変更を監視し、自動でリビルドします。

npx docvars ./templates ./output --watch

テンプレートや変数ファイルを編集すると、即座に出力が更新されます。ドキュメントを書きながらリアルタイムで確認できるので便利です。

変数のリネーム

--rename-from（-F）と--rename-to（-T）オプションで、変数名を一括変更できます。テンプレートファイルと変数ファイルの両方が更新されます。

# 単純なリネーム
npx docvars ./templates ./output --rename-from "name" --rename-to "title"

# プレフィックス付きリネーム（client.* → customer.*）
npx docvars ./templates ./output --rename-from "client" --rename-to "customer"

変数一覧の表示

--list-vars（-l）オプションで、テンプレートで使用されている変数の一覧を確認できます。定義済み・未定義・未使用の変数が一目でわかります。

npx docvars ./templates ./output --list-vars

出力例:

📋 Variables

┌─────────────────┬─────────────┬───────────┐
│ Variable        │ Value       │ Used in   │
├─────────────────┼─────────────┼───────────┤
│ project.name    │ example app │ README.md │
│ project.version │ 0.1.1       │ config.md │
└─────────────────┴─────────────┴───────────┘

Summary: 2 defined · 0 undefined · 0 unused

ドライラン

--dry-run（-d）オプションで、実際にファイルを書き込まずに変更内容をプレビューできます。

npx docvars ./templates ./output --dry-run

使い方のコツ

変数名で値が想像できるようにする

変数が記載されたファイルを読んだときに、ある程度その変数の値が予測できるような名前にすると、ドキュメントを書くときに楽です。

<!-- 分かりにくい例 -->
クライアント: {{c}} 様
担当者: {{p}}

クライアント: {{client.1}} 様
担当者: {{client.2}}

<!-- 良い例 -->
クライアント: {{client.name}} 様
担当者: {{client.contact}}

また、配列（ {{items.0}}、{{items.1}}など ）は何番目に何が入っているか分かりにくくなるため、できるだけ避ける方がいいです。

変数名を変えたくなったら、-Fと-Tオプションで簡単にリネームできます。

小規模ドキュメントがちょうどいい

docvarsはYAMLで変数を定義するため、変数が多くなりすぎると逆に管理が難しくなります。

提案書一式、イベント資料一式など、自分のPC内で作業する小〜中規模のドキュメントに使うのがちょうどいいと思います。

おわりに

docvarsは、シンプルな課題をシンプルに解決するツールとして作りました。提案書、イベント資料、設計書など、複数ファイルで同じ値を管理する場面でドキュメントをコードのように管理することができます。
実際に使うと便利さに気づけると思うので、ぜひ使ってみてください！

https://github.com/ShuntaToda/docvars