企业官网建设流程全解析

• CLI
• 开发工具

ts-node 的README.md并不是手工维护的，而是由website/readme-sources/prefix.md作为头部片段、website/docs下的各篇文档作为正文，通过build-readme.mjs脚本自动合并生成的。本文以 prefix.md 为切入点，拆解 ts-node 的文档工程架构：frontmatter 如何控制合并行为、侧边栏如何决定 README 章节顺序、Markdown 转换管道做了哪些重写，以及贡献者应当如何正确修改文档而不被构建校验拦截。

读完本文，你将掌握 ts-node 文档体系的完整工作流——从编辑源文件、运行yarn build-readme到生成带锚点目录、校验通过的README.md，并理解这一机制背后的“单一事实来源”（single source of truth）设计思路。

prefix.md：README 的“头部源文件”扮演什么角色

打开 prefix.md 可以看到，它本身不是一篇完整文档，而是 README 生成流水线的头部组件，由四个部分构成：

1. YAML frontmatter：omitHeaderOnMerge: true，告知合并脚本在把本文件拼入 README 时不要输出标题头（README 的 H1 就是仓库 Logo 与标题本身，无需重复生成）。
2. 编辑约定注释：声明README.md由website/docs与website/readme-sources中的页面自动合并生成；提交文档改进时应在源 markdown 中修改，并用cd website && yarn build-readme重新生成。
3. 徽章区与项目定位：NPM 版本、下载量、CI 状态、测试覆盖率徽章，以及项目的核心 tagline——TypeScript execution and REPL for node.js, with source map and native ESM support.（TypeScript 执行引擎与 Node.js REPL，支持 source map 与原生 ESM）。
4. Table of Contents 锚点区：由remark-toc在构建阶段根据最终合并结果自动生成，因此源文件里只需保留一个空目录起点。

从仓库结构看，website/readme-sources/目录下仅有两个源文件：prefix.md 与 license.md，分别对应 README 的头部与尾部，中间的全部正文都来自website/docs/——这正是“README 不手写、由文档站点内容派生”的架构设计。

单一事实来源：为什么 README 不能直接编辑

prefix.md 注释中强调的“BEFORE EDITING THIS README”并非随意提示，而是 ts-node 文档治理的核心约定：

• 所有文档正文统一维护在website/docs/（对应站点docs路由）与website/readme-sources/（头部、尾部片段），README.md只是这些内容的渲染产物；
• 直接修改README.md的改动会在下次yarn build-readme时被整体覆盖，因此贡献者必须修改源文件；
• 这一约定同样记录在 CONTRIBUTING.md 中：修改./website/docs下的 markdown 与./website/sidebars.js的侧边栏声明，再运行yarn build-readme重建 README；
• 文档站点由 Docusaurus 渲染（website/docusaurus.config.js），website/package.json中注册了build-readme脚本：./scripts/build-readme.mjs（见 website/package.json）。

也就是说，README 与文档网站共享同一批源文件：改一处源 markdown，yarn start本地预览站点、CI 构建网站、以及 npm 仓库页面上渲染的 README 三处同步更新，避免了手写 README 常见的“文档与站点内容漂移”问题。

合并流水线：build-readme.mjs 的执行顺序与层级控制

README 的生成完全由 website/scripts/build-readme.mjs 驱动，核心流程分四步。

第一步：先拼入头部片段

脚本入口main()首先调用appendMarkdownFileToReadmeAst({ path: 'readme-sources/prefix.md', headerLevel: 1 })（见 build-readme.mjs），把 prefix.md 作为 README 的最顶部内容写入 AST。

第二步：按侧边栏顺序拼入全部文档

随后脚本读取 website/sidebars.js 中的primarySidebar，按General → Advanced → Recipes三个分类、以及分类内各页面的声明顺序逐篇合并docs/<page>.md（见 build-readme.mjs）。侧边栏即 README 的目录骨架，增删文档只需改sidebars.js。

第三步：追加许可证尾部

所有正文合并完成后，再以headerLevel: 1追加readme-sources/license.md（见 build-readme.mjs），声明 MIT 许可证及对 Node.js、TypeScript 源码的版权归属（详见 license.md）。

第四步：标题降级与 frontmatter 处理

每个源文件在合并时都经过remark-behead做标题层级调整（headerLevel - 1），保证来自不同文档的 H2 在 README 中正确降级对齐（见 build-readme.mjs）。frontmatter 的处理逻辑如下（见 build-readme.mjs）：

• 若存在title且未设置omitHeaderOnMerge: true，脚本会额外生成一个对应层级的标题节点；
• 若设置了omitHeaderOnMerge: true（如 prefix.md），则只拼接正文内容，不输出标题；
• 二者配合，既能让website/docs中每篇文档自带titlefrontmatter 作为 README 章节标题，又能让 prefix.md 这类头部片段避免重复标题。

后处理转换管道：生成 README 前的五道工序

