Prose rules

A prose rule checks the words of a document rather than its Markdown syntax. You write one in the recheck block from three parts: a scope that selects the text, an assertion that checks it, and a message that explains the finding.

recheck:
  rules:
    recheck/no-gerund-headings:
      severity: warn
      scope: heading
      message: 'Do not start a heading with a gerund.'
      link: https://example.com/style-guide#headings
      assertions:
        pattern:
          ignoreCase: true
          tokens:
            - '^\w+ing\b'

This page lists every scope and every assertion with its options. The recheck configuration reference lists the other keys of a rule, such as appliesTo, excludes, and exceptions.

A rule key is <namespace>/<name>, in lowercase, for example recheck/us-spelling or acme/product-names. The presets use their own namespaces, such as google/, so your keys never collide with theirs. The report prints the key without the recheck/ prefix.

A prose rule needs a message. The message can hold %s placeholders, which the assertion fills in order. Each assertion lists what it fills. Most assertions fill two values; length fills three and metric fills four. A message with more placeholders than the assertion fills is a configuration error.

The scope key selects which parts of a file the rule reads. The default is all.

A list of scopes selects all of them:

scope:
  - heading.h1
  - heading.h2

A selector narrows a scope: ~ excludes a scope, and & joins conditions. For example, '~blockquote & ~heading' selects everything except blockquotes and headings. all and raw cover the whole file, so they cannot be combined with another scope.

Prose scopes never include inline code, and when Markdoc parsing is on, they do not include the tag syntax either. Set includeCode: true on swap, pattern, repetition, or consistency to match inside inline code.

Each rule has one or more assertions under assertions, keyed by assertion id. The Markdown rules are also assertions, keyed by rule name, and a rule can combine both kinds.

Reports a word or phrase and suggests a replacement. With --fix, each match is replaced, and the match's own casing is applied to the replacement: a capitalized match gets a capitalized replacement, and an all-caps match gets an all-caps replacement. When two pairs match overlapping text, the longest match wins.

assertions:
  swap:
    ignoreCase: true
    wordBoundary: true
    pairs:
      utilize: use
      in order to: to

Message placeholders: the replacement, then the matched text. With the pair utilize: use, the message 'Use "%s" instead of "%s".' prints Use "use" instead of "utilize".

Reports each match of a regex.

assertions:
  pattern:
    ignoreCase: true
    tokens:
      - '\bvery\b'
      - '\breally\b'

Message placeholders: the matched text.

Counts the matches of a regex in each segment and reports the segment when the count is outside min and max. min: 1 without max requires the pattern to be present.

scope: paragraph
assertions:
  occurrence:
    pattern: '[.!?]'
    max: 3

Message placeholders: the match count, then the bound that was crossed.

Reports an adjacent repeated word, such as "the the", including across a line break. With --fix, the pair collapses to the first word.

assertions:
  repetition: {}

Message placeholders: the repeated word.

Each entry of either names two variants. The variant that appears first in a file wins, and later uses of the other variant are reported. With --fix, they are replaced with the winning variant as written in either.

assertions:
  consistency:
    ignoreCase: true
    either:
      behavior: behaviour
      color: colour

Message placeholders: the later variant, then the variant that appeared first.

If first matches in the rule's scope, second must match somewhere in the whole file, code blocks included. Otherwise each first match is reported.

assertions:
  conditional:
    first: '\bTBD\b'
    second: 'https://github\.com/\S+/issues/\d+'

Message placeholders: the first match, then the second pattern.

Reports a segment whose casing does not match the required style.

scope: heading
assertions:
  capitalization:
    match: $sentence
    exceptions: [Redocly, Reunite]

• $title capitalizes every word except articles, conjunctions, and prepositions. ap lowercases prepositions of three letters or fewer; chicago lowercases every preposition. The first and last words are always capitalized.
• $sentence capitalizes the first word and lowercases the rest, except exceptions and words in all caps.
• $lower and $upper require the whole segment in that case.
• A regex must match the whole segment. This mode is detection-only.

Words in all caps, such as API, and inline code are never changed. --fix rewrites a single-line segment for the four $ styles. A segment that spans several lines is skipped.

Message placeholders: the segment text, then the match value.

Measures each segment in the rule's scope and reports it when the size is outside min and max.

scope: sentence
assertions:
  length:
    unit: words
    max: 25

Message placeholders: the measured size, the unit, then the bound that was crossed.

Scores the prose of the whole document with a readability formula and reports the file once, at line 1, when the score is outside min and max. The score reads the same prose as redocly recheck --readability: headings, code, front matter, and Markdoc tags do not count. A file with no prose is never reported.

assertions:
  metric:
    formula: flesch-reading-ease
    min: 30

The assertion always reads the summary scope. Setting another scope prints a warning and has no effect.

Message placeholders: the formula, the score, min, then max.

Reports words that a Hunspell dictionary does not recognize, with up to three suggestions. The English dictionary ships with Redocly CLI.

scope: summary
assertions:
  spelling:
    vocab: [Redocly, Reunite]
    ignore: ['\bAcme\w*']

Words in all caps and words next to a digit, such as utf8, are not checked. Inline code is never checked.

Message placeholders: the unknown word, then a suggestion suffix in the form — did you mean: world?, or an empty string when there is no suggestion.

Requires one sentence, or one phrase, per line. With --fix, long lines are split after each sentence, and list item continuation lines are indented under the item text.

assertions:
  semantic-line-breaks:
    mode: sentence

Reports an image whose file is larger than the limit. The image path is resolved from the Markdown file and must stay inside the folder passed to the command.

assertions:
  max-image-size:
    maxSizeKB: 200

The capitalization and spelling assertions share a list of technical proper nouns, such as OpenAPI, GraphQL, npm, Node.js, VS Code, and Kubernetes. It saves every project from listing the same names. capitalization keeps them cased as written, and spelling accepts them as words. Set builtinVocabulary: false on a rule to use only its own exceptions or vocab.

The list leaves out words that are also ordinary English, such as Chrome or Windows, because an exception for them would weaken the check. Add names like that in the rule's own exceptions or vocab. The list is exported as TECHNICAL_PROPER_NOUNS from the @redocly/recheck package.

recheck:
  rules:
    recheck/us-spelling:
      severity: error
      scope: summary
      message: 'Use the US spelling "%s" instead of "%s".'
      assertions:
        swap:
          ignoreCase: true
          wordBoundary: true
          pairs:
            colour: color
            behaviour: behavior
            organise: organize

recheck:
  rules:
    acme/sentence-length:
      severity: warn
      scope: sentence
      message: 'Sentence is %s %s long; keep it under %s.'
      assertions:
        length:
          unit: words
          max: 25
      exceptions:
        files:
          - docs/legal/**

recheck:
  rules:
    acme/readability-floor:
      severity: warn
      message: 'Readability (%s) is %s; expected between %s and %s.'
      appliesTo:
        - docs/guides/**
      assertions:
        metric:
          formula: flesch-reading-ease
          min: 40