使用 Vale 进行散文风格检查

写作是一个耗时的过程。根据作者和审查过程，可能需要一段时间才能准备好发布内容。无论您是单人作者还是大型团队，散文风格检查器都可以帮助确保一致的语气和风格。

与代码风格检查器类似，散文风格检查器会自动检查您的文本中的错误。与突出显示语法规则违反情况的语法检查器不同，散文风格检查器侧重于如何通过解决常见的用法问题（如多余的空格、重复的单词、过度使用术语、性别歧视语言和不正确的首字母大写）来使您的文本更好。

散文风格检查器还可以为创建和执行编辑风格指南提供框架。这有助于审查过程，因为您现在可以专注于审查内容本身，而不是指出错别字和首选用法模式。当在像 Meilisearch 这样的开源项目中工作时，这一点尤其重要，因为您有很多不熟悉您风格指南的贡献者。

什么是 Vale？

Vale 是一个开源的、高度可定制的、语法感知的散文风格检查器。它支持以多种不同格式编写的文档，例如 Markdown、HTML、reStructuredText、AsciiDoc、DITA 和 XML。

在散文风格检查方面，Vale 不是您唯一的选择。还有许多其他开源工具可用，包括proselint、textlint 和 alex。

在 Meilisearch，我们决定选择 Vale，因为它速度快、易于设置、灵活，并且带有现有规则来帮助您入门。

从哪里开始？

虽然看起来令人生畏，但如果您从小处着手并保持简单，那么设置 Vale 可能非常简单。在这篇文章中，我们将介绍如何在类似于 Meilisearch 文档的项目中使用 Vale。

第 1 步：风格指南

第一步是创建风格指南。风格指南确保一致的语气和风格，无论您的团队有多大。它建立了标准实践，当人们可能有不同的意见时，例如是否使用牛津逗号。

如果您没有内部风格指南，您可以查看Google 或 Microsoft 的风格指南以帮助您入门。随着时间的推移，您将记住大多数规则，但可能会忽略错误，有时甚至会忘记规则。我们只是凡人。

这就是 Vale 的用武之地。它允许您“编纂”风格指南，并根据该风格指南中的所有规则检查您的文本。如果它检测到任何问题，它会在控制台上显示建议、警告或错误。

第 2 步：安装 Vale

我使用的是 macOS，并在我的控制台中运行了 brew install vale 来安装 Vale。

如果您使用的是其他操作系统，请查看 Vale 的文档以获取安装说明。

通过在控制台中键入 vale -v 来验证安装。如果此命令返回 Vale 的版本号，则安装成功。

最后，创建以下文件和文件夹

├── .vale.ini
│   ├──  styles
│   │	    ├── Style guide
│   │       └── Vocab

第 3 步：配置 Vale - vale.ini

在您的存储库根目录中创建一个 vale.ini 文件。这是 Vale 配置文件，您可以在其中定义您希望 Vale 执行的操作以及要检查的文件。让我们从基本设置开始——您可以根据项目的需要随时添加它。

StylesPath = .vale/styles
MinAlertLevel = suggestion

Vocab = word_list

[*.md]
BasedOnStyles = Meilisearch

• StylesPath 是 Vale 查找您的风格指南的位置（下一节将详细介绍）。该路径可以是相对于 vale.ini 文件位置的相对路径或绝对路径。

• MinAlertLevel 指定 Vale 将报告的最低警报级别。默认情况下，它设置为 warning。其他选项是 error 和 suggestion。
  错误表示您做错了什么，例如使用多余的空格或输入错误。警告不如错误严重，但表示您应该避免的事情，例如确保您的句子不会变得太长。建议是建议您做某事，这通常（但不总是）是一个好主意，例如将您的句子分成两个，而不是使用分号。
  如果将规则设置为 suggestion，您将看到建议、警告和错误。如果将其设置为 warning，Vale 将仅显示错误和警告，而不会显示建议。

• Vocab：这是您创建包含 accept.txt 和 reject.txt 文件的目录的位置。这两个文件都接受单词、短语和正则表达式。如果您的文本包含词典中不存在的单词（例如“Meilisearch”），您可以将它们添加到 accept.txt，Vale 不会因为您犯了“错别字”而愤怒地尖叫。Vale 会将 reject.txt 中列出的所有出现情况标记为错误。当您希望作者避免使用特定单词时，这会很有用——例如，如果您正在撰写有关搜索引擎和数据库的文章，则使用“索引”可能会令人困惑。

