bluepencil

A zero-config prose quality gate for technical documentation.

bluepencil checks Markdown prose as a copy editor does: it flags sentences that run too long, passive sentences, and contractions. It also flags terms that have a preferred option. An optional dictionary profile restricts documents to an approved word list, in the style of simplified technical English. It runs on a pinned Vale engine that bluepencil downloads, verifies, and caches automatically — no setup other than the command.

Usage

bunx @shift-labs/bluepencil

By default bluepencil lints README.md and docs/**/*.md in the work directory with the style profile. Give a different target and limit the patterns when necessary:

bluepencil path/to/repo 'guides/**/*.md'

The report shows findings for each file and quotes the applicable text:

README.md
  12:8    error   sentence-length
          Use no more than 25 words in a descriptive sentence.
  14:3    warning passive-voice
          Use the active voice when the agent is known.
          “was written”

1 error, 1 warning in 1 file.

The exit code is 0 when there are no errors, 1 when errors exist, and 2 when the run fails.

Profiles

• style (default) — sentence-length limits, passive voice, contractions, and preferred terms. No dictionary.
• ste — all the style checks, plus an approved-word dictionary: each word must be in the built-in word list or one of your word lists.

Select a profile with --profile ste or in the configuration file.

Documents that match a procedural pattern (skills/**/*.md, **/SKILL.md, and runbooks/**/*.md by default) have a 20-word sentence limit, not the descriptive 25.

Configuration

Add .bluepencil.json to the target repository:

{
  "profile": "ste",
  "files": ["README.md", "manual/**/*.md"],
  "procedural": ["manual/procedures/**/*.md"],
  "wordlists": ["terms/domain-words.txt"],
  "vocabularies": ["terms/product-names.txt"],
  "profiles": {
    "maintenance": {
      "extends": "ste",
      "wordlists": ["terms/maintenance.txt"]
    }
  }
}

• wordlists extend the approved-word dictionary with words from your domain.
• vocabularies list always-accepted terms, such as product names.
• profiles define named profiles that extend a built-in one; select them with --profile <name>.

Each option is also available as a CLI flag (--profile, --procedural, --wordlist, --vocabulary); flags override the configuration file.

Continuous integration

- uses: shift-labs-ai/bluepencil@v1
  with:
    profile: style

Or run the CLI directly: bunx @shift-labs/bluepencil . --no-color.

The word list

The ste profile ships with a built-in list of approximately 1,300 approved words derived from simplified-technical-English usage, and layers your wordlists and vocabularies on top. The dictionary check is strict: it exists for documentation that must stay in a controlled vocabulary, such as operational runbooks and maintenance procedures. For general documentation, the style profile is the recommended default.

Development

bun install
bun run verify   # biome, typecheck, tests

The test suite covers profile resolution, dictionary layering, and end-to-end lint runs against fixtures.

License

MIT