This package contains rules based on the GOV.UK Technical Style guide and is designed to work with the linting tool Vale. You can find more information about Vale on its website.
Errors raised by the linter will show for each file:
- the line and character number of the issue
- the severity level of the issue (error, warning, suggestion)
- a description of the issue
- the path to the rule that flagged the issue
If you would like to suggest a change an existing rule, such as adding an acronym to our list of exceptions, please raise this in the #ask-di-tech-writing-architecture Slack channel, and it will be discussed in our regular forum.
To use the linter (Vale), you must provide a config file which describes where the rules for the linter are located. Confirm that a .vale.ini exists at the root of your repo and that the url for the tech-docs-linter zip file is provided through the Packages field. Here is a template config file for reference.
By default, Vale must be run from the same directory as this config file, unless the --config flag is provided with a path.
- In a terminal window, navigate to your repo
- Run
vale syncto download the latest tech-docs-linter package and unzip this to yourStylesPathlisted in your config file - Run the command
vale .to lint the entire repo or provide a path to a directory to lint only that directory for example:vale source/new-starter-guide/*.erb
Before releasing a new package make sure the CHANGELOG has been updated. To release an update:
- change directory to the styles folder
- create a zip package of the tech-writing-style-guide folder:
zip -r tech-writing-style-guide.zip tech-writing-style-guide - select Draft a new release from the releases page for the linter
- upversion the tag and add information about the changes that have been made
- upload the tech-writing-style-guide package
StylesPath = vale-styles
Packages = https://github.com/alphagov/tech-docs-linter/releases/latest/download/tech-writing-style-guide.zip
# Local Config
[formats]
erb=md
MinAlertLevel = error
[*.{md,org,txt,erb,html}]
TokenIgnores = (\*{2}(.+)\*{2})
BasedOnStyles = tech-writing-style-guide