This repository contains the documentation and the Vale rules for the documentation style guide.
The style guide itself is written in Markdown and contained in the en
directory.
It is published online at: docs.ubuntu.com/en/styleguide
The Vale linter operates from a series of rules. These are defined in individual YAML files, grouped into 'Styles'. This repository contains the Canonical set of rules, or the Canonical Style.
To manually check your documentation with Vale rules use the following steps:
-
Install Vale.
-
Clone this repository.
-
Run Vale with the configuration file
vale.ini
from this repository for testing your documentation source files:vale --config ~/praecepta/vale.ini ~/product/docs/
For automation, see the Canonical Style GitHub action.
Anyone is welcome to submit a PR to add additional rules. However, no additions will be considered unless they are part of the Canonical Style Guide as found at the website above.
For a reference on rule syntax, see the Vale documentation on Styles.
If you are completely new to developing Vale rules, see this introductory guide.
The Vale rules are published here so that they can be used in any workflow anywhere. You can run Vale locally, as part of CI or in a GitHub workflow - all you need is Vale, a configuration file (which you can also copy from this repository) and the Canonical Styles. Two common scenarios are also catered for more directly here, as detailed below.
This repository also includes a file, action.yml
, which is the basis of a GitHub action to automatically run Vale checks on incoming pull requests.
Your repository can make use of the action in a workflow. An example workflow is included in this repository and is demonstrated here. Note that the style guide action is merely part of a functioning workflow.
on: [pull_request]
jobs:
vale:
name: Style checker
runs-on: ubuntu-22.04
defaults:
run:
shell: bash
working-directory: .
steps:
- name: Checkout repo to runner
uses: actions/checkout@v3
- name: Install styles
uses: canonical/praecepta@main
- name: Run Vale tests
uses: errata-ai/vale-action@reviewdog
with:
files: ./docs
fail_on_error: true
In the example above, the workflow is organised as a single job. This is important as the actions rely on persistence through the run. There are three job steps:
- The github/checkout action: this fetches the code from the repo calling the workflow
- The style guide action: this fetches the styles and, if not present, a default config for Vale. The example fetches from the main branch since rules are currently under active development.
- The vale/reviewdog action: this runs Vale using reviewdog, to insert comments into a pull-request
This workflow uses reviewdog to insert output into review comments on any changes. The advantage of this method is:
- the actions only run on new material (i.e. stuff added in the current PR)
- it is surfaced directly where it will be noticed