GraphQL .NET 官方文档站构建与发布指南：基于 Gatsby 的 docs2 站点全解析

• 后端

本文以 graphql-dotnet 仓库中 docs2/README.md 为骨架，系统讲解 GraphQL .NET 官方文档站（docs2）的本地运行、构建与发布流程，并深入剖析其基于 Gatsby 的文档站点架构（菜单配置、Markdown 渲染、导航组件）与 publish_docs.sh 的部署原理。读完本文，你将掌握如何在自己的机器上启动这套文档站、如何用一条命令发布到 GitHub Pages，以及文档目录与页面路由之间是如何一一对应的。

导读

GraphQL .NET 的官方文档并不存放在仓库的静态文件里，而是由一个独立的 Gatsby 站点（docs2目录）托管——它以 site/sitemap.yml 作为导航骨架、以 site/docs 下的 Markdown 作为正文内容，编译成静态站点后发布到 GitHub Pages。本文围绕 docs2/README.md 中的两条核心命令（yarn develop本地开发、yarn deploy发布上线），结合仓库内插件与组件源码，完整还原这套文档系统的运行机制，帮助你理解 GraphQL .NET 官方文档（Getting Started、Guides、Analyzers、Migration Guides 四大栏目）是如何被组织、渲染和部署的。

一、docs2 是什么：GraphQL .NET 官方文档的静态站点

docs2是仓库中承载官方文档的 Gatsby 站点目录。与主项目（src/GraphQL 下的 .NET 源码）完全解耦，文档的正文、导航、样式与发布脚本都集中在docs2之下，结构如下：

• docs2/README.md：文档站的运行与发布说明（本文的主体）；
• docs2/gatsby-config.js：Gatsby 站点配置，声明插件、站点元信息与 Markdown 内容目录；
• docs2/gatsby-node.js：Gatsby Node API 占位实现；
• docs2/package.json：npm 脚本与依赖清单；
• docs2/publish_docs.sh：GitHub Pages 发布脚本；
• docs2/site/sitemap.yml：站点导航菜单定义；
• docs2/site/docs：全部文档正文（Markdown）；
• docs2/src：React 组件（布局、侧边导航、文档页）；
• docs2/plugins/docs：本地 Gatsby 插件，负责解析 sitemap 并生成页面。

从站点配置可以确认，该站点的元信息为：标题GraphQL .NET、描述GraphQL for .NET、关键词graphql,api,web api,.net,.net core（见 docs2/gatsby-config.js），与仓库根目录 README.md 中GraphQL for .NET的项目定位保持一致。

二、本地运行文档站：yarn 与 yarn develop

按照 docs2/README.md 的说明，在docs2目录下执行两条命令即可启动本地开发服务器：

yarn yarn develop

• yarn：根据 docs2/package.json 安装全部依赖（yarn install的简写）。依赖清单包括gatsby@5.16.1、react@18.2.0、react-dom@18.2.0、gatsby-transformer-remark、gatsby-remark-prismjs、gatsby-source-filesystem、gh-pages等；
• yarn develop：对应 docs2/package.json 中的"develop": "gatsby develop"，启动 Gatsby 开发服务器，提供热重载，编辑 docs2/site/docs 下的 Markdown 后浏览器会实时刷新。

2.1 两条 npm 脚本的分工

docs2/package.json 中定义了四个脚本，其中两个与日常使用直接相关：

注意deploy并不是直接调用gh-pages，而是转交给 docs2/publish_docs.sh 执行，脚本内容与参数会在下文第四节详细拆解。

2.2 Node 版本注意事项

docs2/README.md 明确指出发布文档需要Node v10.22.0，并提示v12.x 目前存在已知问题。这一约束是仓库作者留下的运行前提，建议在发布环境中使用版本管理器（如 nvm）锁定v10.22.0；如果只做本地预览，可先尝试当前环境的 Node 版本，遇到兼容性问题再切换到文档要求的版本。这一点属于环境限制，请以你实际安装的版本实测为准。

三、文档站架构：sitemap 驱动 + Markdown 渲染

本地开发之所以能"两条命令跑起来"，背后是docs2一套清晰的文档管线：YAML 菜单 → Gatsby 节点 → 页面路由 → React 组件渲染。

