The Documentation Site is a static documentation website built with Astro and Starlight that serves as the primary documentation portal for the RealWorld project. It generates a comprehensive, searchable, and navigable website from Markdown content located in apps/documentation/src/content/docs/. The site documents the API specifications, implementation guides, and community resources needed for developers to create new RealWorld implementations.
For information about the API specification itself, see API Specification. For details about the reference implementation, see Reference Implementation. For build orchestration and CI/CD, see Build System & Workflows.
The documentation site uses the following core technologies:
| Technology | Version | Purpose |
|---|---|---|
| Astro | ^5.16.16 | Static site generator framework |
| Starlight | ^0.37.4 | Astro documentation theme with built-in features |
| Tailwind CSS | ^4.1.18 | Custom styling and theme configuration |
| Bun | - | JavaScript runtime and package manager |
| React | ^19.2.4 | Component framework for custom components |
| TypeScript | ^5.9.3 | Type checking and development |
| sharp | ^0.34.5 | Image optimization |
Sources: apps/documentation/package.json1-27
Diagram 1: Documentation Site Architecture
The documentation system transforms Markdown source files through Astro's build pipeline, applying Starlight's documentation theme, custom styling, and Vite plugins to produce an optimized static website with integrated search functionality.
Sources: apps/documentation/astro.config.mjs1-181 apps/documentation/package.json5-11
The astro.config.mjs file contains the primary configuration for the documentation site. It defines the Starlight integration, custom Vite plugins, and build settings.
Diagram 2: Astro Configuration Structure
Sources: apps/documentation/astro.config.mjs56-181
The Starlight integration is configured with the following settings:
| Setting | Value | Purpose |
|---|---|---|
title | 'RealWorld' | Site title displayed in header |
social | GitHub link | Social media links in header |
customCss | ['./src/tailwind.css'] | Custom styling file |
sidebar | Nested array | Hierarchical navigation structure |
Sources: apps/documentation/astro.config.mjs57-173
The documentation site includes a custom Vite plugin that removes .md extensions from URLs during the build process:
Diagram 3: removeMdExtension Plugin Flow
This plugin runs in the pre stage of the build process and removes .md extensions from file content, allowing for cleaner URLs in the generated site (e.g., /docs/page instead of /docs/page.md).
Sources: apps/documentation/astro.config.mjs42-53
The documentation content is organized hierarchically in src/content/docs/ with the following structure:
Diagram 4: Content Directory Structure
Sources: apps/documentation/astro.config.mjs69-173
The sidebar navigation is defined in the astro.config.mjs file and mirrors the content structure:
Diagram 5: Sidebar Navigation Structure
Each sidebar item maps to a content file using the slug property. For example, slug: 'implementation-creation/introduction' maps to src/content/docs/implementation-creation/introduction.md.
Sources: apps/documentation/astro.config.mjs69-173
The documentation site uses Bun as the package manager and runtime, with the following npm scripts defined:
| Script | Command | Purpose |
|---|---|---|
dev | astro dev | Start development server with hot reload |
start | astro dev | Alias for dev |
build | astro check && astro build | Type check and build static site |
preview | astro preview | Preview built site locally |
astro | astro | Run Astro CLI commands |
Sources: apps/documentation/package.json5-11
Diagram 6: Build Process Sequence
Sources: apps/documentation/package.json5-11 apps/documentation/astro.config.mjs175-180
The documentation site uses Tailwind CSS with custom theme variables defined in src/tailwind.css.
The custom theme defines color palettes for both light and dark modes:
| CSS Variable | Light Mode Value | Purpose |
|---|---|---|
--color-accent-200 | #e3b6ed | Light accent shade |
--color-accent-600 | #a700c3 | Primary accent color |
--color-accent-900 | #4e0e5b | Dark accent shade |
--color-accent-950 | #36113e | Darkest accent shade |
--color-gray-100 | #f8f4fe | Lightest gray |
--color-gray-200 | #f2e9fd | Light gray |
--color-gray-300 | #c7bdd5 | Medium-light gray |
--color-gray-400 | #9581ae | Medium gray |
--color-gray-500 | #614e78 | Base gray |
--color-gray-700 | #412e55 | Dark gray |
--color-gray-800 | #2f1c42 | Darker gray |
--color-gray-900 | #1c1425 | Darkest gray |
Sources: apps/documentation/src/tailwind.css5-18
The Tailwind CSS file includes overrides to restore standard list styles within Starlight's markdown content area:
.sl-markdown-content ul - Applies disc bullet points to unordered lists.sl-markdown-content ol - Applies decimal numbering to ordered listsSources: apps/documentation/src/tailwind.css20-41
Diagram 7: Development and Build Workflow
During development, the dev command starts a development server that watches for file changes and provides instant hot reload. The build command performs type checking via @astrojs/check before generating the optimized static site.
Sources: apps/documentation/package.json5-11
The documentation site integrates with the broader repository in several ways:
Diagram 8: Documentation Site Integration
The documentation site serves as the primary interface for developers to understand the RealWorld specification. It embeds references to the OpenAPI specification and Postman collection, and is integrated into the root Makefile for centralized build orchestration.
Sources: apps/documentation/src/content/docs/specifications/backend/introduction.md1-10 apps/documentation/src/content/docs/specifications/backend/endpoints.md1-242
The @astrojs/starlight theme provides several features out of the box:
@astrojs/sitemapSources: apps/documentation/package.json15 apps/documentation/astro.config.mjs57-65
The site includes custom enhancements beyond the default Starlight configuration:
removeMdExtension plugin removes .md extensions for cleaner URLs@astrojs/reactSources: apps/documentation/astro.config.mjs42-53 apps/documentation/src/tailwind.css1-41
| Package | Version | Purpose |
|---|---|---|
astro | ^5.16.16 | Core static site generator |
@astrojs/starlight | ^0.37.4 | Documentation theme |
@astrojs/check | ^0.9.6 | TypeScript type checking |
@astrojs/react | ^4.4.2 | React component support |
@astrojs/starlight-tailwind | ^4.0.2 | Tailwind integration for Starlight |
@tailwindcss/vite | ^4.1.8 | Vite plugin for Tailwind CSS |
tailwindcss | ^4.1.18 | CSS framework |
react | ^19.2.4 | Component library |
react-dom | ^19.2.4 | React DOM rendering |
sharp | ^0.34.5 | Image optimization |
typescript | ^5.9.3 | Type checking |
Sources: apps/documentation/package.json12-26
Astro and Starlight bring in numerous transitive dependencies including:
@astrojs/markdown-remark, @astrojs/mdx, remark-*, rehype-*shiki with theme and language supportpagefind with platform-specific binariesSources: apps/documentation/bun.lock1-28
Content files follow MDX format with frontmatter:
The frontmatter title property sets the page title and is used in navigation and search indexing.
The endpoints documentation demonstrates the typical content structure:
Sources: apps/documentation/src/content/docs/specifications/backend/endpoints.md1-242
The API response format documentation shows:
Sources: apps/documentation/src/content/docs/specifications/backend/api-response-format.md1-154
The bun run build command generates a static site in the dist/ directory with the following structure:
dist/index.html - Home pagedist/[page-slug]/index.html - Individual pagesdist/_astro/ - Optimized CSS, JS, and image assetsdist/pagefind/ - Search index filesThe generated site is a fully static website that can be deployed to any static hosting service (Netlify, Vercel, GitHub Pages, etc.).
Sources: apps/documentation/package.json8
Refresh this wiki