Upbound relies on Vale to enforce the style guide.

Upbound’s Vale style definitions are in the utils/vale directory.

Install Vale

Follow the directions on the Vale website to install the Vale binary.

Upbound docs CI uses Vale v2.22.0 or later.

Run Vale

Run Vale on all documentation from the command-line with

vale --config="utils/vale/.vale.ini" content/

To run Vale on a single file use

vale --config="utils/vale/.vale.ini" content/contribute/writing-style-guide.md

Vale styles

Crossplane uses the following Vale styles:

• Alex - for insensitive, inconsiderate writing.
• GitLab
  • for the GitLab documentation style guide.
• Google - for the Google developer documentation style guide.
• Microsoft - for the Microsoft style guide.
• proselint - for higher quality writing.
• write-good - for higher quality writing.

Ignore Vale rules

Vale can turn off specific rules or all rules inside a doc.

All ignored rules must include a justification for why they’re ignored.

After the ignored content turn the rules back on.

Ignore all rules

Use <!-- vale off --> to ignore all Vale rules and <!-- vale on --> to turn Vale back on.

For example,

<!-- vale off -->
<!-- turn off vale checking for this example -->
The following example will use passive voice and lowercase crossplane. Do not do this.
<!-- vale on -->

Ignore specific rules

Ignore a specific rule with <!-- vale <rule name> = NO --> and turn the rule back on with <!-- vale <rule name> = YES -->.

Do not turn off rules without good reasons.

For example,

<!-- vale Microsoft.Contractions = NO -->
<!-- turn off contractions for the example -->
Do not turn off rules without good reasons.
<!-- vale Microsoft.Contractions = YES -->