企业官网建设流程全解析

• 前端
• UI组件

FAST（The adaptive interface system for modern web experiences）仓库中的官方文档网站包@microsoft/fast-site（对应sites/website目录）记录了项目文档体系从搭建、功能扩张到工程化完善的完整轨迹。本文以 sites/website/CHANGELOG.md 为骨架，逐版本解读 fast-site 从 0.2.0（2020 年 8 月）到 0.6.2（2021 年 4 月）的核心变更，并结合当前仓库源码剖析文档站的构建流水线、版本横幅机制与底层样式共享实现，帮助读者理解 FAST 官方文档站的演进逻辑与现状，掌握其查看、本地运行与构建方式。

一、fast-site 是什么：项目定位

fast-site 是 FAST 项目官方文档网站所在的 npm 包（private: true，仅仓库内部使用），负责承载 FAST 的组件文档、API 参考、迁移指南与社区内容。从 sites/website/package.json 可以看到，当前包版本为0.6.2，构建脚本已完全基于Eleventy（11ty）静态站点生成器：

{ "name": "@microsoft/fast-site", "version": "0.6.2", "private": true, "type": "module", "scripts": { "clean": "clean build tmp", "prebuild": "npm run clean && node scripts/generate-docs.cjs 3", "build": "npm run prebuild && npx @11ty/eleventy --output=build --input=src", "start": "npm run prebuild && npx @11ty/eleventy --output=build --input=src --serve --incremental", "help": "npx @11ty/eleventy --help" } }

依赖方面，站点使用@11ty/eleventy（^3.1.2）、@11ty/eleventy-navigation（侧边栏导航）、@11ty/eleventy-plugin-syntaxhighlight（代码高亮），并通过@microsoft/api-documenter从 API 报告生成 API 参考文档。这与变更日志早期 "new docusaurus v2 setup" 的时代形成了鲜明对比，是理解文档站演进的关键线索。

二、版本全景：fast-site 0.2.0 → 0.6.2 变更一览

CHANGELOG 记录的所有版本与核心变更如下（含 4 次纯版本号 bump 与 7 个实质性版本）：

版本号遵循 Conventional Commits 规范（CHANGELOG 头部有明确声明），因此 0.x.y 的 minor 版本（0.3.0、0.4.0、0.5.0、0.6.0）均携带 Features，patch 版本多为核心依赖版本联动（"Version bump only"）。

三、0.2.0：文档站奠基版本，一次完整的从无到有

0.2.0 是 fast-site 的起始版本（2020-08-27），承载了最多类型的变更，可归纳为四类工程决策。

3.1 站点框架与构建体系

• new docusaurus v2 setup with launch toc configuration（#3159）：引入 Docusaurus v2 作为文档框架，并配置了启动 TOC（Table of Contents）。这是文档站技术栈的第一代定型。
• switch to webpack for homepage building（#3510）：首页构建切换到 Webpack，是当时首页构建体系的一次重构。
• update docusaurus and use local fast-components min bundle（#3605）：升级 Docusaurus 并改用本地 fast-components 压缩产物，减少对外部 CDN 的依赖。

3.2 品牌与页面表现

• update the sites to use the same favicon, update the logo（#3406）与update logo on documentation pages（#3686）：统一各站点 favicon 与 logo，保证品牌一致性。当前仓库 sites/website/src/static/favicon.ico 与 sites/website/src/static/fast-inline-logo.svg 即这一工作的延续，且被根布局 sites/website/src/_includes/root.njk 引用。
• restore original docusaurus footer（#3719）：恢复 Docusaurus 原始页脚；当前 root.njk 中仍保留 Docs / Community / Social / Legal 四栏页脚结构。
• website: add more obvious styles to the mobile ToC button（#3714）：增强移动端目录按钮的可见性，呼应移动端阅读体验的重视。

3.3 文档内容与可读性

• add live code examples to docs site（#3216）：文档站加入实时代码示例能力，提升文档的交互性。
• add links to documentation header（#3684）：文档页头部加入导航链接。
• copy editing for writing-documentation markdown（#3724）、correct typo in docs introduction（#3725）、join documentation copywriting and edits（#3729）：对文档写作指南与引言页进行文案编辑与勘误，体现了 FAST 对文档质量本身（"docs about docs"）的工程投入。
• fixing link to documentation（#3362）与addresses an issue where website will not show on safari（#3409）：前者修复文档链接，后者修复网站在 Safari 上不显示的问题，是早期兼容性修复的典型。

3.4 与底层框架能力联动

0.2.0 中有三条变更直接反映 FAST 底层库（fast-element）能力的升级被文档站消费：

