Configuration

Configuration options and config file setup for mdx-formatter

The formatter looks for configuration in three layers (later layers override earlier ones):

1. Built-in defaults (from settings.ts)

2. Config file (.mdx-formatter.json or "mdx-formatter" key in package.json)

3. Programmatic options (passed to format())

Config File

Create .mdx-formatter.json in your project root:

{
  "addEmptyLinesInBlockJsx": {
    "blockComponents": ["Outro", "InfoBox"]
  },
  "indentJsxContent": {
    "containerComponents": ["Outro", "InfoBox", "LayoutDivide"]
  },
  "formatMultiLineJsx": {
    "ignoreComponents": ["CodeBlock"]
  }
}

Or add an "mdx-formatter" key to your package.json:

{
  "mdx-formatter": {
    "addEmptyLinesInBlockJsx": {
      "blockComponents": ["Outro", "InfoBox"]
    }
  }
}

Excluding Files

You can add an exclude array to your config file to skip files matching the given glob patterns during glob discovery. These patterns are merged with the CLI --ignore option. An explicit path argument bypasses both exclude and the automatically loaded .gitignore, but remains subject to --ignore and --ignore-path.

{
  "exclude": ["doc/docs/claude/**", "generated/**/*.md"],
  "formatMultiLineJsx": {
    "ignoreComponents": ["CodeBlock"]
  }
}

This is useful for excluding auto-generated files that don't need formatting, without adding patterns to every CLI invocation.

Git-ignored paths do not need an exclude entry: automatic .gitignore discovery already skips them during glob discovery. Keep exclude for paths that are not covered by Git's ignore rules.

The filters are applied as follows:

The exclude key also works in package.json:

{
  "mdx-formatter": {
    "exclude": ["doc/docs/claude/**"]
  }
}

.gitignore Discovery

For each candidate, rules are read from the current working directory down to the candidate's own directory. A nested .gitignore is anchored to the directory that contains it: for example, generated/ in docs/.gitignore matches docs/generated/, not a similarly named directory elsewhere. Deeper .gitignore files are evaluated after shallower ones, so their rules (including ! negations) take precedence.

Discovery does not consult .gitignore files above the current working directory. If you run the CLI from packages/app, a .gitignore in the repository parent is outside the discovery scope.

Use --ignore-path <file> to supply additional .gitignore-style rules. The option is repeatable; each file is anchored to its own directory, and later files override earlier files. --no-gitignore disables only the automatic .gitignore lookup; supplied --ignore-path files and --ignore patterns still apply.

Always quote glob operands, for example "**/*.md". An unquoted shell glob such as *.md expands to real filenames before mdx-formatter sees it. Those filenames are classified as explicit paths, so they bypass exclude and automatic .gitignore rules (while --ignore and --ignore-path still apply).