Easy Starlight Docs Starter

A production-ready Astro Starlight foundation for Markdown-first documentation, knowledge bases, and developer docs.

Documentation · Discussions · Issues

“What do we build for, if not to lessen each other’s hardship?”

Best for

• Developer and API documentation
• Product documentation and knowledge bases
• Open-source project documentation
• Engineering handbooks and internal knowledge
• Markdown-first static documentation sites
• Multilingual documentation, including RTL languages

Not for: CMS-heavy publishing platforms, application dashboards, or products that require a backend runtime for their primary experience.

Baseline

• Astro + Starlight with Markdown and MDX authoring
• Built-in search, responsive navigation, syntax highlighting, and SEO foundations
• Light and dark themes with a compact theme toggle
• Internationalization with English and Persian examples
• RTL support for Persian and other right-to-left locales
• Reusable custom Astro components inside MDX
• Custom Starlight component overrides
• TypeScript 7 type-checking for .ts and .astro files
• Biome formatting and linting
• Static output with GitHub Pages deployment
• Zero-config GitHub Pages repository detection
• Spec-driven documentation workflow for AI coding agents

Quick start

Preferred:

fonij create my-docs

Direct template use:

gh repo create my-docs \
  --template FonijBuild/easy-starlight-docs-starter \
  --public \
  --clone

cd my-docs
pnpm install
pnpm dev

The local development server is available at:

http://localhost:4321/

Content structure

English is the root locale and Persian content lives under /fa/.

src/content/docs/
├── index.md
├── getting-started.md
├── guides/
├── reference/
└── fa/
    ├── index.md
    ├── getting-started.md
    ├── guides/
    └── reference/

Use Markdown for normal documentation:

page.md

Use MDX only when the page needs custom components:

page.mdx

Reusable content components belong in:

src/components/content/

Starlight UI overrides belong in:

src/components/starlight/

Custom components

Create reusable Astro components under:

src/components/content/

Then import them from an .mdx page:

---
title: Architecture
---

import Callout from "../../../components/content/Callout.astro";

# Architecture

<Callout title="Important">
  Custom components can still contain **Markdown content**.
</Callout>

Prefer Astro components and static HTML. Add client-side JavaScript or another UI framework only when real interactivity requires it.

Internationalization

UI translations live in:

src/content/i18n/
├── en.json
└── fa.json

Documentation translations mirror the root documentation structure:

src/content/docs/
└── fa/

Keep translated pages on matching slugs whenever possible so Starlight can correctly connect localized versions.

Quality checks

Before merging changes:

pnpm check

The project quality gate covers:

• Biome formatting and linting
• TypeScript type-checking
• Astro component type-checking
• Production Astro build
• Starlight content and route validation

Deployment

Push to main and the included GitHub Actions workflow builds and deploys the static site to GitHub Pages.

For a normal project repository:

https://<owner>.github.io/<repository>/

For an <owner>.github.io repository:

https://<owner>.github.io/

The starter derives the repository owner, repository name, site URL, and base path automatically during GitHub Actions builds.

No .env, SITE_URL, or BASE_PATH configuration is required for the standard GitHub Pages path.

For a custom domain, add:

public/CNAME

containing the domain name.

Project contract

• .fonij/starter.json describes this foundation to Fonij.
• AGENTS.md is the canonical repository contract for AI coding agents.
• specs/ contains implementation-ready specifications and documentation plans.
• src/content/docs/ contains published documentation.
• src/content/i18n/ contains custom UI translations.
• src/components/content/ contains author-facing MDX components.
• src/components/starlight/ contains Starlight UI overrides.
• Keep documentation grounded in the actual project implementation.
• Keep specifications, implementation, and published documentation synchronized.
• Keep pnpm check green before merging changes.

Contributing

Keep changes focused, preserve the starter's minimal architecture, and avoid adding dependencies or abstractions without a concrete need.

For bugs or proposals, use Issues. For broader questions and ideas, use FonijBuild Discussions.