本文档描述了 RealWorld 项目中使用的文档系统。它涵盖了项目技术文档的架构、配置、内容结构和构建过程。该文档系统为跨各种前端和后端技术实现 RealWorld 规范的开发者提供了全面的指导。
来源： apps/documentation/astro.config.mjs
RealWorld 文档系统使用 Astro 和 Starlight 集成进行构建，Starlight 提供了一个专门的文档站点框架。这种架构支持组织有序、可搜索的文档，并具有响应式设计和最佳的开发者体验。
文档系统利用了几项关键技术
来源： apps/documentation/astro.config.mjs1-4 apps/documentation/astro.config.mjs56-177
文档系统通过 Astro 配置文件进行配置。该文件定义了站点结构、导航、主题和集成。
主要配置在 astro.config.mjs 中定义，包括
Starlight 配置定义了文档站点的标题、社交链接、自定义 CSS 和导航侧边栏结构。Tailwind 集成通过 applyBaseStyles: false 进行配置，以允许自定义样式控制。
来源： apps/documentation/astro.config.mjs56-173
文档根据侧边栏配置中定义的层级结构进行组织
这种导航结构定义在 Starlight 配置的 sidebar 属性中，将文档内容组织成逻辑部分，指导开发者完成 RealWorld 规范的实现。
来源： apps/documentation/astro.config.mjs66-169
文档系统包含一个名为 removeMdExtension 的自定义 Vite 插件，通过从文档 URL 中删除 .md 扩展名来提高 URL 的可读性。
此插件在构建过程中运行，以确保文档内的内部链接看起来更简洁（例如，/docs/page 而不是 /docs/page.md），从而改善用户体验。
来源： apps/documentation/astro.config.mjs6-54 apps/documentation/astro.config.mjs174-176
文档内容组织在与导航层级结构相匹配的目录结构中。内容采用 Markdown 格式编写，支持富文本格式、代码片段和图像。
内容结构与侧边栏配置直接相关，确保导航项指向正确的内容文件。每个 Markdown 文件代表文档中的一个页面。
来源： apps/documentation/astro.config.mjs66-169
文档系统与整体项目构建过程集成，利用 Turbo 构建系统实现高效的开发和部署。
在开发过程中，Astro 开发服务器提供文档更改的实时预览。对于生产环境，构建过程生成优化的静态文件，可以部署到任何静态托管服务。
文档系统是对 API 规范的补充，提供了对 OpenAPI 定义和 Postman 集合的可读性强的解释。
API 文档页面提供了对 OpenAPI 规范中定义的端点的详细解释，帮助开发者理解如何实现和交互 API。
来源： apps/documentation/astro.config.mjs113-145
文档系统使用 Tailwind CSS 进行样式设置，并将自定义 CSS 包含在 Starlight 配置中。
自定义样式可确保文档与 RealWorld 项目的整体设计语言相匹配，同时保持可读性和可访问性。
来源： apps/documentation/astro.config.mjs63-65 apps/documentation/astro.config.mjs171-173
RealWorld 文档系统为实现 RealWorld 规范的开发者提供了一个全面、组织良好的参考。它基于现代 Web 技术（Astro、Starlight、Tailwind）构建，通过清晰的导航、简洁的 URL 和响应式设计，提供了最佳的文档体验。
该系统与更广泛的 RealWorld 项目基础设施集成，确保文档与 API 规范和实现指南保持同步和一致。