Skip to main content

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
DocusaurusUse 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.
NuxtUse 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 HonKitUse @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 VocsUse @graphql-markdown/cli with the matching formatter preset when you already have one of these frameworks in place.
Any unsupported frameworkStart 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:

FrameworkPackageSetup
Docusaurus@graphql-markdown/formatters/docusaurusGuide
Astro Starlight@graphql-markdown/formatters/starlightGuide
Next.js + Fumadocs@graphql-markdown/formatters/fumadocsGuide
Vocs@graphql-markdown/formatters/vocsGuide
HonKit@graphql-markdown/formatters/honkitGuide
Hugo@graphql-markdown/formatters/hugoGuide
MkDocs@graphql-markdown/formatters/mkdocsGuide
DocFX@graphql-markdown/formatters/docfxGuide
mdBook@graphql-markdown/formatters/mdbookGuide

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:

FrameworkFramework LinkPackageNPM
VitePressvitepress.devgraphql-markdown-vitepressNPM

Custom formatter​

For frameworks not listed above, write your own formatter module. See Custom formatter.