Skip to main content

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.18 or above (which can be checked by running node -v) is required.

You can use npm, yarn, pnpm or bun as your package manager. Command examples have a tab for each package manager; pick yours once and every page follows. To manage several Node.js versions on one machine, use nvm.

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

Pass the project directory as an argument to skip that prompt:

npm create graphql-markdown-docs@latest my-docs

With npm, flags follow a -- separator so that npm forwards them to the CLI; the other package managers pass them directly:

npm create graphql-markdown-docs@latest my-docs -- --framework docusaurus

What the prompts ask​

  1. Framework: Nuxt (default) or Docusaurus.
  2. 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.
  3. Schema: use the bundled example, or your own (local file, introspection URL, git: or github: reference). The matching loader is detected and added as a dependency.
  4. 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.
  5. Title (optional), and a primary color for Nuxt.
  6. Install dependencies.
  7. 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-theme layer, with live reload when the schema changes.
  • Docusaurus: a classic Docusaurus site configured with the @graphql-markdown/docusaurus plugin.

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 sourceExampleLoader added
Local .graphql/.gql file./schema/api.graphqlNone (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 endpointhttps://api.example.com/graphql@graphql-tools/url-loader
Git-hosted filegit:branch:path/schema.graphql@graphql-tools/git-loader
GitHub-hosted filegithub: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, install the dependencies first (npm install, pnpm install, yarn or bun install).

The doc script is a shortcut in the scaffolded site for docusaurus graphql-to-doc. The start script 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
FlagDescription
--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.
--exampleUse 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-installSkip dependency installation.
--no-gitSkip git repository initialization.
-y, --yesAccept all defaults; fully non-interactive.
-h, --helpShow usage and exit.
-v, --versionPrint the CLI version and exit.

Add to an existing site​

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 gqlmd 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​

npm install @graphql-markdown/docusaurus graphql

Then add a schema loader and configure the plugin. See the Docusaurus guide for requirements and configuration.

Nuxt​

npm install @graphql-markdown/nuxt-theme

Then create content.config.ts and generate-docs.ts. See the Nuxt guide.

Other frameworks​

For Hugo, MkDocs, DocFX, mdBook and other formatter-based setups, see Other frameworks.

Use the API​

To generate the documentation from your own script instead of the CLI or a framework plugin, call @graphql-markdown/core directly. buildConfig takes the same settings as the configuration file and fills in the defaults; generateDocFromSchema loads the schema and writes the pages. The loaders option is required: it names the schema loader used to read the schema.

npm install @graphql-markdown/core graphql @graphql-tools/graphql-file-loader
generate-docs.ts
import { buildConfig, generateDocFromSchema } from "@graphql-markdown/core";

const config = await buildConfig({
schema: "./schema.graphql",
rootPath: "./docs",
baseURL: "api",
loaders: {
GraphQLFileLoader: "@graphql-tools/graphql-file-loader",
},
});

await generateDocFromSchema(config);

Run it with any TypeScript-aware runtime, for example node generate-docs.ts (Node.js 22.18 or above), bun generate-docs.ts or deno run -A generate-docs.ts.

buildConfig also reads a GraphQL Config file when graphql-config is installed, and merges it with the options passed in code. Without it, the options in code are all that is needed.

Install from JSR​

The GraphQL-Markdown libraries are also published on JSR for Deno, Node.js and Bun. See JSR for installation, the supported GraphQL.js version and optional features.

Regenerate the documentation​

In a Docusaurus site, see Docusaurus recipes for the build/regenerate commands.

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.