企业官网建设流程全解析

TypeSpec 官网源码解析：基于 Astro + Starlight 的文档站工程实践

【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec

TypeSpec 项目的官方网站（文档站点）位于仓库的website/目录，由 website/README.md 描述其基础结构与常用命令。该站基于 Astro 框架与 Starlight 文档主题构建，承载了全部官方文档、博客、Playground 入口和 Release Notes。本文以website/README.md为骨架，结合仓库内真实的配置文件与源码，讲清这个文档站的目录约定、命令体系、构建管线（侧边栏自动生成、Release Notes 扫描、Mermaid 服务端渲染、llms.txt 生成等），读完后可在本仓库内定位并运行文档站的每一项核心能力。

README 定位：Starlight 起步模板

website/README.md 本身是 Starlight 官方 “Basics” 起步模板的说明文件，其中一句提示很能说明问题：“Seasoned astronaut? Delete this file. Have fun!”——即这份 README 只是脚手架自带的入门指引。它的技术内核有三部分：

1. 创建方式：npm create astro@latest -- --template starlight；
2. 项目目录结构约定（public/、src/assets/、src/content/docs/、astro.config.mjs等）；
3. 一张 npm 命令速查表（install / dev / build / preview / astro）。

TypeSpec 团队在这个模板之上做了大量工程化改造，下面逐层展开。

目录结构约定

README 给出的基础结构如下：

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

三条核心规则（原文照录并对照本仓库实际）：

• Starlight 会在src/content/docs/目录下查找.md或.mdx文件，每个文件按文件名暴露为一个路由。在本仓库中，website/src/content/docs/下按主题划分了getting-started/、handbook/、language-basics/、standard-library/、libraries/、emitters/、extending-typespec/等子目录，例如 language-basics/overview.md 这类文件会直接成为对应路由。
• 图片可放入src/assets/，并在 Markdown 中用相对链接嵌入。本仓库的website/src/assets/下存放了图标（favicon.svg、social.png）与作者头像（img/authors/），以及tsp-samples/目录——存放各功能页演示用的.tsp样例（如tsp-samples/openapi3/hero/main.tsp）。
• favicon 等静态资源放在public/目录。website/public/中包含img/（大量产品截图与 logo）、1ds-init.js（站点分析脚本，配合下方 SRI 校验使用）等静态文件。

在模板结构之外，本仓库的website/还额外包含：

命令体系

README 给出了一张命令速查表（原文继承）：

对照 website/package.json，这些命令的实际实现为：

{ "dev": "astro dev", "start": "astro dev", "build": "node ./.scripts/build.ts", "build:web": "pnpm regen-all-packages-docs && astro check --minimumFailingSeverity hint && NODE_OPTIONS=\"--max-old-space-size=8192\" astro build", "preview": "astro preview", "astro": "astro", "clean": "rimraf ./dist ./temp ./.astro", "update-playground-versions": "node ./.scripts/update-playground-versions.ts", "regen-docs": "node ./.scripts/regen-compiler-docs.ts", "regen-all-packages-docs": "pnpm -w --filter \"@typespec/website...\" --filter \"!@typespec/monorepo\" run regen-docs" }

几个值得注意的工程细节：

