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.
Setting | CLI flag | Default |
---|---|---|
baseURL | -b, --base <baseURL> | schema |
customDirective
β
Use this option to render directive information for types (see custom directive).
Setting | CLI flag | Default |
---|---|---|
customDirective | not supported | undefined |
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 byforce
setting.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 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 buttonsPrevious
andNext
[deprecated, see note below].toc
: enable/disable page table of content [deprecated, see note below].
Setting | CLI flag | Default |
---|---|---|
docOptions.frontMatter | not supported | {} |
docOptions.index | --index | false |
docOptions.pagination | --noPagination | true |
docOptions.toc | --noToc | 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
},
loaders: {
GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
},
},
],
],
-
docOptions.pagination
(CLI flag--noPagination
) has been replaced bydocOptions.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 bydocOptions.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.
Setting | CLI flag | Default |
---|---|---|
force | -f, --force | false |
groupByDirective
β
Use a GraphQL directive for creating documentation categories (see documentation categories).
Setting | CLI flag | Default |
---|---|---|
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
.
Setting | CLI flag | Default |
---|---|---|
homepage | -h, --homepage <homepage> | generated.md |
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.
Setting | CLI flag | Default |
---|---|---|
linkRoot | -l, --link <linkRoot> | / |
loaders
β
GraphQL schema loaders to use (see schema loading).
Setting | CLI flag | Default |
---|---|---|
loaders | not 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" />
.
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
}
},
],
],
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...> | [] |
See also skipDocDirective
.
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 asskipDocDirective
).
exampleSection
: display example section based on directive data (see Examples).hierarchy
: option for type folder structure:api
: folder structure by operations (Operations
group) and typesTypes
group based on GraphQL entity types.entity
: folder structure by GraphQL entity types (eg. queries, mutations, scalars, objects...).flat
: no folder structure (overridegroupByDirective
).
parentTypePrefix
: prefix field names with the parent type name.relatedTypeSection
: display related type sections.typeBadges
: add field type attributes badges.useApiGroup
: split entities inOperations
group (executable types) andTypes
group (system types) [deprecated, see note below].
Setting | CLI flag | Default |
---|---|---|
printTypeOptions.codeSection | --noCode | true |
printTypeOptions.deprecated | --deprecated <option> | default |
printTypeOptions.exampleSection | --noExample | false |
printTypeOptions.hierarchy | --hierarchy | api |
printTypeOptions.parentTypePrefix | --noParentType | true |
printTypeOptions.relatedTypeSection | --noRelatedType | true |
printTypeOptions.typeBadges | --noTypeBadges | true |
printTypeOptions.useApiGroup | --noApiGroup | true |
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
}
},
],
],
Declaring the different option type in CLI flag hierarchy
and config file hierarchy
will generate an error.
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:
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
}
}
},
},
],
],
See customize deprecated sections to customize the rendering of printTypeOptions.deprecated: "group"
.
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.
Setting | CLI flag | Default |
---|---|---|
pretty | --pretty | false |
The prettier
package has to be installed separately. If the package is not present locally, then the formatting will always be skipped.
runOnBuild
β
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
.
Setting | CLI flag | Default |
---|---|---|
runOnBuild | n/a | false |
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
.
Setting | CLI flag | Default |
---|---|---|
rootPath | -r, --root <rootPath> | ./docs |
schema
β
The GraphQL schema location.
Setting | CLI flag | Default |
---|---|---|
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
.
Setting | CLI flag | Default |
---|---|---|
skipDocDirective | --skip <@directive...> | [] |
See also onlyDocDirective
.
Declaring the same type in both onlyDocDirective
and skipDocDirective
will generate an error.
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.
Setting | CLI flag | Default |
---|---|---|
tmpDir | -t, --tmp <tmpDir> | OS temp folder |