github.com/errata-ai/vale/v3@v3.4.2/README.md (about) 1 # Vale: Your style, our editor [![Build status](https://ci.appveyor.com/api/projects/status/snk0oo6ih1nwuf6r?svg=true)](https://ci.appveyor.com/project/jdkato/vale) [![Go Report Card](https://img.shields.io/badge/%F0%9F%93%9D%20%20go%20report-A%2B-75C46B?color=00ACD7)](https://goreportcard.com/report/github.com/errata-ai/vale) [![GitHub All Releases](https://img.shields.io/github/downloads/errata-ai/vale/total?logo=GitHub&color=ff69b4)](https://github.com/errata-ai/vale/releases) [![Docker Pulls](https://img.shields.io/docker/pulls/jdkato/vale?color=orange&logo=docker&logoColor=white)](https://hub.docker.com/r/jdkato/vale) [![Chocolatey](https://img.shields.io/chocolatey/dt/vale?color=white&label=chocolatey&logo=chocolatey)](https://community.chocolatey.org/packages/vale) [![Homebrew](https://img.shields.io/homebrew/installs/dy/vale?color=yellow&label=homebrew&logo=homebrew)](https://formulae.brew.sh/formula/vale) 2 3 > Enjoying Vale? Please consider writing a user [testimonial][5]. 4 5 <p align="center"> 6 <b>Vale</b> is a command-line tool that brings code-like linting to prose. It's <b><a href="#mag-at-a-glance-vale-vs-">fast</a></b>, <b>cross-platform</b> (Windows, macOS, and Linux), and <b>highly customizable</b>. 7 </p> 8 9 <p align="center"> 10 <img width="75%" alt="A demo screenshot." src="https://vale.sh/images/vale/mac.png"> 11 </p> 12 13 <div align="center"> 14 <table> 15 <thead> 16 <tr> 17 <th><a href="https://vale.sh/docs/vale-cli/installation/">Docs</a></th> 18 <th><a href="https://studio.vale.sh/">Vale Studio</a></th> 19 <th><a href="https://vale.sh/hub/">Package Hub</a></th> 20 <th><a href="https://vale.sh/explorer/">Rule Explorer</a></th> 21 <th><a href="https://vale.sh/generator/">Config Generator</a></th> 22 </tr> 23 </thead> 24 </table> 25 </div> 26 27 ## :heart: Sponsors 28 29 > Hi there! I'm [@jdkato](https://github.com/jdkato), the sole developer of Vale. If you'd like to help me dedicate more time to _developing_, _documenting_, and _supporting_ Vale, feel free to donate through [GitHub Sponsors](https://github.com/sponsors/jdkato) or [Open Collective](https://opencollective.com/vale). Any donation—big, small, one-time, or recurring—is greatly appreciated! 30 31 ### Organizations 32 33 <a href="https://opencollective.com/vale/organization/0/website"><img src="https://opencollective.com/vale/organization/0/avatar.svg?avatarHeight=100"></a> 34 <a href="https://opencollective.com/vale/organization/1/website"><img src="https://opencollective.com/vale/organization/1/avatar.svg?avatarHeight=100"></a> 35 <a href="https://opencollective.com/vale/organization/2/website"><img src="https://opencollective.com/vale/organization/2/avatar.svg?avatarHeight=100"></a> 36 <a href="https://opencollective.com/vale/organization/3/website"><img src="https://opencollective.com/vale/organization/3/avatar.svg?avatarHeight=100"></a> 37 <a href="https://opencollective.com/vale/organization/4/website"><img src="https://opencollective.com/vale/organization/4/avatar.svg?avatarHeight=100"></a> 38 <a href="https://opencollective.com/vale/organization/5/website"><img src="https://opencollective.com/vale/organization/5/avatar.svg?avatarHeight=100"></a> 39 <a href="https://opencollective.com/vale/organization/6/website"><img src="https://opencollective.com/vale/organization/6/avatar.svg?avatarHeight=100"></a> 40 <a href="https://opencollective.com/vale/organization/7/website"><img src="https://opencollective.com/vale/organization/7/avatar.svg?avatarHeight=100"></a> 41 <a href="https://opencollective.com/vale/organization/8/website"><img src="https://opencollective.com/vale/organization/8/avatar.svg?avatarHeight=100"></a> 42 <a href="https://opencollective.com/vale/organization/9/website"><img src="https://opencollective.com/vale/organization/9/avatar.svg?avatarHeight=100"></a> 43 44 ### Other 45 46 > Thanks to [DigitalOcean][1] for providing hosting credits for [Vale Studio][2]. 47 48 <p> 49 <a href="https://www.digitalocean.com/"> 50 <img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/PoweredByDO/DO_Powered_by_Badge_blue.svg" width="201px"> 51 </a> 52 </p> 53 54 > Thanks to [Appwrite][4] for supporting Vale through their [Open Source Sponsorship program][3]. 55 56 <p> 57 <a href="https://appwrite.io/"> 58 <img src="https://github.com/errata-ai/vale/assets/8785025/95d4b2f8-a94b-4512-8197-7e80973655cc" width="201px"> 59 </a> 60 </p> 61 62 ### Individuals 63 64 <a href="https://opencollective.com/vale"><img src="https://opencollective.com/vale/individuals.svg?width=890"></a> 65 66 ## :boom: Key Features 67 68 - [x] **Support for markup**: Vale has a rich understanding of many [markup formats](https://docs.errata.ai/vale/scoping#formats), allowing it to avoid syntax-related false positives and intelligently exclude code snippets from prose-related rules. 69 70 - [x] A **highly customizable** [extension system](https://vale.sh/docs/topics/styles/): Vale is capable of enforcing _your style_—be it a standard [editorial style guide](https://github.com/errata-ai/styles#available-styles) or a custom in-house set of rules (such as those created by [GitLab](https://docs.gitlab.com/ee/development/documentation/testing.html#vale), [Homebrew](https://github.com/Homebrew/brew/tree/master/docs/vale-styles/Homebrew), [Linode](https://www.linode.com/blog/linode/docs-as-code-at-linode/), [CockroachDB](https://github.com/cockroachdb/docs/tree/master/vale), and [Spotify](https://github.com/spotify/backstage)). 71 72 - [x] **Easy-to-install**, stand-alone binaries: Unlike other tools, Vale doesn't require you to install and configure a particular programming language and its related tooling (such as Python/pip or Node.js/npm). 73 74 See the [documentation](https://vale.sh) for more information. 75 76 ## :mag: At a Glance: Vale vs. `<...>` 77 78 > **NOTE**: While all of the options listed below are open-source (CLI-based) linters for prose, their implementations and features vary significantly. And so, the "best" option will depends on your specific needs and preferences. 79 80 ### Functionality 81 82 | Tool | Extensible | Checks | Supports Markup | Built With | License | 83 | ---------- | -------------------- | --------------- | ----------------------------------------------------------------------- | ---------- | ------------ | 84 | Vale | Yes (via YAML) | spelling, style | Yes (Markdown, AsciiDoc, reStructuredText, HTML, XML, Org) | Go | MIT | 85 | textlint | Yes (via JavaScript) | spelling, style | Yes (Markdown, AsciiDoc, reStructuredText, HTML, Re:VIEW) | JavaScript | MIT | 86 | RedPen | Yes (via Java) | spelling, style | Yes (Markdown, AsciiDoc, reStructuredText, Textile, Re:VIEW, and LaTeX) | Java | Apache-2.0 | 87 | write-good | Yes (via JavaScript) | style | No | JavaScript | MIT | 88 | proselint | No | style | No | Python | BSD 3-Clause | 89 | Joblint | No | style | No | JavaScript | MIT | 90 | alex | No | style | Yes (Markdown) | JavaScript | MIT | 91 92 The exact definition of "Supports Markup" varies by tool but, in general, it means that the format is understood at a higher level than a regular plain-text file (for example, features like excluding code blocks from spell check). 93 94 Extensibility means that there's a built-in means of creating your own rules without modifying the original source code. 95 96 ### Benchmarks 97 98 <table> 99 <tr> 100 <td width="50%"> 101 <a href="https://user-images.githubusercontent.com/8785025/97052257-809aa300-1535-11eb-83cd-65a52b29d6de.png"> 102 <img src="https://user-images.githubusercontent.com/8785025/97052257-809aa300-1535-11eb-83cd-65a52b29d6de.png" width="100%"> 103 </a> 104 </td> 105 <td width="50%"> 106 <a href="https://user-images.githubusercontent.com/8785025/97051175-91e2b000-1533-11eb-9a57-9d44d6def4c3.png"> 107 <img src="https://user-images.githubusercontent.com/8785025/97051175-91e2b000-1533-11eb-9a57-9d44d6def4c3.png" width="100%"> 108 </a> 109 </td> 110 </tr> 111 <tr> 112 <td width="50%"> 113 This benchmark has all three tools configured to use their implementations of the <code>write-good</code> rule set and Unix-style output. 114 </td> 115 <td width="50%">This benchmark runs Vale's implementation of <code>proselint</code>'s rule set against the original. Both tools are configured to use JSON output.</td> 116 </tr> 117 <tr> 118 <td width="50%"> 119 <a href="https://user-images.githubusercontent.com/8785025/97053402-c5bfd480-1537-11eb-815b-a33ab13a59cf.png"> 120 <img src="https://user-images.githubusercontent.com/8785025/97053402-c5bfd480-1537-11eb-815b-a33ab13a59cf.png" width="100%"> 121 </a> 122 </td> 123 <td width="50%"> 124 <a href="https://user-images.githubusercontent.com/8785025/97055850-7b8d2200-153c-11eb-86fa-d882ce6babf8.png"> 125 <img src="https://user-images.githubusercontent.com/8785025/97055850-7b8d2200-153c-11eb-86fa-d882ce6babf8.png" width="100%"> 126 </a> 127 </td> 128 </tr> 129 <tr> 130 <td width="50%"> 131 This benchmark runs Vale's implementation of Joblint's rule set against the original. Both tools are configured to use JSON output. 132 </td> 133 <td width="50%">This benchmark has all three tools configured to perform only English spell checking using their default output styles.</td> 134 </tr> 135 </table> 136 137 All benchmarking was performed using the open-source [hyperfine](https://github.com/sharkdp/hyperfine) tool on a MacBook Pro (2.9 GHz Intel Core i7): 138 139 ``` 140 hyperfine --warmup 3 '<command>' 141 ``` 142 143 The corpus IDs in the above plots—`gitlab` and `ydkjs`—correspond to the following files: 144 145 - A [snapshot](https://gitlab.com/gitlab-org/gitlab/-/tree/7d6a4025a0346f1f50d2825c85742e5a27b39a8b/doc) of GitLab's open-source documentation (1,500 Markdown files). 146 147 - A [chapter](https://raw.githubusercontent.com/getify/You-Dont-Know-JS/1st-ed/es6%20%26%20beyond/ch2.md) from the open-source book _You Don't Know JS_. 148 149 ## :page_facing_up: License 150 151 [![FOSSA Status](https://app.fossa.com/api/projects/custom%2B21090%2Fgithub.com%2Ferrata-ai%2Fvale.svg?type=large)](https://app.fossa.com/projects/custom%2B21090%2Fgithub.com%2Ferrata-ai%2Fvale?ref=badge_large) 152 153 [1]: https://www.digitalocean.com/open-source/credits-for-projects 154 [2]: https://studio.vale.sh/ 155 [3]: https://appwrite.io/oss-fund 156 [4]: https://appwrite.io/ 157 [5]: https://page.famewall.io/vale