3.1 导航骨架：site/sitemap.yml

整个文档站的栏目结构由 docs2/site/sitemap.yml 单一文件定义，顶层分为四大部分：

• Getting Started：入门系列（Introduction、Installation、Queries、Schema Types、Arguments、Directives、Mutations、Subscriptions、Error Handling、Dependency Injection 等 31 篇，正文位于 docs2/site/docs/getting-started）；
• Guides：进阶指南（ASP.NET Core Integration、Serialization、Dataloader、Complexity Analyzer、Schema Generation、Document Caching 等 8 篇，正文位于 docs2/site/docs/guides）；
• Analyzers：GQL001～GQL020 共 20 条 Roslyn 分析器规则文档（正文位于 docs2/site/docs/analyzers，总览见 docs2/site/docs/analyzers/overview.md）；
• Migration Guides：v0.8.0 到 v8 的迁移指南（正文位于 docs2/site/docs/migrations）。

每个菜单项通过title、dir、file三个字段描述；dir对应 Markdown 所在子目录，file对应文件名。例如Getting Started → Installation对应 docs2/site/docs/getting-started/installation.md。

3.2 菜单如何变成页面：本地插件 docs

站点通过gatsby-config.js中的本地插件docs（指向 docs2/plugins/docs）驱动，核心逻辑在 docs2/plugins/docs/gatsby-node.js：

• sourceNodes（来自 docs2/plugins/docs/gatsby/sourceNodes.js）读取 sitemap YAML，用js-yaml解析后创建DocsMenu类型的 Gatsby 节点，并用chokidar监听配置文件变化，实现"改菜单即热更新"；
• createPages遍历菜单中的每个item.file，用github-slugger将文件名转成 slug，调用createPage生成路由，例如getting-started/installation.md会生成/docs/getting-started/installation这样的路径；
• onCreateNode为每个 Markdown 节点计算相对路径字段，供页面查询使用。

3.3 正文渲染：MarkdownRemark 与代码高亮

docs2/gatsby-config.js 通过gatsby-source-filesystem将 docs2/site/docs 挂载为内容源，再经gatsby-transformer-remark把 Markdown 转为 HTML，并依次套用三个插件：

1. gatsby-remark-prismjs：代码块语法高亮；
2. gatsby-remark-images：文档内图片处理（maxWidth: 600）；
3. gatsby-remark-autolink-headers：为标题自动生成锚点链接，方便文档内跳转与引用。

3.4 页面组件：docs-page 与 SideNav

渲染层面由 docs2/src/components/docs-page.js 负责：它通过 GraphQL 查询（query DocsPage($relativePath: String!)）拿到当前页面的 HTML 和站点元信息，用dangerouslySetInnerHTML注入正文，并在页面顶部提供 "Edit this page on GitHub" 编辑链接（基于siteMetadata.githubEditUrl拼接相对路径生成）。

侧边导航由 docs2/src/components/SideNav.js 递归渲染：根据当前路由高亮对应菜单项，带file的条目渲染为 Gatsby<Link>，无file的分组标题渲染为纯文本<span>，从而形成 docs2/site/sitemap.yml 里四级导航的树形 UI。配套的布局与样式见 docs2/src/components/layout.js、docs2/src/components/header.js 及同名.module.css文件。

四、发布到 GitHub Pages：yarn deploy 全流程

4.1 发布前提

docs2/README.md 列出了两条硬性前提：

1. 对graphql-dotnet/graphql-dotnet.github.io仓库拥有写权限——发布目标仓库是独立于本仓库的 GitHub Pages 站点仓库；
2. Node 版本为 v10.22.0（v12.x 当前存在已知问题）。

满足条件后，在docs2目录执行：

yarn deploy

4.2 脚本逐行拆解

yarn deploy实际运行 docs2/publish_docs.sh。该脚本是理解发布流程的关键，核心逻辑如下：

#!/bin/bash if [ -z "$1" ] then echo echo ERROR: Please provide a version echo echo ex: yarn deploy 2.0.0 echo else echo Generating documentation for Version $1 yarn gatsby build echo Publishing gh-pages -d public -b master \ -r git@github.com:graphql-dotnet/graphql-dotnet.github.io.git \ -m "Documentation update for $1" fi