• 本仓库是 pnpm workspace 单仓（monorepo），package.json中的依赖大量使用workspace:^与catalog:协议（如@typespec/compiler、@typespec/playground、astro）。因此在仓库内实际操作时，应在website/目录使用pnpm dev/pnpm build等对应命令；README 中的npm写法是 Starlight 模板的通用示例。
• build:web展示了完整的生产构建链：先执行regen-all-packages-docs（见下文），再用astro check --minimumFailingSeverity hint做严格的类型检查（hint 级别失败即报错），并以 8GB 堆内存上限运行astro build——这从侧面说明文档站体量不小（数百篇 md/mdx 文档 + 自动生成的 API reference）。
• regen-docs与regen-all-packages-docs构成文档再生成管线：regen-docs（.scripts/regen-compiler-docs.ts）负责从编译器源码重新生成 API 参考文档；regen-all-packages-docs则通过 pnpm workspace 过滤@typespec/website...（即 website 及其依赖包）批量触发各包的regen-docs脚本，跳过@typespec/monorepo本身。
• Turborepo 缓存：website/turbo.json 声明build任务的输出包括dist/**、.astro/**以及public/install.sh、public/install.ps1（安装脚本会被构建生成到public/），并支持通过temp/turbo-build-skipped标记跳过无变化的构建。

站点总配置（astro.config.mjs）

website/astro.config.mjs 是整个文档站的中枢，几个关键配置值得逐一解析：

基础配置与 base 路径

const base = process.env.TYPESPEC_WEBSITE_BASE_PATH ?? "/"; // ... export default defineConfig({ base, site: "https://typespec.io", trailingSlash: "always",

• base支持通过环境变量TYPESPEC_WEBSITE_BASE_PATH指定子路径部署，默认/；
• trailingSlash: "always"强制所有 URL 带尾斜杠，并与 Markdown 相对链接插件保持一致（见下文）。

重定向表：日期版本文档到版本号路由的迁移

配置中维护了一张历史重定向表，把旧版/docs/release-notes/release-YYYY-MM-DD/路径逐条映射到新的语义化版本路径：

redirects: { ...(latestReleaseNote ? { "/release-notes/": `/${latestReleaseNote}/` } : {}), "/docs/release-notes/release-2025-04-02/": "/release-notes/typespec-1-0-0-rc-0/", "/docs/release-notes/release-2025-04-22/": "/release-notes/typespec-1-0-0-rc-1/", // ... 直至 typespec-1-10-0 }

其中第一条是动态生成的：/release-notes/永远 301 到“最新一篇” Release Note（最新篇的识别逻辑见下节）。

侧边栏：手动结构 + 自动目录扫描

Starlight 的sidebar选项由 src/content/current-sidebar.ts 定义的基础结构经processSidebar（来自@typespec/astro-utils/sidebar，实现见 packages/astro-utils/src/sidebar/）处理后注入：

• 顶层分组依次为 Getting started、Guides、Handbook、Language Basics、Standard Library、Libraries、Emitters、Writing TypeSpec Libraries；
• 每个库的条目通过createLibraryReferenceStructure()工厂函数生成：指向${libDir}/reference索引页，并autogenerate扫描reference/子目录（如 libraries/http 下的各库文档）；
• 工厂函数还支持按库的稳定性状态（stable/preview/beta/alpha）自动生成侧边栏徽标，例如 Rest、Events、SSE、Streams 等库标注preview，两个 Server 生成器标注alpha。

在astro.config.mjs中，docs 自动生成的侧边栏之外还追加了两项：指向最新 Release Note 的快捷链接，以及对release-notes/目录的autogenerate分组。

Release Notes 最新篇扫描

function getLatestReleaseNoteSlug() { const dir = resolve(import.meta.dirname, "src/content/docs/release-notes"); const files = readdirSync(dir).filter((f) => /\.mdx?$/.test(f) && !f.startsWith("index")); // 解析 frontmatter 中的 releaseDate，取日期最大者； // 优先使用 frontmatter 中显式的 slug 字段 }

从源码结构看，该函数在构建配置加载阶段同步读取website/src/content/docs/release-notes/下所有*.md/*.mdx文件，用正则提取 frontmatter 里的releaseDate字段，取日期最大的一篇作为“最新 Release Note”，并优先采用其 frontmatter 中显式声明的slug（否则回退为release-notes/<文件名>）。这一结果同时驱动/release-notes/的重定向和侧边栏的“🚀 Release Notes”链接。该目录中可见从release-2022-07-08.md到typespec-1-16-0.mdx的完整版本演进，命名从“日期式”过渡到“语义版本式”，正与上文重定向表对应。

Markdown 管线：锚点、Mermaid 与相对链接

markdown: { remarkPlugins: [remarkHeadingID], rehypePlugins: [ [rehypeMermaid, { strategy: mermaidStrategy }], [rehypeAstroRelativeMarkdownLinks, { base, collectionBase: false, trailingSlash: "always" }], ], shikiConfig: { langs: [TypeSpecLang] }, }

• remarkHeadingID为所有标题生成稳定 id，使文档内的锚点跳转（#xxx）可用；
• Mermaid 渲染采用双策略：getMermaidStrategy()在 CI 环境（process.env.CI）强制inline-svg（服务端用 Playwright 预渲染为 SVG 内联到 HTML）；本地则尝试启动 Playwright Chromium，成功则同样走inline-svg，失败则回退到pre-mermaid（客户端渲染）并打印提示——此时可运行npx playwright install --with-deps chromium启用服务端渲染；
• rehypeAstroRelativeMarkdownLinks按base与trailingSlash: "always"规范 Markdown 中的相对链接，保证迁移 base 路径或部署到子路径时文档内链不断；
• shikiConfig.langs注入TypeSpecLang（来自@typespec/astro-utils/shiki，实现见 packages/astro-utils/src/shiki/），使代码块中tsp语言获得正确的语法高亮。

Expressive Code 与组件覆写

• astroExpressiveCode()集成直接挂在 Astro 层，Starlight 侧关闭了内置的expressiveCode（expressiveCode: false, // defined directly above），避免重复；其配置集中在 website/ec.config.mjs，委托@typespec/astro-utils/expressive-code/config的defineTypeSpecEcConfig(base)统一生成，同样尊重TYPESPEC_WEBSITE_BASE_PATH；
• components中覆写了 Starlight 的三个组件：Header（src/components/header/header.astro，含 search.astro 搜索入口）、PageFrame与Sidebar（src/components/starlight-overrides/），用于定制站点头部与导航；
• head中注入了两段脚本：外部同意管理脚本，以及1ds-init.js——后者是放在 website/public/1ds-init.js 的站点分析脚本，加载时通过computeSriHash("1ds-init.js")（实现见 src/utils/sri-hash.ts）计算 SRIintegrity哈希并写入<script>标签，校验脚本完整性。

内容集合与博客

Starlight 的文档内容通过 Astro Content Layer 管理，定义在 src/content.config.ts：

export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema({ extend: z.object({ version: z.string().optional(), releaseDate: z.coerce.date().optional(), // 需兼容 new Date() llmstxt: llmstxtSchema.optional(), }), }), }), blog: defineCollection({ loader: glob({ pattern: "**/[^_]*.{md,mdx}", base: "./src/content/blog" }), schema: z.object({ title: z.string(), description: z.string(), publishDate: z.coerce.date(), author: authorSchema.optional(), // 单作者 authors: z.array(authorSchema).optional(), // 多作者 // ... }), }), i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }), };

