Storybook + Netlify CMS
将您的内容带到 Storybook
使用 Storybook 构建组件时，您可以免费获得文档。文档插件 会分析 Story，生成包含代码示例、属性表和使用指南的文档页面。Audi、Codecademy、Talend 和 Wix 的团队使用 Storybook 构建他们的设计系统网站。
如果您是开发者，将 Story 和文档散文放在 MDX 文件中会很方便。这样，您就可以使用 React 组件美化网站主题，在 Markdown 中撰写内容，并使用 Git 进行版本控制。
但是非技术同事可能不使用 Git 或 pull requests。设计系统文档涉及设计师、产品经理、测试人员以及无数其他利益相关者。本文将展示如何将 Storybook 与无头 CMS 连接起来，以便您的整个团队都能为文档做贡献。
为什么使用 Storybook 来编写文档？
团队使用 Storybook 来编写文档，因为它会分析组件的属性，生成丰富的文档。这使您可以专注于编写使用指南，而不是手动更新 API 文档。
文档功能由 MDX 提供支持，MDX 结合了 Markdown 的创作能力和 JSX 的交互性。对于开发者来说，在代码编辑器中打开 *.stories.mdx 文件、添加 commit 并打开 pull request 非常简单。
但是设计系统的维护者通常会有各种非技术利益相关者。对开发者来说简单的 Git 工作流可能会无意中限制谁可以为文档做贡献。幸运的是，将无头 CMS 集成到 Storybook 中非常简单。
从无头 CMS 中获取内容
通过将 Storybook 与无头 CMS 连接起来，可以使每个人更容易进行编辑。CMS 为您提供了一个 GUI 编辑器来编辑文本内容，而 Storybook 则作为前端。有大量很棒的无头 CMS 选项。选择最适合您需求的那个。然后在构建时，Storybook 将查询这些内容并将其呈现在各种文档页面上。
Netlify CMS 示例
我们将使用 Netlify CMS 为 Storybook 使用的 MDX 文件提供 GUI 编辑器。它将您的 Git 仓库视为唯一事实来源。首先，您需要将 Storybook 发布到 Netlify。然后要设置 Netlify CMS，请在您的静态目录中创建一个 admin 文件夹并添加一个 config.yml 文件。这会配置 Netlify CMS 来获取您的 MDX 文件，并通过 CMS 界面提供编辑。
# config.yml
backend:
name: git-gateway
branch: main
local_backend: true
publish_mode: editorial_workflow
media_folder: 'public' # Media files will be stored in the repo under public/
public_folder: '/' # The src attribute for uploaded media will begin with /
collections:
- name: 'docs' # Used in routes, e.g., /admin/collections/docs
label: 'Docs' # Used in the UI
folder: 'src' # The path to the folder where the mdx documents are stored
create: true # Allow users to create new documents in this collection
extension: mdx
slug: '{{title}}.stories' # Filename template, e.g., title.stories.mdx
format: yaml-frontmatter
frontmatter_delimiter: ['<!--', '-->']
fields: # The fields for each document, usually in front matter
- { label: 'Title', name: 'title', widget: 'hidden' }
- { label: 'Body', name: 'body', widget: 'markdown', modes: ['raw'] }CMS 需要通过 frontmatter 为每个 MDX 文件提供一个唯一的标识符——在我们的例子中，这是一个标题。然而，MDX 默认不支持 frontmatter。这就是为什么我们配置了 frontmatter_delimiter，以便将 frontmatter 作为 HTML 注释提供。现在您可以在 MDX 文件顶部指定一个标题。例如：
<!--
title: introduction
-->
import { Meta } from '@storybook/addon-docs';
<Meta title="Introduction" />
# Introduction to the Storybook design system tutorial
The Storybook design system tutorial is a subset of the full [Storybook design system](https://github.com/storybookjs/design-system/), created as a learning resource for those interested in learning how to write and publish a design system using best practice techniques.
Learn more in the [Storybook tutorials](https://storybook.org.cn/tutorials/).接下来，在 admin 文件夹中添加一个 index.html 文件。这将设置 CMS 的编辑界面。
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Design system docs CMS</title>
</head>
<body>
<!-- Include the script that builds the page and powers Netlify CMS -->
<script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
<script>
CMS.registerPreviewStyle('preview.css');
</script>
</body>
</html>然后将此更新部署到您的 Storybook，启用 Identity & Git Gateway（用于身份验证），并且您的 CMS 应该可以通过以下地址访问：url_for_your_storybook/admin/index.html。登录后，您就可以编辑您的文档了。
请注意，您正在编辑包含 React 组件的 MDX 文件。Netlify CMS 将无法可视化这些组件。话虽如此，在上面的 HTML 文件中，我包含了一些预览样式，可以显示 Story 的占位符。您可以从示例仓库中获取该 CSS 文件。
编辑完成后，点击发布，Netlify CMS 将会针对您的所有更改开启一个 PR。查看部署预览，如果一切正常，点击合并。
结论
设计系统维护的秘诀是自动生成大部分内容，并请队友协助完成其余部分。
Storybook 文档开箱即用地提供了设计系统基础设施。它提取您的 Story 并生成文档、属性表和示例。然后您可以通过添加 Markdown 进行进一步定制。
将 Storybook 与无头 CMS 结合使用，可以将编辑范围从开发者扩展到团队的其他成员。设计师、产品经理和作者将获得一个 GUI 编辑器，用于修改 Storybook 在构建时获取的文档散文。
团队采用 Storybook 的主要原因之一是其灵活性。请记住，Netlify CMS 只是一个选项。您可以将 Storybook 连接到任何您想要的无头 CMS。希望这篇快速教程能成为您设计系统文档的起点。
设计系统文档需要开发者、设计师、产品经理等跨领域协作。
— Storybook (@storybookjs) 2021年11月24日
但是基于 Git 的工作流限制了贡献者 🙅🏽
将 Storybook 与无头 CMS 结合使用，为您的团队提供易于使用的 GUI 编辑器和自动生成的文档。https://#/xS23FKCO3X pic.twitter.com/cbMJMVfWA5