Integration with Frameworks

GraphQL-Markdown supports multiple documentation frameworks through formatter presets. Each framework has its own setup guide, or you can create a custom formatter for any framework.

Choose a Path

Use the path that matches your documentation stack:

If you are using...	Recommended path
Docusaurus	Use the @graphql-markdown/docusaurus plugin when you want the official Docusaurus integration and default Docusaurus formatter behavior. See Docusaurus recipes for sidebar, styling, and hook recipes.
Nuxt	Use the @graphql-markdown/nuxt-theme layer (or scaffold one with npm create graphql-markdown-docs) for a full reference site — layout, navigation and search included, not just formatted Markdown. See Nuxt Theme.
Hugo, MkDocs, DocFX, mdBook, or HonKit	Use @graphql-markdown/cli with a formatter preset from @graphql-markdown/formatters. This is the main path for non-TS/JS documentation ecosystems.
Starlight, Fumadocs, or Vocs	Use @graphql-markdown/cli with the matching formatter preset when you already have one of these frameworks in place.
Any unsupported framework	Start from the closest preset or create a custom formatter module.

The quickest way to wire any supported framework is to run npm create graphql-markdown-docs@latest inside your existing site. It detects the framework, asks for your schema and output folder, and writes the configuration for you. See Add to an existing site.

For new configurations, use the formatter setting. The legacy mdxParser setting still works as a deprecated alias.

Common Setup

Install the CLI and formatter presets:

npm install @graphql-markdown/cli @graphql-markdown/formatters graphql

Then configure the formatter that matches your framework:

schema: ./schema.graphql
extensions:
  graphql-markdown:
    rootPath: ./docs
    baseURL: api
    formatter: "@graphql-markdown/formatters/hugo"

Supported Formatters

Install the formatters package:

npm install @graphql-markdown/formatters

Then select your framework:

Framework	Package	Setup
Docusaurus	@graphql-markdown/formatters/docusaurus	Guide
Astro Starlight	@graphql-markdown/formatters/starlight	Guide
Next.js + Fumadocs	@graphql-markdown/formatters/fumadocs	Guide
Vocs	@graphql-markdown/formatters/vocs	Guide
HonKit	@graphql-markdown/formatters/honkit	Guide
Hugo	@graphql-markdown/formatters/hugo	Guide
MkDocs	@graphql-markdown/formatters/mkdocs	Guide
DocFX	@graphql-markdown/formatters/docfx	Guide
mdBook	@graphql-markdown/formatters/mdbook	Guide

Quick Example

Declare the settings in your GraphQL Config file, then run the CLI:

.graphqlrc

schema: ./schema.graphql
extensions:
  graphql-markdown:
    rootPath: ./docs
    baseURL: api
    formatter: "@graphql-markdown/formatters/docusaurus" # or your framework

npx gqlmd graphql-to-doc

The command name is graphql-to-doc for the default project, and graphql-to-doc:<id> for each additional GraphQL Config project.

You can also call the generator programmatically. runGraphQLMarkdown takes the configuration as first argument, and CLI-style overrides as second argument:

import { runGraphQLMarkdown } from "@graphql-markdown/cli";

await runGraphQLMarkdown(
  {
    schema: "./schema.graphql",
    rootPath: "./docs",
    baseURL: "api",
    formatter: "@graphql-markdown/formatters/docusaurus", // or your framework
  },
  {}, // CLI flags overrides, eg `{ force: true }`
);

3rd Party Packages

Some frameworks have dedicated integration packages beyond the basic formatters:

Framework	Framework Link	Package	NPM
VitePress	vitepress.dev	graphql-markdown-vitepress	NPM

Custom MDX Formatter

For frameworks not listed above, or to customize formatting behavior, create a custom MDX module.

MDX Module Contract

A custom MDX module can export individual formatter functions:

Export	Type	Description
formatMDXBadge	(badge: { text, classname? }) => string	Format type badges (deprecated, required, etc.)
formatMDXAdmonition	(admonition: { text, title, type, icon? }, meta?) => string	Format callout/warning blocks
formatMDXBullet	(text?: string) => string	Format bullet point separators
formatMDXDetails	(option: { dataOpen, dataClose? }) => string	Format collapsible sections
formatMDXFrontmatter	(props?, formatted?: string[], context?: { entity? }) => string	Format 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) => string	Format named entity references
formatMDXPermalink	(id: string) => string	Format section header permalinks
formatMDXSpecifiedByLink	(url: string) => string	Format scalar specification links

Optional exports:

Export	Type	Description
mdxDeclaration	string	Import statements prepended to generated files
mdxExtension	string	Custom file extension (defaults to .mdx)

tip

You only need to export the formatter functions your framework requires. Any missing functions will 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 Recipes for the full reference and examples.