• design-system-provider now paints CSS color and background color（#3278）：DesignSystemProvider 开始渲染 CSS color 与 background-color。
• export MatchMediaStylesheetBehavior constructor（#3445）：导出 MatchMediaStylesheetBehavior 构造函数（用于基于媒体查询切换样式的行为）。
• export form-associated under alpha flag（#3618）：在 alpha 标志下导出 form-associated（表单关联组件能力）。
• adding directional stylesheet behavior（#3559）：新增方向性样式表行为（配合 RTL/LTR 布局方向切换）。

这一模式在后续版本中反复出现：文档站的版本变更往往与 FAST 组件库、fast-element 的新能力同步落地。

四、0.3.0 与 0.4.0：组件文档版图扩张

• 0.3.0（2020-09-28）：新增skeleton 组件（#3877）与tooltip 组件（#3549）的文档。这两个组件分别用于加载占位与浮层提示，如今在 sites/website/src/docs/3.x/components 目录下仍有对应的组件文档页。
• 0.4.0（2020-11-19）：新增fast-breadcrumb 与 fast-breadcrumb-item 组件（#3627）；同时落地enable shared CSSStyleSheets in DesignSystemProvider（#4065），即 DesignSystemProvider 中启用共享 CSSStyleSheets——这是与 fast-element 样式系统深度相关的底层优化（详见第七节）。

五、0.5.0：可访问性与数据应用组件

0.5.0（2021-01-30）的三项变更展示了文档站的两个方向：

• adding high contrast document to the FAST documentation website（#4178）：新增高对比度（high contrast）主题文档，服务于 Windows 高对比度模式下 Web 组件的可访问性指导。
• addressed missing images in the high contrast document（#4216）：紧随其后修复了高对比度文档中图片缺失的问题，属于典型的内容质量闭环（新增 → 补漏）。
• add fast-number-field component for data applications（#4204）：为数据应用新增 number-field 组件文档。
• add select spec（#4194）：补充 select 组件的规范文档。

六、0.6.0 与 0.6.1：测试基建与文档生成修复

• 0.6.0（2021-03-06）add playwright（#4337）：文档站引入 Playwright 端到端测试能力。这与仓库当前的整体测试策略一脉相承——packages/fast-element/playwright.config.ts 显示组件核心库同样以 Playwright 为浏览器级测试基座（大量*.pw.spec.ts测试文件），说明文档站的工程化与核心库测试体系保持同频。
• 0.6.1（2021-03-16）broken formatting and link when generating docs site（#4459）：修复了生成文档站点时出现的格式错误与链接失效问题。这与今天 sites/website/scripts/generate-docs.cjs 中大量链接重写逻辑（将./xxx.md重写为./xxx/、面包屑链接修正等）要解决的问题同源——自动生成文档的链接可靠性是文档站长期维护的重点。

七、源码佐证：从 CSSStyleSheets 共享看 fast-element 样式系统的底层实现

CHANGELOG 中 0.4.0 的 "enable shared CSSStyleSheets in DesignSystemProvider" 与 0.2.0 的 "design-system-provider now paints CSS color" 背后，是 fast-element 的样式策略（StyleStrategy）体系。当前源码 packages/fast-element/src/styles/element-styles.ts 中可以看到完整的实现：

• StyleTarget接口（packages/fast-element/src/styles/style-strategy.ts）定义了样式应用目标必须具备adoptedStyleSheets、append、removeChild、querySelectorAll能力，同时支持 adopted style sheets 与<style>元素两条注入路径。
• ElementStyles在构造strategy时通过能力检测选择策略（packages/fast-element/src/styles/element-styles.ts）：

this.withStrategy( ElementStyles.supportsAdoptedStyleSheets ? createAdoptedSheetsStrategy() : createStyleElementStrategy(), );

• 能力检测本身（element-styles.ts）：

public static readonly supportsAdoptedStyleSheets = Array.isArray((document as any).adoptedStyleSheets) && "replace" in CSSStyleSheet.prototype;

• createAdoptedSheetsStrategy()（element-styles.ts）用Map<string, CSSStyleSheet>缓存字符串 → 样式表的映射，使同一份 CSS 字符串在多个组件实例间共享同一个 CSSStyleSheet，这正是"shared CSSStyleSheets"的底层机制；它通过向目标的adoptedStyleSheets数组追加/过滤实现样式的添加与移除，避免重复解析 CSS。

由此可见，fast-site 变更日志中关于 DesignSystemProvider 的条目并非孤立的文档工作，而是 fast-element 样式性能优化（样式共享、避免重复序列化）在文档与站点层面的同步体现。

