Vale：适用于散文的代码式检查工具

# Vale：你的风格，我们的编辑器 来源：https://vale.sh/ 开源 · MIT 许可证 · 6.1K 星标 (https://github.com/vale-cli/vale) GitHub 星标6.1K (https://github.com/vale-cli/vale) 下载量13.9M (https://vale.sh/library) 已采用团队90 (https://vale.sh/adopters) Vale 将代码式的校验带入散文写作。将一个团队的风格指南、企业语气或期刊作者指南转化为可在编辑器和代码旁运行的检查项。 快速开始 (https://docs.vale.sh/topics/quickstart) 了解工作原理 (https://vale.sh/#how-it-works) 支持 macOS、Windows 和 Linux · 离线运行 01你的指南 写作指南 · 术语 该产品名为 **Vale CLI**。请勿写作 Vale cli 或 vale-cli。 02你自定义的规则 styles/Docs/Terms.yml ``` extends: substitution message: "请使用‘%s’而非‘%s’。" level: error action: name: replace swap: 'Vale cli|vale-cli': Vale CLI 'style ?guide': style guide 'e-?mail': email ``` 03在你的写作环境中获取反馈 docs/install.md 1. # 安装 3. Vale CLI 可在 macOS、Windows 和 Linux 上运行。 错误：请使用 'Vale CLI' 而非 'Vale cli'。Docs.Terms 将你的指南编码为 YAML 文件，或从已发布的风格入手：Microsoft (https://vale.sh/explorer/Microsoft)、Google (https://vale.sh/explorer/Google) 或 Red Hat (https://vale.sh/explorer/RedHat)。在探索器 (https://vale.sh/explorer) 中浏览所有可用风格。 支持该项目 ## 赞助商聚焦 (https://vale.sh/#spotlight) 这些公司支持 Vale 的未来——并将它应用于自己的产品中。 为何选择 Vale ## 多数工具只看文本。Vale 能理解文档。(https://vale.sh/#features) 在上下文中检查写作。可针对标题、注释或描述进行检查，同时保留其周围的代码。 01作用域 ### 你的文档有结构，你的规则也该有结构。 对标题、列表和表格单元格应用不同的检查。Vale 首先解析标记，因此代码块和链接 URL 不会受到干扰。 探索标记与作用域 (https://vale.sh/features/markup) guide.md Vale 所见内容 `\# Getting started` 标题 `使用你团队的语气写作。` 段落 `\- 保持说明清晰。` 列表 `\[阅读指南\]\(https://example\.com\)` 跳过的 URL `\`\`\`shvale docs/\`\`\`` 跳过的代码块 检查散文，保留代码。 支持12种标记格式 - Markdown - AsciiDoc - reStructuredText - MDX - MyST - Quarto - Typst - HTML - XML - DITA - Org - QDoc 02代码 ### 注释同样重要。 使用 tree-sitter 语法解析器提取注释，然后检查其中的 Markdown。字符串内的注释标记仍视为代码。 文档注释中的 Markdown `/// 使用给定的名称创建一个人。` 段落 `///` `/// \# 示例` 标题 `/// \`\`\`` 代码块已跳过 `/// let person = Person::new\("name"\);` `/// \`\`\`` `pub fn new\(name: &str\) \-\> Person \{` 非注释 支持19种编程语言 - Go - Rust - Python - Ruby - C\+\+ - C - JavaScript - TypeScript - TSX - Java - Haskell - Julia - Lua - PHP - R - QML - Protobuf - YAML - CSS 探索代码注释 (https://vale.sh/features/code) 03视图 ### 在意想不到的地方发现散文。 视图可以选择结构化文件内的写作内容。使用相应上下文的规则检查 API 描述、笔记本单元格或提交信息。 选择描述 `openapi: 3\.1\.0` `info:` `title: Example API` `version: 1\.0\.0` `description: 管理你的项目。` 描述 `paths:` `/projects: \{\}` 超越文档范畴 - OpenAPI - Jupyter - 提交信息 - 转录稿 - 文档字符串 - JSON - YAML - TOML 探索视图 (https://vale.sh/features/views) 04速度 ### 为整个仓库而生。 单一 Go 二进制文件。并行检查。无需单独的运行时。 查看性能基准 (https://vale.sh/features/speed) GitLab 文档 · 单次运行 Markdown 页面数2,827 应用规则数82 从开始到结束<20秒 分发情况 ## Vale 的下载渠道 (https://vale.sh/#stats) 七个注册中心发布了下载计数，且各自统计的时间窗口不同，因此在此并列展示，而非合并为一个总数。 至今总下载量13.9M 报告其生命周期总量的渠道 GitHub 星标6.1K vale-cli/vale 主仓库贡献者64位 - GitHub Releases11.4M 生命周期 (https://github.com/vale-cli/vale/releases) - Docker Hub2.3M 生命周期 (https://hub.docker.com/r/jdkato/vale) - PyPI1.6M 过去6个月 · 社区维护的包装器 (https://pypi.org/project/vale/) - npm139.8K 过去1个月 · 社区维护的包装器 (https://www.npmjs.com/package/@vvago/vale) - conda-forge165.4K 生命周期 (https://anaconda.org/conda-forge/vale) - Homebrew76.6K 过去12个月 (https://formulae.brew.sh/formula/vale) - Chocolatey19.5K 生命周期 (https://community.chocolatey.org/packages/vale) - GitHub Action4.2K 仓库 · 正在使用中 (https://github.com/marketplace/actions/vale-linter) - 同时提供以下平台版本 - WinGet v3.22.0 (https://winstall.app/apps/errata-ai.Vale) - Snap Store v3.17.1 (https://snapcraft.io/vale) - Linux 和 BSD 17 个仓库 (https://repology.org/project/vale/versions) 数据来源：GitHub、Docker Hub、PyPI、npm、conda-forge、Homebrew、Chocolatey、WinGet、Snapcraft 和 Repology · 更新于 2026-08-28 一个工具，适用于所有应用 ## 不仅仅是命令行界面。(https://vale.sh/#integrations) Vale 可在你日常写作的任何地方运行——在你的编辑器中，在你的笔记应用中，以及在 CI 代码合并前。 ## 几行配置，即可获得一致的初稿。 从一个现有的风格指南入手。将配置保存在项目中，确保每个人都运行相同的检查。 1. **安装 Vale。** 为你的操作系统选择一个安装包。 2. **选择你的风格。** 将以下内容保存为项目中的 `.vale.ini` 文件。 3. **同步，然后校验。** 下载风格并检查你的文档。 ``` StylesPath = styles MinAlertLevel = suggestion Packages = Microsoft [*.md] BasedOnStyles = Vale, Microsoft ``` 使用 YAML 规则自定义 ``` extends: substitution message: "请使用‘%s’而非‘%s’。" level: warning swap: utilize: use ``` 学习编写规则 → (https://docs.vale.sh/topics/styles)