Orleans 文档站点工程指南：基于 Astro + Starlight 的构建、API 参考生成与源码级校验体系

后端微服务【免费下载链接】orleansCloud Native application framework for .NET项目地址https://gitcode.com/gh_mirrors/or/orleans点击查看免费下载本篇指南围绕 Orleans 仓库中 docs/site/README.md 所描述的官方文档站点工程展开它从概念文档的写作、本地开发与预览到 API 参考的自动生成、生产部署再到一套编译器级的源码审计与链接校验体系完整地解释了 Orleans 文档如何做到与源码、测试、示例严格一致。读完本文你将掌握该站点的完整构建命令链、校验规则DOCS/PROJECT/SNIPPET/LINK 编号的触发与修复方式以及如何复现其文档工程的本地环境。站点架构Astro Starlight 承载的文档工程Orleans 文档站是一个基于Astro Starlight的单页文档站点其工程入口位于 docs/site/核心配置文件包括docs/site/package.json定义全部 npm 脚本dev、build、validate、各audit:*子命令docs/site/astro.config.mjsStarlight 站点配置声明了base: /orleans/、侧边栏来源、Markdown 处理器与三类 Starlight 插件docs/site/src/content/docs/全部概念文档的 Markdown 源约 200 个概念页面docs/site/src/data/API 包元数据pkgs/、外部链接白名单、旧版页面重定向映射等数据资产docs/site/scripts/文档准备与各项审计的 Node.js 实现。值得特别说明的是文档内容不是直接以 Markdown 交给 Starlight 渲染的。概念文档源文件存放在src/content/docs下其中包含了大量 Microsoft Learn 风格的语法DocFX 转换、:::code命名区域指令、xref 引用等。运行 docs/site/scripts/prepare-docs.mjs对应npm run prepare:docs后每个.md文件会被转换为忽略的.mdx兄弟文件Starlight 才能渲染这些导入的 Microsoft Learn 语法。也就是说源文件是.md渲染内容是自动生成的.mdx后者不应手工维护。环境准备Node 与 .NET SDK 版本要求在开始之前需要满足两个版本前提Node.js 24 或更高版本见 docs/site/package.json 的engines.node字段.NET SDK版本由仓库根目录的 global.json 选定。其中 .NET SDK 的必要性在于两处一是npm run api:generate需要编译 Orleans 源码包来生成 API 参考数据二是文档工程中的 C# 代码片段snippet需要被真实编译校验。因此仅运行前端 dev 服务器可以不装 SDK但要完整跑通validate或buildSDK 必不可少。本地开发三步启动文档站开发模式的核心命令链如下在docs/site目录下执行npm install npm run api:generate npm run devnpm install安装 Astro、Starlight、Pagefind、Vitest 等前端依赖依赖清单见 docs/site/package.jsonnpm run api:generate调用 docs/scripts/Generate-ApiData.ps1构建公开 Orleans 包并生成 API 参考数据细节见下文API 参考生成一节npm run dev先执行prepare:docs完成.md → .mdx转换再启动 Astro 开发服务器。关于 API 生成的几个注意事项沿用原文档说明耗时较长API 生成需要编译全部 Orleans 公开包可能需要数分钟产物不入库生成的包 JSON 被 Git 忽略不应提交可以跳过如果本地预览不需要 API 参考页面完全可以省略npm run api:generate这一步直接npm run dev。生产构建精确复刻线上产物开发服务器为了按需渲染页面不包含 Pagefind 搜索索引。要预览与线上完全一致的静态产物包括生产搜索索引需要两步npm run build npm run previewnpm run build见 docs/site/package.json实际执行的是串行链audit:projects→prepare:docs→astro build→legacy:redirects→audit:links→audit:output。即生产构建本身就把项目审计、链接审计和输出审计作为门禁包含在内。生产构建的额外产物生产构建除了静态页面还会发布三类机器可读产物这对搜索引擎和 LLM 检索尤为重要/llms.txt、/llms-small.txt、/llms-full.txt由starlight-llms-txt插件docs/site/astro.config.mjs 中配置生成的三级 LLM 友好索引每页的 Markdown 伴生文件每个文档页面在其 URL 后追加.md后缀即可获得对应的纯 Markdown 版本由starlight-dot-md插件生成。这些伴生文件复用与 Starlight 相同的 prepared content collection 条目因此 includes、代码指令、xref 与 DocFX 转换均已应用完毕——换句话说.md伴生文件与页面渲染内容是同源的旧版重定向见下文旧版页面重定向。全量校验一条命令打通八道关卡npm run validate是文档工程的总闸门它依次执行npm run audit:projects npm run audit:sources npm run audit:snippets npm run prepare:docs vitest run astro check astro build npm run legacy:redirects npm run audit:links npm run audit:output对应地覆盖了项目结构审计、源码审计、代码片段编译策略校验、文档准备、Vitest 聚焦转换测试、Astro 类型检查、严格片段展开、源码质量与聚合项目策略审计、Starlight 链接校验、Pagefind 索引、生产构建、旧版重定向生成、链接审计与输出审计。上述各子审计分别由 docs/site/scripts/ 下的独立脚本实现并有对应的测试用例见 docs/site/tests/ 下的docfx.test.mjs、source-quality.test.mjs、project-policy.test.mjs、link-audit.test.mjs、redirects.test.mjs、compatibility-paths.test.mjs等验证这些审计本身的行为。源码审计规则DOCS/PROJECT/SNIPPET/LINK 编号速查源码审计npm run audit:sources实现见 docs/site/scripts/audit-sources.mjs 与 docs/site/scripts/lib/source-quality.mjs会报告规则 ID、文件、行号与修复建议并强制执行以下策略版本策略DOCS001除迁移页面与明确标注版本的兼容区外不允许出现针对 Orleans 10 的版本化引导当前发布版本的文档必须保持无版本号导航结构DOCS002/DOCS003每个概念页面必须在toc.ymldocs/site/src/content/docs/toc.yml中恰好出现一次includes、snippet 支持文件与兼容路由需标记为navigation: hidden并排除在外Architecture and internals 与 Event Sourcing 保持为一级导航分区清单一致性DOCS005包与流提供方清单对照源码项目元数据Activity source 与生命周期阶段对照源码/API 常量文档化的指标名称必须存在于InstrumentNames.cs如 src/Orleans.Runtime/ 下相关源码示例路径对照 samples/gallery.json代码片段策略DOCS004C# 示例必须通过:::code命名区域引用可编译的源文件内联 C# 代码块会被审计拒绝。需要把部分示例放入共享源文件并在显示区域之外提供隐藏脚手架选项与指标页选项页刻意保持为精选短清单而非自动生成目录审计要求该页面将自动生成的 API 参考标识为完整来源指标文字同样有选择性但每个被提及的指标标识符必须真实存在于运行时源码中。修复对照表规则触发场景修复方式DOCS001当前版本文档出现版本号保持无版本号版本化引导移入migration/或升级页面DOCS002/DOCS003toc.yml条目缺失或重复在 docs/site/src/content/docs/toc.yml 中修正DOCS004内联 C# 代码块移至已编译 snippet 项目的命名区域并在区域外补充隐藏上下文DOCS005文档清单与源码清单不一致同步手写清单与命名源清单项目策略审计PROJECT 系列规则npm run audit:projects实现见 docs/site/scripts/audit-projects.mjs会扫描docs/与samples/下的每一个项目执行以下硬性约束文件系统发现的每个项目必须精确出现在 docs/Docs.slnx 与 samples/Samples.slnx 中PROJECT001-PROJECT003增删文档/示例项目直至发现与解决方案精确匹配目标框架必须是精确的net10.0PROJECT004每个 Orleans 包引用必须解析到10.2.2PROJECT005历史版本包仅允许出现在迁移项目中且必须带有有效、有意义的OrleansDocumentationVersionException属性待发布的示例允许使用带该属性与具体原因的10.2.2预发布版本PROJECT006识别无效、含糊或过期的版本异常。该审计的聚合策略定义在 docs/project-policy.json并受ORLEANS_DOCS_PROJECT_AUDIT_CONCURRENCY环境变量控制并发度默认 8。代码片段审计SNIPPET 系列规则npm run audit:snippets调用pwsh src/content/docs/validate-snippets.ps1 -PolicyOnly。SNIPPET001/SNIPPET002需要在报告指出的 snippet 项目中修复后重新构建。若要顺序编译已签入的文档 snippet 项目可执行pwsh docs/site/src/content/docs/validate-snippets.ps1链接审计LINK001 与安全防护链接审计npm run audit:links实现见 docs/site/scripts/audit-links.mjs 与 docs/site/scripts/lib/link-audit.mjs覆盖两类目标源码侧与渲染侧链接源码中的相对链接必须使用规范的 Microsoft Learn 绝对 URL即 Learn 官方文档地址形式渲染后的路由、编码路径、重定向与锚点必须在/orleans/前缀下可解析。源码诊断包含文件/行号溯源仓库内链接指向本仓库的生成链接会对照本地检出逐一验证外部链接探测使用有界并发、重定向、超时、重试与按主机区分的 HEAD→GET 回退策略。明确失效的目标判为失败限流与瞬时网络故障会显式报告而不会让 CI 变得不确定。安全性设计值得展开PR 内容被视为不可信输入。探测器会拒绝携带凭据、非默认端口以及任何能触达私网、回环、链路本地、元数据或其他非公开网络的主机名/IPDNS 解析结果会被校验并在每次重定向跳转时固定进实际 TLS 连接从而防止贡献者利用重定向、DNS 重绑定或代理环境变量把链接校验变成对内网的请求。LINK001的修复方式是采用其修复建议中的规范 URL。渲染侧失败在可映射时会指出源文件/行号否则指出渲染路由。docs/site/src/data/external-link-allowlist.json只接受精确 URL每个条目需要简短理由且仍会被主动探测因此可达或未被引用的条目同样会被判为过期。另外一个刚生成、尚未首次发布到 NuGet 的 API 包还需要在 docs/site/src/data/unpublished-api-packages.json 中加临时条目发布后两条记录都要删除。API 参考生成从 Roslyn 到 Starlight 路由生成管线npm run api:generate背后是 docs/scripts/Generate-ApiData.ps1其工作流为筛选可打包项目遍历src/下全部.csproj仅保留IsPackabletrue且IncludeBuildOutputtrue、目标框架含net10.0的项目并校验无重复包 ID 与程序集名要求干净的工作树src目录不允许存在未提交或未跟踪的改动生成前会锁定src的最新提交 SHA并要求本地src与之一致构建源码包与工具按-Configuration Release -Framework net10.0构建每个 API 项目再构建生成器工具 docs/tools/PackageJsonGenerator/组装引用集将框架引用程序集Microsoft.NETCore.App.Ref、Microsoft.AspNetCore.App.Ref、NuGet 包编译资产与同仓库项目程序集合并并做 SHA256 冲突检测批量运行生成器通过 manifest 文件记录输入程序集、引用、输出路径、包名/版本、目标框架与源码提交调用PackageJsonGenerator的batch命令-Parallelism控制并行度npm run api:generate固定为 4默认取 CPU 核数产物校验逐文件校验包名、版本、目标框架、源码仓库与提交并检查类型无重复最终汇总输出生成 N 个包文件、X 个公开类型、Y 个成员。生成结果写入 docs/site/src/data/pkgs/格式为Microsoft.Orleans.*.version.json。这套 JSON 格式来自 Aspire 的 Roslyn/XML/PDBPackageJsonGenerator输出由 Orleans API 生成工作流做了适配。渲染架构/docs/api/csharp/路由树与 Aspire 文档站使用相同的原生渲染架构原文档明确说明其同源于 Aspire 官方文档站Astro 的packagescontent collection 读取src/data/pkgs/*.jsonStarlight 页面据此渲染包、类型、成员种类、单个成员四种粒度的路由每个路由同样附带.md伴生文件。文档项目构建与测试Docs.slnx 与示例构建文档工程内的 C# 项目含所有 snippet 项目以解决方案 docs/Docs.slnx 组织。要在本地构建并测试这些文档项目执行dotnet test --solution ../Docs.slnx --configuration Release --framework net10.0 -p:BuildExternalAssetsfalse --minimum-expected-tests 1 --max-parallel-test-modules 1上述命令在docs/site目录下执行故解决方案路径为相对位置实际按仓库根路径即docs/Docs.slnx。示例工程的构建则通过 samples/Build-Samples.ps1 完成——它会先把当前 Orleans 源码打包到本地 feed再构建 samples/Samples.slnx。新增文档/示例项目时的约定通过dotnet sln add --include-references false添加并使用与其在docs/或samples/下路径一致的解决方案文件夹仓库源码依赖会传递构建不直接作为Docs.slnx条目。旧版页面重定向与输出审计生产构建会为两个历史版本的站点地图生成兼容重定向docs/site/src/data/legacy-jekyll-pages.json映射每个 pre-DocFX 文档页面到其最佳现行页面并通过历史无扩展名别名提供.html重定向docs/site/src/data/legacy-pages.json记录最终的 DocFX 时代站点现有页面若被新站点接管则保留原 URL退役的文档与博客 URL 重定向到最近的现行文档入口docs/site/src/data/redirects.json显式替换保留入站锚点并覆盖自动化的 DocFX 时代路径匹配。输出审计npm run audit:output会扫描完整渲染产物检查重复或缺失的页面标题、泄漏的 Microsoft Learn 指令、格式错误的 API 签名与运算符名称、过大的导航、缺失的旧版重定向以及 GitHub Pages 体积限制回退。CI/CD 与部署GitHub Actions 流水线原文档描述了自动化发布流程在当前仓库中以 Actions 工作流形式存在触发方式推送到main分支、每天 09:00 UTC 定时任务、手动触发执行内容按需生成 API 数据、以诊断 binlog 构建docs/Docs.slnx、构建完整站点、将dist部署到 GitHub Pages权限模型PR 只获得可下载的站点构件绝不获得部署权限首次部署前置需在仓库 Settings → Pages → Source 中设为GitHub Actions本仓库为镜像托管场景下可参考此配置思路在自托管 Pages 环境中等价设置。维护清单速查场景命令docs/site目录下安装依赖npm install生成 API 数据需 .NET SDKnpm run api:generate本地开发预览npm run dev生产产物预览含 Pagefind 索引npm run buildnpm run preview全量校验八道关卡npm run validate仅链接审计npm run audit:links仅输出审计npm run audit:output构建/测试文档 C# 项目dotnet test --solution ../Docs.slnx --configuration Release --framework net10.0 -p:BuildExternalAssetsfalse --minimum-expected-tests 1 --max-parallel-test-modules 1仅编译 snippet 项目pwsh docs/site/src/content/docs/validate-snippets.ps1构建示例samples/Build-Samples.ps1仓库根执行综上Orleans 文档站点并非一个静态 Markdown 文件夹而是一条完整的文档工程流水线Markdown 源经过 DocFX 语法转换进入 Starlight 渲染API 参考由 Roslyn 级工具链自动生成而每一次构建都通过项目策略、源码质量、代码片段编译、链接安全与输出完整性五重审计来保证文档即代码、文档与源码同构。对希望为 .NET 大型开源项目搭建高质量文档体系的读者来说docs/site/ 与 docs/site/scripts/ 是一套可完整复用的参考实现。赞分享后端微服务【免费下载链接】orleansCloud Native application framework for .NET项目地址https://gitcode.com/gh_mirrors/or/orleans点击查看免费下载相关推荐Nhost 文档站点工程化解析基于 Astro Starlight 的编写、生成与校验体系Nhost 文档站点工程化解析基于 Astro Starlight 的编写、生成与校验体系 Nhost 的官方文档站点docs.nhost.io源码位后端认证鉴权数据库无服务开发工具云原生Slint Python API 文档站构建指南griffe Astro Starlight 驱动的 API 参考生成流水线Slint Python API 文档站构建指南griffe Astro Starlight 驱动的 API 参考生成流水线 本文档面向需要构建、维护或深测试开发工具TypeScript 进阶特性全览The Concise TypeScript Book「Others」章节精讲TypeScript 进阶特性全览The Concise TypeScript Book「Others」章节精讲 本文围绕开源项目 typ/typescrip文档教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考