Settings
Every setting is a plugin option in your config file, and most have a CLI flag that overrides it. Run the CLI with npx docusaurus graphql-to-doc (Docusaurus plugin) or npx gqlmd graphql-to-doc (standalone), and see configuration for where the config lives.
At a glance
| Option | Type | Default | Purpose |
|---|---|---|---|
schema | string | ./schema.graphql | Path, URL or introspection result of the schema |
loaders | object | { } | GraphQL schema loaders |
rootPath | string | ./docs | Root folder for the generated documentation |
baseURL | string | schema | Base URL and output folder name under rootPath |
linkRoot | string | / | Root path used for type cross-links |
docOptions | object | - | Index pages, front matter, category sort, header IDs |
printTypeOptions | object | - | Hierarchy, deprecated handling, badges, parent prefix |
groupByDirective | string | undefined | Group types by a directive: @directive(field|=fallback) |
homepage | string | false | generated.md | Landing page file, false to disable |
id | string | default | Identifier of the configuration instance |
onlyDocDirective | string[] | [] | Include only types with these directives |
skipDocDirective | string[] | [] | Exclude types with these directives |
customDirective | object | undefined | Deprecated, use decorators |
decorators | object | undefined | Render custom content for schema nodes |
formatter | string | undefined | Package name or path to a formatter module |
outputAdapter | object | local filesystem | Write pages somewhere other than the filesystem |
metatags | object[] | [] | Page <head> metadata |
pretty | boolean | false | Format generated files with Prettier |
force | boolean | false | Force regeneration of all files |
diffMethod | string | NONE | Change detection: NONE, FORCE, SCHEMA-DIFF, SCHEMA-HASH |
tmpDir | string | OS temp folder | Folder for the schema copy and signature |
telemetry | boolean | on | Anonymous usage telemetry |
--config | flag | null | Print the resolved configuration |
CLI flags
Every flag below works with npx docusaurus graphql-to-doc (Docusaurus plugin) and npx gqlmd graphql-to-doc (standalone CLI), and overrides the matching setting.
| Flag | Setting | Description |
|---|---|---|
-s, --schema <path> | schema | Schema file, URL, or introspection JSON |
-b, --base <baseURL> | baseURL | Base URL and output folder name |
-r, --root <rootPath> | rootPath | Root output folder |
-l, --link <linkRoot> | linkRoot | Root path for cross-links |
-h, --homepage <file> | homepage | Custom homepage file |
-f, --force | force | Skip diff, always regenerate |
-d, --diff <method> | diffMethod | Diff method (NONE, SCHEMA-DIFF, etc.) |
-t, --tmp <dir> | tmpDir | Temp dir for schema diffing |
--index | docOptions.index | Generate category index pages |
--hierarchy <type> | printTypeOptions.hierarchy | Folder structure: api, entity, flat |
--deprecated <option> | printTypeOptions.deprecated | default, group, or skip |
--noParentType | printTypeOptions.parentTypePrefix | Hide parent type prefix on fields |
--noTypeBadges | printTypeOptions.typeBadges | Hide type attribute badges |
--noSectionId | docOptions.sectionHeaderId | Disable section header IDs for permalinks |
--only <@directive...> | onlyDocDirective | Include only types with these directives |
--skip <@directive...> | skipDocDirective | Exclude types with these directives |
--groupByDirective <expr> | groupByDirective | Group by directive: @dir(field|=fallback) |
--pretty | pretty | Format output with Prettier |
--formatter <pkg> | formatter | Formatter package name or path |
--mdxParser <pkg> | mdxParser | Deprecated alias for formatter |
--config | --config | Print resolved config (debug) |
--no-telemetry | telemetry | Disable anonymous usage telemetry |
--formatter and --mdxParser are only registered when the CLI has a default formatter package, as @graphql-markdown/docusaurus does. The standalone gqlmd command doesn't expose them, so set formatter in your configuration file instead.
Input
Where the schema comes from and how its pages are addressed.
schema
The GraphQL schema location.
| Setting | CLI flag | Default |
|---|---|---|
schema | -s, --schema <schema> | ./schema.graphql |
loaders
GraphQL schema loaders to use (see schema loading).
| Setting | CLI flag | Default |
|---|---|---|
loaders | not supported | { } |
rootPath
The output root path for the generated documentation, relative to the current workspace.
It works with baseURL, and the final path will be rootPath/baseURL.
| Setting | CLI flag | Default |
|---|---|---|
rootPath | -r, --root <rootPath> | ./docs |
baseURL
The base URL used by Docusaurus. It will also be used as the folder name under rootPath for the generated documentation.
| Setting | CLI flag | Default |
|---|---|---|
baseURL | -b, --base <baseURL> | schema |
linkRoot
The root for links in documentation. It depends on the entry for the schema main page in the Docusaurus sidebar.
| Setting | CLI flag | Default |
|---|---|---|
linkRoot | -l, --link <linkRoot> | / |
Output structure
How generated pages are organized, named and linked.
docOptions
Use these options to tweak some of the static documentation generator features:
categorySort: control how categories are sorted in the sidebar. Can be"natural"for alphabetical sorting or a custom compare function. When enabled, folder names are automatically prefixed with zero-padded order numbers (e.g.,01-objects,02-queries). When not set, the order depends on document generator folders sorting and no prefixes are added.frontMatter: set custom front matter entries as key/value. If set tofalse, then it will disable the frontmatter and print a level 1 title as the page title.index: enable/disable the index page for categories/groups, see Docusaurus documentation — ONLY FOR DOCUSAURUSsectionHeaderId: enable/disable the generation of custom header IDs for permalinks. When disabled, field and argument names are printed without a link, since their headings have no known anchor. The syntax depends on the formatter:- Docusaurus 3.10 and later:
### Section {/* #ID */}(see Strict Heading IDs and heading IDs). - Fumadocs:
### Section [#ID]. - Other formatters: the classic
### Section {#ID}. - Starlight and Vocs have no custom header ID syntax, so the classic one is escaped as
### Section \{#ID\}to keep the page valid MDX. It is only resolved if a remark plugin such asremark-custom-heading-idis configured. - DocFX does not support
{#ID}by default, so its formatter appends an HTML anchor<a id="ID"></a>to the heading instead. - Override
formatMDXPermalinkin a custom formatter to change it.
- Docusaurus 3.10 and later:
| Setting | CLI flag | Default |
|---|---|---|
docOptions.categorySort | not supported | - |
docOptions.frontMatter | not supported | {} |
docOptions.index | --index | false |
docOptions.sectionHeaderId | --noSectionId | true |
plugins: [
[
"@graphql-markdown/docusaurus",
/** @type {import('@graphql-markdown/types').ConfigOptions} */
{
schema: "./schema/swapi.graphql",
rootPath: "./docs",
baseURL: "swapi",
homepage: "./docs/swapi.md",
docOptions: {
frontMatter: {
pagination_next: null, // disable page navigation next
pagination_prev: null, // disable page navigation previous
hide_table_of_contents: true, // disable page table of content
},
index: true, // enable generated index pages, same as CLI flag --index
categorySort: "natural", // sort categories alphabetically and prefix with order numbers (01-objects, 02-queries, etc.)
sectionHeaderId: false, // disable custom section header IDs (restores previous behavior)
},
loaders: {
GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
},
},
],
],
Compatibility between options
The categorySort option works seamlessly with:
hierarchyoption: Works with all hierarchy types (api,entity,flat)groupByDirectiveoption: When using custom groups, categories are sorted based on group names and prefixed accordinglydeprecatedoption: Deprecated categories are sorted along with other categories
Example with groupByDirective:
docOptions: {
categorySort: "natural", // Sort groups alphabetically and prefix with order numbers
},
groupByDirective: {
directive: "doc",
field: "category",
fallback: "Common",
}
This generates folder names like: 01-common, 02-internal, 03-public
printTypeOptions
Use these options to toggle the type of information rendered on pages:
deprecated: option for displaying deprecated entities (fields, values, operations).default: deprecated entities are displayed with other entities.group: deprecated entities are grouped.skip: deprecated entities are not displayed (same asskipDocDirective).
exampleSection: configure example rendering based on directive data (see Examples).hierarchy: option for type folder structure:api: folder structure by operations (Operationsgroup) and typesTypesgroup based on GraphQL entity types.entity: folder structure by GraphQL entity types (eg. queries, mutations, scalars, objects...).flat: no folder structure (overridegroupByDirective). Filenames are prefixed with the entity kind to keep them unique, e.g.objects-user.mdxandqueries-user.mdx(since 1.38.0).- Namespaced operations are supported by default and generated as nested operation paths (See Namespaced Operations).
parentTypePrefix: prefix field names with the parent type name.typeBadges: add field type attributes badges.
| Setting | CLI flag | Default |
|---|---|---|
printTypeOptions.deprecated | --deprecated <option> | default |
printTypeOptions.exampleSection | n/a | — |
printTypeOptions.hierarchy | --hierarchy | api |
printTypeOptions.parentTypePrefix | --noParentType | true |
printTypeOptions.typeBadges | --noTypeBadges | true |
Use beforeComposePageTypeHook to control section visibility and order. To customize the rendering of printTypeOptions.deprecated: "group", see customize deprecated sections.
Declaring a different option type in the CLI flag hierarchy and the config file hierarchy will generate an error.
plugins: [
[
"@graphql-markdown/docusaurus",
/** @type {import('@graphql-markdown/types').ConfigOptions} */
{
schema: "./schema/swapi.graphql",
rootPath: "./docs",
baseURL: "swapi",
homepage: "./docs/swapi.md",
printTypeOptions: {
deprecated: "group", // group deprecated entities, same as CLI flag --deprecated group
exampleSection: {
field: "example", // use directive field for example rendering
},
hierarchy: "entity", // disable type API grouping, same as CLI flag --hierarchy entity
parentTypePrefix: false, // disable parent prefix, same as CLI flag --noParentType
typeBadges: false, // disable type attribute badges, same as CLI flag --noTypeBadges
},
formatter: require.resolve("./custom-mdx.cjs"), // use hook-based section composition
loaders: {
GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
}
},
],
],
const DocusaurusMDX = require("@graphql-markdown/docusaurus/mdx");
const beforeComposePageTypeHook = async (event) => {
// Hide code and relations sections
event.output = event.output.filter(
(key) => key !== "code" && key !== "relations",
);
};
module.exports = {
...DocusaurusMDX,
beforeComposePageTypeHook,
};
Custom group names
The api option for hierarchy can use customized group names (defaults are operations and types). Pass an object instead of api, using the group name as key for the new name:
plugins: [
[
"@graphql-markdown/docusaurus",
/** @type {import('@graphql-markdown/types').ConfigOptions} */
{
printTypeOptions: {
hierarchy: { // no customization 'hierarchy: "api"' (default)
api: { // enable useApiGroup with custom groups name
operations: "api", // rename the group 'operations' to 'api'
//group 'types' left unchanged
}
}
},
},
],
],
groupByDirective
Use a GraphQL directive for creating documentation categories (see documentation categories).
| Setting | CLI flag | Default |
|---|---|---|
groupByDirective | --groupByDirective <@directive(field|=fallback)> | undefined |
homepage
The location of the landing page to be used for the documentation, relative to the current workspace (see custom homepage). The file will be copied to the root folder of the generated documentation.
The plugin provides a default page in assets/generated.
| Setting | CLI flag | Default |
|---|---|---|
homepage | -h, --homepage <homepage> | generated.md |
Set homepage: false to disable the homepage generation. The GraphQL-Markdown template for Docusaurus provides a customized homepage located at static/index.md.
id
The identifier of the configuration instance. It is used for supporting additional schemas: each instance gets its own command graphql-to-doc:<id>, and it maps to the GraphQL Config project of the same name.
| Setting | CLI flag | Default |
|---|---|---|
id | not supported | default |
Content filtering
Which types and directives end up in the documentation.
onlyDocDirective
The schema directive/s is used for selecting types to be rendered in the documentation.
The CLI flag supports multiple values separated by a space character, eg --only @stable @beta.
| Setting | CLI flag | Default |
|---|---|---|
onlyDocDirective | --only <@directive...> | [] |
It only applies to types with a location compatible with the directive, i.e. if the onlyDocDirective cannot be applied to a type (e.g. ENUM), then the type will be displayed. See also skipDocDirective.
skipDocDirective
The schema directive/s is used for skipping types from documentation.
The CLI flag supports multiple values separated by a space character, eg --skip @noDoc @deprecated.
| Setting | CLI flag | Default |
|---|---|---|
skipDocDirective | --skip <@directive...> | [] |
Types with @deprecated directive can also be skipped using the setting printTypeOptions.deprecated: "skip" or the flag --deprecated skip. See also onlyDocDirective.
Declaring the same type in both onlyDocDirective and skipDocDirective will generate an error.
customDirective
Deprecated in favor of decorators, which supersedes it. See migrating from customDirective.
Use this option to render directive information for types (see custom directive).
| Setting | CLI flag | Default |
|---|---|---|
customDirective | not supported | undefined |
decorators
Select any node in the schema with a predicate and render a custom section, badge, or description text for it (see decorators). Supersedes customDirective.
| Setting | CLI flag | Default |
|---|---|---|
decorators | not supported | undefined |
Rendering
How pages are formatted, written and decorated.
formatter
Provide a custom module for formatting output content. You can also use built-in formatter presets from @graphql-markdown/formatters. @graphql-markdown/docusaurus comes with @graphql-markdown/formatters/docusaurus by default.
| Setting | CLI flag | Default |
|---|---|---|
formatter | --formatter | undefined |
The mdxParser setting and --mdxParser CLI flag are deprecated aliases for formatter / --formatter. They still work but emit a deprecation warning, so migrate to formatter.
The --formatter and --mdxParser CLI flags are only registered when the CLI is set up with a default formatter package, which is what @graphql-markdown/docusaurus does. The standalone gqlmd command does not expose them, so set formatter in your configuration file instead.
The custom module can export individual formatter functions:
| Export | Type | Description |
|---|---|---|
formatMDXBadge | (badge: { text, classname? }) => string | Format type badges |
formatMDXAdmonition | (admonition, meta?) => string | Format callout/warning blocks |
formatMDXBullet | (text?: string) => string | Format bullet point separators |
formatMDXDetails | (option) => string | Format collapsible sections |
formatMDXFrontmatter | (props?, formatted?, context?) => string | Format page frontmatter |
formatMDXLink | (link) => { text, url } | Transform type links |
formatMDXNameEntity | (name, parentType?) => string | Format named entity references |
formatMDXPermalink | (id) => string | Format section header permalinks |
formatMDXSpecifiedByLink | (url) => string | Format scalar specification links. Receives an absolute http(s) URL; encode it for where you write it (for example as an HTML attribute) |
formatMDXTitle | (title) => string | Optional visible page title, printed after the frontmatter |
For detailed examples on formatter functions, see Other frameworks.
Additionally, the module can export:
| Export | Type | Description |
|---|---|---|
mdxDeclaration | string | Import statements prepended to generated files |
mdxExtension | string | Custom file extension (defaults to .mdx) |
The custom module can also export lifecycle hooks for customizing the generation process, see Hooks Recipes.
plugins: [
[
"@graphql-markdown/docusaurus",
/** @type {import('@graphql-markdown/types').ConfigOptions} */
{
schema: "./schema/swapi.graphql",
rootPath: "./docs",
baseURL: "swapi",
homepage: "./docs/swapi.md",
formatter: "./lib/custom-mdx.cjs",
loaders: {
GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
}
},
],
],
outputAdapter
The destination for generated documentation. By default pages are written to the local filesystem under rootPath/baseURL. Set an adapter to send them somewhere else instead — a CMS storage API, an object store, an in-memory map — without forking the renderer.
| Setting | CLI flag | Default |
|---|---|---|
outputAdapter | none | local filesystem |
An adapter must provide writeFile and readFile, and may provide ensureDir:
interface OutputAdapter {
writeFile: (filePath: string, content: string) => Promise<void>;
readFile: (filePath: string) => Promise<string | undefined>;
ensureDir?: (
dirPath: string,
options?: { forceEmpty?: boolean },
) => Promise<void>;
}
See Output adapter for the full contract and worked examples:
- when each method is called
- how paths map onto keys
- which formatters read their output back
- why omitting
ensureDirleaves pages for deleted types behind - the limitations worth knowing before relying on one in a pipeline
metatags
Set page metadata in <html>, <head> using Docusaurus head metadata.
Meta tags are provided as a list of metadata objects, eg [{ name: "robots", content: "noindex" }] for <meta name="robots" content="noindex" />.
| Setting | CLI flag | Default |
|---|---|---|
metatags | not supported | [] |
plugins: [
[
"@graphql-markdown/docusaurus",
/** @type {import('@graphql-markdown/types').ConfigOptions} */
{
schema: "./schema/swapi.graphql",
rootPath: "./docs",
baseURL: "swapi",
homepage: "./docs/swapi.md",
metatags: [
{ name: "robots", content: "noindex" }, // <meta name="robots" content="noindex" />
{ charset: "utf-8" }, // <meta charset="utf-8" />
],
loaders: {
GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
}
},
],
],
pretty
Use prettier to format generated files. The prettier package has to be installed separately. If the package is not present locally, then the formatting will always be skipped.
| Setting | CLI flag | Default |
|---|---|---|
pretty | --pretty | false |
Run behavior
How and when generation runs.
force
Force generating documentation in an empty folder and set diffMethod to FORCE. If the folder located at rootPath/baseURL is not empty, then the plugin will delete the folder recursively and recreate it.
| Setting | CLI flag | Default |
|---|---|---|
force | -f, --force | false |
diffMethod
The method to be used for identifying changes in the schema for triggering the documentation generation.
The possible values are:
FORCE: skip diff, always generate documentation, also triggered byforcesetting.NONE: skip diff (same asFORCE).SCHEMA-DIFF: use GraphQL Inspector to identify changes in the schema (including description).SCHEMA-HASH: use the schema SHA-256 hash for identifying changes in the schema (this method is sensitive to white spaces and invisible characters).
| Setting | CLI flag | Default |
|---|---|---|
diffMethod | -d, --diff <diffMethod> | NONE |
The package @graphql-markdown/diff is required for using diffMethod. If the package is missing, then the change detection is always skipped.
- npm
- pnpm
- yarn
- bun
npm install @graphql-markdown/diff
pnpm add @graphql-markdown/diff
yarn add @graphql-markdown/diff
bun add @graphql-markdown/diff
tmpDir
The folder used for storing schema copy and signature is used by diffMethod setting.
| Setting | CLI flag | Default |
|---|---|---|
tmpDir | -t, --tmp <tmpDir> | OS temp folder |
telemetry
Enables or disables anonymous usage telemetry. Set it to false to opt out; true only enables telemetry for programmatic use of @graphql-markdown/core, and never overrides DO_NOT_TRACK, GRAPHQL_MARKDOWN_TELEMETRY_DISABLED or gqlmd telemetry disable.
| Setting | CLI flag | Default |
|---|---|---|
telemetry | --no-telemetry | on |
--config
Print the resolved configuration used for generating documentation. This CLI flag is used for debugging purposes.
| Setting | CLI flag | Default |
|---|---|---|
--config | null |
Example:
- npm
- pnpm
- yarn
- bun
npx docusaurus graphql-to-doc --config
pnpm exec docusaurus graphql-to-doc --config
yarn docusaurus graphql-to-doc --config
bunx docusaurus graphql-to-doc --config