Nuxt theme
@graphql-markdown/nuxt-theme is a Nuxt layer that turns a GraphQL schema into a full API reference site. It provides a two-column layout (prose on the left, schema definitions and examples on the right), navigation, search, and generation.
Extend it from your own Nuxt project instead of building on the CLI's raw Markdown output. This is the recommended path for a Nuxt stack; see Integration with frameworks for the others.
Fastest path: the scaffolding CLI
- npm
- pnpm
- yarn
- bun
npm create graphql-markdown-docs@latest
pnpm create graphql-markdown-docs
yarn create graphql-markdown-docs
bun create graphql-markdown-docs
It asks a few questions (project directory, schema source, package manager, optional title and color) and produces a ready-to-run project. See Getting started for the full prompt and flag reference, including non-interactive usage, or the create-graphql-markdown-docs README.
Extending the layer directly
- npm
- pnpm
- yarn
- bun
npm install @graphql-markdown/nuxt-theme
pnpm add @graphql-markdown/nuxt-theme
yarn add @graphql-markdown/nuxt-theme
bun add @graphql-markdown/nuxt-theme
// nuxt.config.ts
export default defineNuxtConfig({
extends: ["@graphql-markdown/nuxt-theme"],
});
Two files are required in your own project — not inherited from the layer:
// content.config.ts
import { defineContentConfig, defineCollection } from "@nuxt/content";
export default defineContentConfig({
collections: {
content: defineCollection({
type: "page",
source: "api-reference/**/*.md",
}),
},
});
// generate-docs.ts
import { createGenerateDocs } from "@graphql-markdown/nuxt-theme/generate";
export const generate = createGenerateDocs({
schema: "./schema/your-schema.graphql",
});
content.config.ts has to live in your own project. Nuxt Content scopes each layer's content.config.ts to that layer's directory, so a collection declared only in the theme would never see the files your project generates.
generate-docs.ts is invoked automatically by the layer's Nuxt module, before Nuxt Content indexes the directory. So npm run dev, generate and build all work from a fresh clone with nothing generated yet. You don't need a build:before hook of your own.
Passing schema loading options
createGenerateDocs accepts the same printTypeOptions, decorators, and loaders you'd pass to runGraphQLMarkdown. The schema can be a local file, a URL, or anything a graphql-tools loader can read:
export const generate = createGenerateDocs({
schema: "https://api.example.com/graphql",
loaders: { UrlLoader: "@graphql-tools/url-loader" },
});
Customizing
- Config and CSS — site title, GitHub link, Shiki theme, and a set of
--gqlmd-*CSS custom properties for badge/callout/sidebar styling. No file copying, survives layer upgrades. - Swizzling — for changes config can't reach (different markup, a different component entirely), eject a single component into your own project with the bundled
gqlmd-swizzleCLI. The ejected copy is version-stamped so you can tell when it's drifted from a newer layer release.
Both are documented in full, with every config key and CSS property listed, in @graphql-markdown/nuxt-theme's own README.
What's fixed, not configurable, in this version
- The content collection is always named
content, and generated pages always live underapi-reference/, because the navigation and search UI assume this path. - Multiple schemas on one site aren't supported by the navigation yet, even though
generate-docs.tscan callcreateGenerateDocsmore than once. - The reference page's code-column extraction assumes graphql-markdown's default section/heading structure — unusual
decorators/customSectionspositions can render into the wrong place.