企业官网建设流程全解析

• 开发工具
• 前端

React Styleguidist 是一个隔离式 React 组件开发环境与“活样式指南”（living style guide）生成工具，而它的官方文档站点（react-styleguidist.js.org）本身就是一个基于 Docusaurus 2 构建的现代静态网站。本文以仓库中的 site/Readme.md 为主线，结合site/目录下的配置与脚本源码，完整讲解该站点的安装、文档同步、本地开发、生产构建与部署工作流，帮助读者掌握一套“文档与源码同仓库、命令式驱动发布”的静态站点维护方案。

站点定位与技术栈

site/目录是 React Styleguidist 项目仓库中的一个独立子项目，负责承载项目的官方文档网站。它使用Docusaurus 2（一个现代静态站点生成器）构建，这一点在原文档中被明确指出，也可以从 site/package.json 中核实：该子项目依赖@docusaurus/core与@docusaurus/preset-classic，版本均为2.0.0-alpha.64（即 Docusaurus 2 的早期 alpha 版本），同时引入了react/react-dom（^16.13.1）、fs-extra、glob、lodash与unist-util-visit等辅助依赖。

从 site/Readme.md 的描述可以看出，这是一个“内容与代码同源”的站点：主仓库根目录的docs/下保存着全部 Markdown 技术文档，site/只负责把这些文档吸收、渲染并发布成网站。因此站点维护流程分为四个核心命令：

npm install # 安装站点依赖 npm run sync # 从仓库根目录同步文档到站点目录 npm start # 启动本地开发服务器（热更新） npm run build # 生成静态站点到 build 目录

下文将逐一剖析每个环节背后的脚本与配置实现。

安装依赖与文档同步（npm install + npm run sync）

安装依赖

与所有 Node 项目一样，第一步是安装依赖：

npm install

site/是一个独立的 npm 包（name为styleguidist-site，见 site/package.json），因此依赖与锁文件（package-lock.json）都独立维护，不会污染主仓库的依赖树。

文档同步：npm run sync

这是本站点工作流中最具特色的步骤。在 site/package.json 中可以看到sync脚本的定义：

"sync": "node scripts/sync.js"

它执行的 site/scripts/sync.js 负责把仓库根目录docs/文件夹中的 Markdown 文档“吸收”进站点：

