企业官网建设流程全解析

• 认证鉴权
• 后端

OpenAuth 是一个通用的、基于标准的认证服务提供方（Universal, standards-based auth provider），其官方文档站点位于仓库的www/目录，采用 Astro + Starlight 搭建，并配合 TypeDoc 从packages/openauth源码自动生成 API 参考文档。本篇以 www/README.md 的项目结构与命令说明为骨架，结合仓库内真实的配置与生成脚本，讲解文档站的目录组织、日常开发命令、文档内容组织方式、TypeDoc 自动生成链路以及站点级配置，帮助你快速上手这套文档站的本地开发与构建流程。

一、www/README.md与文档站的定位

www/README.md 是 Starlight Starter Kit 的模板说明文件，描述的是一个 Astro + Starlight 文档工程的标准骨架。在 OpenAuth 仓库中，这个骨架被实际落地为www/目录——即 OpenAuth 的官方文档站（站点地址配置在 astro.config.mjs 中，域名由仓库根目录的 CNAME 指向openauth.js.org）。

与仓库中其他目录（如 packages/openauth 承载核心 SDK、examples 承载示例应用）不同，www/是一个纯文档工程：它不包含任何运行时业务逻辑，只负责把 OpenAuth 的架构理念、Provider 配置、UI 主题、存储适配器等内容，以可搜索、可导航、可主题化切换的文档站点形式呈现给开发者。

二、项目结构：Starlight 文档工程的标准骨架

按照 www/README.md 的说明，一个 Astro + Starlight 项目内部通常包含以下文件夹和文件：

. ├── public/ ├── src/ │ ├── assets/ │ ├── content/ │ │ ├── docs/ │ │ └── config.ts │ └── env.d.ts ├── astro.config.mjs ├── package.json └── tsconfig.json

对照 OpenAuth 仓库中www/的真实目录，这一骨架被完整实现：

README 还给出了三条使用规则，在www/中都能找到对应印证：

1. Starlight 会读取src/content/docs/下的.md或.mdx文件，每个文件根据其文件名暴露为一个路由（route）。例如 client.mdx 对应/docs/client页面，issuer.mdx 对应/docs/issuer页面。
2. 图片可以添加到src/assets/并用相对链接嵌入 Markdown。文档首页 index.mdx 就是通过import themeDark from "./themes-dark.png"的方式引入主题截图的。
3. 静态资源（如 favicon）可以放在public/目录，站点配置中的<link rel="icon">标签即引用这些文件。

三、常用命令：从本地开发到生产构建

www/README.md 给出的命令表适用于所有 Astro + Starlight 工程，在 OpenAuth 的 www/package.json 中有与之对应的脚本定义：

需要特别注意的是build脚本：OpenAuth 文档站的生产构建并非直接astro build，而是先执行bun generate.ts再构建。这一步在 README 的标准模板上做了实质性扩展——它会在构建前用 TypeDoc 从 SDK 源码重新生成全部 API 参考文档，具体机制见本文第五节。

此外，www/package.json 中的脚本还包含了"start": "astro dev"别名，方便在部分依赖npm start的容器平台上直接启动开发服务器。依赖方面，除了astro与@astrojs/starlight，还引入了@astrojs/markdown-remark（用于标题 ID 处理）、rehype-autolink-headings（自动为标题生成锚点链接）、toolbeam-docs-theme（文档站主题插件）、typedoc（API 文档生成）以及sharp（图片处理）、@fontsource/ibm-plex-mono（等宽字体）。

四、文档内容组织：docs 集合、Frontmatter 与 Sidebar

4.1 Content Collection 配置

www/src/content/config.ts 定义了唯一的文档集合：

import { defineCollection } from "astro:content" import { docsSchema } from "@astrojs/starlight/schema" export const collections = { docs: defineCollection({ schema: docsSchema() }), }

