Skip to main content

Custom formatter

Use a custom formatter module for frameworks without a preset, or to change how a preset renders pages. It exports the formatter functions below and falls back to the defaults for the rest.

MDX module contract​

A custom MDX module can export individual formatter functions:

ExportTypeDescription
formatMDXBadge(badge: { text, classname? }) => stringFormat type badges (deprecated, required, etc.)
formatMDXAdmonition(admonition: { text, title, type, icon? }, meta?) => stringFormat callout/warning blocks
formatMDXBullet(text?: string) => stringFormat bullet point separators
formatMDXDetails(option: { dataOpen, dataClose? }) => stringFormat collapsible sections
formatMDXFrontmatter(props?, formatted?: string[], context?: { entity? }) => stringFormat page frontmatter; context.entity is the page's entity kind (e.g. objects, queries)
formatMDXLink(link: { text, url }) => { text, url }Transform type links
formatMDXNameEntity(name: string, parentType?: string) => stringFormat named entity references
formatMDXPermalink(id: string) => stringFormat section header permalinks
formatMDXSpecifiedByLink(url: string) => stringFormat scalar specification links. Receives an absolute http(s) URL; encode it for where you write it (for example as an HTML attribute)
formatMDXTitle(title: string) => stringOptional: format a visible page title printed after the frontmatter (e.g. # Title), for frameworks that do not render the frontmatter title

Optional exports:

ExportTypeDescription
mdxDeclarationstringImport statements prepended to generated files
mdxExtensionstringCustom file extension (defaults to .mdx)

You only need to export the formatter functions your framework requires. Any missing functions use the default HTML-like implementation.

formatMDXDetails contract​

The string returned by formatMDXDetails must contain a single \r (carriage return) character as a delimiter between the opening and closing parts. The printer splits on "\r" to wrap content, so reserve \r only for that separator and use \n for line breaks.

// ✅ correct — use \n for line breaks and a single standalone \r as the delimiter
export const formatMDXDetails = ({ dataOpen }) =>
`\n\n<MyDetails label="${dataOpen}">\n\r</MyDetails>\n\n`;

// ❌ incorrect — no \r means the closing tag is lost
export const formatMDXDetails = ({ dataOpen }) =>
`\n\n<MyDetails label="${dataOpen}">\n</MyDetails>\n\n`;

// ❌ incorrect — CRLF introduces extra \r characters
export const formatMDXDetails = ({ dataOpen }) =>
`\r\n\r\n<MyDetails label="${dataOpen}">\r\n\r</MyDetails>\r\n\r\n`;

Extending a preset​

To customize a preset, spread its exports and override specific formatters:

// src/modules/custom-mdx.cjs
const PresetMDX = require("@graphql-markdown/formatters/starlight");

const formatMDXBadge = ({ text, classname }) => {
// Your custom logic
return `<Badge>${text}</Badge>`;
};

module.exports = {
...PresetMDX,
formatMDXBadge,
};

Lifecycle hooks​

Custom MDX modules can also export lifecycle hooks to customize the generation process. See Hooks for the full reference and examples.