安全

使用 Vale

以 Markdown 格式查看

Vale 是一个开源的语法检查工具，有助于维护一致的写作风格并捕获文档中的常见错误。

将 Vale 与您的 Fern 文档一起使用，以自动检查风格问题并强制执行写作指南。Vale 可以在本地或 CI/CD 中运行，在问题发布之前捕获它们。

设置

1

安装 Vale

在您的本地机器上安装 Vale。

2

在您的仓库根目录创建 .vale.ini 文件

创建一个 .vale.ini 文件并添加以下内容，以便 Vale 将 MDX 文件解析为 Markdown：

vale.ini
[formats]
mdx = md
3

添加风格规则

导入现有的 Vale 风格包或创建您自己的风格规则。

4

检查您的文档

检查您的整个文档集、目录中的所有页面或特定页面：

$vale fern/
$vale fern/pages/payments/
$vale fern/pages/payments/overview.mdx
5

为特定类型的内容禁用 Vale

要在 Fern 文档的特定部分禁用 Vale，请使用包装在 MDX 语法中的 Vale 注释。这对于代码块特别有用，因为 Vale 可能会将变量名或代码语法标记为风格违规。

Example Vale Usage
1Vale 将检查此文本。
2
3{/* <!-- vale off --> */}
4
5Vale 不会检查此文本
6
7<CodeBlock>
8```typescript
9import { PlantClient } from "@plantstore/sdk";
10
11const client = new PlantClient({ apiKey: "YOUR_API_KEY" });
12const plant = await client.createPlant({
13  name: "Monstera",
14  species: "Monstera deliciosa"
15});
16```
17</CodeBlock>
18
19{/* <!-- vale on --> */}
20
21Vale 将重新开始检查此文本。
6

自动化 Vale（可选）

考虑将 Vale 集成到您的工作流程中，以便为所有贡献者自动运行：

  • GitHub Actions：使用 Vale Action 在拉取请求上运行 Vale 并在风格问题上添加内联注释
  • Pre-commit 钩子：使用 Vale 的 pre-commit 集成 在文件提交之前检查它们

这有助于在您的文档团队中强制执行一致的风格标准，而无需手动运行 Vale。