Vale custom style guides
Note
This document is for your information only. For custom style guides we have a single source which is located in linters repository. You are not allowed to create custom style guides in our projects unless it’s a custom dictionary of exclusions.
You need to do the following steps to start using these style guides:
Clone this repository
Copy & paste (overwrite) style directories into your own repository.
One of the key benefits of using Vale as a linting automation tool is the ability to add custom style guides.
Using this feature, you can check your documents against your own style guides rather than using predefined third-party ones.
Based on Vale documentation, the following rules can be checked in your documentation:
existence
substitution
occurrence
repetition
consistency
conditional
capitalization
Adding custom style guides
Note
To update linters, a TW must discuss it with the rest of our team and create a MR to the linters repo. After approval, TWs update linters in their projects.
1- Create style guides folder
Create a folder inside your project. You should mention this folder name in your .vale.ini file. In this example, you named the folder B2Broker, and this is how your .vale.ini should look like:
StylesPath = styles
Vocab =
MinAlertLevel = suggestion
[*.rst]
BasedOnStyles = B2broker, Google
2- Create a style guide YAML file
For each custom style guide, you need to create a YAML file. Let’s start with an example.
Generally, you want to avoid using the tense will in your documentation. Therefore you need to check for the existence of will. To do so, you need to have the following lines of code inside a file named avoid.yml.
extends: existence
message: "Avoid using '%s'."
ignorecase: false
level: warning
tokens:
- will
In the first line, specify the extension. Since you need to check the existence of a word, the extension is existence
On the second line, specify the message that should be shown to the client in case you have will in a document.
On the third line, specify case sensitivity. In this case, you are looking for every form of will.
On the fourth line, specify the notification level, which can be one of the following items. The first two are only for your information, but the third one stops the process of committing new change(s), and you should fix it.
suggestion
warning
error
On the fifth line, you specify tokens, which contains a list of all the words that should be removed from your documents. Here are a few examples of these words:
simple
simply
easy
easily
just
of course
he
him