⚠️
由于最近的文档站点迁移，我们的文档目前不使用 Vale。您仍然可以在 GitHub 上查看我们的风格指南。

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

与代码代码检查器类似，散文代码检查器会自动检查您的文本中的错误。与语法检查器不同的是，语法检查器会突出显示语法规则的违反，散文代码检查器专注于通过解决常见的用法问题（例如多余空格、重复单词、过度使用行话、性别歧视语言和错误的字母大小写）来改进文本。

散文代码检查器还可以提供一个框架来创建和执行 编辑风格指南。这有助于审阅过程，因为您现在可以专注于审阅内容本身，而不是指出错别字和首选用法模式。当在 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 附带了现成的风格指南，您可以将其应用于您的文档并开始检查。以下是一些帮助我们入门的风格指南

您可以在 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: \b(\w+)\b

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

level 设置为 warning。书面文本很复杂，Vale 会发现误报。没有万无一失的方法来确定何时规则应该是建议、警告或错误。您需要做出决定并边走边学。

我建议您定期查看您的规则，以更新规则，并在某些情况下删除过时的规则。最初，Meilisearch 文档没有关于句子长度的规则。当我们添加它时，句子的最大长度是 45。现在是 40，我们计划将其降低到 35。

您还可以通过将它们添加到 vale.ini 中来启用或禁用风格指南中的特定规则

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

上面的行禁用了 Meilisearch 风格指南 中的标题、拼写和分号规则。

步骤 5：运行 Vale

现在，当您使用以下命令在您的控制台中检查整个项目时

vale .

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

您还可以使用以下命令检查单个文件

vale {file_path}

步骤 6：自动化 Vale 检查

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

结论

就是这样，朋友们！我希望我已经帮助您开始使用 Vale（以及风格指南）。这是一个快速概述，介绍 Vale 的功能。根据您的需要调整它需要时间和许多、许多迭代。

配置好后，Vale 可以自动化审阅过程的一部分，让您专注于计算机不太擅长的文本部分。至少现在还没有。

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