@mastra/lint-docs

A collection of linting tools for Mastra's documentation sites. This package contains:

• /check-duplicate-redirects: A checker for duplicate or invalid redirect sources
• /check-frontmatter: A checker for required MDX frontmatter fields
• /oxfmt-mdx: An Oxfmt-powered formatter for MDX JSX expressions and fenced code blocks
• /prettier-mdx: A Prettier plugin to correctly format code blocks in MDX files
• /remark-preset: A preset of remark plugins to lint MDX files for common issues and style consistency

Installation

npm install @mastra/lint-docs

Usage

Check duplicate redirects

Use the CLI with a redirects JSON file. The file can be either a plain redirects array or an object with a redirects array.

check-duplicate-redirects ./redirects.json

You can also use the subpath programmatically:

import { checkDuplicateRedirects } from '@mastra/lint-docs/check-duplicate-redirects'

const result = await checkDuplicateRedirects('./redirects.json')

if (!result.ok) {
	console.error(result.messages.join('\n'))
}

Check frontmatter

Use the CLI with a docs directory. It recursively checks *.mdx files for required frontmatter fields and validates package names.

check-frontmatter ./src/content

Skip paths with repeatable --skip flags. Paths are relative to the docs directory and can target exact files or directory prefixes.

check-frontmatter ./src/content --skip kitchen-sink/ --skip reference/index.mdx

You can also use the subpath programmatically:

import { checkFrontmatter } from '@mastra/lint-docs/check-frontmatter'

const result = await checkFrontmatter('./src/content', {
	skipPaths: ['kitchen-sink/', 'reference/index.mdx'],
})

if (!result.ok) {
	console.error(result.messages.join('\n'))
}

Oxfmt MDX

Oxfmt does not expose a custom MDX plugin API, so this package provides an oxfmt-mdx CLI that applies the repository's Oxfmt options to JSX expressions and fenced code blocks before serializing the MDX.

oxfmt-mdx --write ./src/content
oxfmt-mdx --check ./src/content

The CLI searches parent directories for .oxfmtrc.json. You can also use the formatter programmatically:

import { formatMdx } from '@mastra/lint-docs/oxfmt-mdx'

const formatted = await formatMdx(source, {
	semi: false,
	singleQuote: true,
})

Set formatCodeBlocks: false to disable fenced code-block formatting, or add oxfmt: false to an individual code fence's metadata.

Prettier MDX

The original Prettier plugin remains available for projects that still use Prettier:

{
	"plugins": ["@mastra/lint-docs/prettier-mdx"],
	"overrides": [
		{
			"files": ["*.mdx"],
			"options": {
				"parser": "mdx-custom"
			}
		}
	]
}

remark preset

import remarkPresetMastra from '@mastra/lint-docs/remark-preset'

const config = {
	plugins: [remarkPresetMastra],
}

export default config