Skip to content
Codex

2026-05-19: Serving the codex as a Starlight website at codex.constructions-3d.com

2026-05-19 Accepted

Context

Section titled “Context”

The codex was established as a collection of Markdown files versioned in the Groupe-3D/Groupe-3D repository (see 2026-04-08-codex-setup). A known trade-off of that initial setup was the absence of a dedicated search interface: navigation relied entirely on links between files and the folder structure.

As the codex grows and the team wants to share it beyond its current contributors — in particular with candidates considering joining the company — navigating raw Markdown files on GitHub becomes a poor experience. A public, readable web interface is needed.

The requirements are:

  • Easy to read and navigate for anyone, including people unfamiliar with GitHub.
  • Lightweight with a low maintenance overhead.
  • The existing Markdown files should be reusable with minimal changes.
  • Publicly accessible at a memorable URL (codex.constructions-3d.com).

Decision

Section titled “Decision”

The codex is wrapped in an Astro Starlight site hosted at codex.constructions-3d.com.

The existing Markdown files are migrated into Starlight’s content collection with minimal changes: the main addition is a YAML frontmatter title field on each page. The Starlight site lives in the codex/ directory of the repository alongside the source files it serves.

Rationale

Section titled “Rationale”

Why Starlight

Section titled “Why Starlight”

Starlight is a documentation framework built on top of Astro. It ships with built-in search (via Pagefind), a sidebar navigation, dark mode, and responsive design — all out of the box, with no configuration required. Its output is a fully static site with no runtime server.

The key advantage for this project is that Starlight is Markdown-first: it treats .md and .mdx files as first-class content. The existing codex files required only the addition of a title frontmatter field to become valid Starlight pages. There was no need to rewrite, restructure, or convert the content.

Why not Docusaurus or VitePress

Section titled “Why not Docusaurus or VitePress”

Both Docusaurus and VitePress are valid alternatives. However:

  • Docusaurus has a heavier React runtime and a more complex configuration surface than needed for a documentation-only site.
  • VitePress is tightly coupled to the Vue ecosystem, which is not used elsewhere in the organisation.

Starlight (on Astro) generates a static output with minimal JavaScript shipped to the browser, making it the lightest option while still providing full-featured documentation tooling.

Why not a hosted service (Notion, GitBook…)

Section titled “Why not a hosted service (Notion, GitBook…)”

Hosted services introduce an external dependency, may involve a cost, and break the Git-based contribution workflow. Content would live outside version control, making reviews and history harder. Keeping the source of truth in the repository and generating the website from it preserves the existing PR-based workflow.

Trade-offs

Section titled “Trade-offs”
  • The Starlight framework is an additional dependency to keep up to date.

Consequences

Section titled “Consequences”
  • The codex/ directory now contains an Astro Starlight project in addition to the Markdown source files.
  • The codex is publicly accessible at codex.constructions-3d.com.
  • The “no dedicated search interface” trade-off identified in 2026-04-08-codex-setup is resolved: Starlight’s built-in Pagefind search is available on every page.
  • New codex pages must include a title frontmatter field to render correctly in Starlight.
  • The deployment pipeline for codex.constructions-3d.com must be kept in sync with the codex/ folder in the repository.