@platformos/graphql-docs-markdown
v1.6.3
Published
Docusaurus 2 plugin for generating Markdown documentation from a GraphQL schema.
Downloads
9
Readme
slug: /
GraphQL Documentation Generator for Docusaurus 2
This plugin generates a Markdown documentation from a GraphQL schema.
The documentation is generated for Docusaurus 2 docs feature.
Installation
npm
npm install --save @edno/docusaurus2-graphql-doc-generator
Yarn
yarn add @edno/docusaurus2-graphql-doc-generator
Then you add it in your site's docusaurus.config.js
's plugins option:
module.exports = {
// ...
plugins: ["@edno/docusaurus2-graphql-doc-generator"],
};
Configuration
You can define some or all of the plugin options directly at the plugin level in in the Docusaurus configuration file docusaurus.config.js
:
Plugin Options
module.exports = {
// ...
plugins: [
[
'@edno/docusaurus2-graphql-doc-generator',,
{
schema: "./schema/swapi.graphql",
rootPath: "./docs", // docs will be generated under './docs/swapi' (rootPath/baseURL)
baseURL: "swapi",
homepage: "./docs/swapi.md",
},
],
],
};
Each option is described in the section Options.
Plugin Loaders
Starting version 1.5.0
, docusaurus2-graphql-doc-generator
only provides graphql-file-loader
document loader out-of-the-box.
Thus, by default, the schema
default loading expects a local GraphQL schema definition file (*.graphql
).
However, this behavior can be extended by installing additional GraphQL document loaders (see full list).
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:
yarn add @graphql-tools/url-loader
Once done, you can declare the loader into docusaurus2-graphql-doc-generator
configuration:
plugins: [
[
'@edno/docusaurus2-graphql-doc-generator',
{
// ... other options
loaders: {
UrlLoader: "@graphql-tools/url-loader"
}
},
],
],
You can declare as many loaders as you need using the structure:
type className = string; // UrlLoader
type moduleName = string; // "@graphql-tools/url-loader"
type moduleOptions = { [option: string]: any };
type module = {
module: moduleName,
options: moduleOptions | undefined
}
type loaders = {
[className: className]: moduleName | module
}
Site Settings
You will also need to add a link to your documentation on your site. One way to do it is to add it to your site's navbar in docusaurus.config.js
:
module.exports = {
// ...
navbar: {
items: [
{
to: "/swapi/homepage", // adjust the location depending on your baseURL (see configuration)
label: "SWAPI Schema", // change the label with yours
position: "left",
},
],
},
};
For more details about navbar, please refer to Docusaurus 2 documentation.
Sidebars Settings
A sidebar file sidebar-schema.js
will be generated for the documentation, you have them different options depending on your Docusaurus setup:
1. Single Docs instance
In this use case, you have a unique set of documentation, then you just need to add a reference to sidebar-schema.js
into the default sidebar.js
.
module.exports = {
docsSidebar: [
// ... your site's sidebar
],
...require("./docs/swapi/sidebar-schema.js"),
};
Important
The sidebar path must be relative to the sidebars.js
location. By default, the plugin provides a relative path from the root folder of Docusaurus.
For example: if your
sidebars.js
is located under./src
folder, then you need to go one level up in the path:./../docs/swapi/sidebar-schema
2. Docs Multi-instance
In this use case, you have multiple sets of documentation (a.k.a. Docs Multi-instance), then you need to add a reference to sidebar-schema.js
into the dedicated instance of @docusaurus/plugin-content-docs
:
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'api',
path: 'api',
routeBasePath: 'api',
sidebarPath: require.resolve('./api/sidebar-schema.js'),
// ... other options
},
],
],
Home Page
If 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
:
---
id: schema
slug: /schema
title: Schema Documentation
sidebar_position: 1
---
This documentation has been automatically generated from the GraphQL schema.
Usage
The plugin adds a new command graphql-to-doc
to the Docusaurus CLI.
npx docusaurus graphql-to-doc
Options
By default, the plugin will use the options as defined in the plugin's configuration, but they can be overridden by passing them with the command.
| Config File | CLI Flag | Default | Description |
| ------------------ | -------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseURL
| -b, --base <baseURL>
| schema
| The base URL to be used by Docusaurus. It will also be used as folder name under rootPath
for the generated documentation. |
| diffMethod
| -d, --diff <diffMethod>
| SCHEMA-DIFF
| The method to be used for identifying changes in the schema for triggering the documentation generation. The possible values are: - SCHEMA-DIFF
: use GraphQL Inspector 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. |
| groupByDirective
| -gdb, --groupByDirective <@directive(field\ | =fallback)>
| - | Group documentation by directive (see below).
| homepage
| -h, --homepage <homepage>
| generated.md
| The location of the landing page to be used for the documentation, relative to the current workspace. The file will be copied at the root folder of the generated documentation.By default, the plugin provides a default page assets/generated.md
. |
| linkRoot
| -l, --link <linkRoot>
| /
| The root for links in documentation. It depends on the entry for the schema main page in the Docusaurus sidebar. |
| loaders
| | {GraphQLFileLoader: "@graphql-tools/graphql-file-loader"}
| GraphQL schema loader/s to be used (see Loaders). |
| rootPath
| -r, --root <rootPath>
| ./docs
| The output root path for the generated documentation, relative to the current workspace. The final path will be rootPath/baseURL
. |
| schema
| -s, --schema <schema>
| ./schema.graphql
| The schema location. It should be compatible with the GraphQL Tools schema loaders (see Loaders). |
| tmpDir
| -t, --tmp <tmpDir>
| OS temp folder | The folder used for storing schema copy and signature used by diffMethod
. |
| | -f, --force
| - | Force documentation generation (bypass diff). |
About diffMethod
The diffMethod
is only used for identifying if the schema has changed. If a change is detected since last documentation generation, then the full schema documentation will be generated.
About groupByDirective
The 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.
For example, we have two mutations called addCourse
and dropCourse
, and we want to group them together under a category called Courses
.
We 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.
type Mutation{
AddCourse(input: String): String @doc(category: "Course")
}
type Mutation{
DropCourse(input: String): String @doc(category: "Course")
}
It can be set either with the command line flag -gdb
:
npx docusaurus graphql-to-doc -gdb "@doc(category|=Common)"
or the plugin configuration groupByDirective
:
plugins: [
[
'@edno/docusaurus2-graphql-doc-generator',
{
// ... other options
groupByDirective: {
directive: "doc",
field: "category",
fallback: "Common", // default is Miscellaneous
}
},
],
],
Troubleshooting
Duplicate "graphql" modules cannot be used at the same time
Add a resolutions
entry to your package.json
file:
"resolutions": {
"graphql": "15.5.2"
}
Unable to find any GraphQL type definitions
Try changing the temporary folder for the plugin by setting tmpDir: "./.docusaurus"
(see options section for more details).
You can also disable the schema diff feature by setting diffMethod: "NONE"
.
Unable to find any GraphQL type definitions for the following pointers
This error may occur when upgrading to version
1.5.0
or above.
Install and declare the missing GraphQL document loader package, see Loaders.
If the error persists, check that you have the correct class name in the configuration declaration.
Contributions
Contributions, issues and feature requests are very welcome. If you are using this package and fixed a bug for yourself, please consider submitting a PR!
Made with contributors-img.