所有文档都归入docs集合，并统一使用 Starlight 提供的docsSchema()校验 Frontmatter（title、description、editUrl、sidebar等字段）。例如文档首页 www/src/content/docs/index.mdx 的 Frontmatter：

--- title: OpenAuth description: Universal, standards-based auth provider. template: splash hero: title: Universal, standards-based auth tagline: A universal, standards-based auth provider. image: dark: ../../assets/logo-dark.svg light: ../../assets/logo-light.svg alt: OpenAuth logo ---

其中template: splash与hero字段驱动了 Hero.astro 对首页的特殊渲染（详见第七节）。

4.2 文档目录的四大板块

www/src/content/docs/docs/下的文档按主题分目录组织，与 astro.config.mjs 中的sidebar配置一一对应：

• Quick Start：standalone.mdx、sst.mdx——快速开始指南；
• Core：client.mdx、issuer.mdx、subject.mdx——核心概念；
• Providers：provider/ 目录下的 18 个文件——第三方身份提供商与内置流程（Google、GitHub、Apple、Password、Code、OIDC、OAuth 等）；
• UI：theme.mdx、select.mdx、code.mdx、password.mdx——主题与预置 UI；
• Storage：memory.mdx、dynamo.mdx、cloudflare.mdx——存储适配器。

注意一个细节：src/content/docs/下存在两层docs/（即www/src/content/docs/index.mdx与www/src/content/docs/docs/...）。前者是文档集合的入口文件（/docs路由），后者是 TypeDoc 自动生成的 API 参考文档（对应/docs/client、/docs/issuer等路由），在 astro.config.mjs 的sidebar配置中可以看到它们的映射关系（如{ label: "Intro", slug: "docs" }、{ label: "Standalone", slug: "docs/start/standalone" }）。

五、TypeDoc 自动生成：文档站的核心构建链路

www/README.md 只描述了通用的 Starlight 工程，而 OpenAuth 文档站最独特的地方在于 www/generate.ts——一个基于 TypeDoc 的文档自动生成脚本，它在每次build前运行，把 packages/openauth/src 下的 TypeScript 源码直接转译为 MDX 文档。

5.1 生成流程

脚本的核心逻辑（www/generate.ts）大致如下：

