illegalCreed

中文

English

中文

English

Appearance

参考 ​

基于 react-styleguidist.js.org 官方文档编写，对照当前稳定版 13.1.4

速查 ​

  • 配置入口：styleguide.config.js（CommonJS 导出对象）
  • 核心字段：components / sections / webpackConfig / theme / styles / styleguideComponents / require / pagePerSection / exampleMode / usageMode / propsParser / compilerConfig
  • 代码块语义：```jsx/js/javascript = 交互式可编辑；其他 = 仅高亮；无标签 = 交互式（向后兼容）
  • 代码块修饰符：padded / noeditor / static / {"props":{...}}
  • Props 表原理：react-docgen 静态分析 propTypes + JSDoc + defaultProps
  • JSDoc 标签：@ignore / @public / @component / @visibleName / @example
  • Wrapper 注入：styleguideComponents.Wrapper 包裹所有示例注入 Provider
  • 双重导出：基础组件 named export（文档）+ 增强组件 default export（渲染）
  • vs Storybook：Markdown 驱动风格指南 vs CSF 驱动开发工作台
  • 当前稳定版：13.1.4（MIT，作者 Artem Sapegin / sapegin）
  • CRA 零配置 glob：src/components/**/*.{js,jsx,ts,tsx}，自动忽略 __tests__ / .test. / .spec.
  • CLI 命令：npx styleguidist server（开发，默认 6060 端口）/ npx styleguidist build（静态站）

配置项清单 ​

路径与组件发现 ​

字段类型默认作用
componentsstring / string[]src/components/**/*.{js,jsx,ts,tsx}组件扫描 glob
sectionsarray-嵌套分组（替代 components）
ignorestring[]-排除组件的 glob
skipComponentsWithoutExampleboolfalse跳过无示例文件的组件（建议 true）
getExampleFilenamefunction查找同目录 Readme.md自定义示例文件查找规则
getComponentPathLinefunction默认文件路径自定义组件路径行显示
exampleModestringcollapse示例代码初始状态：collapse / hide / expand
usageModestringcollapseProps 表初始状态：collapse / hide / expand
pagePerSectionboolfalse每个 section 独立页面（大型库建议 true）
defaultExamplebool / stringfalse无 Readme 时自动生成最小示例

构建与打包 ​

字段类型作用
webpackConfigobject / function自定义 webpack 配置（一旦设置禁用 CRA 自动加载）
dangerouslyUpdateWebpackConfigfunction无限制改 webpack（可能破坏 Styleguidist）
compilerConfigobjectBublé 浏览器端转译配置
propsParserfunction替换默认 react-docgen（如换 react-docgen-typescript）
requirestring[]全局注入的模块（polyfill / CSS / context helper）
mountPointIdstringrsg-root
styleguideDirstringstyleguide
templateobject / function默认 HTML 模板
assetsDirstring-

渲染与主题 ​

字段类型作用
styleguideComponentsobject替换内部组件（Wrapper / Playground / ReactComponent / TableOfContents / Editor 等）
themeobject主题（color / fontFamily / fontSize / spaceFactor / borderRadius / maxWidth）
stylesobject / function细粒度样式覆盖（按组件 key 返回 style 对象）
titlestringStyle Guide
showCodeboolfalse
showUsageboolfalse
showSidebarbooltrue
previewTemplatefunction-
ribbonobject-

服务与部署 ​

字段类型默认作用
serverHoststring0.0.0.0开发服务器 host
serverPortnumber6060开发服务器端口
openBrowserbooltrue启动时自动开浏览器
verboseboolfalse详细日志
loggerobjectconsole自定义日志器

CLI 命令清单 ​

bash
# 开发服务器（默认 http://localhost:6060）
npx styleguidist server

# 构建静态站（输出到 styleguide 目录）
npx styleguidist build

# 指定配置文件
npx styleguidist server --config ./path/to/styleguide.config.js

package.json 脚本示例：

json
{
  "scripts": {
    "styleguide": "styleguidist server",
    "styleguide:build": "styleguidist build"
  }
}

代码块语义表 ​

写法行为
```jsx / ```js / ```javascript交互式可编辑示例（渲染真实组件 + 显示编辑器）
```bash / ```json / ```css 等其他仅高亮源码
``` 无语言标签交互式（向后兼容）
```jsx padded交互式 + 示例之间增加内边距
```jsx noeditor仅渲染示例，不显示编辑器
```jsx static仅高亮源码
```jsx {"props":{"title":"提示"}}交互式 + 给 wrapper 注入 props