逐段解读：

• 版本号参数：yarn deploy 2.0.0这样调用，脚本通过$1接收版本号；若未传参则打印ERROR: Please provide a version并给出示例后退出。版本号最终会写入 git 提交信息Documentation update for <版本号>；
• 生产构建：yarn gatsby build执行 Gatsby 生产构建，把 docs2/site/docs 的全部文档编译成静态文件输出到public/目录；
• 发布：gh-pages -d public将public目录作为站点内容发布；-b master指定目标分支为master（注意与常见默认gh-pages分支不同）；-r指定远端仓库git@github.com:graphql-dotnet/graphql-dotnet.github.io.git；-m指定提交信息。

gh-pages工具来自 docs2/package.json 的devDependencies（版本^5.0.0），由yarn安装后以二进制形式在脚本中调用。

4.3 一个容易忽略的细节：deploy 的版本号参数

README 写的是yarn deploy，而脚本要求$1版本号，两者需要配合理解：发布时实际应执行yarn deploy <版本号>，例如yarn deploy 2.0.0。若不传版本号，脚本会明确报错退出，这是脚本内置的"防呆"设计，确保每次发布都留下可追溯的版本标记。

五、发布产物与内容映射：从 sitemap 到线上 URL

理解文档管线后，可以把"仓库目录 → 线上路径"的映射关系总结如下：

• docs2/site/sitemap.yml 中的Docs栏目挂载在/docs路径下；
• 每个菜单项dir + file对应的 Markdown，经插件createPages生成 slug 路由，如 docs2/site/docs/getting-started/installation.md →/docs/getting-started/installation；
• 站点首页由 docs2/site/pages/landing.js（配 docs2/site/pages/landing.css）渲染，指向/根路径；
• 404 页面由 docs2/src/pages/404.js 提供。

也就是说，文档站的内容与 docs2/site/docs 目录保持一一对应：要新增或修改文档，只需编辑对应的.md文件并在 sitemap.yml 中登记菜单项，其余构建、路由、导航全部由 Gatsby 管线自动完成。

六、结合仓库源码的进阶阅读指引

如果你希望进一步深入这套文档系统，仓库内提供了完整的可追溯材料：

• 菜单 → 页面生成：docs2/plugins/docs/gatsby-node.js、docs2/plugins/docs/gatsby/sourceNodes.js；
• 站点与插件配置：docs2/gatsby-config.js、docs2/package.json；
• 导航与页面组件：docs2/src/components/SideNav.js、docs2/src/components/docs-page.js、docs2/src/utils/navigation.js；
• 发布脚本：docs2/publish_docs.sh；
• 文档正文样例：入门篇 docs2/site/docs/getting-started/installation.md、分析器总览 docs2/site/docs/analyzers/overview.md；
• sitemap 结构参考：docs2/site/sitemap.yml。

说明：本文所述均为仓库现有实现事实。Node 版本约束、GitHub Pages 发布目标等属于 docs2/README.md 明确记载的运行前提；脚本行为、路由生成规则等均可在上述源码文件中直接核对。若要在新环境复现发布流程，请先确认你具备对graphql-dotnet.github.io仓库的写权限，并按 README 要求锁定 Node 版本。

七、小结

• 本地预览文档站只需在docs2下依次执行yarn与yarn develop；
• 正式发布需满足两个前提（目标仓库写权限、Node v10.22.0），然后执行yarn deploy <版本号>；
• 发布链路为publish_docs.sh→gatsby build产出public/→gh-pages -d public -b master推送到graphql-dotnet.github.io仓库；
• 整套站点由 docs2/site/sitemap.yml 单一文件驱动导航，正文与 docs2/site/docs 目录一一映射，新增文档只需"加 Markdown + 登记菜单"两步。

掌握这套流程，你既能在本地快速预览 GraphQL .NET 官方文档，也能在获得权限后完整复现其 GitHub Pages 发布过程；更重要的是，理解了 Gatsby 文档管线的组织方式，为后续维护或借鉴这套文档方案打下了基础。

• 后端