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 |