create-graphql-markdown-docs

create-graphql-markdown-docs

Interactive CLI that either creates a new GraphQL Markdown project (a ready-to-run Nuxt or Docusaurus API reference site, or plain Markdown or MDX output) or adds GraphQL-Markdown to an existing documentation site. The Nuxt preset is built on the @graphql-markdown/nuxt-theme layer.

Full guide: graphql-markdown.dev/docs/get-started.

Quick start

Run it in an empty or new folder to create a new site, or inside an existing project to add GraphQL-Markdown to it (see Add to an existing site):

npm create graphql-markdown-docs@latest
# or pass the project directory directly
npm create graphql-markdown-docs@latest my-docs

To create a new site, follow the interactive prompts to:

1. Choose a project directory — press Enter to accept my-graphql-docs. It must not exist yet or must be empty; a non-empty directory is rejected and you're asked again.
2. Provide a GraphQL schema, or use the bundled example.
3. Confirm the package manager (auto-detected from how you invoked the command; only asked if detection fails).
4. Optionally customize the site title and primary color.
5. Install dependencies.
6. Initialize a git repository (skipped when the project is already inside one, e.g. a monorepo).

Add to an existing site

Run the same command inside a folder that already contains a project. The CLI detects it and adds GraphQL-Markdown to it (wire mode):

cd my-starlight-site
npm create graphql-markdown-docs@latest

If you run the command without a directory inside a non-empty folder, it asks whether to add GraphQL-Markdown to this project or create a new one in a subfolder. --new and --existing force one mode or the other.

In wire mode the CLI:

1. Detects the framework from package.json, or asks you to choose one (generic for anything unlisted).
2. Asks for the schema (a path, glob or URL, written as you enter it) and the output folder. The output folder is always asked, never guessed.
3. Suggests a link root for the generated pages.
4. Writes a .graphqlrc file and a gqlmd script that runs gqlmd graphql-to-doc.
5. Prints the next step for your framework, such as adding a sidebar or navigation entry.

It never edits your framework configuration files and never overwrites existing files. If the project already has a GraphQL config, the CLI prints the block to merge into it instead. It installs nothing unless you pass --install; otherwise it prints the install command. Use --dry-run to see what it would write without writing anything.

For CI or scripting, pass the required options and skip the prompts:

npm create graphql-markdown-docs@latest . -- --yes --schema ./schema.graphql --output src/content/docs/api --install

With --yes, --schema and --output are required, and so is --framework when the framework cannot be detected from package.json.

Supported frameworks (existing sites)

Schema sources

Point --schema (or the equivalent prompt) at any of the following — the CLI detects which graphql-tools loader it needs and adds that dependency to the scaffolded project automatically:

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, with no local file to copy. For Nuxt, generate-docs.ts is rewritten to match and nuxt.config.ts's watch entry points at the local file (or is removed for a remote source); for Docusaurus, .graphqlrc is rewritten. Local code-first schemas are referenced in place rather than copied, so their imports keep working.

Non-interactive mode

For CI/CD or scripting, use --yes:

npm create graphql-markdown-docs@latest -- --yes --dir ./my-docs --schema ./schema.graphql --no-install --no-git

Flags

Shared

Scaffold only

Wire only

What's included

The scaffolded project is a real, complete Nuxt 4 project:

• nuxt.config.ts — extends @graphql-markdown/nuxt-theme, nothing else required.
• content.config.ts — required in every consuming project (not inherited from the layer — see the theme's own README for why).
• generate-docs.ts — calls the theme's createGenerateDocs factory with your schema (and, if applicable, the loader it needs).
• schema/ — your schema, or the bundled example.
• app/app.config.ts / app/pages/index.vue — a minimal landing page and theme override point, yours to edit.

Docusaurus

With --framework docusaurus, the scaffold replaces the standalone graphql-markdown/template repo:

• docusaurus.config.js — Docusaurus 3 with the classic preset and @graphql-markdown/docusaurus.
• .graphqlrc — schema and loader configuration (rewritten for your --schema).
• schema/ — your schema, or the bundled example.
• static/index.md, src/css/custom.css, babel.config.js — landing page, styling and build config.

Then run npm run doc to generate the docs and npm start to serve them.

Telemetry

The scaffolder reports one anonymous event per run (scaffold or wire): the framework, mode and schema loader type, with custom strings, URLs and paths masked. No schema content is sent. Nothing is sent on --dry-run. The first run shows a notice.

Opt out with the --no-telemetry flag, DO_NOT_TRACK=1, or gqlmd telemetry disable. See what is collected.

Documentation

• @graphql-markdown/nuxt-theme — the layer this scaffolds, including the full customization/swizzling reference.
• GraphQL-Markdown documentation
• Nuxt documentation

License

MIT