企业官网建设流程全解析

• 文档
• 静态站点
• 开发工具

Docz 本身基于 Gatsby 构建，因此它的主题系统直接复用了 Gatsby 的 Theme Shadowing（主题遮蔽）机制：你不需要 fork 整个主题，只需要在项目里放置同名目录与同名文件，就能覆盖 Docz 默认主题中的任意组件。本文以仓库中的examples/with-custom-docz-theme示例为骨架，完整演示如何从零创建一个名为gatsby-theme-docz-pink的自定义主题（为每个页面外层包裹带粉色背景与内边距的容器），再在另一个 Docz 项目中安装并消费它；同时结合源码说明 shadowing 的底层原理，并给出覆盖 Header、Sidebar、Logo、Playground 等更多组件的扩展思路。读完本文，你将能够独立打造一套属于自己的 Docz 文档站主题。

先理解 Docz 主题的底层机制

Docz 的运行时主题位于core/gatsby-theme-docz，它在gatsby-config.js中通过gatsby-plugin-compile-es6-packages把自己以及docz、docz-core声明为需要被 webpack 编译的 ES6 包（见 gatsby-config.js）：

{ resolve: 'gatsby-plugin-compile-es6-packages', options: { modules: ['docz', 'docz-core', 'gatsby-theme-docz'], }, }

Docz 主题系统依托的 Shadowing 规则非常简单：Gatsby 会优先加载项目里路径为src/gatsby-theme-docz/<组件名>的文件，用它“遮蔽”主题包内同名的默认组件。你可以遮蔽两大类东西：

• 单个组件文件，例如wrapper.js、Sidebar/index.js、Header/index.js、Logo/index.js、Playground/index.js；
• 组件批量入口components/index.js，一次性替换 MDX 渲染时用到的全套内置组件。

以本示例遮蔽的wrapper.js为例，Docz 主题包的原始实现只是一个透传容器（见 core/gatsby-theme-docz/src/wrapper.js）：

import React from 'react' const Wrapper = ({ children }) => <>{children}</> export default Wrapper

也就是说，默认情况下每个页面外层没有任何包裹容器。自定义主题要做的，就是用自己版本的wrapper.js把这个透传层替换成带样式的容器。

创建一个自定义主题：gatsby-theme-docz-pink

示例的目标是：写一个主题，让每个页面都被一个带内边距和粉色背景的div包裹。你完全可以按需让主题做得更多或更少——它只是一个普通的 Gatsby 主题包。

第 1 步：建立主题包目录

在项目中创建目录gatsby-theme-docz-pink，其最终结构如下（见 examples/with-custom-docz-theme/gatsby-theme-docz-pink）：

gatsby-theme-docz-pink/ ├── index.js # 空文件（noop），标记包入口 ├── package.json └── src/ └── gatsby-theme-docz/ # 关键目录：声明要遮蔽 gatsby-theme-docz └── wrapper.js # 被遮蔽的目标组件

其中src/gatsby-theme-docz这一层目录名是固定约定：它告诉 Gatsby，本包要遮蔽gatsby-theme-docz主题。其下再按“主题包内的相对路径”放置要覆盖的组件文件。

第 2 步：书写被遮蔽的 wrapper 组件

在src/gatsby-theme-docz/wrapper.js中编写新组件。它引入了原始 Wrapper，再把原始 Wrapper 包进一个带样式的div中（见 wrapper.js）：

import React from 'react' import OriginalWrapper from 'gatsby-theme-docz/src/wrapper' const Wrapper = ({ children, doc }) => { return ( <div style={{ background: 'pink', padding: 30 }}> <OriginalWrapper>{children}</OriginalWrapper> </div> ) } export default Wrapper

这段代码有两个要点：

• 从gatsby-theme-docz/src/wrapper导入原始组件：这是组合（而非替换）的惯用写法。先引入原组件，再叠加自己的样式或逻辑，可以保证不丢失默认行为。children是页面内容，doc是当前文档的元数据（route、name、menu 等，由 Docz 的sourceNodes注入，参见 core/gatsby-theme-docz/gatsby-node.js）；
• 内联样式即可生效：本示例使用style内联样式演示，你完全可以用 emotion/theme-ui 或任何你熟悉的样式方案，因为 shadow 组件本身就是一个普通 React 组件。

第 3 步：添加 package.json

在gatsby-theme-docz-pink根目录添加package.json：

{ "name": "gatsby-theme-docz-pink", "version": "1.0.0", "main": "index.js", "license": "MIT" }

main指向index.js，因此还需要在包根目录创建一个空文件index.js，让打包器（bundler）能识别这个包是存在的（见 index.js）：

// noop

到这里，这个主题就已经制作完成，可以分发和消费了——你可以把它发布到 npm，也可以托管在 git 仓库里用任意包管理器安装。

消费一个自定义主题

第 1 步：把主题安装为项目依赖

如果主题已发布到 npm，直接添加依赖即可：

yarn add gatsby-theme-docz-pink

