GraphQL-Markdown

Generate Markdown and MDX documentation from GraphQL schemas for Nuxt, Docusaurus and other supported documentation ecosystems.

Installation

Run the scaffolder in an empty folder to create a new project, or inside an existing documentation site to add GraphQL-Markdown to it:

npm create graphql-markdown-docs@latest

New projects can be a Nuxt site (default), a Docusaurus site, or plain Markdown or MDX output with no site (--framework markdown or --framework mdx). In an existing site, the scaffolder detects the framework and writes a .graphqlrc and a gqlmd script. See the Getting started guide for options.

To set it up by hand instead, there are two main setup paths:

• use the official Docusaurus integration for Docusaurus sites
• use the CLI with formatter presets for other supported ecosystems such as Starlight, Fumadocs, Vocs, Hugo, MkDocs, DocFX, mdBook and HonKit, or the generic mdx preset for any MDX-based site

Choose your preferred package based on your documentation stack:

# For Docusaurus sites
npm install @graphql-markdown/docusaurus graphql

# For formatter-based setups
npm install @graphql-markdown/cli @graphql-markdown/formatters graphql

Usage

Docusaurus Plugin

Add to your docusaurus.config.js:

module.exports = {
  plugins: ["@graphql-markdown/docusaurus"],
};

Run the generation command:

npx docusaurus graphql-to-doc

CLI Usage

Use the CLI directly for custom workflows, or pair it with @graphql-markdown/formatters to adapt the generated output for supported frameworks.

npx gqlmd graphql-to-doc --schema ./schema.graphql --root ./docs

For formatter-based setups:

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

API Usage

For programmatic usage, you can use the CLI package:

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

const config = {
  schema: "./schema.graphql",
  rootPath: "./docs",
};

await runGraphQLMarkdown(config);

See API documentation and our Framework Integration page for the full list of supported formatter presets.

Configuration

See documentation configuration page.

Troubleshooting

See documentation troubleshooting page.

Showcase

Used in production by 30+ teams including Saleor, Sui, Mozilla, IOTA, Swan, Sablier, and Browserless.

View the full showcase · Add your site

License

GraphQL-Markdown packages are 100% free and open-source, under the MIT license.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Contributions

Contributions, issues and feature requests are very welcome. If you are using this package and fixed a bug for yourself, please consider submitting a PR!