文档工具

概述

Node.js 维护着一套广泛的文档，包括 API 参考、指南和教程。为了确保这些文档的一致性和质量，项目采用了专门的工具来进行 linting（代码规范检查）、格式化和验证。主要组成部分是建立在 unified/remark 生态系统之上的 markdown linting 系统。

来源

Markdown Linting System

Node.js 项目使用位于 tools/lint-md 目录中的自定义 markdown linter。该工具建立在 unified/remark 生态系统之上，它提供了一个强大的框架来处理 markdown 内容。

Linting 系统通过几个阶段处理 markdown 文件：

解析：将 markdown 文本转换为抽象语法树 (AST)
Linting：应用 Node.js 特定的规则来强制执行文档标准
格式化：可以重新格式化文档以匹配样式约定
验证：执行其他检查，例如确保 API 文档具有版本标签

该工具可以以两种模式运行：

检查模式：报告 linting 错误而不修改文件
格式化模式：通过重写文件自动修复格式问题

来源

核心组件

Linting 系统由以下关键组件构建：

组件	包	目的
处理器框架	`unified`	编排 markdown 处理管道的核心框架
Markdown 解析器	`remark-parse`	将 markdown 文本解析为结构化的 AST
Linting 规则	`remark-preset-lint-node`	Node.js 特定的 markdown 规则和约定
序列化器	`remark-stringify`	将 AST 转换回 markdown 文本
文件处理	`to-vfile`	将文件读取到处理系统中的实用程序
错误报告	`vfile-reporter`	格式化并显示 lint 错误

来源

用法和实现

Linting 工具实现为一个 JavaScript 模块，可以处理一个或多个 markdown 文件。它通常通过 Node.js 构建脚本调用。

实现过程

解析命令行参数以确定操作模式
设置 unified processor 和所需的插件
处理每个输入文件
- 读取文件内容
- 通过 linting 管道运行它
- 比较原始内容和处理后的内容
- 根据模式报告错误或写入格式化后的内容

对于 API 文档文件（位于 doc/api/），它会执行额外的检查，确保其包含 introduced_in 版本标签。

来源

文档格式要求

Node.js 文档遵循 linting 系统强制执行的特定格式要求。这些要求有助于确保所有文档的一致性和正确的版本信息。

版本标记

API 文档文件必须包含一个 introduced_in 标签，指定功能添加到 Node.js 的时间。此标签可帮助用户了解 API 兼容性。

文档文件示例

linter 专门检查位于 doc/api/ 目录中的文件的此标签，如果缺少则会失败。

来源

YAML Frontmatter

文档文件使用 YAML frontmatter 来描述版本更改。这些信息用于生成更改日志，并为用户提供有关功能何时添加、更改或弃用的信息。

示例

来源

doc/api/typescript.md3-11

依赖管理

文档工具的依赖通过 npm 管理，并通过 GitHub 的 Dependabot 服务按月更新。这确保了工具及时获得安全补丁和改进。

依赖项在以下文件中指定：

package.json 用于直接依赖
package-lock.json 用于指定版本和子依赖

Dependabot 配置为将所有 lint-md 依赖更新分组在一起，以简化审查过程。

来源

与构建系统的集成

文档 linting 已集成到 Node.js 构建系统中。它可以在构建脚本中使用 format-md 目标作为通用格式化过程的一部分来触发。

在 Unix/macOS 上：make format-md
在 Windows 上：vcbuild format-md

如果不带格式化标志运行，linter 将检查问题但不会修改文件，使其适用于持续集成检查。

来源

tools/lint-md/lint-md.mjs51-53

结论

Node.js 文档工具提供了一个强大的系统，用于确保文档的质量和一致性。通过利用 unified/remark 生态系统，它强制执行项目特定的标准，同时为贡献者提供有用的反馈。该工具通过自动化的依赖更新进行积极维护，并集成到项目的构建和 CI 系统中。