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
- pnpm
- yarn
- bun
npm install @graphql-markdown/cli @graphql-markdown/formatters graphql
pnpm add @graphql-markdown/cli @graphql-markdown/formatters graphql
yarn add @graphql-markdown/cli @graphql-markdown/formatters graphql
bun add @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
- pnpm
- yarn
- bun
npm install @graphql-markdown/formatters
pnpm add @graphql-markdown/formatters
yarn add @graphql-markdown/formatters
bun add @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:
schema: ./schema.graphql
extensions:
graphql-markdown:
rootPath: ./docs
baseURL: api
formatter: "@graphql-markdown/formatters/docusaurus" # or your framework
- npm
- pnpm
- yarn
- bun
npx gqlmd graphql-to-doc
pnpm exec gqlmd graphql-to-doc
yarn gqlmd graphql-to-doc
bunx 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 formatter
For frameworks not listed above, write your own formatter module. See Custom formatter.