• docs集合在 Starlight 标准 schema 上扩展了三个字段：version、releaseDate（即上文 Release Notes 扫描所依赖的 frontmatter 字段，类型层面同样被 zod 校验）以及llmstxt（来自@typespec/astro-utils/llmstxt/schema，用于控制 llms.txt 输出，见 packages/astro-utils/src/llmstxt/）；
• blog集合用 glob loader 扫描website/src/content/blog/下的所有md/mdx（[^_]前缀约定排除下划线开头的非文章文件），当前包含 Introducing TypeSpec、TypeSpec 1.0 发布等多篇博文（如 2025-03-31-typespec-1-0-release/typespec_1_0_release.md）；
• i18n集合承载 Starlight 的国际化字典（src/content/i18n/en.json）。

与 llms.txt 相关的路由在 src/pages/docs/ 下实现（llms.txt.ts、llms-full.txt.ts、llms.json.ts等），配合docs集合的llmstxt字段，面向 LLM/Agent 提供机器可读的站点文本接口；src/pages/playground.astro与components/playground-component/则内嵌了@typespec/playground在线编辑器。

小结

website/README.md以 Starlight 起步模板的口吻给出了文档站的最小认知框架——src/content/docs/即路由、public/放静态资源、npm run dev/build/preview三大命令；而 astro.config.mjs、content.config.ts、current-sidebar.ts 与.scripts/下的再生成脚本则展示了它在生产中的完整形态：

1. 内容层：docs 集合扩展releaseDate/version/llmstxt字段，博客集合独立管理作者与日期；
2. 导航层：侧边栏 = 手动分组（含稳定性徽标）+ 目录自动扫描，Release Notes 通过 frontmatter 日期扫描自动定位最新篇并生成重定向；
3. 渲染层：tsp 语言高亮、Mermaid 服务端 SVG（可回退客户端）、相对链接规范化、标题锚点；
4. 构建层：build:web= 全仓文档再生成 + 严格类型检查 + 大内存 Astro 构建，配合 Turborepo 输出缓存。

对希望在本地运行该文档站的读者：在website/目录执行pnpm install后，pnpm dev即可在localhost:4321预览；需要修改 API 参考文档时先运行pnpm regen-docs（或全量pnpm regen-all-packages-docs）再重新构建；若本地 Mermaid 提示回退为客户端渲染，安装 Playwright Chromium 即可恢复服务端 SVG 渲染。

【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec