This document describes the hierarchical organization of Markdown content within the documentation site, including the directory structure, content categories, and how files map to navigation and URLs.
For information about the Astro and Starlight configuration that renders this content, see Astro & Starlight Configuration. For build and deployment processes, see Build & Deployment.
All documentation content resides in apps/documentation/src/content/docs/ following a hierarchical folder structure that directly maps to the site's navigation and URL paths.
Sources: apps/documentation/astro.config.mjs69-173
The documentation is organized into three primary categories, each serving distinct purposes within the RealWorld ecosystem.
Located in apps/documentation/src/content/docs/implementation-creation/ this section guides developers through creating new RealWorld implementations.
| File | Slug | Purpose |
|---|---|---|
introduction.md | implementation-creation/introduction | Overview of Conduit project and getting started steps |
features.md | implementation-creation/features | Required features for implementations |
expectations.md | implementation-creation/expectations | Quality and completeness expectations |
Sources: apps/documentation/astro.config.mjs71-86 apps/documentation/src/content/docs/implementation-creation/introduction.md1-20
The specifications section contains three subsections defining API contracts and UI requirements for different implementation types.
Located in apps/documentation/src/content/docs/specifications/frontend/:
| File | Slug | Coverage |
|---|---|---|
templates.md | specifications/frontend/templates | UI templates and layout requirements |
styles.md | specifications/frontend/styles | Bootstrap 4 theme and styling guidelines |
routing.md | specifications/frontend/routing | URL structure and page routing |
api.md | specifications/frontend/api | API integration requirements |
tests.md | specifications/frontend/tests | Testing requirements |
Sources: apps/documentation/astro.config.mjs92-114 apps/documentation/src/content/docs/specifications/frontend/routing.md1-22
Located in apps/documentation/src/content/docs/specifications/backend/:
| File | Slug | Coverage |
|---|---|---|
introduction.md | specifications/backend/introduction | API spec overview and Postman collection |
endpoints.md | specifications/backend/endpoints | Complete endpoint documentation |
api-response-format.md | specifications/backend/api-response-format | JSON response schemas |
cors.md | specifications/backend/cors | CORS configuration requirements |
error-handling.md | specifications/backend/error-handling | Error response format and status codes |
postman.md | specifications/backend/postman | Postman collection usage |
tests.md | specifications/backend/tests | Testing requirements |
Sources: apps/documentation/astro.config.mjs116-147 apps/documentation/src/content/docs/specifications/backend/endpoints.md1-242
Located in apps/documentation/src/content/docs/specifications/mobile-specs/:
| File | Slug | Coverage |
|---|---|---|
introduction.md | specifications/mobile-specs/introduction | Mobile implementation guidelines |
Sources: apps/documentation/astro.config.mjs149-152 apps/documentation/src/content/docs/specifications/mobile-specs/introduction.md1-12
Located in apps/documentation/src/content/docs/community/:
| File | Slug | Purpose |
|---|---|---|
authors.md | community/authors | Project authors and contributors |
resources.md | community/resources | Community articles and performance comparisons |
special-thanks.md | community/special-thanks | Acknowledgments |
Sources: apps/documentation/astro.config.mjs155-172 apps/documentation/src/content/docs/community/resources.md1-16
The sidebar navigation structure is defined in apps/documentation/astro.config.mjs69-173 and maps directly to the content directory structure.
Each sidebar item configuration includes:
label: Display text in navigationslug: Path to content file (without .md extension)items: Nested array for hierarchical sectionsExample from apps/documentation/astro.config.mjs71-86:
Sources: apps/documentation/astro.config.mjs69-173
Documentation pages use Markdown (.md) or MDX (.mdx) with YAML frontmatter.
Every content file requires frontmatter with at minimum a title field:
Example from apps/documentation/src/content/docs/specifications/backend/endpoints.md1-4:
Example from apps/documentation/src/content/docs/introduction.mdx1-3:
Sources: apps/documentation/src/content/docs/specifications/backend/endpoints.md1-4 apps/documentation/src/content/docs/introduction.mdx1-3
.md files: Standard Markdown with CommonMark/GFM syntax.mdx files: Markdown with embedded JSX/React componentsThe introduction page uses .mdx to potentially leverage React components, while specification pages use standard .md for simplicity.
Sources: apps/documentation/src/content/docs/introduction.mdx1-36 apps/documentation/src/content/docs/specifications/backend/endpoints.md1-242
Starlight automatically generates URLs from the file path structure, with the .md extension removed by the removeMdExtension Vite plugin.
The removeMdExtension() plugin in apps/documentation/astro.config.mjs42-53 processes Markdown files during build to remove .md extensions from internal links:
Sources: apps/documentation/astro.config.mjs42-53 apps/documentation/astro.config.mjs176
The specifications section demonstrates three-level nesting:
specifications/frontend/, backend/, mobile-specs/.md filesSources: apps/documentation/astro.config.mjs88-154
The community section uses flat organization with all pages at the same level:
Sources: apps/documentation/astro.config.mjs155-172
Content files can reference other pages using either:
<FileRef file-url="https://github.com/realworld-apps/realworld/blob/5cd08ae2/link text" undefined file-path="link text">Hii</FileRef><FileRef file-url="https://github.com/realworld-apps/realworld/blob/5cd08ae2/link text" undefined file-path="link text">Hii</FileRef><FileRef file-url="https://github.com/realworld-apps/realworld/blob/5cd08ae2/link text" undefined file-path="link text">Hii</FileRef>Example from apps/documentation/src/content/docs/specifications/backend/endpoints.md26-46:
This cross-references the api-response-format.md file with a specific anchor.
Sources: apps/documentation/src/content/docs/specifications/backend/endpoints.md26-46
The content processing flow:
src/content/docs/@astrojs/markdown-remark processes Markdown@astrojs/mdx handles .mdx filesremoveMdExtension() plugin modifies linksSources: apps/documentation/astro.config.mjs56-181 apps/documentation/package.json12-26
The content system depends on:
astro.config.mjs: Defines sidebar structure and maps slugs to files@astrojs/starlight: Provides layout, navigation, and searchsrc/tailwind.css: Custom theme colors and list stylingpackage.json: Dependencies for Markdown processingSources: apps/documentation/astro.config.mjs1-182 apps/documentation/package.json1-28 apps/documentation/src/tailwind.css1-41
Refresh this wiki