ドキュメントサイトデータの一元管理：`site.json`の導入

2026年05月07日 01:23 JST shoelace-style/webawesome

https://github.com/shoelace-style/webawesome/pull/2359

WebAwesomeのドキュメントサイトに _data/site.json を新設し、ブランド名・メールアドレス・SNS URL・GitHub URL・法的リンクパスといった繰り返し使われる文字列を一箇所に集約しました。約54ファイルに散在していたハードコード値が {{ site.* }} テンプレート参照に置き換えられ、将来的な変更コストが大幅に低減されます。

背景

ドキュメントを構成する多数の .njk / .md ファイルに、メールアドレス・SNSリンク・GitHubリポジトリURLなどの文字列がそのままハードコードされていました。たとえば hello@webawesome.com や https://github.com/shoelace-style/webawesome は 503.md・sidebar-colophon.njk・community.md など複数のファイルに重複して記述されており、一箇所の変更が全ファイルの修正を要する状態でした。

ブランド名についても同様で、"Web Awesome Pro" という文字列が各所に直書きされていたため、表記を統一・変更する際の影響範囲の把握が困難でした。

技術的な変更

packages/webawesome/docs/_data/site.json を新規追加し、サイト全体で共有するデータを6つのカテゴリに整理しています。

{
  "name": "Web Awesome",
  "nameCore": "Web Awesome Core",
  "namePro": "Web Awesome Pro",
  "tagline": "Go Make Something Awesome!",
  "company": "Fonticons, Inc.",
  "domain": "webawesome.com",

  "siblings": {
    "fontAwesome": { "name": "Font Awesome", "url": "https://fontawesome.com" },
    "buildAwesome": { "name": "Build Awesome" }
  },

  "urls": {
    "discord": "https://discord.gg/mg8f26C",
    "x": "https://x.com/webawesomer",
    "bluesky": "https://bsky.app/profile/webawesome.com",
    "mastodon": "https://mastodon.social/@webawesome",
    "threads": "https://www.threads.com/@web.awesome",
    "support": "/docs/resources/support"
  },

  "github": {
    "repo": "https://github.com/shoelace-style/webawesome",
    "issues": "https://github.com/shoelace-style/webawesome/issues",
    "discussions": "https://github.com/shoelace-style/webawesome/discussions",
    "ideas": "https://github.com/shoelace-style/webawesome/discussions/categories/ideas-suggestions",
    "helpSupport": "https://github.com/shoelace-style/webawesome/discussions/categories/help-support",
    "stargazers": "https://github.com/shoelace-style/webawesome/stargazers"
  },

  "emails": {
    "hello": "hello@webawesome.com",
    "help": "help@webawesome.com",
    "privacy": "privacy@webawesome.com",
    "dpo": "dpo@awesome.me"
  },

  "legal": {
    "licenseCore": "/license",
    "licensePro": "/license/pro",
    "privacy": "/privacy",
    "tos": "/tos",
    "refunds": "/refunds"
  }
}

Eleventyの _data/ 規約 により、このファイルは自動的にテンプレートのグローバルデータとして読み込まれ、全ての .njk / .md ファイルから {{ site.* }} 形式でアクセスできます。既存のビルドマージの仕組みによって、docsバンドルへの伝播も自動的に行われます。

各ファイル側の変更は、ハードコード値をテンプレート参照に置き換えるのみです。たとえば sidebar-colophon.njk では次のように変わります。

変更前:

<a href="https://github.com/shoelace-style/webawesome" rel="noopener noreferrer" target="_blank">
  <wa-icon family="brands" name="github" label="GitHub"></wa-icon>
</a>
<a href="https://discord.gg/mg8f26C" rel="noopener noreferrer" target="_blank">
  <wa-icon family="brands" name="discord" label="Discord"></wa-icon>
</a>

変更後:

<a href="{{ site.github.repo }}" rel="noopener noreferrer" target="_blank">
  <wa-icon family="brands" name="github" label="GitHub"></wa-icon>
</a>
<a href="{{ site.urls.discord }}" rel="noopener noreferrer" target="_blank">
  <wa-icon family="brands" name="discord" label="Discord"></wa-icon>
</a>

なお、フロントマター・<title>/<meta> タグ・コードブロック・フィクスチャデータはリテラルのままとされており、テンプレート参照への置き換えは意図的に対象外とされています。

設計判断

Eleventyの _data/ 規約を活用することで、フレームワークの既存の仕組みに乗る形でデータ集約が実現されています。 専用のプラグインや設定変更を加えることなく、JSONファイルを配置するだけでグローバルデータとして機能するEleventyの特性を最大限に利用した設計です。

データ構造はフラットなキーバリューではなく、urls・github・emails・legal・siblings といるカテゴリで階層化されています。これにより、site.github.issues のようにコンテキストが明確なパスでデータにアクセスでき、テンプレート内での意図が読み取りやすくなっています。

またPR説明では、フロントマターやコードブロック内のリテラルは意図的に変更対象から除外されたことが明記されています。これはテンプレートエンジンの処理対象外となる箇所や、ドキュメントのサンプルとして示す目的のコードに {{ site.* }} を混入させないための判断と読み取れます。

まとめ

_data/site.json の導入により、WebAwesomeドキュメントサイトの繰り返し文字列が単一の真実の源（Single Source of Truth）に集約されました。Eleventyの規約に沿った最小限の変更でありながら、ブランド名・URL・メールアドレスの一括管理という保守性の向上をもたらす変更です。