新文档

经过几周的工作，我非常高兴地终于发布了Formik的新文档网站，以及它在https://formik.reactjs.ac.cn的新域名。

Formik是最早使用Facebook的Docusaurus文档框架的用户之一。它运行良好，并且由于样式选项有限，它有助于确保我们专注于内容而不是外观。

话虽如此，Docusaurus v1 确实存在一些缺点。首先，它确实是一个静态网站生成器。它输出纯 HTML。这对许多库和工具来说都很棒，但对于像 Formik 这样的 React 包来说，无法运行现代客户端 JS 变得令人沮丧。诸如页面内游乐场或可编辑代码块之类的东西是不可行的。

当需要对文档进行急需的刷新时，我评估了 Gatsby 和 Docusaurus v2，但最终**决定使用Next.js**。由于 getStaticProps、通配符路由和增量静态站点生成等新功能，Formik 文档现在拥有了坚实的基础，我们可以在此基础上进行未来的创新。

tl;dr

Formik 文档使用以下工具构建

• Next.js 9.4.x + MDX
• Notion（为你现在正在阅读的这篇博文提供支持）
• Tailwind CSS
• Algolia DocSearch v3 Alpha 用于搜索

这篇博文的其余部分将更详细地概述 Formik 的文档堆栈、其背后的部分基本原理以及一些你可能会觉得有趣的小细节。

Next.js 9.4

我选择 Next.js 而不是 Gatsby 和 Docusaurus v2 等替代方案，原因有很多。做出这个决定的最大因素是我相信**文档是产品的一部分**。由于我即将推出的 SaaS 仪表板和营销网站已经使用 Next.js，因此保持在 Next.js 宇宙中意味着所有代码库都将以相同的方式工作，即使是开源的。这减少了认知开销，并简化了跨应用程序工作和共享组件的操作。

为什么不选择 Gatsby？

Gatsby 是一个基于 React 的静态网站生成器，拥有丰富的插件和主题生态系统。其核心价值主张是基于GraphQL 的单个数据图。在文档网站方面，Gatsby 主题（插件、布局和组件的组合，子主题可以继承这些主题）非常有用。鉴于我们正在进行的开源项目数量不断增加我们正在进行的，这一点非常有吸引力。但是，我相当确信 GraphQL 对于文档和大多数静态文档驱动网站来说仍然是过度杀鸡用牛。是的，我完全意识到你从技术上讲并不需要在 Gatsby 中使用 GraphQL，但它绝对是其理想路径。

为什么不选择 Docusaurus v2？

截至撰写本文时，Docusaurus v2.0 仍处于 alpha 阶段。新版本通过允许客户端 React、插件甚至自定义主题修复了 v1.0 的许多问题。

对我来说，Docusaurus 2 最大的问题是/是其基本主题。

对于许多项目来说，Facebook 用于文档的新静态 CSS 框架称为Infima（Docusaurus 使用该框架，并且由同一个团队共同开发）是可以的。但是，它的一些方面确实让我感到困扰。

移动导航感觉很笨拙

我始终难以在手机上浏览每个 Docusaurus v2 网站。我发现浮动子导航与 Docusaurus v1 的子导航栏相比，不直观。这是一个比较视频。v1 在左侧，v2 在右侧。

Infima CSS 不易于主题化

虽然 Infima CSS 是一个完整的 CSS 框架，但它的主题化选项有些有限。使新的 Formik 文档在视觉上与我们的企业 SaaS 应用程序的设计系统保持一致似乎也很有挑战性，因为我们需要大幅弯曲/扩展 Infima CSS。

缺乏社区主题

Docusaurus 在 v2 中的另一个重大改进是自定义主题和一流的主题组件覆盖（也称为“Swizzling”）。如果你以前从未听说过它，组件 Swizzling 的工作原理类似于 Wordpress 的主题和插件模板层次结构，但适用于 React 组件。当你运行 docusaurus swizzle <theme name> [component name] 时，Docusaurus 会将该组件从指定的主题复制出 node_modules 并复制到 src/theme/[component name] 中的本地文件。然后，你可以对该文件进行任何更改，Docusaurus 在构建你的站点时将使用“Swizzled”版本而不是基本版本。

Swizzling 的最大缺点与永远困扰 Wordpress 子主题的缺点相同——它可能使升级变得**更加复杂**(尤其是在基本主题中添加新功能时)。这个问题实际上非常突出，以至于 Docusaurus 文档目前**警告不要**使用 Swizzling，直到 v2 进入 Beta 阶段

在达到 Beta 阶段之前，我们希望阻止组件的 Swizzling。组件 API 变化很快，并且可能在达到 Beta 阶段之前继续变化。如果可能，请坚持使用默认外观，以避免将来遇到一些潜在问题。

此时，我花了一些时间评估为 Formik 编写我们自己的自定义 Docusaurus v2 主题需要做哪些工作，但最终决定放弃，因为上面提到了警告。我的理由是，如果我要钻研这个兔子洞，我最好完全控制 Next.js 的整个 markdown 处理管道——而这正是我所做的……