八、当下架构：从 Docusaurus 到 Eleventy 的文档站现状

尽管 CHANGELOG 记录的是 Docusaurus v2 时代，当前仓库中的文档站已全面迁移到Eleventy（11ty）。理解现状有助于读者正确查看与使用这份文档：

8.1 文档生成流水线

npm run build会先执行prebuild（node scripts/generate-docs.cjs 3），再运行 Eleventy。生成脚本 sites/website/scripts/generate-docs.cjs 承担三项工作：

1. copyAPI：从packages/fast-element/dist/拷贝fast-element.api.json及context、declarative、di三个子导出的 API 报告到临时目录。
2. runApiDocumenter：调用@microsoft/api-documenter将 API 报告转换为 Markdown，输出到src/docs/3.x/api/。
3. convertDocFiles：为生成的 API Markdown 注入 Eleventy frontmatter（id、title、layout、eleventyNavigation、navigationOptions），并将相对链接改写为站点可用的路径格式（如./index.md→../index.html、./xxx.md→./xxx/）。

同时buildSizesPage会从 packages/fast-element/SIZES.md 生成src/docs/3.x/resources/export-sizes.md页面。

8.2 版本横幅机制

站点为不同文档大版本（1.x、2.x、3.x）提供可配置的版本状态横幅。配置位于 sites/website/src/_data/versionBanners.js：

export default function () { return { "1.x": { enabled: true, type: "legacy", message: "You are viewing documentation for a previous version of FAST. The latest version is 3.x.", }, "2.x": { enabled: true, type: "legacy", message: "You are viewing documentation for a previous version of FAST. The latest version is 3.x.", }, "3.x": { enabled: false, type: "stable", message: "You are viewing the current stable version of FAST.", }, }; }

三种type对应三种视觉语义（详见 sites/website/README.md 与 sites/website/src/css/version-banner.css）：

横幅通过 sites/website/src/_includes/version-banner.njk 渲染，由 sites/website/src/_includes/doc.njk include，并且只在/docs/路径下展示；CSS 通过 sites/website/src/_includes/root.njk 全站加载。legacy横幅中的版本判断依赖 Eleventy 过滤器version（在 sites/website/eleventy.config.js 中从 URL 提取版本段，默认回退到3.x）。

8.3 导航、分页与扩展语法

• 侧边栏导航：基于@11ty/eleventy-navigation插件（sites/website/eleventy.config.js），布局模板如 sites/website/src/_includes/2x-container.njk 通过eleventyNavigationToHtml渲染菜单。
• 上一篇/下一篇分页：prevNext过滤器（eleventy.config.js）深度优先展平导航树，按侧边栏顺序找到当前页的前后条目，供分页导航组件使用。
• Admonition 提示块：仓库自研的 markdown-it 插件 sites/website/plugins/admonitions.js 解析 Docusaurus 风格的:::tip/:::note/:::warning/:::important围栏块，渲染为带alert--success、alert--secondary、alert--warning、alert--info样式的提示框，支持单段与跨段闭合两种形态。

九、本地运行与构建指南

根据 sites/website/README.md，在仓库根目录执行：

# 安装依赖（仓库锁文件驱动） npm ci # 构建文档站：生成 API 文档到 src/docs/3.x/api/，再输出静态站点到 build 目录 npm run build # 本地开发：生成文档并启动增量热更新服务器 npm start

npm run build生成的build目录为纯静态产物，可用任意静态托管服务部署。npm start走--serve --incremental模式，适合文档写作时的实时预览。仓库使用 lage 进行任务编排（见 lage.config.js），构建产物缓存于dist/**与wasm/**。

十、结语：一份 CHANGELOG 背后的工程演进史

从 0.2.0 的 Docusaurus v2 奠基，到 0.5.0 的可访问性与数据应用组件扩张，再到 0.6.0 的 Playwright 测试基建，fast-site 的 CHANGELOG 完整记录了一个官方文档站在"框架选型、品牌统一、内容质量、能力扩张、测试工程化"五个维度的演进节奏；而当前仓库则展示其最终形态——基于 Eleventy 的静态站点生成、脚本驱动的 API 文档流水线、可配置的版本横幅与导航分页体系。若读者希望进一步探索，推荐依次阅读 sites/website/CHANGELOG.md、sites/website/scripts/generate-docs.cjs 与 packages/fast-element/src/styles/element-styles.ts，从"变更记录 → 构建逻辑 → 底层实现"三个层面完整还原这条演进链路。

• 前端
• UI组件