liveBook · Manning

Vale

As explained in Automating API Delivery

Vale is a configurable prose linter that checks documents against language style guides and supports formats including Markdown, AsciiDoc, and reStructuredText.

Vale is a fast, configurable prose linter for checking documentation against language, style, tone, and branding guidance. It detects issues such as punctuation, spelling, grammar, redundancy, jargon, clichés, and unidiomatic vocabulary. It supports Markdown, AsciiDoc, and reStructuredText, and can run from the command line or an editor plugin. section 8.10

Use Vale to govern API guide documentation through version-controlled delivery workflows:

  • Store Markdown API guides in the project source repository so prose checks can run in the delivery pipeline. section 8.10
  • Configure .vale.ini with a styles path, alert threshold, and selected style packages or rules. section 8.5.5
  • Run Vale as a pull-request check alongside API linting, breaking-change checks, and other governance controls. section 8.14
  • Treat lint results as editorial feedback rather than a replacement for design review or consumer-focused judgment. section 8.10
StylesPath = ./../.github/styles       #1
MinAlertLevel = suggestion                 #2

Packages = Microsoft      #3

[*.md]                             #4
BasedOnStyles = Vale, Microsoft     #5

This configuration selects the styles directory, reports suggestions and higher-severity alerts, downloads the Microsoft package, and applies Vale and Microsoft rules to Markdown files. section 8.5.5

Run Vale in a pull request

Install the pinned Vale release, add it to PATH, synchronize configured packages with `vale sync --config='pr-branch/chapter8/.vale.ini'`, and lint the documentation directory with `vale pr-branch/chapter8/apis/docs --config='pr-branch/chapter8/.vale.ini'`. The workflow logs the resulting prose-linting status. section 8.5.5

      - name: Prose Linting
        run: | 
          wget -nv 
 https://github.com/errata-ai/vale/releases/download/v2.15.4/
 vale_2.15.4_Linux_64-bit.tar.gz
          mkdir bin && tar -xvzf vale_2.15.4_Linux_64-bit.tar.gz -C bin
          export PATH=./bin:"$PATH"
          cd pr-branch/chapter8
          vale sync --config=
 'pr-branch/chapter8/.vale.ini'       #1
          vale pr-branch/chapter8/apis/docs 
 --config='pr-branch/chapter8/.vale.ini'      #2

This pipeline step downloads Vale, installs the executable, synchronizes its configuration, and checks API guide files during a pull-request build. section 8.5.5

How Automating API Delivery covers it

How deep it goes
Defines configuration and CI execution steps, but does not detail individual style rules or lint diagnostics.
Examples
Uses Markdown API guides, a .vale.ini file, the Microsoft style package, and a pull-request command-line workflow.
What it assumes
Assumes version-controlled documentation and basic command-line workflow knowledge while leaving style rules configurable.
What you can do after
Operate/configure it to lint API documentation locally or in a pull-request build against selected editorial styles.
How it connects
Connects prose linting with API linting, breaking-change checks, version control, pull requests, and editorial style guides.
Cover of Automating API Delivery
liveBookmanning.com
Read Automating API Delivery on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Automating API Delivery. The section links point to the parts of the book it draws on.