Skip to main content

Settings

By default, the plugin will use the options as defined in the configuration, and they can be overridden using CLI flags.

baseURL​

The base URL used by Docusaurus. It will also be used as the folder name under rootPath for the generated documentation.

SettingCLI flagDefault
baseURL-b, --base <baseURL>schema

customDirective​

Use this option to render directive information for types (see custom directive).

SettingCLI flagDefault
customDirectivenot supportedundefined

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 by force setting.
  • NONE: skip diff (same as FORCE).
  • 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).
SettingCLI flagDefault
diffMethod-d, --diff <diffMethod>NONE

info

The package @graphql-markdown/diff is required for using diffMethod. If the package is missing, then the change detection is always skipped.

npm install @graphql-markdown/diff

docOptions​

Use these options to tweak some of the Docusaurus documentation features:

  • frontMatter: set custom front matter entries, see Docusaurus documentation.
  • index: enable/disable the index page for categories/groups, see Docusaurus documentation.
  • pagination: enable/disable page buttons Previous and Next [deprecated, see note below].
  • toc: enable/disable page table of content [deprecated, see note below].
SettingCLI flagDefault
docOptions.frontMatternot supported{}
docOptions.index--indexfalse
docOptions.pagination--noPaginationtrue
docOptions.toc--noToctrue

docusaurus.config.js
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
},
loaders: {
GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
},
},
],
],

DEPRECATED
  • docOptions.pagination (CLI flag --noPagination) has been replaced by docOptions.frontMatter:

    docOptions: {
    frontMatter: {
    pagination_next: null, // disable page navigation next
    pagination_prev: null, // disable page navigation previous
    },
    },
  • docOptions.toc (CLI flag --noToc) has been replaced by docOptions.frontMatter:

    docOptions: {
    frontMatter: {
    hide_table_of_contents: true, // disable page table of content
    },
    },

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.

SettingCLI flagDefault
force-f, --forcefalse

groupByDirective​

Use a GraphQL directive for creating documentation categories (see documentation categories).

SettingCLI flagDefault
groupByDirective-gdb, --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 at the root folder of the generated documentation.

The plugin provides a default page in assets/generated.

SettingCLI flagDefault
homepage-h, --homepage <homepage>generated.md

info

The GraphQL-Markdown template for Docusaurus provides a customized homepage located at static/index.md.

linkRoot​

The root for links in documentation. It depends on the entry for the schema main page in the Docusaurus sidebar.

SettingCLI flagDefault
linkRoot-l, --link <linkRoot>/

loaders​

GraphQL schema loaders to use (see schema loading).

SettingCLI flagDefault
loadersnot supported{ }

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" />.

SettingCLI flagDefault
metatagsnot supported[]

docusaurus.config.js
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
}
},
],
],

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.

SettingCLI flagDefault
onlyDocDirective--only <@directive...>[]

See also skipDocDirective.


info

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.

printTypeOptions​

Use these options to toggle type information rendered on pages:

  • codeSection: display type code section.
  • 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 as skipDocDirective).
  • exampleSection: display example section based on directive data (see Examples).
  • hierarchy: option for type folder structure:
    • api: folder structure by operations (Operations group) and types Types group based on GraphQL entity types.
    • entity: folder structure by GraphQL entity types (eg. queries, mutations, scalars, objects...).
    • flat: no folder structure (override groupByDirective).
  • parentTypePrefix: prefix field names with the parent type name.
  • relatedTypeSection: display related type sections.
  • typeBadges: add field type attributes badges.
  • useApiGroup: split entities in Operations group (executable types) and Types group (system types) [deprecated, see note below].
SettingCLI flagDefault
printTypeOptions.codeSection--noCodetrue
printTypeOptions.deprecated--deprecated <option>default
printTypeOptions.exampleSection--noExamplefalse
printTypeOptions.hierarchy--hierarchyapi
printTypeOptions.parentTypePrefix--noParentTypetrue
printTypeOptions.relatedTypeSection--noRelatedTypetrue
printTypeOptions.typeBadges--noTypeBadgestrue
printTypeOptions.useApiGroup--noApiGrouptrue

docusaurus.config.js
plugins: [
[
"@graphql-markdown/docusaurus",
/** @type {import('@graphql-markdown/types').ConfigOptions} */
{
schema: "./schema/swapi.graphql",
rootPath: "./docs",
baseURL: "swapi",
homepage: "./docs/swapi.md",
printTypeOptions: {
codeSection: false, // disable code section, same as CLI flag --noCode
deprecated: "group", // group deprecated entities, same as CLI flag --deprecated group
exampleSection: false, // disable code section, same as CLI flag --noExample
hierarchy: "entity", // disable type API grouping, same as CLI flag --hierarchy entity
parentTypePrefix: false, // disable parent prefix, same as CLI flag --noParentType
relatedTypeSection: false, // disable related type sections, same as CLI flag --noRelatedType
typeBadges: false, // disable type attribute badges, same as CLI flag --noTypeBadges
},
loaders: {
GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
}
},
],
],

hierarchy

If you upgraded to version 1.23.0 or higher, then in some cases the old GraphQL documentation structure is not being removed.

To resolve this, you can regenerate the documentation using the force setting; or use hierarchy: "entity" to keep the previous behavior.

danger

Declaring the different option type in CLI flag hierarchy and config file hierarchy will generate an error.

tip

api option for hierarchy can use customized group names (defaults are operations and types) by passing an object instead of api using the group name as key for the new name:

docusaurus.config.js
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
}
}
},
},
],
],
info

See customize deprecated sections to customize the rendering of printTypeOptions.deprecated: "group".

DEPRECATED

printTypeOptions.useApiGroup (CLI flag --noApiGroup) has been replaced by printTypeOptions.hierarchy:

printTypeOptions: {
hierarchy: "api", // use value "entity" for --noApiGroup equivalent
},

pretty​

Use prettier to format generated files.

SettingCLI flagDefault
pretty--prettyfalse

info

The prettier package has to be installed separately. If the package is not present locally, then the formatting will always be skipped.

runOnBuild​

EXPERIMENTAL

runOnBuild is an experimental feature, and it should not be used in production.

When set to true enables running doc generation on docusaurus build. If false, then the documentation can only be generated with the Docusaurus command graphql-to-doc.

SettingCLI flagDefault
runOnBuildn/afalse

rootPath​

The output root path for the generated documentation, relative to the current workspace. It works in relation to baseURL, and the final path will be rootPath/baseURL.

SettingCLI flagDefault
rootPath-r, --root <rootPath>./docs

schema​

The GraphQL schema location.

SettingCLI flagDefault
schema-s, --schema <schema>./schema.graphql

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.

SettingCLI flagDefault
skipDocDirective--skip <@directive...>[]

See also onlyDocDirective.


danger

Declaring the same type in both onlyDocDirective and skipDocDirective will generate an error.

info

Types with @deprecated directive can also be skipped using the setting printTypeOptions.deprecated: "skip" or the flag --deprecated skip.

tmpDir​

The folder used for storing schema copy and signature is used by diffMethod setting.

SettingCLI flagDefault
tmpDir-t, --tmp <tmpDir>OS temp folder