静的サイトジェネレーターの検討

1. 目的

Markdownを中心に、技術、英語、健康、投資など複数テーマのコンテンツを継続的に公開するWebサイトを構築する。

以下を主な要件とする。

• Markdownでコンテンツを管理できること
• ページ数が数百～数千ページに増えても管理しやすいこと
• PCでは左側にサイドバー、右側にページ内目次を表示できること
• ディレクトリ単位の一覧ページを作成できること
• 一覧ページやサイドバーを柔軟にカスタマイズできること
• 日本語・英語の多言語サイトを構築できること
• 日本語と英語で異なるサイドバー構成を利用できること
• 日本語サイトでは日本語のみ、英語サイトでは英語のみ検索できること
• 必要に応じてカテゴリやディレクトリ単位で検索対象を絞り込めること
• SEOを考慮した構成にできること
• Google AdSenseを利用できること
• 画像やdraw.ioの構成図を利用できること
• Windows PC上でWSLを使用せず開発できること
• GitHubでコンテンツとソースコードを管理できること
• Cloudflare Pagesなどの静的サイトホスティングを利用できること
• 将来的にAIによる日本語から英語への翻訳を自動化できること

2. 検討した静的サイトジェネレーター

主に以下を比較した。

• Astro Starlight
• Hugo + Docsy
• Docusaurus
• Zensical
• MkDocs系ツール

最終的には Astro Starlightを第一候補とする。

3. Astro Starlightを選択する理由

3.1 Markdownを中心に管理できる

コンテンツはMarkdownまたはMDXで管理する。

例えば以下のような構成とする。

src/content/docs/
├── ja/
│   ├── tech/
│   │   ├── aws/
│   │   ├── terraform/
│   │   └── kubernetes/
│   ├── english/
│   ├── health/
│   └── investment/
│
└── en/
    ├── tech/
    │   ├── aws/
    │   ├── terraform/
    │   └── kubernetes/
    ├── health/
    └── investment/

ファイルおよびディレクトリ構造をコンテンツ分類の基本とする。

3.2 左サイドバーと右ページ内目次

PC表示では以下の3カラム構成を基本とする。

┌──────────────────────────────────────────────────────┐
│ Header                                               │
├──────────────┬─────────────────────────┬─────────────┤
│              │                         │             │
│ Sidebar      │       Content           │ On this page│
│              │                         │             │
│ Technology   │                         │             │
│  ├ AWS       │                         │             │
│  ├ Terraform │                         │             │
│  └ Kubernetes│                         │             │
│              │                         │             │
└──────────────┴─────────────────────────┴─────────────┘

Starlightは左サイドバーと右側のページ内目次を標準で提供する。

さらにAstroコンポーネントを利用することで、サイドバーやコンテンツ表示を柔軟に変更できる。

4. ディレクトリの一覧ページ

Hugo + Docsyでは _index.md を利用してセクションページを作り、配下ページの一覧を表示できる点が魅力だった。

Starlightには完全に同一の仕組みはないが、index.mdx と独自Astroコンポーネントを組み合わせることで同様の仕組みを実現できる。

例えば以下とする。

aws/
├── index.mdx
├── control-tower.md
├── organizations.md
├── iam-identity-center.md
└── vpc.md

index.mdx では共通コンポーネントを使用する。

---
title: AWS
description: AWSに関する記事一覧
---

<DirectoryIndex />

DirectoryIndex コンポーネントが現在のディレクトリを判定し、配下のMarkdownを自動取得して一覧表示する。

表示内容は例えば以下とする。

AWS

AWS Control Tower
AWS Control Towerによるマルチアカウント管理について解説します。

AWS Organizations
OrganizationsとOUの設計について解説します。

IAM Identity Center
IAM Identity Centerのユーザー・グループ管理について解説します。

一覧には必要に応じて以下を表示できる。

• タイトル
• description
• 更新日
• タグ
• アイコン
• カテゴリ

また、以下のような並び替えも実装できる。

• 任意の表示順
• タイトル順
• 更新日順

