API Reference

CLI options and programmatic API reference for mdx-formatter

CLI Options

The --ignore patterns are merged with exclude patterns from the config file for glob matches. Explicit path arguments bypass exclude and automatically loaded .gitignore rules, but --ignore and --ignore-path still apply. See .gitignore discovery for nested-rule and cwd details.

Ignore-file options

Supply your own .gitignore-style rules with --ignore-path:

# .ci/mdx-ignore contains rules such as: generated/
mdx-formatter --check "**/*.mdx" --ignore-path .ci/mdx-ignore

# Multiple files are allowed; later files override earlier files.
mdx-formatter --check "**/*.mdx" \
  --ignore-path .ci/base-ignore \
  --ignore-path .ci/local-ignore

To include files that automatic .gitignore discovery would skip, disable it for that invocation:

mdx-formatter --check "**/*.mdx" --no-gitignore

--no-gitignore affects only automatically discovered files; explicit --ignore-path files and --ignore patterns remain active. Quote glob operands: an unquoted shell glob such as *.md is expanded into explicit filenames before the CLI sees it, so exclude and automatic .gitignore rules do not apply to those paths.

format(content, options?)

Format markdown/MDX content.

• content (string) - Content to format

• options.config (string) - Path to config file

• options.settings (object) - Direct settings overrides (see Options Reference)

• Returns Promise<string> - Formatted content (returns original on error)

The exclude config option is CLI-only. When using the programmatic API (format, formatFile, checkFile), handle file filtering in your own code.

formatFile(filePath, options?)

Format a file and write it back if changed.

• filePath (string) - Path to the file

• options - Same as format()

• Returns Promise<boolean> - true if file was changed

checkFile(filePath, options?)

Check if a file needs formatting without modifying it.

• filePath (string) - Path to the file

• options - Same as format()

• Returns Promise<boolean> - true if file needs formatting

formatSync(content)

Synchronous format with default settings. API-compatible with @takazudo/mdx-formatter-wasm's format_with_defaults(). Useful for mocking the WASM module in Node.js test environments.

• content (string) - Content to format

• Returns string - Formatted content

import { formatSync } from "@takazudo/mdx-formatter";

const formatted = formatSync("# Hello\nSome text");

Test mock example

vi.mock("@takazudo/mdx-formatter-wasm", async () => {
  const { formatSync } = await import("@takazudo/mdx-formatter");
  return {
    default: async () => {},
    format_with_defaults: formatSync,
  };
});

detectMdx(content)

Check if content is likely MDX (has imports, exports, JSX components, or frontmatter).

• content (string) - Content to check

• Returns boolean