Options

All configurable options for mdx-formatter

Every option can be set via config file or programmatic API. Each rule has an enabled flag that can be toggled independently.

Full Configuration Example

{
  "exclude": ["generated/**"],
  "addEmptyLineBetweenElements": {
    "enabled": true
  },
  "formatMultiLineJsx": {
    "enabled": true,
    "indentSize": 2,
    "ignoreComponents": ["CodeBlock"],
    "preserveTemplateLiteralIndent": true
  },
  "formatHtmlBlocksInMdx": {
    "enabled": true,
    "formatterConfig": {
      "parser": "html",
      "tabWidth": 2,
      "useTabs": false
    }
  },
  "expandSingleLineJsx": {
    "enabled": false,
    "propsThreshold": 2
  },
  "indentJsxContent": {
    "enabled": false,
    "indentSize": 2,
    "containerComponents": []
  },
  "addEmptyLinesInBlockJsx": {
    "enabled": true,
    "blockComponents": ["Outro", "InfoBox"]
  },
  "formatYamlFrontmatter": {
    "enabled": true,
    "indent": 2,
    "lineWidth": 100,
    "quotingType": "\"",
    "forceQuotes": false,
    "noCompatMode": true,
    "fixUnsafeValues": true
  },
  "preserveAdmonitions": {
    "enabled": true
  },
  "autoDetectIndent": {
    "enabled": false,
    "fallbackIndentSize": 2,
    "fallbackIndentType": "space",
    "minConfidence": 0.7
  },
  "errorHandling": {
    "throwOnError": false
  },

  "tighten-list-continuations": "heuristic",
  "tighten-list-item-spacing": "heuristic",
  "recover-escaped-code-in-lists": "safe",
  "recover-escaped-tables-in-lists": "safe",
  "recover-escaped-paragraphs-in-lists": "off"
}

The last five keys above are the List Normalize rules. Unlike the nested object options above, they are exposed as flat top-level kebab-case string enums.

List Normalize

Five rules that clean up AI-authored list-item content. Each accepts "off" to disable. The middle value ("heuristic" / "safe") is the conservative trigger; "aggressive" drops structural preconditions.

Key	Default	Purpose
`tighten-list-continuations`	`"heuristic"`	Collapse blank lines inside a list item whose children are continuation paragraphs.
`tighten-list-item-spacing`	`"heuristic"`	Collapse a single blank line between adjacent sibling list items when the list is safe to tighten.
`recover-escaped-code-in-lists`	`"safe"`	Re-indent a fenced code block that escaped to column 0 between two list items.
`recover-escaped-tables-in-lists`	`"safe"`	Re-indent a GFM table that escaped to column 0 between two list items.
`recover-escaped-paragraphs-in-lists`	`"off"`	Re-indent a paragraph that escaped to column 0 between two list items (opt-in — highest false-positive risk).

Use --dry-run to preview what each rule would change before committing.