1. 引导 TypeDoc：TypeDoc.Application.bootstrap(...)以packages/openauth/src下的所有公开模块为入口点，包括client.ts、issuer.ts、subject.ts、error.ts、全部provider/*、storage/*和ui/*文件；
2. 转换源码：app.convert()生成项目反射（reflection），同时输出一份output/doc.json供调试；
3. 按模块分类：脚本把转换结果按subject、issuer、client、ui/*、provider/*、storage/*分类（www/generate.ts）；
4. 渲染 MDX：renderProvider、renderStorage、renderUI、renderClient、renderIssuer等函数把每个模块的方法签名、接口属性、参数、返回值、JSDoc 注释渲染为带 Frontmatter 的 MDX 文件，写入src/content/docs/docs/。

5.2 生成的文档内容形态

以renderProvider为例（www/generate.ts），每个 Provider 模块会生成一个页面，包含：

• 从FRONTMATTER映射表（www/generate.ts）取出的title、description、editUrl——后者指向源码中对应的.ts文件（如packages/openauth/src/provider/github.ts），供读者点击跳转编辑；
• <Section type="about">模块说明、## Methods方法列表（签名 + 参数 + 返回值）、## Interfaces接口属性说明。

每个函数页面的签名以代码块呈现（renderSignatureAsCode），例如issuer(...)会渲染为issuer(input)形式的代码片段。editUrl的生成逻辑位于 www/generate.ts，其 base URL 由 www/config.ts 中的github字段提供。

5.3 生成与手写文档的协作

由于生成脚本的输出目录与手写文档（如 docs/index.mdx）共存于src/content/docs/docs/，两者通过不同的 Frontmatter 与文件名避免冲突。Starlight 的docsSchema()保证所有文档（无论手写还是生成）都符合同一套字段规范。这意味着：修改 SDK 源码中的 JSDoc 注释后，重新执行bun generate.ts（即npm run build）即可同步更新 API 参考文档，手写教程（Quick Start、Approach 等）则保持独立维护。

六、站点级配置：astro.config.mjs 详解

www/astro.config.mjs 是文档站的枢纽配置，其中值得关注的配置项包括：

其中rehypeHeadingIds与rehypeAutolinkHeadings的组合（www/astro.config.mjs）对文档检索尤为关键：它让每个章节标题都有稳定的锚点 URL（如/docs/issuer#errors），无论人是机器都能精确引用到具体小节。

七、自定义组件与样式：Hero、Lander 与明暗主题

Starlight 允许通过components.Hero覆盖默认 Hero 组件。OpenAuth 的 www/src/components/Hero.astro 根据当前路由决定渲染方式：

• 当slug === ""（即/docs首页）时，渲染自定义的 www/src/components/Lander.astro 落地页；
• 其余文档页面回退到 Starlight 默认的 Hero 组件。

落地页 www/src/components/Lander.astro 展示了 OpenAuth 的核心卖点——Universal（可作为独立服务部署，也可嵌入现有应用，兼容任意框架与平台）、Self-hosted（完全运行在自己的基础设施上，支持 Node.js、Bun、AWS Lambda、Cloudflare Workers）、Standards-based（实现 OAuth 2.0 规范，任何 OAuth 客户端都可使用）、Customizable（提供可主题化的预置 UI，可自定义或完全弃用）——并提供"查看文档"与"Star on GitHub"的入口按钮。

样式层面，customCss引入了 www/src/custom.css 与 www/src/styles/lander.css：前者目前为空文件（预留扩展点），后者专供落地页布局（hero、cta、content、footer等区块的边框与排版，见 Lander.astro）。

八、本地开发与部署实践

结合 README 与仓库配置，完整的本地开发流程如下：

1. 在仓库根目录安装依赖（根目录 package.json 使用 bun workspaces 管理packages/openauth与示例目录，且仓库存在 bun.lockb，表明项目默认使用 bun）：

   bun install

2. 启动文档站开发服务器：

   cd www && npm run dev

   浏览器访问http://localhost:4321即可看到文档站，修改www/src/content/docs/下的 MDX 文件会触发热更新。

3. 生产构建（会先触发 TypeDoc 生成，再执行 Astro 构建）：

   cd www && npm run build

   产物输出到./dist/，可用npm run preview在部署前本地预览。

4. 需要校验文档 Frontmatter 或组件类型时，可运行npm run astro check。

需要说明的适用前提：build脚本依赖bun（bun generate.ts），如果环境只安装了 Node.js/npm，需要先安装 bun；TypeDoc 生成步骤要求packages/openauth的源码与 tsconfig.json 可用，因此不能脱离仓库根目录单独构建www/。

九、总结

www/README.md 虽然是一份 Starlight 模板说明，但在 OpenAuth 仓库中它对应着一套真实、完整的文档工程。通过本文可以看到：

• 目录组织：public/、src/assets/、src/content/docs/、src/content/config.ts、astro.config.mjs各司其职，MDX 文件名即路由；
• 命令体系：dev/build/preview覆盖开发到发布，且build前置了 TypeDoc 生成步骤；
• 内容管线：手写教程与generate.ts自动生成的 API 参考文档共存于同一集合，保证 SDK 文档与源码注释同步；
• 站点能力：明暗主题、锚点标题、自定义落地页、社交链接、编辑链接等配置均可在astro.config.mjs中集中管理。

对于想参与 OpenAuth 文档贡献或搭建类似"SDK 源码驱动文档"站点的开发者，www/这套 Astro + Starlight + TypeDoc 的组合是一个可以直接复用的范式。

• 认证鉴权
• 后端