• 使用glob匹配../docs/*.md（即仓库根目录docs/下的一级文档）；
• 用正则从文档中提取# 标题作为 Docusaurus 的title；
• 解析<!-- 侧边栏标题 #自定义id -->形式的注释，生成sidebar_label与可选的id；
• 若未指定自定义 id，则通过lodash.kebabCase将侧边栏标题转换为短横线 id（例如GettingStarted→getting-started）；
• 将 Markdown 中形如> **注意:** xxx的引用块转换为 Docusaurus 的:::提示语法；
• 为每篇文档生成带id/title/sidebar_label/custom_edit_url的 front matter，并写入site/docs/目录；
• 每次同步前会先emptyDirSync清空目标目录，保证文档目录与源保持一致。

这一脚本意味着：主仓库 docs/ 下的文档是唯一事实来源，站点只是其渲染层。开发者更新文档后，只需运行npm run sync即可让站点内容同步。

本地开发（npm start）

同步完成后，即可启动本地开发环境：

npm start

该命令在内部执行docusaurus start，启动一个本地开发服务器并自动打开浏览器窗口。如原文档所述，“大多数修改都能实时反映在页面上，无需重启服务器”——这是 Docusaurus 开发服务器的热更新（live reload）能力，编辑docs/下的文档（重新 sync 后）或site/src/下的源码、样式都会即时生效。

值得注意的一点是：由于文档来自npm run sync生成的副本，本地调试流程通常为“修改docs/→npm run sync→ 浏览器实时刷新”，这与直接编辑site/docs/的方式相比更能保证最终发布内容与仓库源文档一致。

生产构建与部署（npm run build + deploy.sh）

生成静态站点

npm run build

该命令执行docusaurus build，将整个站点编译为纯静态内容输出到build目录。如原文档所述，这个目录“可以使用任意静态内容托管服务来提供服务”，不需要 Node 运行时，因此可以部署到 Netlify、GitHub Pages 或任何 CDN / 对象存储。

自动化部署脚本

仓库中还提供了完整的自动部署脚本 site/scripts/deploy.sh，展示了“示例 + 文档站”的一体化发布流程：

1. 先构建examples/basic基础示例：cd ../examples/basic && npm install && npm run styleguide:build，生成一份真实可运行的 Styleguidist 样式指南；
2. 将示例产物复制到站点静态目录static/examples/basic，使其成为官网上的在线 Demo；
3. 执行npm run sync同步文档；
4. 最后执行npm run build产出完整静态站点。

也就是说，官网不仅包含文档，还内置了基础示例的在线演示——这正是“活样式指南”理念在站点层面的延伸。该脚本同时输出了构建环境信息（node -v、npm -v），便于排查版本问题。结合原文档与deploy.sh的set -e可以确认：任何一步失败都会中断部署，保证不会发布不完整的站点。

此外，site/CNAME 中的react-styleguidist.js.org表明站点绑定了自定义域名（配合 Netlify 等托管服务使用），而 site/Readme.md 顶部的 Netlify 状态徽章链接也印证了站点托管在 Netlify 上。

站点核心配置：docusaurus.config.js

站点行为的核心集中在 site/docusaurus.config.js，它定义了几大类配置：

• 站点元信息：title: 'React Styleguidist'、tagline: 'Isolated React component development environment with a living style guide'、url与baseUrl；
• favicon：指向img/favicon.ico（位于 site/static/img/favicon.ico）；
• 导航栏（navbar）：包含 Docs（指向docs/getting-started）、Learn、GitHub、Twitter 四个入口，其中 Docs 使用activeBasePath: 'docs'高亮当前章节；
• 页脚（footer）：按 Misc / Social / Sponsor 分组展示链接与版权信息；
• 搜索：接入 Algolia 文档搜索（indexName: 'react_styleguidist'）；
• 代码高亮：使用prism-react-renderer/themes/nightOwlLight主题（配置中以内联require方式引入）；
• 自定义样式：通过 preset 的theme.customCss引入 site/src/css/custom.css；
• remark 插件：通过docs.remarkPlugins引入 site/remark.js；
• 插件：在plugins数组中注册了 site/src/plugins/goatcounter-plugin.js。

导航侧边栏：sidebars.js

site/sidebars.js 定义了文档侧边栏的分组结构，与sync.js生成的文档 id 一一对应：

• Essentials：getting-started、documenting、components、thirdparties、webpack、cookbook；
• Advanced：configuration、cli、api、development、maintenance。

这些 id 对应的正是 docs/ 目录下的GettingStarted.md、Configuration.md、CLI.md、API.md等文档经sync.js转换后的短横线形式。

文档链接重写：remark.js

由于站点文档来自主仓库docs/，文档内互相引用的链接原本是相对路径（如GettingStarted.md）。site/remark.js 通过unist-util-visit遍历 Markdown AST 中的链接节点，将.md结尾的链接统一重写为/docs/getting-started这类 Docusaurus 路由，从而保证站内文档互链在发布后依然有效。

自定义首页与学习页

站点不止渲染文档，还提供了两个自定义 React 页面：

• site/src/pages/index.js：官网首页，使用Layout组件、自建的Row/Column/Stack等布局组件，展示三大特性（隔离开发环境、样式指南、交互式 Playground），并嵌入真实示例站点的截图作为“See it in action”栏目；
• site/src/pages/learn.js：“Learn React Styleguidist”学习资源页，聚合视频课程、工作坊、文章与演讲等外部学习资源（仅作为页面数据存在，不影响站点构建本身）。

配套的还有 site/src/components/ 下的一系列可复用组件（Box、Column、Stack、ImageLink、VisuallyHidden等），以及各自的 CSS Modules 样式，展示了在 Docusaurus 站点内组织 React 组件代码的方式。

访问统计与站点主题定制

GoatCounter 统计插件

site/src/plugins/goatcounter-plugin.js 是一个 Docusaurus 插件，通过injectHtmlTags在页面<head>注入 GoatCounter 统计脚本，并针对 SPA 场景对history.pushState做 monkey-patch：每次路由切换都会调用window.goatcounter.count()上报location.pathname + location.search。这种实现保证了纯前端路由下的页面切换也能被准确统计，而无需整页刷新。

Infima 主题变量定制

site/src/css/custom.css 通过覆盖 Infima（Docusaurus 默认 CSS 框架）的 CSS 变量来定制主题：包括品牌主色（--ifm-color-primary: #0094a9）、字体族（Open Sans）、按钮样式、代码高亮配色等，并在:root中定义了--color-base: #252525作为全局文字色。这类 CSS 变量覆盖方式比直接写死样式更利于保持组件样式的一致性。

小结：一套完整的文档站点工作流

从 site/Readme.md 的四个命令出发，结合仓库源码可以看到 React Styleguidist 官方站点是一套“源文档 + 同步脚本 + Docusaurus 2 渲染 + 静态部署”的完整流水线：

整个流程以仓库根目录的 docs/ 为文档唯一来源，配合 site/docusaurus.config.js、site/sidebars.js 与 site/remark.js 完成站点路由、导航与链接的自动化处理。对于任何想用“文档与代码同仓库”方式维护项目官网的团队，这套命令式工作流都是一个简洁、可复制、可自动化的参考范本。

• 开发工具
• 前端