mdxlint

A CLI to lint and format MDX content.

Table of Contents

• Installation
• Usage
• Configuration file
  • Plugins
  • Settings
• API
  • defineConfig(config)
  • mdxlint
• Examples
  • Syntax extensions
  • Linting
  • Spell checking
  • Consistent formatting
• Prettier
• Compatibility
• Related projects
• Sponsoring
• License

Installation

npm install mdxlint

Usage

Check all .mdx files for lint violations:

mdxlint . --frail

Transform and format all .mdx files:

mdxlint . --output

For more options, see:

mdxlint --help

Configuration file

The mdxlint CLI loads one the following configuration files:

• The mdxlint key in package.json
• .mdxlintrc
• .mdxlintrc.json
• .mdxlintrc.js
• .mdxlintrc.cjs
• .mdxlintrc.mjs
• .mdxlintrc.yml
• .mdxlintrc.yaml

Ignore patterns can be specified in .mdxlintignore.

Plugins

The plugins property specifies which plugins or presets to load. All remark plugins and remark-lint rules are supported.

Settings

The settings property specifies how content is formatted. It accepts the same fields as the options from remark-stringify.

API

defineConfig(config)

A type-safe way to define a mdxlint configuration.

Arguments

• config (Config) — The configuration.

Returns

The configuration.

mdxlint

A unified processor which can process MDX content.

Examples

Syntax extensions

The following .mdxlintrc.json file adds support for GFM and frontmatter with TOML and YAML syntax.

{
  "plugins": ["remark-gfm", ["remark-frontmatter", ["toml", "yaml"]]]
}

Linting

The following .mdxlintrc.js file reports errors if link definitions or JSX attributes are not sorted.

import { defineConfig } from 'mdxlint'

export default defineConfig({
  plugins: ['remark-lint-definition-sort', 'remark-lint-mdx-jsx-attribute-sort']
})

Spell checking

The following .mdxlintrc.mjs file does spell checking based on retext plugins.

/**
 * @import { Config } from 'mdxlint'
 */

import dictionary from 'dictionary-en'
import remarkRetext from 'remark-retext'
import retextEnglish from 'retext-english'
import retextSpell from 'retext-spell'
import retextSyntaxURLs from 'retext-syntax-urls'
import { unified } from 'unified'

/** @type {Config} */
export default {
  plugins: [
    [
      remarkRetext,
      unified().use(retextEnglish).use(retextSyntaxURLs).use(retextSpell, { dictionary })
    ]
  ]
}

Consistent formatting

The following .mdxlintrc.yaml file ensures the file is always formatted, where a hyphen (-) is used for bullet lists. It also makes sure the table of contents is always up-to-date.

settings:
  bullet: '-'
plugins:
  - remark-toc
  - unified-consistency

Prettier

Unfortunately Prettier doesn’t support MDX 3. If you use Prettier, add the following to your .prettierignore:

*.mdx

Compatibility

This project is compatible with Node.js 20 or greater.

Related projects

• remark-cli can lint and format markdown content.
• eslint-plugin-mdx can check MDX files using ESLint. It can also apply remark rules via the mdx/remark rule.
• mdxlint-language-server provides a language server for mdxlint.
• vscode-mdxlint provides a Visual Studio Code extension for mdxlint.

Sponsoring

If you like this project, consider sponsoring me via GitHub Sponsors.

License

MIT © Remco Haszing