これにより、Hugo + Docsyの _index.md に近い使い勝手を維持しながら、一覧ページのデザインをより自由に変更できる。

5. サイドバー

基本的にはディレクトリ構造からサイドバーを自動生成する。

例えば、

Technology
├── AWS
├── Terraform
└── Kubernetes

English
Investment
Health

とする。

必要な箇所のみ手動設定や独自コンポーネントによってカスタマイズする。

コンテンツ追加時に、

aws/new-article.md

を追加するだけで、

• サイドバー
• AWS一覧ページ
• サイトマップ
• 検索インデックス

へ反映される構成を目指す。

6. 多言語化

同一ドメイン配下で日本語と英語を分離する。

example.com/ja/
example.com/en/

テーマはその下に配置する。

example.com/ja/tech/
example.com/ja/english/
example.com/ja/health/
example.com/ja/investment/

example.com/en/tech/
example.com/en/health/
example.com/en/investment/

サブドメインではなくサブディレクトリ方式を基本とする。

6.1 日本語と英語の情報構造

日本語と英語は必ずしも同一構成にしない。

例えば日本語サイトでは、

Technology
├── AWS
├── Terraform
└── Kubernetes

英語学習
投資
健康

英語サイトでは、

Technology
├── AWS
├── Cloud Security
└── Infrastructure Engineering

Finance

といった構成も可能とする。

つまり単純な翻訳サイトではなく、

同一ブランドの日本語サイトと英語サイト

として設計する。

日本語利用者と英語利用者で検索ニーズが異なるため、すべての日本語記事を英訳することは必須としない。

7. AI翻訳

日本語Markdownを原則としてSource of Truthとする。

日本語Markdown
       ↓
AI翻訳
       ↓
英語Markdown
       ↓
GitHub Pull Request
       ↓
レビュー
       ↓
Merge
       ↓
Build / Deploy

例えば、

src/content/docs/ja/tech/aws/control-tower.md

から、

src/content/docs/en/tech/aws/control-tower.md

を生成する。

日本語Markdownの更新を検出できるように、英語版に日本語原文のhashなどを保持する方式も検討する。

translation:
  source: ja
  source_hash: "52c7c6..."

日本語原文のhashと一致しない場合、英語版を「翻訳更新が必要」と判定できる。

将来的にはGit差分を利用して変更箇所だけAIに再翻訳させることも検討する。

完全自動公開ではなく、

AI翻訳
  ↓
Pull Request
  ↓
確認
  ↓
公開

を基本とする。

8. 検索

Starlight標準のPagefindを基本とする。

8.1 言語別検索

日本語ページでは日本語コンテンツのみを検索対象とする。

/ja/
 ↓
日本語検索インデックス

英語ページでは英語コンテンツのみを検索対象とする。

/en/
 ↓
英語検索インデックス

Pagefindの多言語インデックス機能を利用する。

8.2 カテゴリ・ディレクトリ検索

将来的には以下のような検索範囲を選択できるようにする。

検索範囲

○ サイト全体
○ Technology
○ AWS
○ Terraform
○ Kubernetes

ディレクトリ構造などから検索用メタデータを生成する。

例えば、

/ja/tech/aws/control-tower/

に対して、

section  = tech
category = aws

という情報を持たせ、Pagefindのfilter機能で絞り込む。

ページ数が数百～数千ページに増えても、まずはPagefindを利用する。

より高度な検索が必要になった場合は、Algoliaなどへの移行も検討する。

9. SEO

複数テーマは当初、同一ドメイン内のディレクトリで分離する。

example.com/ja/tech/
example.com/ja/english/
example.com/ja/health/
example.com/ja/investment/

テーマごとにサブドメインを分けることは初期段階では行わない。

各テーマを独立したセクションとして明確に構造化する。

多言語ページについては、日本語・英語ページの関係を検索エンジンへ適切に伝えられる構成とする。

また、健康や投資など信頼性が特に重要となるテーマについては、著者情報、根拠、出典などを明確にする。

10. Google AdSense

StarlightはAstroベースであるため、必要なHTMLやJavaScriptを追加できる。