• [*.md] 告诉 Vale 仅检查 Markdown 文件。如果要检查纯文本文件，请使用 [*.txt]。

• BasedOnStyles 指定 Vale 应该用于检查的风格指南。

您可以指定其他设置，包括要忽略的标记和 HTML 标签以及 Vale 应将什么视为单个单词。您可以在 Vale 的文档中阅读有关 vale.ini 文件的更多信息。

第 4 步：规则和 styles 文件夹

正如我之前提到的，您需要一个风格指南才能使用 Vale。然后，您将此风格指南转换为 Vale 可以理解的内容：规则。

规则使用不同的扩展点来执行特定任务。例如，existence 扩展点查找特定标记是否存在，repetition 查找重复的标记，spelling 实现拼写检查等等。在 Vale 中，每个规则都是一个 YAML 文件。styles 文件夹包含构成风格指南的单个规则。

如果您不想创建自己的风格指南，或者需要一个起点来构建，Vale 附带了可以应用于您的文档并开始检查的现成风格指南。以下是一些帮助我们入门的风格指南

• Google
• GitLab
• RedHat

您可以在Vale 的 GitHub 存储库中找到更多信息。

让我们从一个关于句子长度的规则开始。你的风格可能会说类似“确保句子不超过40个单词”这样的话。以下是该规则在 YAML 文件中的样子：

# Warning: Meilisearch.SentenceLength

# Counts words in a sentence and alerts if a sentence exceeds 40 words.

extends: occurrence
message: 'Shorter sentences improve readability (max 40 words).'
scope: sentence
link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language
level: warning
max: 40
token: (w+)

这个规则会计算句子中的单词数量，如果超过 40 个单词，则会发出警告。scope 被设置为 sentence：这确保了 Vale 不会将此规则应用于文本的其他部分，例如标题或表格。

level 被设置为 warning。书面文本是很复杂的，Vale 会发现误报。没有万无一失的方法来决定一个规则应该是一个建议、警告还是一个错误。你需要做出决定，并在实践中学习。

我建议你随着时间的推移审查你的规则，以更新规则，并在某些情况下删除过时的规则。最初，Meilisearch 文档中没有关于句子长度的规则。当我们添加它时，句子的最大长度是 45 个单词。现在是 40 个单词，我们计划将其降至 35 个单词。

你还可以通过将特定规则添加到 vale.ini 中，在风格指南中启用或禁用它们。

Meilisearch.Headings = NO
Meilisearch.Spelling = NO
Meilisearch.Semicolons = NO

上面的几行代码禁用了来自 Meilisearch 风格指南中的 Heading、Spelling 和 Semicolons 规则。

第五步：运行 Vale

现在，当你在控制台上使用以下命令来检查你的整个项目时：

vale .

Vale 将根据存储在 BasedOnStyles 中的规则检查你所有的文件。如果 Vale 检测到任何问题，它将在控制台上显示建议、警告和错误。

你还可以使用以下命令来检查单个文件：

vale {file_path} 

第六步：自动化 Vale 检查

到目前为止，我们讨论的所有检查都是针对你本地文件的。一旦你确信这些规则可以按预期工作，你就可以使用 Vale GitHub action 来自动化这些检查！在 Meilisearch 文档存储库中，我们将其配置为对每个拉取请求运行。如前所述，Vale 可能会发现误报。由于你不希望因为 Vale 没有正常工作而阻止 PR，我建议从几个规则开始，然后慢慢调整它们，以避免检查失败。

结论

各位，这就是全部内容！我希望我能够帮助你开始使用 Vale（和一个风格指南）。这只是一个快速概述，向你介绍 Vale 的功能。根据你的需求进行调整需要时间和许多很多次迭代。

配置完成后，Vale 可以自动化部分审查过程，并让你专注于计算机不太擅长的文本部分。至少目前还不行。

哦，如果你好奇，请查看 我们在 GitHub 上的风格指南，看看我们是如何使用 Vale 的！