@graphql-markdown/docusaurus

@graphql-markdown/docusaurus

Docusaurus docs feature plugin for generating Markdown documentation from a GraphQL schema.

Installation

graphql package is a peer-dependency, and it should be installed separately.

npm install @graphql-markdown/docusaurus graphql

Add @graphql-markdown/docusaurus to your site's docusaurus.config.js plugins option:

module.exports = {
  // ...
  plugins: ["@graphql-markdown/docusaurus"],
};

Usage

The plugin adds a new command graphql-to-doc to the Docusaurus CLI.

npx docusaurus graphql-to-doc

Command line options are described in the documentation settings page.

Configuration

See documentation settings page.

Troubleshooting

See documentation troubleshooting page.

License

GraphQL-Markdown packages are 100% free and open-source, under the MIT license.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Changelog

1.19.0 - 2023-06-03

:warning: This release introduces minor breaking changes, see section breaking changes.

---

:label: Building upon customDirective released in 1.18.0, we added a new option tag that allows one to display custom badges (tags) in the documentation pages.

The feature is an extension of the customDirective by using the already available directive processing. It works the same way as descriptor, and it also comes with an helper directiveTag... more details in the documentation.

  customDirective: {
    beta: {
      tag: (directive) => ({
        text: directive?.name.toUpperCase(),
        classname: "badge--danger",
      }),
    },

Breaking changes

• Since tags have now a dedicated handler, the directives declared in customDirective for descriptor won't display a badge. A helper helper.directiveTag is provided for backward compatibility. Users who want to keep the previous behavior just need to declare tag: helper.directiveTag for each directive declared.

  const { helper } = require("@graphql-markdown/utils");
  
  //---//
    auth: {
        descriptor: (directive, type) =>
          helper.directiveDescriptor(
            directive,
            type,
            "This requires the current user to be in `${requires}` role.",
          ),
        tag: helper.directiveTag,
      },
  

• The deprecated "warning badge" has been changed into an admonition for a clearer UI.

  

• Last change is the change of position of the custom directive descriptions that are now after the type description instead of before.

  

What's Changed