文档示例使用 TypeScript 替换 JavaScript

[cpylua]

背景

目前文档是使用 markdown-doc-loader 和 react-markdown-doc-loader 生成的，这两个 loader 目前来说可以满足项目需求，但也有点年久失修。最大的问题是文档中示例代码使用 JavaScript 编写，不支持 TypeScript。Zent 组件库已经全面 TypeScript 化，示例代码不可能一直使用 JavaScript，因此需要文档生成工具支持 TypeScript。

整体设计

最重要的变化是将现有的示例代码文件从 .md 文件替换成 .tsx 文件，从而让 TypeScript 编译器能够识别。

组件目录结构：

- button
   - index.ts
   - Button.tsx
   - README_zh-CN.md
   - README_en-US.md
   - demos
     - 01-basic.tsx
     - 02-loading.tsx

类型检查依赖 TypeScript 编译器的原生支持，所以 demos 下的代码就是普通的 TypeScript 代码，但是必须按照我们的规范编写。在编译阶段，将 .md 文件转换成 TypeScript 代码，同时将 demos 下的示例插入到输出文件中。

这里有几个关键点：

• .md 文件编译后输出为 TypeScript 代码，之前是 JavaScript 代码
• demos 下的代码通过 export 和 import 机制插入到 .md 文件的输出中，而不是将代码直接注入进去，避免作用域冲突问题
• 中英文文档中运行的示例代码是同一份，不做编译时的特化处理，所以国际化的处理需要在运行时做。这么做的好处是示例代码不用在编译过程中衍生出很多中间文件，导致项目目录内容很混乱，难以管理。
• 中英文文档中的示例对应的代码展示部分，需要在编译期做特化处理，也就是说在中文文档中示例代码应该是国际化之后仅包含中文的样子。

技术方案设计

示例代码规范

interface TestLocale {
  title: string;
  name: string;
  count: string;
  complex: [string, string];
}

// 必须导出同名常量
export const translations: Record<string, TestLocale> = {
  "zh-CN": {
    title: "基础",
    name: "张三",
    count: "12",
    complex: ["100", "200"],
  },
  "en-US": {
    title: "Basics",
    name: "John Doe",
    count: "43",
    complex: ["1", "2"],
  },
};

interface DemoProps {
  // 编译时根据当前的 locale 动态注入
  i18n: TestLocale;
}

// 必须导出同名组件
export function Demo(props: DemoProps) {
  const { i18n } = props;
  return (
    <div>
      <span>{i18n.complex[0]}</span>
      <span>{i18n.name}</span>
      <span>{i18n.count}</span>
    </div>
  );
}

在 .md 文件的编译阶段会插入一段动态获取 i18n 值的代码，示例代码还是同一份。

// README_zh-CN.md 的编译结果
import { translations as translations01, Demo as Demo01 } from './demo';

// 渲染示例组件处
<Demo01 i18n={translations01['zh-CN']} />

在 .md 文件编译阶段还需要对代码做一次国际化处理，以确保展示给用户的示例代码中不存在这些国际化逻辑。

// README_zh-CN.md 的编译结果的示例中展示给用户看的代码

function Demo() {
  return (
    <div>
      <span>100</span>
      <span>张三</span>
      <span>12</span>
    </div>
  )
}

实现

和现有方案类似，依然通过 webpack 的 loader 来实现，但是会合并 markdown-doc-loader 和 react-markdown-doc-loader 为一个 loader。

• unified 处理 .md 文件
• 示例样式通过 webpack 的机制去处理，不再放在 .md 文件中
• 代码高亮使用 Prism.js，highlight.js 不支持 jsx 高亮。高亮换到运行时做，编译时不做高亮，因为 Prism.js 官方不支持 Node.js 运行环境