0024. The website and the docs site

• Status: Accepted
• Date: 2026-10-28

Context

OpenKedai needs a landing page at openkedai.com and a documentation site at docs.openkedai.com. The domain is on Cloudflare. The docs change with almost every feature, are written mostly by the same people (and agents) who change the code, and should later be readable in English, Malay and Chinese. People increasingly paste docs into AI assistants, so pages should also be available as plain Markdown.

Decision

Two repositories, both static sites on Cloudflare Pages (free), both built with Astro:

• OpenKedai/website: the landing page at openkedai.com.
• OpenKedai/docs: the docs site at docs.openkedai.com, built with Starlight. It holds the site’s configuration, theme and home page, and no documentation of its own.

The documentation stays in this repository’s docs/ folder. A feature and its docs change in the same pull request, and the files keep reading well on GitHub:

• Format: plain Markdown without frontmatter. The first line is the # Title, and links between pages are relative .md links.
• What’s published: only the pages listed in docs/site.json (an allowlist, in sidebar order, with section names in all three languages). Nothing in docs/internal/ is ever published.
• The export: scripts/docs-export.ts (Node built-ins only) turns the listed pages into Starlight pages with frontmatter and site links. It also writes a Markdown copy of each page served next to it, llms.txt and llms-full.txt, and the sidebar. It refuses to export while a page is untitled, unlisted or has a broken link, or while a page links to internal notes. scripts/docs-site.test.ts runs the same check with pnpm test.
• Rebuilds: the docs site’s build clones this repository and runs the export. When the public docs change on main, .github/workflows/docs-site.yml checks the export and calls the Cloudflare Pages deploy hook.

Starlight rather than Fumadocs. Fumadocs has better built-in AI features (Markdown copies of pages, copy buttons), but it is a Next.js app exported to static files. Its search and its language routing need extra work on a static host, and it is more code to keep up to date. Starlight is static from the start, has search built in (Pagefind) and per-page translations with fallback to English. The AI features are a small part of our own export.

Consequences

• Adding a page: add it to docs/site.json in the same pull request; the test fails otherwise. Moving or renaming a page changes its address on the site.
• While this repository is private: the docs site’s build needs a read-only GitHub token to clone it. Links to files outside docs/ point at GitHub and only work for people with access.
• Translations: not set up yet. When the first one is written, it goes in docs/i18n/<locale>/ with the same paths, and the export learns to publish it.
• Switching docs frameworks only means replacing the docs repository and the export’s frontmatter. The content doesn’t move.