合并完成后，渲染阶段依次执行多道 AST 重写（见 build-readme.mjs）：

1. codeLanguageJsonToJsonc（L114-L120）：把所有json代码块语言标记改写为jsonc，避免 npm 渲染 README 时对带注释的 JSON 报错；
2. rewritePageLinksToAnchorLinks（L121-L130）：把website/docs中的页面间相对链接（如./options.md）重写为 README 内的#锚点链接，使合并后的文档在单页 README 中依然可跳转；
3. rewriteImgTargets（L132-L138）：将以/开头的图片路径重写为website/static/前缀，确保相对路径在 README 中可解析；
4. trimCutFromTwoslashCode（L140-L150）：对带twoslashmeta 的代码块，裁剪掉// ---cut---注释以上的引导代码，只保留可运行片段——这是文档站点 twoslash 交互示例与 README 静态代码之间的关键兼容处理；
5. remarkToc（L88）：依据最终标题树自动生成 Table of Contents——即 prefix.md 中那个空目录起点最终被填充为完整锚点目录的过程。

最后，脚本还会用remark-validate-links与remark-preset-lint-recommended对生成的 README 做链接与规范校验，任何坏链接或 lint 错误都会导致构建以非零状态码中止（见 build-readme.mjs），从机制上保证 README 与文档站点的链接质量。

侧边栏如何决定 README 章节标题

合并时各分类是否生成 H1 大标题，由generateReadmeHeadersForCategories显式控制（见 build-readme.mjs）：

• General：false，不生成分类大标题，文档直接以 H1 呈现（对应 README 开头的 Overview、Installation 等章节）；
• Advanced与Recipes：true，生成分类级 H1 大标题，文档标题降级为 H2。

因此 README 的实际层级是：Overview / Installation / Usage / Configuration / Options / SWC / ...以 H1 平铺，随后出现# Advanced与# Recipes分组标题。这一设计直接映射 sidebars.js 的分类结构，维护者调整分类归属即可同步改变 README 的组织方式。

贡献者工作流：如何正确修改 ts-node 文档

结合 prefix.md 注释、CONTRIBUTING.md 与构建脚本，修改文档的标准流程如下：

# 1. 修改源文件（而不是 README.md） # - 新增/修改正文：编辑 website/docs/<page>.md # - 调整章节顺序：修改 website/sidebars.js # - 修改头部/尾部片段：编辑 website/readme-sources/prefix.md / license.md # 2. 本地启动文档站点预览 cd website yarn yarn start # Docusaurus 本地站点，验证渲染效果 # 3. 重建 README yarn build-readme # 重新生成仓库根目录的 README.md # 4. 校验 # 脚本会对生成的 README 做链接与 lint 校验，有问题会直接报错中止

版本发布前，维护者还会执行yarn prepack（其入口为 scripts/prepack.mjs，实际构建由package.json中的prepack-worker完成，见 package.json），而 README 的更新是 npm 发布清单中的必要一环——因为 npmjs 仓库页直接渲染该 README。此外，发布流程约定将稳定版文档维护在docs分支、未发布功能文档合入main，发布时再合并统一，从而让网站、README 与代码版本始终保持一致。

从 tagline 回看文档背后的项目定位

prefix.md 中的 tagline——TypeScript execution and REPL for node.js, with source map and native ESM support——不是一句空泛宣传语，而是对仓库核心能力的精确概括：

• 它通过钩住 Node.js 的模块加载 API，在.ts/.tsx/.js/.jsx模块被加载时即时把 TypeScript 编译为 JavaScript（原理见 website/docs/how-it-works.md，对应实现位于 src/）；
• 提供ts-node/register等注册入口（如 register/index.js 仅一行require('../').register()），也提供基于 ESM loader 的ts-node/esm入口（esm.mjs）；
• 支持 source map 堆栈追踪与原生 ESM，这两点正是 prefix.md 徽章区下 tagline 所强调的核心卖点。

理解这条 tagline，有助于读懂website/docs中为何单列commonjs-vs-native-ecmascript-modules.md、swc.md、transpilers.md等文档——整个文档体系都是围绕“在 Node.js 上直接运行 TypeScript”这一件事展开的，而 README 只是这套文档体系在单一文件视图下的自动生成投影。

小结

• README.md是构建产物，真正的文档源位于website/docs与website/readme-sources；
• prefix.md 通过omitHeaderOnMerge: true作为无标题头部组件注入 README，承载徽章、tagline 与目录起点；
• 生成流水线由 build-readme.mjs 执行：先头部、再按 sidebars.js 合并正文、后追加 license.md，并经五道转换与链接/lint 校验后落盘；
• 贡献者修改文档的唯一正确姿势是：改源文件 →yarn start预览 →yarn build-readme重建，而不是直接编辑 README。

这套“站点与 README 同源、构建驱动、自动校验”的文档工程实践，是 ts-node 开源仓库中值得借鉴的通用方案，也让 README 始终与最新文档保持严格一致。

• CLI
• 开发工具