菜单
文档面包屑箭头 Writers' Toolkit面包屑箭头 构建和评审面包屑箭头 检查散文
开源 RSS
最后评审日期：2024 年 5 月 28 日

使用 Vale linter 对散文进行检查

Vale 是一款语法感知的散文检查工具，设计时考虑到了速度和可扩展性。

要在本地使用 Vale 对散文进行检查，请在文本编辑器中配置 Vale 或从 docs/ 目录运行 make vale。要在 Visual Studio Code 中使用 Vale，请参阅在 Visual Studio Code 中使用 Vale。

一些仓库将 Vale 作为持续集成 (CI) 的一部分运行。在 CI 中运行 Vale 的仓库包括

跳过 CI

对于移动存在 linting 问题的文件或需要推迟内容 linting 的拉取请求，您可能希望跳过 linting。

要在 CI 中跳过 Vale linting，请在拉取请求描述中包含 <-- vale = NO -->。

跳过规则

要跳过某条规则，请使用 HTML 注释将该部分括起来，先禁用，然后再重新启用特定的 Vale 规则。在注释中包含具体的规则名称，例如 Grafana.We 或 Grafana.GoogleEllipses。以下示例展示了如何禁用 Grafana.GooglePassive 规则

markdown 
<!-- vale Grafana.GooglePassive = NO -->

- [Deprecated content](#deprecation-example): Features that have been deprecated, but still need to be documented for some time.
- [Configuration options](#configuration-options-example): Features that have several ways they can be configured.

<!-- vale Grafana.GooglePassive = YES -->

在 Visual Studio Code 中使用 Vale

您可以使用 Vale 在 Visual Studio Code 中检查当前文档。

开始之前

如果您在 Linux 上安装 Vale，您可以尝试从您的 Linux 发行版的软件包仓库安装 Vale。但是，以下手动安装说明是在 Linux 上安装 Vale 的首选方法。

注意

Vale Snap 已过时且未维护。请勿使用 Ubuntu Snap 商店安装 Vale。

如果您在 macOS 上安装 Vale，请先安装 Homebrew。

如果您在 Windows 上安装 Vale，请先安装 Chocolatey。

注意

您可以在 Linux、macOS 或 Windows 上下载并手动安装 Vale。

如果您手动安装 Vale，您必须配置系统将 Vale 添加到您的路径，或在 Vale Visual Studio Code 扩展配置中设置 Vale › Vale CLI: Path。

在 Visual Studio Code 中安装和配置 Vale

  1. 克隆 Writers’ Toolkit 仓库。

    bash 
    git clone git@github.com:grafana/writers-toolkit.git

    如果您之前克隆过该仓库，请在 main 分支上运行 git pull。

  2. 下载并安装 Vale。

    注意

    请验证您下载的是 Vale for Linux 的最新构建版本。要查找最新构建版本，请参阅Releases - errata-ai/vale。

    linux-cli 
    wget https://github.com/errata-ai/vale/releases/download/v3.1.0/vale_3.1.0_Linux_64-bit.tar.gz
mkdir bin && tar -xvzf vale_3.1.0_Linux_64-bit.tar.gz -C bin
export PATH=./bin:"$PATH"
    macos 
    brew install vale
    windows 
    choco install vale

  3. 在您的主目录或工作目录中创建名为 .vale.ini 的文件，内容如下

    ini 
    MinAlertLevel = suggestion
Packages = <PATH TO WRITERS TOOLKIT REPOSITORY>/vale/Grafana, https://github.com/errata-ai/Hugo/releases/download/v0.2.0/Hugo.zip

[*]
BasedOnStyles = Grafana

    将 <PATH TO WRITERS TOOLKIT REPOSITORY> 替换为您 checkout 的 Writer’s Toolkit 仓库的完整路径。该路径取决于您克隆 Git 仓库的位置。例如

    • 在 Linux 上，您可以将 StylesPath 设置为 /home/<USERNAME>/git-repos/writers-toolkit/vale
    • 在 macOS 上，您可以将 StylesPath 设置为 /Users/<USERNAME>/git-repos/writers-toolkit/vale
    • 在 Windows 上，您可以将 StylesPath 设置为 C:\Users\<USERNAME>\git-repos\writers-toolkit\vale

  4. 安装已配置的 Vale 包。

    在您的主目录中，运行 vale sync 以安装您在 .vale.ini 配置文件中定义的包。

    注意

    每次在您的 Writers’ Toolkit 仓库中拉取更改后，都需要使用 vale sync 同步这些更改。

  5. 在 Visual Studio Code 中安装 Vale Visual Studio Code 扩展。

    1. 启动 Visual Studio Code。

    2. 按下 Ctrl+P，粘贴以下命令，然后按 Enter。或者，点击 Extensions 图标，搜索“Vale VSCode”，打开它，然后点击 Install。

      ext install ChrisChinchilla.vale-vscode

  6. 配置 Vale Visual Studio Code 扩展。

    1. 按下 Ctrl+Shift+X 或点击 Extensions 图标并选择 Vale Visual Studio Code 扩展。
    2. 选择齿轮图标。
    3. 要对所有仓库使用您自己的 Vale 配置，请将 Vale › Vale CLI: Config 设置为您的 .vale.ini 文件的路径。该路径取决于您创建 .vale.ini 文件的位置。例如
      • 在 Linux 上，路径可能是 /home/<USERNAME>/.vale.ini
      • 在 macOS 上，路径可能是 /Users/<USERNAME>/.vale.ini
      • 在 Windows 上，路径可能是 C:\Users\<USERNAME>\.vale.ini
    4. 对于 Linux、macOS 或 Windows 上的手动安装，请将 Vale › Vale CLI: Path 设置为 Vale 可执行文件的路径。该路径取决于您解压 Vale 可执行文件的位置。例如，在 Linux 上，路径可能是 /home/<USERNAME>/bin/vale。

  7. 重启 Visual Studio Code。

每次保存更改时，Vale 都会检查当前文档。该扩展以两种方式报告 linting 结果

  • 行内编辑标记。您可以将鼠标光标悬停在编辑标记上，以查看 Vale 警告或错误。
  • 在 PROBLEMS 选项卡中查看完整报告。报告中的每个 Vale 警告或错误都包含错误发生的行号和列号。