Static Site Generator Evaluation

1. Purpose

The goal is to build a content website covering multiple topics, such as technology, English learning, health, and investment, with Markdown as the primary content format.

The main requirements are:

• Manage content primarily in Markdown.
• Remain manageable as the site grows to hundreds or thousands of pages.
• Display a left sidebar and a right-hand table of contents on desktop.
• Provide index pages for directories and sections.
• Allow flexible customization of index pages and the sidebar.
• Support both Japanese and English.
• Allow different sidebar structures for Japanese and English.
• Search only Japanese content on the Japanese site and only English content on the English site.
• Allow searches to be restricted to specific categories or directories when required.
• Support an SEO-friendly site structure.
• Support Google AdSense.
• Support images and diagrams created with draw.io.
• Run natively on Windows without requiring WSL.
• Manage source code and content in GitHub.
• Support static hosting platforms such as Cloudflare Pages.
• Allow future automation of Japanese-to-English translation using AI.

2. Static Site Generators Considered

The main candidates evaluated were:

• Astro Starlight
• Hugo + Docsy
• Docusaurus
• Zensical
• MkDocs-based tools

The current preferred solution is Astro Starlight.

3. Why Astro Starlight

3.1 Markdown-Centered Content Management

Content will be managed using Markdown or MDX.

A possible structure is:

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

The filesystem and directory hierarchy will be the primary basis for organizing content.

3.2 Left Sidebar and Right-Hand Table of Contents

The desktop layout will generally use three columns:

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

Starlight provides both the left sidebar and the page-level table of contents.

Astro components can also be used to customize navigation and content presentation.

4. Directory Index Pages

One attractive feature of Hugo + Docsy is the ability to use _index.md as a section page and display the pages contained within that section.

Starlight does not provide exactly the same mechanism out of the box, but equivalent behavior can be implemented using index.mdx and a reusable Astro component.

For example:

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

The index.mdx file can use a common component:

---
title: AWS
description: AWS articles
---

<DirectoryIndex />

The DirectoryIndex component can determine the current directory and automatically retrieve the Markdown pages below it.

The resulting page could look like:

AWS

AWS Control Tower
An introduction to multi-account management using AWS Control Tower.

AWS Organizations
An overview of AWS Organizations and OU design.

IAM Identity Center
An overview of user and group management with IAM Identity Center.

The index can display information such as:

• Title
• Description
• Last updated date
• Tags
• Icon
• Category

Sorting can also be implemented by:

• Explicit order
• Title
• Last updated date

This provides an experience similar to Hugo + Docsy’s _index.md while allowing greater freedom over the design of section pages.

5. Sidebar

The default approach is to generate the sidebar from the directory hierarchy.

For example:

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

English
Investment
Health

Only sections that require special behavior will be customized manually or through custom components.

The goal is for adding a file such as:

aws/new-article.md

to automatically update:

• The sidebar
• The AWS index page
• The sitemap
• The search index

6. Internationalization

Japanese and English content will be separated under the same domain.

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

Topic sections will exist below the language level.

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/

Language subdirectories are preferred over language-specific subdomains.

6.1 Different Information Architectures by Language

The Japanese and English sites do not need to have identical structures.

For example, the Japanese site might contain:

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

English Learning
Investment
Health

while the English site might contain:

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

Finance

The two language versions should therefore be treated as:

Japanese and English sites under the same brand

rather than simply as mirrored translations.

Because Japanese-speaking and English-speaking audiences have different search intent, not every Japanese page needs an English translation.

7. AI Translation

Japanese Markdown will generally be treated as the Source of Truth for content that is translated.

Japanese Markdown
       ↓
AI Translation
       ↓
English Markdown
       ↓
GitHub Pull Request
       ↓
Review
       ↓
Merge
       ↓
Build / Deploy

For example:

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

can generate:

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

To detect outdated translations, the English page may store a hash of its Japanese source.

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

If the current Japanese source hash differs from source_hash, the English translation can be marked as requiring an update.

A future enhancement could use Git diffs to translate only changed sections.

The preferred workflow is not fully automatic publication, but:

AI Translation
      ↓
Pull Request
      ↓
Review
      ↓
Publish

8. Search

Starlight’s Pagefind-based search will be used initially.

8.1 Language-Specific Search

