Getting started
The fastest way to start is the create-graphql-markdown-docs scaffolder, which creates a ready-to-run Nuxt or Docusaurus site, or adds GraphQL-Markdown to an existing site. Or try it right away with one of our demos.
Create a new site
Requirements
Node.js version 22.12 or above (which can be checked by running node -v) is required.
You can use either npm, yarn, pnpm or bun as your package manager. The examples in this documentation use npm, but you can substitute the commands with your preferred package manager.
When installing Node.js, you are recommended to check all checkboxes related to dependencies.
You can use nvm, installed on a single machine, to manage multiple Node.js versions.
Run the scaffolder
You can type these commands into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
npm create graphql-markdown-docs@latest
pnpm create graphql-markdown-docs
yarn create graphql-markdown-docs
bun create graphql-markdown-docs
Pass the project directory as an argument to skip that prompt:
npm create graphql-markdown-docs@latest my-docs
With npm, flags must follow a -- separator so that npm forwards them to the CLI:
npm create graphql-markdown-docs@latest my-docs -- --framework docusaurus
What the prompts ask
- Framework: Nuxt (default) or Docusaurus.
- Directory: press Enter to accept
my-graphql-docs. The directory must not exist yet or must be empty; a non-empty directory is rejected and you are asked again. - Schema: use the bundled example, or your own (local file, introspection URL,
git:orgithub:reference). The matching loader is detected and added as a dependency. - Package manager: detected from the command you used (
pnpm create,yarn create,bun create,npm create), then from lockfiles. You are only asked if detection fails. - Title (optional), and a primary color for Nuxt.
- Install dependencies.
- Git repository: initialized unless the project is already inside one.
Choose a framework
- Nuxt (default): a full API reference site built on the
@graphql-markdown/nuxt-themelayer, with live reload when the schema changes. - Docusaurus: a classic Docusaurus site configured with the
@graphql-markdown/docusaurusplugin.
See Nuxt Theme for what the Nuxt layer provides.
Use your own schema
A schema loader is required to load your GraphQL schema. Without --schema, the site uses a bundled example schema. Pass --schema <path-or-url> (or answer the prompt) to use your own: the CLI picks the matching graphql-tools loader, adds it as a dependency, and writes it into the site configuration (.graphqlrc for Docusaurus, generate-docs.ts for Nuxt).
| Schema source | Example | Loader added |
|---|---|---|
Local .graphql/.gql file | ./schema/api.graphql | None (default loader) |
Local .json introspection result | ./introspection.json | @graphql-tools/json-file-loader |
| Local code-first schema | ./schema.ts | @graphql-tools/code-file-loader |
| Introspection/SDL endpoint | https://api.example.com/graphql | @graphql-tools/url-loader |
| Git-hosted file | git:branch:path/schema.graphql | @graphql-tools/git-loader |
| GitHub-hosted file | github:owner/repo#branch:path/schema.graphql | @graphql-tools/github-loader |
github: sources call the GitHub API and need a token: set the GITHUB_TOKEN environment variable before generating the docs (the scaffolded config reads it).
A local SDL/JSON file is copied into the scaffolded project's schema/ directory; a remote source is referenced as-is. Local code-first schemas are referenced in place rather than copied, so their imports keep working.
See schema loading for other loaders and configuration options.
Start your site
For a Nuxt site:
cd my-graphql-docs
npm run dev
The development server is available at http://localhost:3000/.
For a Docusaurus site:
cd my-graphql-docs
npm run doc
npm run start
If you skipped the install step, run npm install first.
The npm run doc command is a shortcut in the scaffolded Docusaurus site for command-line document generation: npm run docusaurus graphql-to-doc.
The npm run start command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
Non-interactive usage (CI)
Use --yes to accept all defaults and skip every prompt:
npm create graphql-markdown-docs@latest -- --yes --dir ./my-docs --schema ./schema.graphql --no-install --no-git
| Flag | Description |
|---|---|
--framework <nuxt|docusaurus> | Framework preset. Default nuxt. |
[dir], -d, --dir <path> | Project directory, as the first argument or via --dir (--dir wins). Default my-graphql-docs. Must be a directory that doesn't exist yet or is empty (an existing empty directory, including ., is scaffolded in place); the CLI exits with an error if it is a file or not empty. |
--schema <path-or-url> | Schema source, see the table above. A local path must point to an existing file; the CLI exits with an error otherwise. |
--example | Use the bundled example schema (the default when --schema is omitted). |
--pm <npm|pnpm|yarn|bun> | Package manager to use; otherwise detected from the invoking command, then from lockfiles. |
--title <name> | Site title. |
--color <name> | Nuxt only. Primary color, any Nuxt UI / Tailwind color name (e.g. violet, emerald). |
--no-install | Skip dependency installation. |
--no-git | Skip git repository initialization. |
-y, --yes | Accept all defaults; fully non-interactive. |
-h, --help | Show usage and exit. |
-v, --version | Print the CLI version and exit. |
Add to an existing site
With the scaffolder (recommended)
Run the scaffolder inside your existing project. When the folder already holds a project, it adds GraphQL-Markdown to it instead of creating a new site. It detects your framework from package.json (or asks you), then asks for your schema (a path, glob or URL) and the output folder for the generated docs. It writes a .graphqlrc file and a docs:api script, and prints the one step left for your framework, such as adding a sidebar or navigation entry.
cd my-starlight-site
npm create graphql-markdown-docs@latest
To skip the prompts, for example in CI, pass the options explicitly:
npm create graphql-markdown-docs@latest . -- --yes --schema ./schema.graphql --output src/content/docs/api --install
The scaffolder never edits your framework configuration files and never overwrites existing files. It installs nothing unless you pass --install. Use --dry-run to preview the changes first.
For every option, see the create-graphql-markdown-docs flags.
Prefer to set it up by hand? Follow the steps for your framework.
Docusaurus
Prerequisites
These requirements are specific to Docusaurus integration. See our Framework Integration Guide for formatter-based setups and their requirements.
Your project needs to meet the following requirements:
- Node.js version 22.12 or above
- Docusaurus instance version 2.0 or above with the docs plugin enabled
- GraphQL.js version 16.0 or above
Install the plugin
Add the @graphql-markdown/docusaurus plugin to your site installation:
npm install @graphql-markdown/docusaurus graphql
Add a schema loader
See schema loading.
Configure the plugin
See configuration.
Nuxt
Add the @graphql-markdown/nuxt-theme layer to your Nuxt project and create content.config.ts and generate-docs.ts. See extending the layer directly.
Other frameworks
For Hugo, MkDocs, DocFX, mdBook and other formatter-based setups, see Integration with Frameworks.
Regenerate the documentation
In a Docusaurus site, build your website:
npm run docusaurus build
Or run the documentation generator directly:
npm run docusaurus graphql-to-doc
The npm run docusaurus graphql-to-doc command generates MDX files locally from your GraphQL schema. The possible command flags are documented in settings.
In a Nuxt site, generation runs automatically on npm run dev, npm run generate and npm run build through the layer's own module, so there is no separate command.