本示例为了演示没有走 npm 发布流程，而是把gatsby-theme-docz-pink目录直接复制到node_modules中：cp -r gatsby-theme-docz-pink/ node_modules/gatsby-theme-docz-pink。示例项目的package.json里也内置了install:theme脚本（见 package.json）："install:theme": "cp -r gatsby-theme-docz-pink/ node_modules/gatsby-theme-docz-pink"。

第 2 步：在 gatsby-config.js 中声明插件

在项目根目录创建gatsby-config.js，声明使用gatsby-theme-docz-pink，同时让 webpack 编译这个包——因为包内是 JSX 语法，并非合法的普通 JS（见 gatsby-config.js）：

// gatsby-config.js module.exports = { plugins: [ 'gatsby-theme-docz-pink', { resolve: 'gatsby-plugin-compile-es6-packages', options: { modules: ['gatsby-theme-docz-pink'], }, }, ], }

gatsby-plugin-compile-es6-packages的modules数组用于声明哪些包需要被 webpack 编译——Docz 自己的gatsby-config.js也是用同样的方式编译docz、docz-core与gatsby-theme-docz的。凡是包含 JSX 或未编译 ES 语法的自定义主题，都必须在这里登记。

第 3 步：运行并观察效果

安装好依赖后执行：

yarn docz dev

此时打开开发服务器，就能看到每个页面外层都被粉色背景 + 30px 内边距的容器包裹，即自定义主题已经生效。

从 wrapper 扩展到更多组件

Shadowing 并不局限于wrapper.js。Docz 主题包默认暴露了这些可遮蔽组件（见 core/gatsby-theme-docz/src/components 目录结构）：

仓库中的其他示例给出了多种遮蔽套路：

• 遮蔽Sidebar：examples/logo-in-sidebar通过 Sidebar/index.js 在侧边栏顶部插入一张图片，同时复用gatsby-theme-docz/src/components/NavSearch、NavLink、NavGroup以及样式模块gatsby-theme-docz/src/components/Sidebar/styles，保持默认行为不变；
• 遮蔽components/index.js：examples/with-custom-links通过 components/index.js 一次性导出全部内置组件（headings、Code、Playground、Pre、Layout、Props），并自定义a链接组件——外部链接自动target="_blank"加rel="noreferrer nofollow"，站内链接保持默认行为；
• 遮蔽Playground：examples/shadowed-playground、examples/wrapped-playground、examples/with-styled-components-and-scoping均演示了如何定制<Playground>的渲染外壳（对应Playground/Wrapper.js）。

遮蔽任意组件时都可以沿用本示例的“先导入原始组件、再包裹增强”的模式：

import React from 'react' import OriginalHeader from 'gatsby-theme-docz/src/components/Header' const Header = props => { return ( <header style={{ borderBottom: '2px solid pink' }}> <OriginalHeader {...props} /> </header> ) } export default Header

快速起步：create-docz-app 与手动下载

使用 create-docz-app

如果你的项目还没有初始化，可以用官方脚手架直接创建一个 Docz 应用：

npx create-docz-app docz-app-with-custom-docz-theme # 或 yarn create docz-app docz-app-with-custom-docz-theme

手动下载示例

也可以直接获取本仓库中的with-custom-docz-theme示例目录，随后进入目录即可：

# 从仓库的 examples 目录中取出 with-custom-docz-theme 示例（等价于 curl 下载并解压该目录） mv with-custom-docz-theme docz-with-custom-docz-theme-example cd docz-with-custom-docz-theme-example

你也可以直接git clone本仓库后，查看并运行其中的 examples/with-custom-docz-theme 目录。

安装、运行、构建与部署

进入示例项目后按需执行：

yarn # 或 npm i

安装完成后即可启动开发服务器：

yarn dev # 或 npm run dev

生产构建：

yarn build # 或 npm run build

本地预览构建产物：

yarn serve # 或 npm run serve

对应的脚本定义在 package.json 中：dev对应docz dev，build对应docz build，serve对应docz serve。示例项目的文档内容位于 src/index.mdx 与 src/components/Alert.mdx（后者使用了docz提供的<Playground>、<Props>组件），侧边栏菜单由 doczrc.js 中的menu: ['Getting Started', 'Components']控制。

小结

Docz 的自定义主题能力，本质上是把 Gatsby Theme Shadowing 暴露给文档站开发者：

1. 创建主题包：建立gatsby-theme-docz-pink目录，在其中放置src/gatsby-theme-docz/<组件路径>覆盖目标组件，补上package.json与空的index.js即可发布；
2. 组合优先：在 shadow 组件中先import原始组件，再用样式与逻辑包裹增强，避免丢失默认行为；
3. 消费主题：yarn add安装后，在gatsby-config.js中声明插件，并用gatsby-plugin-compile-es6-packages让 webpack 编译含 JSX 的主题包；
4. 按需扩展：wrapper.js之外，Header、Sidebar、Logo、Playground、Props等组件以及批量入口components/index.js都可以用同一套机制遮蔽定制。

掌握了这套机制，你就能为团队构建带有专属品牌样式、定制导航与交互组件的文档站主题，并像普通 npm 包一样分发和复用。

• 文档
• 静态站点
• 开发工具