Schema loading

GraphQL-Markdown use external loaders for loading GraphQL schemas (see full list).

You can declare as many loaders as you need using a LoaderOption map:

type LoaderOption = {
  [name: ClassName]: PackageName | PackageConfig;
};

type PackageName = string & { _opaque: typeof PackageName };

type ClassName = string & { _opaque: typeof ClassName };

type PackageConfig = {
  module: PackageName;
  options?: PackageOptionsConfig;
};

type RootTypes = { query?: string; mutation?: string; subscription?: string };

type PackageOptionsConfig = BaseLoaderOptions & RootTypes;

Local schema (file)

Use @graphql-tools/graphql-file-loader if you want to load a local schema:

shell

npm install @graphql-tools/graphql-file-loader

Once done, you can declare the loader in @graphql-markdown/docusaurus configuration:

docusaurus.config.js

plugins: [
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // ... other options
      loaders: {
        GraphQLFileLoader: "@graphql-tools/graphql-file-loader"
      }
    },
  ],
],

Remote schema (url)

Use @graphql-tools/url-loader, if you want to load a schema from a URL:

shell

npm install @graphql-tools/url-loader

Once done, you can declare the loader in @graphql-markdown/docusaurus configuration:

docusaurus.config.js

plugins: [
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // ... other options
      loaders: {
        UrlLoader: {
          module: "@graphql-tools/url-loader",
          options: {
            headers: {
              Authorization: "<API_KEY>" // replace with your key if the gateway needs an auth key
             }
          }
        }
      }
    },
  ],
],

tip

See our Troubleshooting section in case of error 'UrlLoader' does not exist in type 'LoaderOption'.ts.

Code-first schema (TypeScript/JavaScript)

For teams using a code-first approach, use @graphql-tools/code-file-loader to load a schema exported directly from a TypeScript or JavaScript file:

shell

npm install @graphql-tools/code-file-loader

Once done, you can declare the loader in @graphql-markdown/docusaurus configuration:

docusaurus.config.js

plugins: [
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // ... other options
      schema: "./src/**/graphql/*.ts",
      loaders: {
        CodeFileLoader: "@graphql-tools/code-file-loader"
      }
    },
  ],
],

The schema file must export a GraphQLSchema instance as its default or named export. This works with any code-first library that produces a GraphQLSchema — including makeExecutableSchema (graphql-tools), Pothos, TypeGraphQL, and NestJS.