Japanese pages should search only Japanese content.

/ja/
 ↓
Japanese search index

English pages should search only English content.

/en/
 ↓
English search index

Pagefind’s multilingual indexing capabilities can be used for this purpose.

8.2 Category and Directory Filtering

Search can later provide scopes such as:

Search scope

○ Entire site
○ Technology
○ AWS
○ Terraform
○ Kubernetes

Search metadata can be derived from the content directory hierarchy.

For example:

/ja/tech/aws/control-tower/

can be associated with:

section  = tech
category = aws

Pagefind filters can then be used to restrict search results.

Pagefind should be sufficient initially even when the site grows to hundreds or thousands of pages.

If significantly more advanced search functionality becomes necessary, services such as Algolia can be evaluated later.

9. SEO

Multiple unrelated topics will initially be separated by directories within one domain.

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

Separate subdomains will not be introduced initially.

Each topic should instead be organized as a clearly defined content section.

The relationship between Japanese and English versions should also be communicated appropriately to search engines.

For topics where trust is particularly important, such as health and investment, author information, evidence, and sources should be clearly provided.

10. Google AdSense

Because Starlight is based on Astro, the required HTML and JavaScript can be added to the generated site.

Google AdSense can therefore be integrated.

Advertising should be positioned so that it does not significantly reduce content readability.

11. Images

Markdown pages can use standard images.

Images should generally be stored close to the related article or section in an images directory.

For example:

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

A Markdown page can reference the image as follows:

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

Rather than storing every image in one large global images directory, images should generally be kept close to the content that uses them.

12. draw.io

The original draw.io file should be maintained in GitHub as the editable source.

architecture.drawio
        ↓
Edit with draw.io
        ↓
Export to SVG
        ↓
architecture.svg
        ↓
Reference from Markdown

SVG should generally be preferred for architecture and other technical diagrams.

*.drawio  = Editable source
*.svg     = Web version

Screenshots and photographs can use PNG, WebP, or AVIF as appropriate.

Images should be shared between Japanese and English pages when they contain no language-specific text.

Separate language-specific images may be created when diagrams contain Japanese or English text.

13. Windows Development Environment

WSL will not be required.

Development will run natively on Windows.

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

The repository can, for example, be located at:

C:\git\my-site

The Starlight development server will run locally and be accessed through a web browser.

Neither Docker nor WSL is required for normal development.

14. GitHub and Deployment

Content, configuration, Astro components, and images will all be managed in GitHub.

The basic workflow will be:

Windows PC
    ↓
Edit Markdown
    ↓
Git commit / push
    ↓
GitHub
    ↓
Cloudflare Pages
    ↓
Starlight Build
    ↓
Publish

If AI translation is introduced, GitHub Actions may also be used to generate translation pull requests.

15. Comparison with Hugo + Docsy

Hugo + Docsy was also considered a strong candidate.

Its advantages include:

• Section management using _index.md
• Automatic section page listings
• Left sidebar
• Right-hand page table of contents
• Hugo’s strong multilingual capabilities
• Very fast static site generation

Adding Pagefind would also make language-specific and category-specific search possible.

However, the following requirements are particularly important for this project:

• Flexible design of directory index pages
• Flexible customization of the left sidebar
• Extensibility through Astro components
• Future automation such as AI translation
• Extensibility using JavaScript and TypeScript

For these reasons, Starlight is preferred.

16. Conclusion

The current direction is to adopt Astro Starlight as the static site generator.

The expected architecture is:

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

The fundamental content-management principle will be:

Use Markdown files and the directory hierarchy as the primary content model, and automatically derive index pages, sidebars, search metadata, and related navigation from that structure wherever practical.

For directory index pages, a reusable index.mdx + DirectoryIndex component will provide behavior similar to Hugo + Docsy’s _index.md.

The Japanese and English sites will not necessarily be complete mirrors. Each language version may have its own content structure and sidebar to better serve its target audience.

The next step is to build a Starlight proof of concept and validate:

1. Japanese and English sites
2. Language-specific sidebars
3. Customizable left sidebar
4. Right-hand page table of contents
5. Automatic directory index pages
6. Language-specific Pagefind search
7. Category and directory search
8. Image, SVG, and draw.io management
9. SEO configuration
10. Deployment to Cloudflare Pages
11. AI translation workflow