MDX 最佳选择

只要付出一点努力，Next.js 就可以成为出色的文档工具——MDX 是其中的秘诀。但是，要使其功能与 Docusaurus 达到同等水平，需要付出相当大的努力，并且不适合胆小者。话虽如此，我对新文档的工作方式、对其进行贡献的便捷性和网站的外观感到非常满意。

值得指出的是，Formik 的新文档处理 MDX 的方式与大多数 Next.js 网站可能略有不同。我没有使用官方的 @next/mdx 插件，而是厚颜无耻地从 Expo.io 文档中窃取了 Brent Vatne 的自定义 webpack 加载器，该加载器会自动提取前置内容并在每个 .mdx 文件中注入包装器 Layout 组件导出。

1 const fm = require('gray-matter');
2 
3 // Makes mdx in next.js much better by injecting necessary exports so that
4 // the docs are still readable on github
5 // (Shamelessly stolen from Expo.io docs)
6 // @see https://github.com/expo/expo/blob/master/docs/common/md-loader.js
7 module.exports = async function (src) {
8   const callback = this.async();
9   const { content, data } = fm(src);
10   const layout = data.layout || 'Docs';
11   const code =
12     `import { Layout${layout} } from 'components/Layout${layout}';
13 export const meta = ${JSON.stringify(data)};
14 export default ({ children, ...props }) => (
15   <Layout${layout} meta={meta} {...props}>{children}</Layout${layout}>
16 );
17 ` + content;
18 
19   return callback(null, code);
20 };

默认情况下，此加载器将 LayoutDocs.tsx 布局组件注入为包装器，但可以在我们需要时添加其他布局。可以通过 layout 前置内容键在每个页面上指定它们。

使用静态站点生成的 Notion 支持的博客

此博客你正在阅读的实际上是由Notion 和 Next.js 的静态站点生成功能提供支持，而不是使用传统的 CMS 或 MDX。我们将帖子保存在 Notion API 中的表格中，其中包含相关元数据，然后将 Notion 未公开的 API 映射到./src/pages/blog/[...slug].tsx 中的自定义 React 组件。结果令人惊叹，并且提供了极佳的写作体验。有关此设置的更详细示例，以及你可以立即部署的示例，请访问此处：https://notion-blog.now.sh/

Tailwind

多年来我一直是原子 CSS 的粉丝。Tailwind 是所有原子 CSS 框架中最新且可能是最棒的框架。它灵活、直观、外观精美，并且在性能方面无可匹敌（因为它只是 CSS！）。由于 Tailwind 1.4.x，我们还可以使用其新的 purge 功能来清除所有多余的类。

Algolia DocSearch v3 Alpha

在处理文档时，我偶然发现了 docsearch.js 的新版本，它甚至比我想象的还要好。它有一个很酷的全能栏，甚至可以跟踪最近的搜索和收藏。

总的来说，我对新的文档网站非常满意。有一段时间，我再次对编写文档感到兴奋。仍然缺少一些功能，但我对最终用户体验和此堆栈提供的开发者体验非常满意。Next.js 为我们在文档网站中构建更多类似应用程序的功能奠定了坚实的基础。其中第一个将是一个全新的交互式教程，以及一个新的可搜索示例和样板目录。与往常一样，如果你有兴趣提供帮助或深入了解，新文档的完整源代码可在 GitHub 上获得。

因此，请四处浏览，但要温柔。如果你发现任何错误，提交问题。有了这个新的 Notion 支持的博客，我将更频繁地发布内容，因此请输入你的电子邮件并点击页脚中的订阅按钮，加入 Formik 邮件列表。

-J

2021年9月更新

自从撰写这篇文章以来，Notion 现在拥有了一个公共 API。但是，我们最终还是切换到 MDX 来编写博客内容。

我们在 Notion 中遇到的问题是，外部贡献者在未经批准的情况下进行的 PR 会导致文档构建失败。这是因为使用 Notion 作为 CMS 需要一个秘密的 API 令牌，Vercel 正确地不允许外部开发者访问该令牌，以进行 PR 部署。这并不是特定于 Notion 的问题，而是对于任何用于在开源项目上为博客提供支持的无头 CMS 来说都是一样的。这使得在 GitHub 上浏览 Formik 的问题变得困难，因为每个 PR 都会在开箱即用时失败。此外，对于新贡献者来说，看到一个红色的 X 并不是一个很好的体验，即使他们没有做错任何事情。

此时，我们可以将博客移到它自己的仓库或站点，但我们认为放弃 Notion 并使用传统的 MDX 并将所有内容保留在代码库中更容易。

除了 Notion 的公共 API 之外，Docusaurus v2 还更新并改进了其移动导航。值得一试，还可以尝试另一个名为Nextra的项目，它类似于 Docusaurus，但由 Next.js 提供支持。如果我今天要重写 Formik 文档，我可能会 fork nextra-theme-docs。