.markdownlint-cli2.jsonc

{
  // Markdown linting for the prose in this repository: the READMEs, the
  // security policy and the documentation site's content collection.
  //
  // Everything below is markdownlint's default rule set. The handful of
  // settings here either match a convention the files already follow or turn
  // off a check that is measuring the wrong thing for this repository, and
  // each one says which.
  "config": {
    "default": true,

    // The prose here wraps at 100 columns, not markdownlint's default 80.
    // Code samples and tables are exempt because breaking either to fit a
    // column limit makes them worse: a wrapped line of TypeScript no longer
    // runs, and a wrapped table cell stops being a table.
    "MD013": {
      "line_length": 100,
      "code_blocks": false,
      "tables": false
    },

    // Tabs are wrong in prose and correct in the code samples that use them,
    // which includes every sample copied out of a file that is itself
    // tab-indented.
    "MD010": {
      "code_blocks": false
    },

    // The docs site takes each page's title from `title` in the frontmatter
    // and renders it as the h1, so a document that opens with an h1 of its own
    // would render two. markdownlint's own frontmatter-title escape hatch
    // covers this, and is the default, but is stated here because the reason
    // is not obvious from the outside.
    "MD041": {
      "front_matter_title": "^\\s*title\\s*[:=]"
    },

    // Headings in this documentation are sentences and are punctuated as
    // sentences. A question mark or a full stop at the end of one is a
    // deliberate choice, not a stray character; a trailing colon still is
    // not, so the rule keeps working on those.
    // The tables in these files were already written aligned, and aligned is
    // what a table should be in a plain-text diff: the columns are the point.
    // `scripts/align-markdown-tables.mjs` does the padding, since markdownlint
    // can only report this one, not repair it.
    "MD060": {
      "style": "aligned"
    },

    "MD026": {
      "punctuation": ",;:"
    }
  },

  // Prose only. See the ignores for what is deliberately out of scope.
  "globs": [
    "**/*.md",

    // Generated by changesets on release, and rewritten wholesale each time.
    "!**/CHANGELOG.md",

    // Changeset fragments. Also generated, and intentionally headingless.
    "!.changeset/*.md",

    // Agent prompts rather than documentation. They are structured with XML
    // tags on purpose, which is exactly what MD033 exists to catch.
    "!.opencode/**/*.md",
    "!.github/**/*.md",

    "!**/node_modules/**",
    "!**/dist/**"
  ],

  // `.mdx` is deliberately absent from the globs above. markdownlint has no
  // MDX parser, so it reads JSX components as raw HTML and reports every
  // `<Card>` as inline HTML, and it mistakes the fenced blocks nested inside
  // a component for unlabelled top-level ones. The findings would be noise
  // and the fixes would be wrong. `astro check` covers those files instead.
  "customRules": ["./scripts/markdownlint-no-code-after-heading.mjs"],

  "outputFormatters": [["markdownlint-cli2-formatter-default"]]
}