Markdown rules

Markdown rules check the structure and formatting of a file: headings, lists, links, images, tables, code fences, and whitespace. Recheck ports every built-in markdownlint rule and adds a few of its own. The recheck/markdown preset turns the 53 ported rules on at error.

A Markdown rule is configured under its key in the recheck block. The key of a preset rule is recheck/<rule>, and the rule's options go under the assertion of the same name:

extends:
  - recheck/markdown
recheck:
  rules:
    recheck/line-length:
      severity: warn
      assertions:
        line-length:
          lineLength: 120
          codeBlocks: false
    recheck/ul-style: off

A rule that is not in any preset is added the same way. The message is optional for a Markdown rule, because each rule has its own:

recheck:
  rules:
    recheck/list-length:
      severity: warn
      assertions:
        list-length:
          min: 2
          max: 10

The table lists each rule with its markdownlint id and whether --fix can repair it. Options are listed after the table.

These rules have no markdownlint counterpart and no preset turns them on. Add them to the recheck block by name.

The four Markdoc rules are documented with the recheck/markdoc preset.

Options go under the assertion with the rule's name. A rule not listed here has no options. An option name a rule does not recognize is ignored without a warning.

The accepted names match markdownlint's options for the rule with the same id.

With crossFile: true, the rule replaces an external link checker for links inside the repository:

• A relative link or image target must exist on disk.
• A file.md#anchor fragment must exist in the target file's headings and anchors.
• Extensionless links resolve the way the Realm router does: ./page tries page.md, and a folder link reads its index.md.
• Site-root links such as /x/y resolve against rootDir, and are skipped without it.
• Links to <details> sections resolve, with the id derived from the <summary> text when none is set.
• Markdoc tags in a heading do not change its anchor.
• External URLs and mailto: links are skipped.

recheck:
  rules:
    recheck/link-fragments:
      severity: error
      assertions:
        link-fragments:
          crossFile: true
          rootDir: docs
          ignoredTargets:
            - '/gateways/**'

The front-matter rule validates front matter against a JSON Schema with the same validator that Redocly CLI uses for API descriptions. Map file globs to schemas. The first mapping that matches a file wins, and a file that matches no mapping is not checked.

recheck:
  rules:
    recheck/front-matter:
      severity: error
      assertions:
        front-matter:
          schemas:
            - files: ['.changeset/**']
              schema:
                type: object
                patternProperties:
                  '^@redocly/': { enum: [major, minor, patch] }
                additionalProperties: false
            - files: ['docs/**']
              schema: realm
              strict: true

Each mapping takes these keys:

A file with no front matter validates as an empty object, so the schema's required list decides whether front matter is mandatory. Each finding points at the line of the offending top-level key. Front matter that is not valid YAML is one finding at the start of the block.

The built-in realm schema checks the type of every front matter option that a Realm page accepts, such as title, description, slug, sidebar, excludeFromSearch, and the options that override redocly.yaml on one page. It does not check the inner shape of those option objects, because Realm evolves them independently. strict is off by default, because pages often carry their own keys that Markdoc templates read back through $frontmatter.