graphql-markdown

🐛 Generated links now follow Docusaurus recommended practices to link docs files by full path. This fix adds the .mdx extension to generated links in Markdown files.

🐰 A CodeSandox demo using Docusaurus versioning is available here: https://codesandbox.io/p/devbox/determined-spence-mrpnmp

What's Changed

• ✨ support relative paths by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/1583
• 🧑‍💻 fix snyk reports by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/1585

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.24.3...1.24.4

🐛 This release removes the use of block quotes for type description, fixing issues like #1535

What's Changed

• 🐛 remove blockquotes by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/1572

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.24.2...1.24.3

🔧 Technical maintenance release for dependencies upgrades.

⚠️ This version removes compatibility with the graphql package version below 16 (see issue https://github.com/graphql-markdown/graphql-markdown/issues/1458).

What's Changed

• 📦 restrict graphql version to 16 and fix peer deps declarations in https://github.com/graphql-markdown/graphql-markdown/pull/1525

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.24.1...1.24.2

What's Changed

• 🐛 fix mdx special chars escaped in code section (https://github.com/graphql-markdown/graphql-markdown/pull/1382)
• 🐛 add missing support for non printable type in examples (https://github.com/graphql-markdown/graphql-markdown/pull/1419) reported by @Dodoboulistick in #1417

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.24.0...1.24.1

What's Changed

🤖 A new feature printTypeOptions.exampleSection adds supports for examples using schema directives.
The feature allows inheritance of examples, so once a scalar is set with an example all types using this scalar will share the example. And, of course, you can override those examples. You can also use a custom directive and custom parser.
More details in the documentation.

Object	Operation

The screenshots come from the Group by demo with the feature enabled.

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.23.0...1.24.0

What's changed

❇️ Executable types (operations and related directives) and system types (entity types) have now separate sections.
The behaviour can be disabled by setting the option printTypeOptions.useApiGroup to false or using the cli flag --noApiGroup (see documentation).

The online examples have been updated with one using the new sections and one with the option disabled. Note that the examples have some custom CSS that is not part of the default package.

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.22.0...1.23.0

🧑‍🔧 A new setting docOptions.frontMatter makes easier to generate pages with Docusaurus settings. Using this setting you can pass any front matter setting to the generator.

Example for the Docusaurus draft setting:

plugins: [
    [
      "@graphql-markdown/docusaurus",
       {
        schema: "./schema/swapi.graphql",
        docOptions: {
          frontMatter: {
            draft: true, // set draft for generated pages
          },
        },
      },
    ],
  ],

This option deprecates the options docOptions.pagination and docOptions.toc (more details in the documentation).

What's Changed

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.21.3...1.22.0

🐛 Fix the incorrect build for 1.21.2 that was missing the changes for #1101.

What's Changed

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/core to 1.7.3
• 📦 bump dependency @graphql-markdown/printer-legacy to 1.5.3

@graphql-markdown/[email protected]

• 📦 bump peer dependency @graphql-markdown/printer-legacy to 1.5.3

@graphql-markdown/[email protected]

• ✨ rebuild package

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.21.2...1.21.3

🪄 Improve compatibility with Docusaurus 3 by using the new admonition format for the deprecated admonition (see #1096).

What's Changed

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/core to 1.7.2 #1103
• 📦 bump dependency @graphql-markdown/printer-legacy to 1.5.2 #1103

@graphql-markdown/[email protected]

• 📦 bump peer dependency @graphql-markdown/printer-legacy to 1.5.2 #1103

@graphql-markdown/[email protected]

• ✨ (feat) replace caution admonition by warning for docusaurus v3 by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/1101

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.21.1...1.21.2

🚀 Fix compatibility with Docusaurus 3, since it MDX v3 is stricter than previous version used with Docusaurus 2.

💡 The compatibility with Docusaurus 2 is maintained, and there is no plan to drop it for now.

What's Changed

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/core to 1.7.1 #1075
• 📦 bump dependency @graphql-markdown/printer-legacy to 1.5.1 #1075

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/graphql to 1.0.1 #1075
• 📦 bump dependency @graphql-markdown/utils to 1.6.1 #1075
• 📦 bump peer dependency @graphql-markdown/diff to 1.1.1 #1075
• 📦 bump peer dependency @graphql-markdown/helpers to 1.0.1 #1075
• 📦 bump peer dependency @graphql-markdown/printer-legacy to 1.5.1 #1075
• 📦 bump peer dependency graphql-config to 5.0.3 #1075

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/graphql to 1.0.1 #1075

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/utils to 1.6.1 #1075

@graphql-markdown/[email protected]

• 🐛 fix docusaurus v3 support by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/1073
• 📦 bump dependency @graphql-markdown/graphql to 1.0.1 #1075
• 📦 bump dependency @graphql-markdown/utils to 1.6.1 #1075

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/graphql to 1.0.1 #1075
• 📦 bump dependency @graphql-markdown/utils to 1.6.1 #1075

@graphql-markdown/[email protected]

• 📝 udpate typedoc to fix compatibility with docusaurus v3 #1072

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.21.0...1.21.1

🚀 BIG release 🚀

This is an exceptionally big and packed release with a lot of changes, so read carefully the release notes before upgrading.

The main changes are under the hood as we migrated the codebase from Javascript to Typescript to simplify the coding experience but also to increase the code safety.

⚠️ Breaking changes

• Custom directive helpers have been moved to dedicated packages, see docs.

✨ New features

• onlyDocDirective filters the schema entities to be rendered in the documentation. This is the counterpart of skipDocDirective, based on a request from @brampurnot in #994. See documentation.
• metatags adds HTML metadata to pages using Docusaurus head metadata, based on a request from @akillkumar in #1015. See documentation.
• Helper directiveDescriptor now supports the description placeholder, where description is the default directive's description.

🛠️ Other changes

• Typing is available in a dedicated package @graphql-markdown/types.
• Modules helpers, graphql and logger have been extracted from @graphql-markdown/utils into dedicated packages.
• Logger has now a single method called log().
• TS API is getting documented, see API in the docs.
• More and better tests.
• Upgrade dependencies version.

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.20.4...1.21.0

This is a pre-release following the code base migration from JS to TS.

Breaking change

• Custom directive helpers have been moved to dedicated packages, see docs.

Patch change

• Helper directiveDescriptor now supports description placeholder, where description is the default directive description.

Technical change

• Typing is available in a dedicated package @graphql-markdown/types.
• Modules helpers, graphql and logger have been extracted from @graphql-markdown/utils into their own package.
• Logger has now a single method called Logger().
• TS API is getting documented, see API in our docs.
• More and better tests.

🧑‍💻 Technical release to freeze the last JS changes before the migration of the code to TS.

What's Changed

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/core to 1.6.4

@graphql-markdown/[email protected]

• 🐛 fix typo in generateDocFromSchema (no impact) by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/917

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.20.3...1.20.4

🐛 Fix a CSS issue for type badges in related type sections (see option printTypeOptions.relatedTypeSection).

• Before fix 😞
  

• After fix 😀
  

What's Changed

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/core to 1.6.3
• 📦 bump dependency @graphql-markdown/printer-legacy to 1.4.3

@graphql-markdown/[email protected]

• 📦 bump peerDependency @graphql-markdown/printer-legacy to 1.4.3

@graphql-markdown/[email protected]

• 🐛 fix badge css for relation of type sections by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/908

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.20.2...1.20.3

✨ New option printTypeOptions.codeSection and CLI flag --noCode for hiding the codeblock section, based on an initial request from @ris314 in https://github.com/graphql-markdown/graphql-markdown/issues/895. See documentation for more information.

What's Changed

@graphql-markdown/[email protected]

• ✨ add print option to hide code blocks by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/897
• 📦 bump dependency @graphql-markdown/core to 1.6.2
• 📦 bump dependency @graphql-markdown/printer-legacy to 1.4.2

@graphql-markdown/[email protected]

• ✨ add print option to hide code blocks by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/897
• 📦 bump peerDependency @graphql-markdown/printer-legacy to 1.4.2

@graphql-markdown/[email protected]

• ✨ add print option to hide code blocks by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/897

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.20.1...1.20.2

What's Changed

📦 Update compatibility with prettier v3 when using pretty setting. 🪄

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/core to 1.6.1
• 📦 bump dependency @graphql-markdown/printer-legacy to 1.4.1

@graphql-markdown/[email protected]

• 📦 chore(deps): update dependency prettier to v3 by @renovate in https://github.com/graphql-markdown/graphql-markdown/pull/892
• 📦 bump dependency @graphql-markdown/utils to 1.5.1
• 📦 bump peerDependency @graphql-markdown/diff to 1.0.14
• 📦 bump peerDependency @graphql-markdown/printer-legacy to 1.4.1

@graphql-markdown/[email protected]

• 📦 chore(deps): update dependency prettier to v3 by @renovate in https://github.com/graphql-markdown/graphql-markdown/pull/892

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/utils to 1.5.1

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/utils to 1.5.1

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.20.0...1.20.1

✨ GraphQL Config is now supported, see the documentation for more information and limitations 🚀

This is the default set up when creating a new site using the template.

First install the package graphql-config, then you are ready to go.

npm install graphql-config

Example .graphqlrc:

schema: "https://graphql.anilist.co/"
extensions:
  graphql-markdown:
    linkRoot: "/examples/default"
    baseURL: "."
    homepage: "data/anilist.md"
    loaders:
      UrlLoader:
        module: "@graphql-tools/url-loader"
        options: 
          method: "POST"
    printTypeOptions:
      deprecated: "group"
    docOptions:
      pagination: false
      toc: false

What's Changed

@graphql-markdown/[email protected]

• 🧑‍💻 force loading @docusaurus/logger on module init by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/886
• ✨ add graphql-config projects support by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/888
• 📦 bump dependency @graphql-markdown/core to 1.6.0

@graphql-markdown/[email protected]

• ✨ add support for graphql-config (#828) by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/885
• ✨ add graphql-config projects support by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/888
• ✨ support schema options in graphql-config by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/889
• 📦 bump peerDependency @graphql-markdown/diff to 1.0.13

@graphql-markdown/[email protected]

• 📦 fix(deps): update dependency @graphql-inspector/core to v4.2.2 by @renovate in https://github.com/graphql-markdown/graphql-markdown/pull/880
• 📦 fix(deps): update dependency @graphql-inspector/core to v5 by @renovate in https://github.com/graphql-markdown/graphql-markdown/pull/881

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.19.0...1.20.0

⚠️ This release introduces minor breaking changes, see section breaking changes.

🏷️ 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

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/core from 1.4.2 to 1.5.0
• 📦 bump dependency @graphql-markdown/printer-legacy from 1.3.1 to 1.3.2
• ✨ add custom logger support by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/869

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/utils from 1.4.1 to 1.5.0
• 📦 bump peerDependency @graphql-markdown/printer-legacy from 1.3.2 to 1.4.0
• 📦 bump peerDependency @graphql-markdown/diff from 1.0.11 to 1.0.12
• ✨ custom tags for types by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/863
• ✨ add custom logger support by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/869

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/utils from 1.4.1 to 1.5.0
• ✨ custom tags for types by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/863

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/utils from 1.4.0 to 1.4.1

@graphql-markdown/[email protected]

• ✨ custom tags for types by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/863
• ✨ add custom logger support by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/869

❇️ Add wildcard * support for customDirective, more details in the documentation.

What's Changed

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/core from 1.4.1 to 1.4.2
• 📦 bump dependency @graphql-markdown/printer-legacy from 1.3.1 to 1.3.2

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/utils from 1.4.0 to 1.4.1
• 📦 bump peerDependency @graphql-markdown/printer-legacy from 1.3.1 to 1.3.2
• 📦 bump peerDependency @graphql-markdown/diff from 1.0.10 to 1.0.11

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/utils from 1.4.0 to 1.4.1

@graphql-markdown/[email protected]

• 📦 fix(deps): update graphql-tools monorepo to v8 (major) by @renovate in https://github.com/graphql-markdown/graphql-markdown/pull/854
• 📦 bump dependency @graphql-markdown/utils from 1.4.0 to 1.4.1

@graphql-markdown/[email protected]

• 📦 fix(deps): update graphql-tools monorepo to v8 (major) by @renovate in https://github.com/graphql-markdown/graphql-markdown/pull/854
• ✨ add wildcard support to custom directive feature by @edno in https://github.com/graphql-markdown/graphql-markdown/pull/860

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.18.1...1.18.2

🐛 Fix missing code indentation for fields in some cases (#850) by @ljiang-ti in #851.

What's Changed

@graphql-markdown/[email protected]

• 📦 bump dependency @graphql-markdown/core from 1.4.0 to 1.4.1
• 📦 bump dependency @graphql-markdown/printer-legacy from 1.3.0 to 1.3.1

@graphql-markdown/[email protected]

• 📦 bump peerDependency @graphql-markdown/printer-legacy from 1.3.0 to 1.3.1

@graphql-markdown/[email protected]

• 🐛 Fix indentation level in code section by @ljiang-ti in https://github.com/graphql-markdown/graphql-markdown/pull/851

Full Changelog: https://github.com/graphql-markdown/graphql-markdown/compare/1.18.0...1.18.1