- `SCHEMA-DIFF`: use [GraphQL Inspector](https://graphql-inspector.com/) for identifying 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)
Any other value will disable the change detection. |\n| `docOptions` | `--noPagination`, `--noToc`, `--index` | `{pagination: true, toc: true, index: false}` | Documentation presentation options (see [doc options](#documentation-options)). |\n| `groupByDirective` | `-gdb, --groupByDirective <@directive(field\\|=fallback)>` | - | Group documentation by directive (see [groupByDirective](#option-groupbydirective)). |\n| `homepage` | `-h, --homepage
By default, the plugin provides a default page `assets/generated.md`. |\n| `linkRoot` | `-l, --link
\n
\n\nUse these options to tweak some of the Docusaurus documentation features:\n\n- `docOptions.pagination`: page buttons `Previous` and `Next` (default: `true`)\n- `docOptions.toc`: page table of content (default: `true`)\n- `docOptions.index`: generate index page for categories/groups, see [Docusaurus documentation](https://docusaurus.io/docs/sidebar/items#generated-index-page) (default: `false`)\n\n```js {9-13}\nplugins: [\n [\n \"@edno/docusaurus2-graphql-doc-generator\",\n {\n schema: \"./schema/swapi.graphql\",\n rootPath: \"./docs\",\n baseURL: \"swapi\",\n homepage: \"./docs/swapi.md\",\n docOptions: {\n pagination: false, // disable buttons previous and next, same as cli flag --noPagination\n toc: false, // disable page table of content, same as cli flag --noToc\n index: true, // enable generated index pages, same as cli flag --index\n },\n },\n ],\n ],\n```\n\n
\n\nDocumentation options
\n\nUse these options to tweak some of the Docusaurus documentation features:\n\n- `docOptions.pagination`: page buttons `Previous` and `Next` (default: `true`)\n- `docOptions.toc`: page table of content (default: `true`)\n- `docOptions.index`: generate index page for categories/groups, see [Docusaurus documentation](https://docusaurus.io/docs/sidebar/items#generated-index-page) (default: `false`)\n\n```js {9-13}\nplugins: [\n [\n \"@edno/docusaurus2-graphql-doc-generator\",\n {\n schema: \"./schema/swapi.graphql\",\n rootPath: \"./docs\",\n baseURL: \"swapi\",\n homepage: \"./docs/swapi.md\",\n docOptions: {\n pagination: false, // disable buttons previous and next, same as cli flag --noPagination\n toc: false, // disable page table of content, same as cli flag --noToc\n index: true, // enable generated index pages, same as cli flag --index\n },\n },\n ],\n ],\n```\n\n\n
\n\nUse these options to toggle type information rendered on pages:\n\n- `printTypeOptions.parentTypePrefix`: prefix field names with parent type name (default: `true`)\n- `printTypeOptions.relatedTypeSection`: display related type sections (default: `true`)\n- `printTypeOptions.typeBadges`: add field type attributes badges (default: `true`)\n\n```js {9-13}\nplugins: [\n [\n \"@edno/docusaurus2-graphql-doc-generator\",\n {\n schema: \"./schema/swapi.graphql\",\n rootPath: \"./docs\",\n baseURL: \"swapi\",\n homepage: \"./docs/swapi.md\",\n printTypeOptions: {\n parentTypePrefix: false, // disable parent prefix, same as cli flag --noParentType\n relatedTypeSection: false, // disable related type sections, same as cli flag --noRelatedType\n typeBadges: false, // disable type attribute badges, same as cli flag --noTypeBadges\n },\n },\n ],\n ],\n```\n\n
\n\nType information options
\n\nUse these options to toggle type information rendered on pages:\n\n- `printTypeOptions.parentTypePrefix`: prefix field names with parent type name (default: `true`)\n- `printTypeOptions.relatedTypeSection`: display related type sections (default: `true`)\n- `printTypeOptions.typeBadges`: add field type attributes badges (default: `true`)\n\n```js {9-13}\nplugins: [\n [\n \"@edno/docusaurus2-graphql-doc-generator\",\n {\n schema: \"./schema/swapi.graphql\",\n rootPath: \"./docs\",\n baseURL: \"swapi\",\n homepage: \"./docs/swapi.md\",\n printTypeOptions: {\n parentTypePrefix: false, // disable parent prefix, same as cli flag --noParentType\n relatedTypeSection: false, // disable related type sections, same as cli flag --noRelatedType\n typeBadges: false, // disable type attribute badges, same as cli flag --noTypeBadges\n },\n },\n ],\n ],\n```\n\n\n
\n\n`graphql-file-loader`, the local file loader, is provided out-of-the-box. Thus, by default, the `schema` default loading expects a local GraphQL schema definition file (`*.graphql`).\n\nAdditional GraphQL document loaders can be used (see [full list](https://github.com/ardatan/graphql-tools/tree/master/packages/loaders)).\n\nFor example, if you want to load a schema from a URL, you first need to install the package `@graphql-tools/url-loader` into your Docusaurus project:\n\n```shell\nyarn add @graphql-tools/url-loader\n```\n\nOnce done, you can declare the loader into `docusaurus2-graphql-doc-generator` configuration:\n\n```js\nplugins: [\n [\n \"@edno/docusaurus2-graphql-doc-generator\",\n {\n // ... other options\n loaders: {\n UrlLoader: \"@graphql-tools/url-loader\"\n }\n },\n ],\n],\n```\n\nYou can declare as many loaders as you need using the structure:\n\n```ts\ntype className = string; // UrlLoader\n\ntype moduleName = string; // \"@graphql-tools/url-loader\"\ntype rootTypes = { query?: string, mutation?: string, subscription?: string};\ntype moduleOptions = { [option: string]: any, rootType?: rootTypes };\n\ntype module = { \n module: moduleName, \n options: moduleOptions | undefined \n}\n\ntype loaders = {\n [className: className]: moduleName | module\n}\n```\n\n
\n\nLoaders
\n\n`graphql-file-loader`, the local file loader, is provided out-of-the-box. Thus, by default, the `schema` default loading expects a local GraphQL schema definition file (`*.graphql`).\n\nAdditional GraphQL document loaders can be used (see [full list](https://github.com/ardatan/graphql-tools/tree/master/packages/loaders)).\n\nFor example, if you want to load a schema from a URL, you first need to install the package `@graphql-tools/url-loader` into your Docusaurus project:\n\n```shell\nyarn add @graphql-tools/url-loader\n```\n\nOnce done, you can declare the loader into `docusaurus2-graphql-doc-generator` configuration:\n\n```js\nplugins: [\n [\n \"@edno/docusaurus2-graphql-doc-generator\",\n {\n // ... other options\n loaders: {\n UrlLoader: \"@graphql-tools/url-loader\"\n }\n },\n ],\n],\n```\n\nYou can declare as many loaders as you need using the structure:\n\n```ts\ntype className = string; // UrlLoader\n\ntype moduleName = string; // \"@graphql-tools/url-loader\"\ntype rootTypes = { query?: string, mutation?: string, subscription?: string};\ntype moduleOptions = { [option: string]: any, rootType?: rootTypes };\n\ntype module = { \n module: moduleName, \n options: moduleOptions | undefined \n}\n\ntype loaders = {\n [className: className]: moduleName | module\n}\n```\n\n\n
\n\nFor custom operation root types (queries not of type `Query`, or root type name used for other purpose), use the loader option `rootTypes`:\n\n```ts\ntype rootTypes = { query?: string, mutation?: string, subscription?: string};\n```\n\n- use a custom type name to override standard type\n- use a empty string to disable the GraphQL standard type\n- unset root types will use the GraphQL standard type\n\nAdd the option `rootTypes` to the loader options under `docusaurus2-graphql-doc-generator` configuration (see also [Loaders](#plugin-loaders)):\n\n```js\nplugins: [\n [\n \"@edno/docusaurus2-graphql-doc-generator\",\n {\n // ... other options\n loaders: {\n GraphQLFileLoader: {\n module: \"@graphql-tools/graphql-file-loader\",\n options: { \n rootTypes: { \n query: \"Root\", // use custom root type Root for queries, instead of Query\n subscription: \"\" // disable Subscription type\n },\n }\n }\n },\n ],\n],\n```\n\n
\n\nCustom root types
\n\nFor custom operation root types (queries not of type `Query`, or root type name used for other purpose), use the loader option `rootTypes`:\n\n```ts\ntype rootTypes = { query?: string, mutation?: string, subscription?: string};\n```\n\n- use a custom type name to override standard type\n- use a empty string to disable the GraphQL standard type\n- unset root types will use the GraphQL standard type\n\nAdd the option `rootTypes` to the loader options under `docusaurus2-graphql-doc-generator` configuration (see also [Loaders](#plugin-loaders)):\n\n```js\nplugins: [\n [\n \"@edno/docusaurus2-graphql-doc-generator\",\n {\n // ... other options\n loaders: {\n GraphQLFileLoader: {\n module: \"@graphql-tools/graphql-file-loader\",\n options: { \n rootTypes: { \n query: \"Root\", // use custom root type Root for queries, instead of Query\n subscription: \"\" // disable Subscription type\n },\n }\n }\n },\n ],\n],\n```\n\n\n
\n\nIf you decide to use your own home page for the GraphQL generated documentation, then set the page ID to `id: schema` and the sidebar position to `sidebar_position: 1`:\n\n```markdown {2,5}\n---\nid: schema\nslug: /schema\ntitle: Schema Documentation\nsidebar_position: 1\n---\n\nThis documentation has been automatically generated from the GraphQL schema.\n```\n\n> ***Tip***\n>\n> *If you want to hide it from the sidebar (like in the demo), then set the front matter `sidebar_class_name` (or `className` depending on your Docusaurus version) to `navbar__toggle`.*\n>\n> ```markdown {6}\n> ---\n> id: schema\n> slug: /schema\n> title: Schema Documentation\n> sidebar_position: 1\n> sidebar_class_name: navbar__toggle\n> ---\n> ```\n\n
\n\nHome Page
\n\nIf you decide to use your own home page for the GraphQL generated documentation, then set the page ID to `id: schema` and the sidebar position to `sidebar_position: 1`:\n\n```markdown {2,5}\n---\nid: schema\nslug: /schema\ntitle: Schema Documentation\nsidebar_position: 1\n---\n\nThis documentation has been automatically generated from the GraphQL schema.\n```\n\n> ***Tip***\n>\n> *If you want to hide it from the sidebar (like in the demo), then set the front matter `sidebar_class_name` (or `className` depending on your Docusaurus version) to `navbar__toggle`.*\n>\n> ```markdown {6}\n> ---\n> id: schema\n> slug: /schema\n> title: Schema Documentation\n> sidebar_position: 1\n> sidebar_class_name: navbar__toggle\n> ---\n> ```\n\n\n
\n\nThe `diffMethod` is only used for identifying if the schema has changed. If a change is detected since the last documentation generation, then the full schema documentation will be generated.\n
\n\nOption diffMethod
\n\nThe `diffMethod` is only used for identifying if the schema has changed. If a change is detected since the last documentation generation, then the full schema documentation will be generated.\n\n
\n\nThe `groupByDirective` is used to add grouping to the documentation to provide for an easier user experience to navigate. This is accomplished by adding a directive to all the types you want to have grouped.\n\nFor example, we have two mutations called `addCourse` and `dropCourse`, and we want to group them under a category called `Courses`.\n\nWe can accomplish this by adding a directive called `doc` with a field `category` to each mutation. Also, we can add a fallback option called `Common` which is for types that we don't explicitly add a directive to.\n\n```graphql\ntype Mutation{\n AddCourse(input: String): String @doc(category: \"Course\") \n}\n\ntype Mutation{\n DropCourse(input: String): String @doc(category: \"Course\") \n}\n```\n\nIt can be set either with the command line flag `-gdb`:\n\n```shell\nnpx docusaurus graphql-to-doc -gdb \"@doc(category|=Common)\"\n```\n\nor the plugin configuration `groupByDirective`:\n\n```js {6-10}\nplugins: [\n [\n \"@edno/docusaurus2-graphql-doc-generator\",\n {\n // ... other options\n groupByDirective: {\n directive: \"doc\",\n field: \"category\",\n fallback: \"Common\", // default is Miscellaneous\n }\n },\n ],\n],\n```\n\n
\n\n## Troubleshooting\n\n### `Duplicate \"graphql\" modules cannot be used at the same time`\n\nAdd a [`resolutions`](https://classic.yarnpkg.com/en/docs/selective-version-resolutions/) entry to your `package.json` file:\n\n```json\n\"resolutions\": {\n \"graphql\": \"15.5.2\"\n}\n```\n\n### `Unable to find any GraphQL type definitions`\n\nTry changing the temporary folder for the plugin by setting `tmpDir: \"./.docusaurus\"` (see [options](#options) section for more details).\n\nYou can also disable the schema diff feature by setting `diffMethod: \"NONE\"`.\n\n### `Unable to find any GraphQL type definitions for the following pointers`\n\n> This error may occur when upgrading to version `1.5.0` or above.\n\nInstall and declare the missing GraphQL document loader package, see [Loaders](#plugin-loaders).\n\nIf the error persists, check that you have the correct class name in the configuration declaration.\n\n## License\n\nGraphQL-Markdown packages are 100% free and open-source, under the [MIT license](https://github.com/graphql-markdown/graphql-markdown/blob/main/LICENSE).\n\nThis package is [Treeware](https://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/graphql-markdown/graphql-markdown) to thank us for our work. By contributing to the Treeware forest youโll be creating employment for local families and restoring wildlife habitats.\n\n## Contributions\n\n[Contributions](https://github.com/graphql-markdown/graphql-markdown/blob/main/CONTRIBUTING.md), issues and feature requests are very welcome. If you are using this package and fixed a bug for yourself, please consider submitting a PR!\n\n\n