そのためGoogle AdSenseの広告コードも配置可能である。

広告はコンテンツの可読性を損なわないように配置する。

11. 画像

Markdownから通常の画像を利用できる。

記事またはセクションの近くに images ディレクトリを配置することを基本とする。

例えば、

aws/
├── index.mdx
├── control-tower.md
└── images/
    ├── control-tower-architecture.drawio
    └── control-tower-architecture.svg

Markdownからは例えば以下のように参照する。

![AWS Control Tower構成](images/control-tower-architecture.svg)

巨大な共通imagesディレクトリへすべての画像を集約するのではなく、関連するコンテンツの近くに配置する。

12. draw.io

draw.ioファイルは編集用原本としてGitHubで管理する。

architecture.drawio
        ↓
draw.ioで編集
        ↓
SVGへエクスポート
        ↓
architecture.svg
        ↓
Markdownから参照

構成図などは原則SVGを利用する。

*.drawio  = 編集用原本
*.svg     = Web表示用

スクリーンショットや写真については、PNG、WebP、AVIFなどを用途に応じて利用する。

日英で同じ画像を利用できる場合は画像を共有する。

画像内に日本語・英語の文字が含まれる場合は、必要に応じて言語別画像を用意する。

13. Windows開発環境

WSLは使用しない。

Windowsネイティブ環境で開発する。

Windows 11
├── Windows Terminal / PowerShell
├── Git for Windows
├── Node.js
├── VS Code
└── Astro Starlight

リポジトリは例えば以下に配置する。

C:\git\my-site

ローカルでStarlightの開発サーバーを起動してブラウザから確認する。

DockerやWSLは必須としない。

14. GitHubとデプロイ

コンテンツ、設定、Astroコンポーネント、画像などをすべてGitHubで管理する。

基本的な流れは以下とする。

Windows PC
    ↓
Markdown編集
    ↓
Git commit / push
    ↓
GitHub
    ↓
Cloudflare Pages
    ↓
Starlight Build
    ↓
公開

AI翻訳を導入した場合は、GitHub Actionsなどを利用して翻訳用Pull Requestを生成することも検討する。

15. Hugo + Docsyとの比較

Hugo + Docsyも有力候補として検討した。

特に以下は魅力がある。

• _index.mdによるセクション管理
• 配下ページ一覧
• 左サイドバー
• 右ページ内目次
• Hugoの強力な多言語機能
• 高速な静的サイト生成

Pagefindを追加すれば、言語別検索やカテゴリ別検索も実現可能である。

一方、今回特に重視する、

• 一覧ページの自由なデザイン
• 左サイドバーの柔軟なカスタマイズ
• Astroコンポーネントによる機能拡張
• AI翻訳など将来の自動化
• JavaScript / TypeScriptによる拡張性

を考慮し、Starlightを優先する。

16. 結論

静的サイトジェネレーターには Astro Starlightを採用する方向とする。

想定構成は以下とする。

Astro Starlight
      +
Markdown / MDX
      +
Pagefind
      +
GitHub
      +
Cloudflare Pages
      +
AI Translation

特に、

Markdownファイルとディレクトリ構造をコンテンツ管理の中心とし、その構造から一覧ページ、サイドバー、検索などを可能な限り自動生成する

ことを基本方針とする。

一覧ページについては index.mdx + DirectoryIndex の共通コンポーネントを作成し、Hugo + Docsyの _index.md に近い運用を実現する。

日本語・英語については単純な完全ミラーではなく、それぞれの利用者に適したコンテンツ構成とサイドバーを持たせる。

今後はStarlightのPoCを作成し、以下を実際に確認する。

1. 日本語・英語サイト
2. 言語別サイドバー
3. 左サイドバーのカスタマイズ
4. 右ページ内目次
5. ディレクトリ一覧ページの自動生成
6. Pagefindによる言語別検索
7. カテゴリ・ディレクトリ検索
8. 画像・SVG・draw.io管理
9. SEO関連設定
10. Cloudflare Pagesへのデプロイ
11. AI翻訳ワークフロー