Documentation Site
Relevant source files
The following files were used as context for generating this wiki page:
The shunt project maintains two distinct documentation surfaces to serve different audiences: a Nimbus-based public documentation site and an Astro Starlight-based internal wiki. The public site (located in site/) is designed for end-users and operators, focusing on getting started, guides, and provider references. The internal wiki (located in wiki/) serves as a "memex" or technical knowledge base for contributors, featuring deep-dive architectural details and onboarding guides.
Both surfaces utilize the Astro framework to generate static content and include specialized support for LLM consumption via llms.txt and llms-full.txt files.
Sources: site/README.md:3-5, AGENTS.md:27-29, wiki/AGENTS.md:21-26
Architecture and Components
The documentation infrastructure is split into two primary modules, each with its own build pipeline and deployment target.
Public Documentation Site (site/)
The public site is built using @cloudflare/nimbus-docs and is deployed to Cloudflare Pages. It features a custom locale fallback routing system to handle internationalization across English, Korean, Japanese, and Simplified Chinese.
Internal Wiki (wiki/)
The wiki uses @astrojs/starlight for content management and astro-mermaid for rendering architectural diagrams. It is designed to be generated from source material rather than hand-edited.
The following diagram illustrates the documentation build and deployment flow:
This diagram shows the parallel paths for the public documentation and the internal wiki, from source content to final deployment.
Sources: site/README.md:3-8, wiki/AGENTS.md:1-12, wiki/package.json:11-15, AGENTS.md:27-29
Internationalization (i18n)
The public documentation site supports multiple languages through a structured directory hierarchy and a fallback mechanism.
| Locale | Source Path | Description |
|---|---|---|
| English | src/content/docs/ | Primary source language |
| Korean | src/content/docs/ko/ | Translation subtree |
| Japanese | src/content/docs/ja/ | Translation subtree |
| Chinese | src/content/docs/zh-cn/ | Simplified Chinese subtree |
src/lib/i18n.ts serves as the single source of truth for locale metadata. A catch-all route ensures that if a translation is missing, the site emits an English fallback page to maintain consistent URL paths across all locales.
Sources: site/README.md:19-27
Technical Standards and Formatting
Documentation content must adhere to specific technical standards, particularly regarding diagrams and citations.
Mermaid Diagram Standards
For the wiki, Mermaid diagrams must use specific dark-mode color tokens to ensure visibility:
- Node Colors:
#2d333b,#6d5dfc,#e6edf3 - Background/Border:
#161b22,#30363d,#8b949e - Requirements: All sequence diagrams must include the
autonumberdirective. Labels must not contain<br/>tags.
Prose Styling
The prose.css file defines the typographic rhythm and visual styles for the documentation. It uses a base font size of 0.9375rem and a line height of 1.75. Markdown elements like headings (h1-h4) are configured with text-wrap: balance to prevent orphans, while body copy (p, li) uses text-wrap: pretty.
Sources: wiki/AGENTS.md:32-37, site/src/styles/prose.css:3-10, site/src/styles/prose.css:80-87
LLM Optimization
Both documentation platforms are optimized for Large Language Model (LLM) consumption. They generate specialized text files during the build process:
llms.txt: A concise map of the documentation.llms-full.txt: The full content of the documentation for providing complete context to LLMs.
Sources: site/README.md:11-17, wiki/AGENTS.md:25-26
Development Workflow
The documentation sites utilize standard npm scripts for lifecycle management.
# For either site/ or wiki/
npm install # Install dependencies
npm run dev # Local development server
npm run build # Generate static files
For the wiki, the build output is directed to wiki/dist/. For the public site, the build process includes a typecheck and a documentation-specific linting step (nimbus-docs lint).
Sources: site/README.md:8-12, wiki/AGENTS.md:4-9, site/package.json:9-15
Conclusion
The documentation system for shunt provides a robust, multi-tiered approach to project information. By separating public-facing guides from internal technical wikis and providing LLM-optimized formats, the project ensures that both human developers and AI agents have accurate, structured access to the system's architecture and operational requirements.