JSDoc 标签清单 ​

标签作用
@ignore在 Props 表中隐藏该 prop
@public把类组件的实例方法公开到文档
@componentstyled-components 标记（必加才能被 docgen 识别）
@visibleName自定义在文档中的显示名
@example ./path.md关联外部示例文件

双重导出模式速查 ​

jsx
// 命名导出：基础组件（react-docgen 识别，生成 Props 表）
export function Component(props) { /* ... */ }
Component.propTypes = { /* ... */ };

// 默认导出：增强组件（HOC 包裹，供示例渲染）
export default withRouter(Component);

约定：

  • 单文件仅 1 个 default 或 1 个 named export（多 named 官方警告不可靠）
  • 命名导出供文档生成（含 propTypes）
  • 默认导出供示例渲染（拿到 HOC 注入的 router / theme / store）

与 Storybook 对比表 ​

维度StyleguidistStorybook
驱动方式MarkdownCSF（Component Story Format）
类比商店橱窗（storefront）工作台（workshop）
示例展示所有组件及其变体同页陈列一次一个变体
受众开发 + 设计 + 产品主要面向开发者
核心强项文档可读性、Markdown 易写addon 生态、交互测试、视觉回归
addon 生态无数百个
视觉回归无内置（chromatic / percy addon）
组件测试无stories + play function
框架支持React 专用React / Vue / Angular / Svelte / Web Components
零配置启动CRA 项目开箱即用需 init 配置
社区趋势趋于稳定（部分团队迁出）主流（生态持续增长）
维护状态13.1.4（活跃），102 open issues / 144 PR持续高速迭代
作者Artem Sapegin（sapegin）Storybook 团队（Norbert de Langen 等）

二者并非二选一——一些团队同时用：Storybook 做开发期测试、Styleguidist 做对外风格指南。

与相邻章边界 ​

  • vs Storybook：Styleguidist = Markdown 驱动的「风格指南 / 文档展示」（storefront），所有组件及其变体同页陈列；Storybook = CSF 驱动的「组件开发工作台」（workshop），一次一个变体，重交互测试、addon 生态、视觉回归。Styleguidist 不做 addon 体系、视觉回归、组件交互测试自动化（那属 Storybook / 前端测试工具边界）。
  • vs react-docgen：react-docgen 是 Styleguidist 内部依赖的 PropTypes 静态分析器，本章不深入 docgen API 本身（属 AST / 静态分析章）。
  • vs MDX / Docz / Catalog：同属「组件文档生成工具」赛道，但 Styleguidist 是纯 Markdown（非 MDX 混 JSX），面向 React 生态、CRA 零配置。
  • 本章覆盖范围：仅 Styleguidist 的安装配置、Markdown 写法、Props 表生成、隔离渲染、与 Storybook 定位对比；不覆盖通用 Markdown 语法、webpack 通用配置、React 组件设计本身。

版本与运行环境 ​

项取值
当前稳定版13.1.4（npm dist-tags.latest）
许可MIT
作者Artem Sapegin（sapegin，v0.0.1 起唯一长期维护者）
beta tag12.0.0-alpha9.9（早期 v12 尝试，主线已跳到 13.x）
GitHub 状态102 open issues / 144 PR（积压但未停更）
Node 要求建议 LTS（Node 18+）
React 支持16.8+（支持 Hooks）
默认端口6060
默认输出目录styleguide/

官方资源 ​