# GraphQL-Markdown Documentation

> Human-friendly documentation for GraphQL-Markdown schemas and tooling.

Complete offline export of the core docs, API reference, and worked examples published on graphql-markdown.dev.

## Introduction


GraphQL-Markdown generates Markdown and MDX documentation from a GraphQL schema. You can use the official Docusaurus integration for Docusaurus sites, or use the CLI with formatter presets for other supported documentation ecosystems such as Hugo, MkDocs, DocFX, and mdBook.

## Why GraphQL Markdown?

Managing API documentation can be time-consuming and prone to becoming outdated. This package solves these challenges by:

- Automatically generating documentation from your schema
- Keeping documentation in sync with your API
- Providing a consistent documentation structure
- Integrating with Docusaurus and supported formatter-based documentation ecosystems

## Features

- Easy set up and customizable output
- Full cross-linking between types with visual relationship hierarchy
- MDX output fully customizable using your own components
- Extensible lifecycle hooks and events system
- Any schema loader compatible with `@graphql-tools/load` — SDL files, remote endpoints, or code-first TS/JS schemas
- Group types into categories using directives
- Namespaced operations (nested query/mutation/subscription objects)
- GraphQL config support

## Quick Install

For **Docusaurus** projects:

```bash
npm install @graphql-markdown/docusaurus graphql
```

For **formatter-based setups** (Hugo, MkDocs, DocFX, mdBook, Astro, Next.js, etc.):

```bash
npm install @graphql-markdown/cli @graphql-markdown/formatters graphql
```

For the full list of supported formatter presets, see [Integration with Frameworks](/docs/advanced/integration-with-frameworks).

---

## Getting started


:::info

GraphQL-Markdown supports two main setup paths:

- the official Docusaurus integration for Docusaurus sites
- the CLI with formatter presets for other supported documentation ecosystems

This guide focuses on the Docusaurus path. If you are using Hugo, MkDocs, DocFX, mdBook, or another supported formatter-based setup, start with our [Framework Integration Guide](/docs/advanced/integration-with-frameworks).

:::

If you are setting up Docusaurus, get started by [creating a new site](#new-docusaurus-site).

Or try GraphQL-Markdown immediately with our [demo](/docs/try-it).

If you are not using Docusaurus, install the CLI and formatter presets:

```shell title="shell"
npm install @graphql-markdown/cli @graphql-markdown/formatters graphql
```

Then continue with [Integration with Frameworks](/docs/advanced/integration-with-frameworks) to choose the preset for your documentation stack.

## New Docusaurus site

### Requirements

Node.js version [22.12](https://nodejs.org/en/download/) or above (which can be checked by running `node -v`) is required.

:::info[Package managers]

You can use either `npm`, `yarn`, or `pnpm` as your package manager. The examples in this documentation use `npm`, but you can substitute the commands with your preferred package manager.

When installing Node.js, you are recommended to check all checkboxes related to dependencies.

:::

:::tip

You can use [nvm](https://github.com/nvm-sh/nvm), installed on a single machine, to manage multiple Node.js versions.

:::

### Generate a new site

Generate a new Docusaurus site using the [GraphQL-Markdown template](https://github.com/graphql-markdown/template).

The template will automatically be added to your project after you run the command:

```shell title="shell"
npm init docusaurus my-website https://github.com/graphql-markdown/template.git
```

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.

The command also installs all the necessary dependencies you need to run Docusaurus.

### Add a GraphQL schema loader

A schema loader is required to load your GraphQL schema. The template comes with `@graphql-tools/url-loader` pre-configured for remote schemas.

See [schema loading](/docs/advanced/schema-loading) for other loaders and configuration options.

### Start your site

Run the development server:

```shell title="shell"
cd my-website
npm start
```

:::tip

The `npm run doc` command is a shortcut in the template for command-line document generation: `npm run docusaurus graphql-to-doc`.

:::

The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at [http://localhost:3000/](http://localhost:3000/).

## Existing Docusaurus site

### Prerequisites

:::note

These requirements are specific to Docusaurus integration. See our [Framework Integration Guide](/docs/advanced/integration-with-frameworks) for formatter-based setups and their requirements.

:::

Your project needs to meet the following requirements:

- Node.js version [22.12](https://nodejs.org/en/download/) or above
- [Docusaurus](https://docusaurus.io/) instance version 2.0 or above with the [docs plugin](https://docusaurus.io/docs/docs-introduction) enabled
- [GraphQL.js](https://graphql.org/graphql-js/) version 16.0 or above

### Install the plugin

Add the `@graphql-markdown/docusaurus` plugin to your site installation:

```shell title="shell"
npm install @graphql-markdown/docusaurus graphql
```

### Add a schema loader

See [schema loading](/docs/advanced/schema-loading).

### Configure the plugin

See [configuration](/docs/configuration).

## Update your documentation

Build your website:

```shell title="shell"
npm run docusaurus build
```

Or run the documentation generator directly:

```shell title="shell"
npm run docusaurus graphql-to-doc
```

The `npm run docusaurus graphql-to-doc` command generates MDX files locally from your GraphQL schema. The possible command flags are documented in [settings](/docs/settings).

---

## Try it


## Docusaurus

Use the [CodeSandbox template](https://codesandbox.io/p/sandbox/github/graphql-markdown/demo-docusaurus/tree/main?file=/.graphqlrc) or fork our [demo repo](https://github.com/graphql-markdown/demo-docusaurus) to try with your own GraphQL schema.

Edit the configuration in `.graphqlrc`.

## Astro/Starlight

Use the [CodeSandbox template](https://codesandbox.io/p/sandbox/github/graphql-markdown/demo-astro-starlight/tree/main?file=/.graphqlrc) or fork our [demo repo](https://github.com/graphql-markdown/demo-astro-starlight) to try with your own GraphQL schema.

Edit the configuration in `graphql.config.mjs`.

## Next.js/Fumadocs

Use the [CodeSandbox template](https://codesandbox.io/p/sandbox/github/graphql-markdown/demo-nextjs-fumadocs/tree/main?file=/.graphqlrc) or fork our [demo repo](https://github.com/graphql-markdown/demo-nextjs-fumadocs) to try with your own GraphQL schema.

Edit the configuration in `graphql.config.mjs`.

## Vite/Vocs

Fork our [demo repo](https://github.com/graphql-markdown/demo-vite-vocs) to try with your own GraphQL schema.

Edit the configuration in `graphql.config.mjs`.

## HonKit / GitBook legacy

Fork our [demo repo](https://github.com/graphql-markdown/demo-honkit) to try with your own GraphQL schema.

Edit the configuration in `graphql.config.mjs`.

## Hugo

Fork our [demo repo](https://github.com/graphql-markdown/demo-hugo) to try with your own GraphQL schema.

Edit the configuration in `.graphqlrc.yml`.

## MkDocs

Fork our [demo repo](https://github.com/graphql-markdown/demo-mkdocs) to try with your own GraphQL schema.

Edit the configuration in `scripts/generate-docs.mjs`.

## mdBook

Fork our [demo repo](https://github.com/graphql-markdown/demo-mdbook) to try with your own GraphQL schema.

Edit the configuration in `scripts/generate-docs.mjs`.

## DocFX

Fork our [demo repo](https://github.com/graphql-markdown/demo-docfx) to try with your own GraphQL schema.

Edit the configuration in `scripts/generate-docs.mjs`.

---

## How It Works


GraphQL-Markdown reads your schema, parses every type and operation, and writes one MDX file per type category — ready to publish with Docusaurus or any MDX framework.

## Pipeline

![pipeline](/img/docs/pipeline.png)

### Input

Given this schema:

```graphql
type User {
  """User's unique identifier"""
  id: ID!
  """User's full name"""
  name: String!
  """List of posts authored by this user"""
  posts: [Post!]
}

type Post {
  id: ID!
  title: String!
  author: User!
}

type Query {
  getUser(id: ID!): User
  getPosts: [Post!]!
}
```

### Output

GraphQL-Markdown generates a file per type category. For example, `objects/user.mdx`:

```mdx
---
id: user
title: User
---

# User

Object Type

## Fields

| Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | `ID!` | User's unique identifier |
| `name` | `String!` | User's full name |
| `posts` | [`[Post!]`](/docs/graphql/objects/post) | List of posts authored by this user |

## Returned by

[`getUser`](/docs/graphql/queries/get-user)
```

Notice the cross-link on `Post` and the back-reference under "Returned by" — these are generated automatically from the schema graph.

## What gets generated

| Output | Description |
| ------ | ----------- |
| `objects/` | One file per Object type |
| `inputs/` | One file per Input type |
| `queries/` | One file per Query field |
| `mutations/` | One file per Mutation field |
| `subscriptions/` | One file per Subscription field |
| `enums/` | One file per Enum type |
| `interfaces/` | One file per Interface type |
| `unions/` | One file per Union type |
| `scalars/` | One file per Scalar type |
| `_category_.yml` | Sidebar metadata for each folder |

## Customization

The generation pipeline exposes lifecycle hooks at every stage — before/after schema load, before/after rendering each type, before/after composing each page. See [hook recipes](/docs/advanced/hook-recipes) and [custom directives](/docs/advanced/custom-directive).

To see the full output in action, browse the [live examples](/examples/default).

---

## Configuration Cheat Sheet


:::note
This is a quick reference guide. All settings are thoroughly documented in the [**Settings** page](/docs/settings).
:::

:::tip
For formatter-based setups, prefer `formatter`. The older `mdxParser` setting and CLI flag are deprecated aliases.
:::

## Essential Options

| Option     | Type     | Default    | Description                                               |
| ---------- | -------- | ---------- | --------------------------------------------------------- |
| `schema`   | `string` | —          | **Required**. Path to schema file or introspection result |
| `rootPath` | `string` | `./docs`   | Root folder for documentation generation                  |
| `baseURL`  | `string` | `schema`   | Base URL path and output folder name under `rootPath`     |

## Document Structure

| Option             | Type                   | Default        | Description                                                      |
| ------------------ | ---------------------- | -------------- | ---------------------------------------------------------------- |
| `linkRoot`         | `string`               | `/`            | Root path used for type cross-links in generated documentation   |
| `homepage`         | `string` \| `false`    | `generated.md` | Custom homepage content file, `false` to disable                 |
| `hierarchy`        | `string`               | `api`          | Documentation structure: `api`, `entity`, or `flat`              |
| `index`            | `boolean`              | `false`        | Generate category indices                                        |
| `categorySort`     | `string` \| `function` | —              | Sort categories: `"natural"` for alphabetical or custom function |
| `sectionHeaderId`  | `boolean`              | `true`         | Generate custom section header IDs for permalinks                |
| `pretty`           | `boolean`              | `false`        | Format generated Markdown files                                  |

## Content Options

| Option         | Type      | Default | Description             |
| -------------- | --------- | ------- | ----------------------- |
| `noParentType` | `boolean` | `false` | Hide parent type prefix |
| `noTypeBadges` | `boolean` | `false` | Hide type badges        |

## Filtering Options

| Option             | Type       | Default   | Description                                                        |
| ------------------ | ---------- | --------- | ------------------------------------------------------------------ |
| `groupByDirective` | `string`   | —         | Group by directive: `@directive(field)` or `@directive(=fallback)` |
| `only`             | `string[]` | —         | Include only types with specified directives                       |
| `skip`             | `string[]` | —         | Exclude types with specified directives                            |
| `deprecated`       | `string`   | `default` | Handling of deprecated items: `default`, `group`, `skip`           |

## Build Control Options

| Option        | Type      | Default | Description                                                       |
| ------------- | --------- | ------- | ----------------------------------------------------------------- |
| `force`       | `boolean` | `false` | Force regeneration of all files                                   |
| `diffMethod`  | `string`  | `NONE`  | Change detection: `NONE`, `FORCE`, `SCHEMA-DIFF`, `SCHEMA-HASH`   |
| `tmpDir`      | `string`  | —       | Temporary directory for storing schema signature (used by diff)   |
| `pretty`      | `boolean` | `false` | Format output files with Prettier (requires `prettier` installed) |
| `formatter`   | `string`  | —       | Package name or path to a custom formatter module                 |
| `outputAdapter` | `object` | fs     | Write pages somewhere other than the local filesystem             |

## CLI Flags

All config options can be passed as CLI flags to `npx docusaurus graphql-to-doc` (Docusaurus plugin) or `npx gqlmd graphql-to-doc` (standalone CLI).

| Flag                              | Config option                         | Description                                    |
| --------------------------------- | ------------------------------------- | ---------------------------------------------- |
| `-s, --schema <path>`             | `schema`                              | Schema file, URL, or introspection JSON        |
| `-b, --base <baseURL>`            | `baseURL`                             | Base URL and output folder name                |
| `-r, --root <rootPath>`           | `rootPath`                            | Root output folder                             |
| `-l, --link <linkRoot>`           | `linkRoot`                            | Root path for cross-links                      |
| `-h, --homepage <file>`           | `homepage`                            | Custom homepage file                           |
| `-f, --force`                     | `force`                               | Skip diff, always regenerate                   |
| `-d, --diff <method>`             | `diffMethod`                          | Diff method (`NONE`, `SCHEMA-DIFF`, etc.)      |
| `-t, --tmp <dir>`                 | `tmpDir`                              | Temp dir for schema diffing                    |
| `--index`                         | `docOptions.index`                    | Generate category index pages                  |
| `--hierarchy <type>`              | `printTypeOptions.hierarchy`          | Folder structure: `api`, `entity`, `flat`      |
| `--deprecated <option>`           | `printTypeOptions.deprecated`         | `default`, `group`, or `skip`                  |
| `--noParentType`                  | `printTypeOptions.parentTypePrefix`   | Hide parent type prefix on fields              |
| `--noTypeBadges`                  | `printTypeOptions.typeBadges`         | Hide type attribute badges                     |
| `--noSectionId`                   | `docOptions.sectionHeaderId`          | Disable section header IDs for permalinks      |
| `--only <@directive...>`          | `onlyDocDirective`                    | Include only types with these directives       |
| `--skip <@directive...>`          | `skipDocDirective`                    | Exclude types with these directives            |
| `--groupByDirective <expr>`       | `groupByDirective`                    | Group by directive: `@dir(field\|=fallback)`   |
| `--pretty`                        | `pretty`                              | Format output with Prettier                    |
| `--formatter <pkg>`[^1]           | `formatter`                           | Formatter package name or path                 |
| `--mdxParser <pkg>`[^1]           | ~~`mdxParser`~~ (deprecated)          | Deprecated alias for `formatter`               |
| `--config`                        | —                                     | Print resolved config (debug)                  |

[^1]: The `--formatter` and `--mdxParser` flags are only registered when the CLI is set up with a default formatter package, as done by `@graphql-markdown/docusaurus`. The standalone `gqlmd` command does not expose them &mdash; set `formatter` in your configuration file instead.

---

## Configuration


GraphQL-Markdown supports three configuration methods. Use GraphQL Config for framework-agnostic setups, use Docusaurus plugin options for Docusaurus sites, and use CLI flags when you need temporary overrides. Later entries in this list take precedence over earlier ones.

## Framework-agnostic Configuration

### GraphQL Config

:::tip
GraphQL Config is the recommended way to configure GraphQL-Markdown across all frameworks.
:::

You can use a [GraphQL Config](https://the-guild.dev/graphql/config/docs/user/usage) file (multiple formats supported) to configure GraphQL-Markdown:

```yaml title=".graphqlrc"
schema: "https://graphql.anilist.co/"
extensions:
  graphql-markdown:
    linkRoot: "/examples/default"
    baseURL: "."
    homepage: "data/anilist.md"
    formatter: "@graphql-markdown/formatters/hugo"
    loaders:
      UrlLoader:
        module: "@graphql-tools/url-loader"
        options:
          method: "POST"
    printTypeOptions:
      deprecated: "group"
```

For supported formatter presets, see [Integration with Frameworks](/docs/advanced/integration-with-frameworks).

## Docusaurus Integration

### Plugin Configuration

You can define plugin settings directly in your Docusaurus configuration file `docusaurus.config.js`:

```js title="docusaurus.config.js"
module.exports = {
  // ...
  plugins: [
    [
      "@graphql-markdown/docusaurus",
      /** @type {import('@graphql-markdown/types').ConfigOptions} */
      {
        schema: "./schema/swapi.graphql",
        rootPath: "./docs", // docs will be generated under './docs/swapi' (rootPath/baseURL)
        baseURL: "swapi",
        homepage: "./docs/swapi.md",
        loaders: {
          GraphQLFileLoader: "@graphql-tools/graphql-file-loader", // local file schema
        },
        // Optional advanced settings
        pretty: true,
      },
    ],
  ],
};
```

All settings are described in the page **[settings](/docs/settings)**.

:::tip

If you want to use several GraphQL schemas, read our guide for **[additional schemas](/docs/advanced/additional-schema)**.

:::

### 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`:

```js title="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 the `navbar`, please refer to Docusaurus [documentation](https://docusaurus.io/docs/api/themes/configuration#navbar).

## Configuration Lifecycle

GraphQL-Markdown processes configuration sources in the following priority order (later sources override earlier ones):

1. **Default configuration**: Built-in default settings
2. **GraphQL Config file** (`.graphqlrc`): Framework-agnostic project settings
3. **Framework-specific configuration**: (e.g., Docusaurus plugin settings)
4. **CLI flags**: Command-line arguments override all other settings

:::tip
For any framework, you can use CLI flags to temporarily override settings without modifying your configuration files.
:::

**Current limitations:**

- Single schema only, no schema stitching
- `include`, `exclude`, `documents` and glob pattern are not supported

---

## Additional schemas


If you need to support multiple schemas, then you can set multiple instances of the plugin

Assign a unique `id` attribute to each plugin instance (if not set, then `id` value is `default`).

```js title="docusaurus.config.js"
plugins: [
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // highlight-next-line
      // id: 'default', // omitted => default instance
      schema: "./schema/swapi.graphql",
      rootPath: "./docs", // docs will be generated under './docs/swapi' (rootPath/baseURL)
      baseURL: "swapi",
      homepage: "./docs/swapi.md",
      loaders: {
        GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
      }
    },
  ],
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // highlight-next-line
      id: "admin",
      schema: "./schema/admin.graphql",
      rootPath: "./docs", // docs will be generated under './docs/admin' (rootPath/baseURL)
      baseURL: "admin",
      homepage: "./docs/admin.md",
      loaders: {
        GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
      }
    },
  ],
],
```

Instance with an `id` will have their command line:

```shell
npm run docusaurus graphql-to-doc:admin
```

## GraphQL Config

If you use [GraphQL config](/docs/configuration#graphql-config), then you need to define `projects` with the same `id` (including `default`).

```js title="docusaurus.config.js"
plugins: [
  "@graphql-markdown/docusaurus", // default instance
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // highlight-next-line
      id: "admin",
    },
  ],
],
```

```yaml title=".graphqlrc"
projects:
  # highlight-next-line
  default:
    schema: "./schema/swapi.graphql"
    extensions:
      graphql-markdown:
        linkRoot: "./docs"
        baseURL: "swapi"
        homepage: "./docs/swapi.md"
        loaders:
          GraphQLFileLoader: "@graphql-tools/graphql-file-loader"
  # highlight-next-line
  admin:
    schema: "./schema/admin.graphql"
    extensions:
      graphql-markdown:
        linkRoot: "./docs"
        baseURL: "admin"
        homepage: "./docs/admin.md"
        loaders:
          GraphQLFileLoader: "@graphql-tools/graphql-file-loader"
```

---

## Customize deprecated sections


When using the option [`printTypeOptions.deprecated`](/docs/settings#printtypeoptions) set to `group`, the rendering can be customized using the CSS class `.deprecated`.

Adding a `warning` emoji ⚠️ is done with a quick tweak of [Docusaurus CSS](https://docusaurus.io/docs/styling-layout).

```css title="/src/css/custom.css"
.deprecated a::after,
span.deprecated::after {
  content: "⚠️";
  padding-left: 4px !important;
  transform: none !important;
}

.deprecated {
  padding-top: 1rem;
}
```

The above CSS will render the deprecated sections as the following

![custom-deprecated-section](/img/docs/custom-deprecated-section.png)

---

## Custom schema directives handling


For directives applied to the schema, you can select which ones to be rendered for the types or in the locations they are declared. Information about the custom directives includes a custom description.

For example, we have one query called `searchRole`, and we want to limit access to `ADMIN` user roles only.

We can accomplish this by adding a directive called `auth` with an argument `requires` to the query.

```graphql
directive @auth(requires: Roles = ADMIN) on OBJECT | FIELD_DEFINITION

enum Roles {
  ADMIN
  USER
}

type Query {
  searchRole(roles: [Roles!]! = [ADMIN]): Int! @auth
}
```

## Usage

Add the option [`customDirective`](/docs/settings#customdirective) to the `@graphql-markdown/docusaurus` configuration.

The `descriptor` and `tag` functions receive 2 arguments:

- `directive` of type [`GraphQLDirective`](https://github.com/graphql/graphql-js/blob/main/src/type/directives.ts)
- `node` of type [`GraphQLNamedType`](https://github.com/graphql/graphql-js/blob/main/src/type/definition.ts) or [`ASTNode`](https://github.com/graphql/graphql-js/blob/main/src/language/ast.ts)

```ts
type DirectiveName = string & { _opaque: typeof DirectiveName };

type CustomDirective = {
  [name: DirectiveName]: {
    descriptor?: (directive?: GraphQLDirective, node?: unknown): string;
    tag?: (directive?: GraphQLDirective, node?: unknown): Badge;
  };
};

type Badge = {
  text: string | TypeLocale;
  classname: string;
};
```

### `descriptor`

The `descriptor` allows rendering the custom directive's description applicable to entities.

```js title="docusaurus.config.js"
plugins: [
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // ... other options
      customDirective: {
        auth: {
          // highlight-start
          descriptor: (directive, node) =>
            directiveDescriptor(
              directive,
              node,
              "This requires the current user to be in `${requires}` role.",
            ),
          // highlight-end
        }
        // ... other custom directive options
      },
    },
  ],
],
```

### `tag`

The `tag` allows rendering custom badges (tags) based on the custom directive applicable to entities.

```js title="docusaurus.config.js"
plugins: [
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // ... other options
      customDirective: {
        beta: {
          // highlight-next-line
          tag: (directive, node) => ({ text: directive.name, classname: "badge--info" }),
        }
        // ... other custom directive options
      },
    },
  ],
],
```

### Wildcard

You can use **`"*"` as a wildcard** for the directive name. This will allow all directives not declared with their name under `customDirective` to be handled by the wildcard `descriptor` and/or `tag`.

```js title="docusaurus.config.js"
const { directiveDescriptor, directiveTag } = require("@graphql-markdown/helpers");

//...//

plugins: [
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // ... other options
      customDirective: {
        // highlight-start
        "*": {
          descriptor: directiveDescriptor,
          tag: directiveTag,
        },
        // highlight-end
        // ... optionally specific custom directive options
      },
    },
  ],
],
```

## Helpers

The packages `@graphql-markdown/helpers` and `@graphql-markdown/graphql` provide a few helper functions to quickly start.

:::info

`@graphql-markdown/helpers` is an optional peer dependency, and it needs to be installed before using it.

```shell title="shell"
npm i @graphql-markdown/helpers
```

:::

### `@graphql-markdown/helpers`

- [`directiveDescriptor`](/api/helpers/directives/descriptor)
- [`directiveTag`](/api/helpers/directives/tag)

### `@graphql-markdown/graphql`

- [`getTypeDirectiveValues`](/api/graphql/introspection#gettypedirectivevalues)
- [`getTypeDirectiveArgValue`](/api/graphql/introspection#gettypedirectiveargvalue)

---

## Custom root types


For custom operation root types (queries not of type `Query`, or root type name used for other purpose), use the loader option `RootTypes`:

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

- use a custom type name to override the standard type
- use an empty string to disable the GraphQL standard type
- unset root types will use the GraphQL standard type

Add the option `rootTypes` to the loader options under `@graphql-markdown/docusaurus` configuration (see also [schema loading](/docs/advanced/schema-loading)):

```js title="docusaurus.config.js"
plugins: [
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // ... other options
      loaders: {
        GraphQLFileLoader: {
          module: "@graphql-tools/graphql-file-loader",
          options: {
            // highlight-start
            rootTypes: {
              query: "Root", // use custom root type Root for queries, instead of Query
              subscription: "" // disable Subscription type
            },
            // highlight-end
          },
        },
      },
    },
  ],
],
```

---

## Examples


Examples are added to types documentation as soon as the schema declares an `@example` directive. The option [`printTypeOptions.exampleSection`](/docs/settings#printtypeoptions) is only needed when the directive name, its field, or the value parsing has to be customized (see [advanced options](#advanced-options)).

## Usage

**1. Add a type definition directive `@example` to the schema**

  ```graphql
  directive @example(
    value: String
  ) on OBJECT | INPUT_OBJECT | INTERFACE | FIELD_DEFINITION | ARGUMENT_DEFINITION | SCALAR
  ```

**2. Add examples to the schema**

  ```graphql
  scalar Date @example(value: "1970-01-01")

  interface Record {
    id: ID! @example(value: "1")
  }

  type Course implements Record @example(value: "{ \"id\": 2, \"title\": \"GraphQL\" }") {
    id: ID!
    title: String!
  } 

  type Semester implements Record {
    id: ID!
    startDate: Date
    withdrawDate: Date @deprecated
    endDate: Date
    courses: [Course!]!
  }

  type Query {
    course(id: ID!): Course @example(value: "{ course(id: \"1\") { title } }")
  }
  ```

Examples can be inherited, this is why in the above example there is no example explicitly set for the type `Semester`, and it will render as the following

![examples](/img/docs/examples.png)

## Advanced options

Example directive definition and parser behavior can be customized through the configuration by setting `printTypeOptions.exampleSection` to a `TypeExampleSectionOption` object (any other value is ignored, and the defaults `@example(value: ...)` apply):

```ts
interface TypeExampleSectionOption {
  directive?: string; // customize the directive name
  field?: string; // customize the directive's field name
  parser?: (value?: unknown, type?: unknown) => unknown; // customize the field's value parsing
}
```

For example, if the GraphQL schema already supports examples using the `@spectaql` directive.

```graphql
type CustomExampleDirective {
  myField: String @spectaql(options: [{ key: "undocumented", value: "true" }])
  myFieldOtherField: String @spectaql(options: [{ key: "example", value: "An Example from the Directive" }])
  myFieldOtherOtherField: String @spectaql(options: [{ key: "examples", value: "[\"Example 1 from the Directive\", \"Example 2 from the Directive\"]" }])
}
```

```js title="docusaurus.config.js"
plugins: [
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // ... other options
      printTypeOptions: {
        exampleSection: {
          directive: "spectaql",
          field: "options",
          /* simplified parser for @spectaql (non production ready) */
          parser: (options, type) => {
            if (!options) {
              return undefined;
            }

            const example = options.find(
              (option) => {
                return ["example", "examples"].includes(option.key);
              },
            );

            if (!example) {
              return undefined;
            }

            if (example.key === "example") {
              return example.value;
            }

            return JSON.parse(example.value)[0];
          }
        }
      }
    }
  ]
]
```

---

## Documentation categories


You can group the documentation to provide 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 under a category called `Courses`.

```graphql
type Mutation {
  AddCourse(input: String): String
  DropCourse(input: String): String
}
```

## Usage

We can accomplish this by adding a directive called `doc` with a field `category` to each mutation.

```graphql
type Mutation {
  AddCourse(input: String): String @doc(category: "Course")
  DropCourse(input: String): String @doc(category: "Course")
}
```

We can add a fallback option called `Common` which is for types that we don't explicitly add a directive to.

It can be set either with the command line flag `--groupByDirective`:

```shell
npx docusaurus graphql-to-doc --groupByDirective "@doc(category|=Common)"
```

or the plugin configuration `groupByDirective`:

```js title="docusaurus.config.js"
plugins: [
  [
    "@graphql-markdown/docusaurus",
    /** @type {import('@graphql-markdown/types').ConfigOptions} */
    {
      // ... other options
      // highlight-start
      groupByDirective: {
        directive: "doc",
        field: "category",
        fallback: "Common", // default is Miscellaneous
      }
      // highlight-end
    },
  ],
],
```

---

## Homepage


If you decide to use a custom homepage for the GraphQL-generated documentation, then set the sidebar position to `sidebar_position: 1` to ensure it shows first:

```markdown title="schema.md"
---
id: schema
slug: /schema
title: Schema Documentation
sidebar_position: 1
---

This documentation has been automatically generated from the GraphQL schema.
```

:::tip

If you want to hide the homepage from the sidebar, then set the front matter `sidebar_class_name` (or `className` depending on your Docusaurus version) to `navbar__toggle`.

```markdown {6} title="schema.md"
---
id: schema
slug: /schema
title: Schema Documentation
sidebar_position: 1
sidebar_class_name: navbar__toggle
---
```

:::

---

## Hooks Recipes


This page lists examples of usage of [hooks](/api/category/events).

:::info

Hooks are part of the [documentation frameworks integration](./integration-with-frameworks.md) API.

:::

## Available Hooks

GraphQL-Markdown provides lifecycle hooks for customizing the documentation generation process.

### Generation Hooks

| Hook                                | Description                                  |
| ----------------------------------- | -------------------------------------------- |
| `beforeLoadSchemaHook`              | Called before loading the GraphQL schema     |
| `afterLoadSchemaHook`               | Called after loading the GraphQL schema      |
| `beforeCheckDiffHook`               | Called before checking schema differences    |
| `afterCheckDiffHook`                | Called after checking schema differences     |
| `beforeRenderRootTypesHook`         | Called before rendering root types           |
| `afterRenderRootTypesHook`          | Called after rendering root types            |
| `beforeRenderHomepageHook`          | Called before rendering the homepage         |
| `afterRenderHomepageHook`           | Called after rendering the homepage          |
| `beforeRenderTypeEntitiesHook`      | Called before rendering type entities        |
| `afterRenderTypeEntitiesHook`       | Called after rendering type entities         |
| `beforeGenerateIndexMetafileHook`   | Called before generating index metafiles     |
| `afterGenerateIndexMetafileHook`    | Called after generating index metafiles      |
| `afterRenderFilesHook`              | Called once after all pages have been written — receives the full pages collection |

### Printer Hooks

| Hook                          | Description                                                                             |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| `beforePrintCodeHook`         | Called before generating code blocks — can modify options or prevent default generation |
| `afterPrintCodeHook`          | Called after generating code blocks — can modify the generated output                   |
| `beforePrintTypeHook`         | Called before generating type documentation — can modify options or prevent default     |
| `afterPrintTypeHook`          | Called after generating type documentation — can modify the generated output            |
| `beforeComposePageTypeHook`   | Called before composing type page sections — can reorder, remove, or inject sections    |

:::info

All hooks receive an `event` object with a `data` property containing context-specific information. Printer hooks also have an `output` property that can be modified.

For `beforeComposePageTypeHook`, `event.output` is the ordered list of section keys to render, and `event.data.sections` is the section content map.

:::

## Using Hooks with Docusaurus

When using Docusaurus, you can extend the default MDX module to add custom hooks while keeping all the built-in formatters:

```js title="custom-mdx.cjs"
const DocusaurusMDX = require("@graphql-markdown/docusaurus/mdx");

const afterPrintCodeHook = async (event) => {
  // Your custom logic here
  event.output = `${event.output}\n\n<!-- Custom content -->`;
};

module.exports = {
  ...DocusaurusMDX,  // Keep all default formatters
  afterPrintCodeHook, // Add your custom hook
};
```

Then configure your Docusaurus plugin to use the custom module:

```js title="docusaurus.config.js"
plugins: [
  [
    "@graphql-markdown/docusaurus",
    {
      schema: "./schema.graphql",
      // highlight-next-line
      formatter: require.resolve("./custom-mdx.cjs"),
      // ... other options
    },
  ],
],
```

## Generate index.md files

You can use this hook to generate `index.md` files.

```md
---
title: "Unions"
---

- [ActivityUnion](./activity-union.mdx)
- [LikeableUnion](./likeable-union.mdx)
- [NotificationUnion](./notification-union.mdx)
```

Declare the custom module in GraphQL-Markdown configuration `formatter: "./custom-mdx.mjs"`.

```js title="custom-mdx.mjs"

import { join, dirname, resolve, basename } from "node:path";
import { appendFile } from "node:fs/promises";

import {
  ensureDir,
  fileExists,
  saveFile,
  startCase,
} from "@graphql-markdown/utils";

const INDEX_MD = "index.md";

/**
 * Hook that generates an index metadata file for a category directory.
 * 
 * This hook is executed before generating index metadata files. 
 * It checks if an index.md file exists in the specified directory. 
 * If not, it creates one with a title derived from the category name.
 */
const beforeGenerateIndexMetafileHook = async (event) => {
  const { dirPath, category } = event.data;
  const filePath = join(dirPath, INDEX_MD);

  if (await fileExists(filePath)) {
    return;
  }

  const label = startCase(category);
  const content = `---\ntitle: "${label}"\n---\n\n`;
  await ensureDir(dirPath);
  await saveFile(filePath, content);
};

/**
 * Hook that appends a link to the entity's page in the index file after rendering type entities.
 * 
 * This hook is triggered after a GraphQL type entity is rendered. 
 * It checks if an index file exists in the same directory as the 
 * rendered entity, and if so, appends a markdown link to the entity's page.
 */
const afterRenderTypeEntitiesHook = async (event) => {
  const { filePath, name } = event.data;
  const indexFilePath = resolve(dirname(filePath), INDEX_MD);
  const pageFileName = basename(filePath);
  if (await fileExists(indexFilePath)) {
    const entryLine = `- [${name}](./${pageFileName})\n`;
    await appendFile(indexFilePath, entryLine);
  }
};

export { 
  beforeGenerateIndexMetafileHook, 
  afterRenderTypeEntitiesHook 
};
```

## Display response types for operations

You can use this hook to automatically add the response type's SDL (Schema Definition Language) after each GraphQL operation (query, mutation, subscription).

This is useful when you want your documentation to show not just the operation signature but also the structure of the data it returns.

**Before (default output):**

```graphql
query user(id: ID!): User
```

**After (with hook):**

The hook appends a "Response Type" section after the operation's code block:

```graphql
query user(id: ID!): User
```

**Response Type**

```graphql
type User {
  id: ID!
  name: String!
  email: String
  posts: [Post!]!
}
```

Declare the custom module in GraphQL-Markdown configuration `formatter: "./custom-mdx.mjs"`.

```js title="custom-mdx.mjs"
import { 
  isOperation, 
  isScalarType, 
  getNamedType 
} from "@graphql-markdown/graphql";
import { Printer } from "@graphql-markdown/printer-legacy";

/**
 * Hook that adds the response type's SDL after operation code blocks.
 *
 * This hook is executed after generating the code block for a GraphQL type.
 * For operations (queries, mutations, subscriptions), it appends a second
 * code block showing the structure of the return type.
 */
const afterPrintCodeHook = async (event) => {
  const { type, options } = event.data;

  // Only process operations (types with a `type` property for return type)
  if (!isOperation(type)) {
    return;
  }

  // Get the unwrapped return type (removes NonNull and List wrappers)
  const returnType = getNamedType(type.type);
  if (!returnType) {
    return;
  }

  // Skip scalar types - they don't need expanded documentation
  if (isScalarType(returnType)) {
    return;
  }

  // Generate the SDL code block for the return type
  const returnTypeCode = Printer.printCode(returnType, options);

  if (returnTypeCode) {
    event.output = `${event.output}\n\n### Response Type\n\n${returnTypeCode}`;
  }
};

export { afterPrintCodeHook };
```

:::tip

You can customize the heading level or text by changing `### Response Type` to match your documentation style.

:::

:::note

The `getNamedType` function from `@graphql-markdown/graphql` unwraps GraphQL type wrappers like `NonNull` and `List`. For example, `[User!]!` becomes `User`.

:::

## Reorder or hide sections before page composition

Use `beforeComposePageTypeHook` to customize the final section order for each type page. This is the recommended approach for section visibility and ordering.

```js title="custom-mdx.mjs"
const beforeComposePageTypeHook = async (event) => {
  // Hide the generated code section
  event.output = event.output.filter((key) => key !== "code");

  // Move "relations" before "metadata" when both are present
  const relationsIndex = event.output.indexOf("relations");
  const metadataIndex = event.output.indexOf("metadata");

  if (relationsIndex > -1 && metadataIndex > -1 && relationsIndex > metadataIndex) {
    event.output.splice(relationsIndex, 1);
    event.output.splice(metadataIndex, 0, "relations");
  }
};

export { beforeComposePageTypeHook };
```

---

## Integration with Frameworks


GraphQL-Markdown supports multiple documentation frameworks through formatter presets. Each framework has its own setup guide, or you can create a custom formatter for any framework.

## Choose a Path

Use the path that matches your documentation stack:

| If you are using... | Recommended path |
| ------------------- | ---------------- |
| **Docusaurus** | Use the `@graphql-markdown/docusaurus` plugin when you want the official Docusaurus integration and default Docusaurus formatter behavior. |
| **Hugo, MkDocs, DocFX, mdBook, or HonKit** | Use `@graphql-markdown/cli` with a formatter preset from `@graphql-markdown/formatters`. This is the main path for non-TS/JS documentation ecosystems. |
| **Starlight, Fumadocs, or Vocs** | Use `@graphql-markdown/cli` with the matching formatter preset when you already have one of these frameworks in place. |
| **Any unsupported framework** | Start from the closest preset or create a custom formatter module. |

For new configurations, use the `formatter` setting. The legacy `mdxParser` setting still works as a deprecated alias.

## Common Setup

Install the CLI and formatter presets:

```bash
npm install @graphql-markdown/cli @graphql-markdown/formatters graphql
```

Then configure the formatter that matches your framework:

```yaml
schema: ./schema.graphql
extensions:
  graphql-markdown:
    rootPath: ./docs
    baseURL: api
    formatter: "@graphql-markdown/formatters/hugo"
```

## Supported Formatters

Install the formatters package:

```bash
npm install @graphql-markdown/formatters
```

Then select your framework:

| Framework | Package | Setup |
| --------- | ------- | ----- |
| **Docusaurus** | `@graphql-markdown/formatters/docusaurus` | [Guide](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/README.md) |
| **Astro Starlight** | `@graphql-markdown/formatters/starlight` | [Guide](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/starlight/README.md) |
| **Next.js + Fumadocs** | `@graphql-markdown/formatters/fumadocs` | [Guide](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/fumadocs/README.md) |
| **Vocs** | `@graphql-markdown/formatters/vocs` | [Guide](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/vocs/README.md) |
| **HonKit** | `@graphql-markdown/formatters/honkit` | [Guide](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/README.md) |
| **Hugo** | `@graphql-markdown/formatters/hugo` | [Guide](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/hugo/README.md) |
| **MkDocs** | `@graphql-markdown/formatters/mkdocs` | [Guide](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/README.md) |
| **DocFX** | `@graphql-markdown/formatters/docfx` | [Guide](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docfx/README.md) |
| **mdBook** | `@graphql-markdown/formatters/mdbook` | [Guide](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mdbook/README.md) |

### Quick Example

Declare the settings in your GraphQL Config file, then run the CLI:

```yaml title=".graphqlrc"
schema: ./schema.graphql
extensions:
  graphql-markdown:
    rootPath: ./docs
    baseURL: api
    formatter: "@graphql-markdown/formatters/docusaurus" # or your framework
```

```bash
npx gqlmd graphql-to-doc
```

The command name is `graphql-to-doc` for the default project, and `graphql-to-doc:<id>` for each additional [GraphQL Config project](/docs/advanced/additional-schema#graphql-config).

You can also call the generator programmatically. `runGraphQLMarkdown` takes the configuration as first argument, and CLI-style overrides as second argument:

```js
import { runGraphQLMarkdown } from "@graphql-markdown/cli";

await runGraphQLMarkdown(
  {
    schema: "./schema.graphql",
    rootPath: "./docs",
    baseURL: "api",
    formatter: "@graphql-markdown/formatters/docusaurus", // or your framework
  },
  {}, // CLI flags overrides, eg `{ force: true }`
);
```

## 3rd Party Packages

Some frameworks have dedicated integration packages beyond the basic formatters:

| Framework | Framework Link | Package | NPM |
| --------- | -------------- | ------- | --- |
| **VitePress** | [vitepress.dev](https://vitepress.dev/) | graphql-markdown-vitepress | [NPM](https://www.npmjs.com/package/graphql-markdown-vitepress) |

## Custom MDX Formatter

For frameworks not listed above, or to customize formatting behavior, create a custom MDX module.

### MDX Module Contract

A custom MDX module can export individual formatter functions:

| Export                     | Type                                                               | Description                                      |
| -------------------------- | ------------------------------------------------------------------ | ------------------------------------------------ |
| `formatMDXBadge`           | `(badge: { text, classname? }) => string`                          | Format type badges (deprecated, required, etc.)  |
| `formatMDXAdmonition`      | `(admonition: { text, title, type, icon? }, meta?) => string`      | Format callout/warning blocks                    |
| `formatMDXBullet`          | `(text?: string) => string`                                        | Format bullet point separators                   |
| `formatMDXDetails`         | `(option: { dataOpen, dataClose? }) => string`                     | Format collapsible sections                      |
| `formatMDXFrontmatter`     | `(props?, formatted?: string[]) => string`                         | Format page frontmatter                          |
| `formatMDXLink`            | `(link: { text, url }) => { text, url }`                           | Transform type links                             |
| `formatMDXNameEntity`      | `(name: string, parentType?: string) => string`                    | Format named entity references                   |
| `formatMDXPermalink`       | `(id: string) => string`                                           | Format section header permalinks                 |
| `formatMDXSpecifiedByLink` | `(url: string) => string`                                          | Format scalar specification links                |

Optional exports:

| Export            | Type     | Description                                          |
| ----------------- | -------- | ---------------------------------------------------- |
| `mdxDeclaration`  | `string` | Import statements prepended to generated files       |
| `mdxExtension`    | `string` | Custom file extension (defaults to `.mdx`)           |

:::tip
You only need to export the formatter functions your framework requires. Any missing functions will use the default HTML-like implementation.
:::

### `formatMDXDetails` Contract

The string returned by `formatMDXDetails` **must** contain a single `\r` (carriage return) character as a delimiter between the opening and closing parts. The printer splits on `"\r"` to wrap content, so reserve `\r` only for that separator and use `\n` for line breaks.

```js
// ✅ correct — use \n for line breaks and a single standalone \r as the delimiter
export const formatMDXDetails = ({ dataOpen }) =>
  `\n\n<MyDetails label="${dataOpen}">\n\r</MyDetails>\n\n`;

// ❌ incorrect — no \r means the closing tag is lost
export const formatMDXDetails = ({ dataOpen }) =>
  `\n\n<MyDetails label="${dataOpen}">\n</MyDetails>\n\n`;

// ❌ incorrect — CRLF introduces extra \r characters
export const formatMDXDetails = ({ dataOpen }) =>
  `\r\n\r\n<MyDetails label="${dataOpen}">\r\n\r</MyDetails>\r\n\r\n`;
```

### Extending a Preset

To customize a preset, spread its exports and override specific formatters:

```js
// src/modules/custom-mdx.cjs
const PresetMDX = require('@graphql-markdown/formatters/starlight');

const formatMDXBadge = ({ text, classname }) => {
  // Your custom logic
  return `<Badge>${text}</Badge>`;
};

module.exports = {
  ...PresetMDX,
  formatMDXBadge,
};
```

### Lifecycle Hooks

Custom MDX modules can also export lifecycle hooks to customize the generation process. See **[Hooks Recipes](/docs/advanced/hook-recipes#available-hooks)** for the full reference and examples.

---

## Namespaced operations


Grouping also works with namespaced operations (for example, `Query.analytics.*`, `Mutation.admin.*`, or `Subscription.events.*`).

If a root operation returns a namespace object, nested fields are generated as operation pages.

Namespace object type names must follow the corresponding operation suffix convention (`*Query`, `*Mutation`, `*Subscription`).

```graphql
type Query {
  analytics: AnalyticsQuery @doc(category: "Grade")
}

type AnalyticsQuery @doc(category: "Grade") {
  semesterGPA(semesterId: ID!): Int @doc(category: "Grade")
  coursesByDepartment(departmentId: ID!): [Course!]! @doc(category: "Course")
}
```

Generated operation pages include nested paths such as:

- `operations/queries/analytics/semester-gpa`
- `operations/queries/analytics/courses-by-department`

When [`groupByDirective`](/docs/advanced/group-by-directive) is enabled, these namespaced operations are still grouped by their directive category.

Generated code snippet for these namespaced operations will be wrapped in the namespace:

```graphql
# highlight-next-line
analytics {
  coursesByDepartment(
    departmentId: ID!
  ): [Course!]!
}
```

## Disable namespace wrapping with hooks

If you want to keep nested output paths but render operation code blocks without the namespace wrapper, use `beforePrintCodeHook` in your custom MDX module.

This hook runs before the code block is generated, so you can clear `operationNamespaceParts` only for the printed snippet.

```js title="custom-mdx.mjs"
import { isOperation } from "@graphql-markdown/graphql";

const beforePrintCodeHook = async (event) => {
  const { type } = event.data;

  if (!isOperation(type)) {
    return;
  }

  // highlight-next-line
  event.data.options.operationNamespaceParts = null;
};

export { beforePrintCodeHook };
```

Then register the module with `formatter` as described in [Hooks Recipes](/docs/advanced/hook-recipes) and [Integration with Frameworks](/docs/advanced/integration-with-frameworks).

With this hook enabled, a namespaced operation page can still be generated at `operations/queries/analytics/courses-by-department`, but its code block will render without the namespace wrapper:

```graphql
coursesByDepartment(
  departmentId: ID!
): [Course!]!
```

---

## Output Adapter


By default every generated page is written to the local filesystem, under [`rootPath`](/docs/settings#rootpath)/[`baseURL`](/docs/settings#baseurl). The [`outputAdapter`](/docs/settings#outputadapter) setting replaces that destination with one of your own — an object store, a headless CMS, a database, an in-memory map in a test — without forking the renderer.

This page covers what the renderer expects from an adapter, with two worked examples. For the setting itself, see [`outputAdapter`](/docs/settings#outputadapter) in the settings reference.

## The contract

```ts
interface OutputAdapter {
  writeFile: (filePath: string, content: string) => Promise<void>;
  readFile: (filePath: string) => Promise<string | undefined>;
  ensureDir?: (
    dirPath: string,
    options?: { forceEmpty?: boolean },
  ) => Promise<void>;
}
```

`writeFile` and `readFile` are required. `ensureDir` is optional, so a destination with no directory concept can leave it out — but read [Deleted types](#deleted-types) before you do.

## When each method is called

| Method | Called |
| --- | --- |
| `ensureDir` | once for the output directory when generation starts, then once per category directory by the Docusaurus and Hugo presets |
| `writeFile` | once per type page, once for the homepage, plus any navigation file the preset maintains (`_category_.yml`, `_index.md`, `toc.yml`, `SUMMARY.md`) |
| `readFile` | once per page for the DocFX, mdBook and MkDocs presets, once per category for Docusaurus, and once per navigation file a preset maintains |

An adapter is used for the whole run: there is no per-page opt-out.

## Paths are keys

The paths handed to an adapter are the ones the filesystem writer would use. Two properties matter if you map them onto something that is not a filesystem:

**They are relative to the working directory**, not absolute, unless [`rootPath`](/docs/settings#rootpath) is itself absolute. With the default `rootPath: "./docs"` and `baseURL: "schema"`, a page arrives as `docs/schema/types/objects/book.md`. Key off them directly, or make them relative to `outputDir` — do not assume a leading `/`.

Because they are relative, a key derived from them depends on the working directory the generator was started from. Resolve both sides before comparing them, and the two forms can no longer be mixed — a relative `rootPath` against an absolute path yields a key that climbs out of the tree with `..`.

**One path sits outside the output directory.** mdBook requires `SUMMARY.md` one level above the generated pages, so an adapter computing keys with `path.relative(outputDir, filePath)` gets a leading `..` for that one file, which many object stores reject.

Do not strip the `..`: that moves `SUMMARY.md` in among the pages, and the links it holds — `schema/index.md` and the like — then resolve one level too deep. Key off [`rootPath`](/docs/settings#rootpath) instead, which keeps every path inside the tree and preserves the layout:

```js
const toKey = (location) =>
  path
    .relative(path.resolve(rootPath), path.resolve(location))
    .split(path.sep)
    .join("/");
```

| Written | Key |
| --- | --- |
| `docs/schema/types/objects/book.md` | `schema/types/objects/book.md` |
| `docs/schema/index.md` | `schema/index.md` |
| `docs/SUMMARY.md` | `SUMMARY.md` |

Use forward slashes in keys regardless of the OS that generated them, so the same schema produces the same keys everywhere.

## Reading back

Some presets post-process what they just wrote: DocFX rewrites `uid` values and builds `toc.yml`, mdBook and MkDocs rewrite internal links to relative paths, and Docusaurus checks whether a `_category_.yml` already exists before replacing it.

That is what `readFile` is for. It returns `undefined` when there is nothing at the path — a normal answer, not a failure.

A destination that genuinely cannot serve back what it wrote may return `undefined` always, but then:

- DocFX, mdBook and MkDocs cannot rewrite internal links, which stay as absolute paths, and DocFX produces no `toc.yml`
- Docusaurus regenerates `_category_.yml` on every run, discarding edits made to it by hand

Starlight, Fumadocs, Vocs, Hugo and HonKit never read back their output, so a write-only destination costs them nothing.

The first page that cannot be read back is reported once for that adapter, rather than once per page, so a broken destination is visible without burying the run in identical errors.

## Deleted types

`ensureDir` receives `{ forceEmpty: true }` when [`force`](/docs/settings#force) is set, which is how a run clears out what a previous one left behind. Omit `ensureDir` and `force` has nothing to act on: pages for types deleted from the schema stay in the destination forever.

A destination with no directories still usually wants `ensureDir` for exactly that reason — deleting by key prefix is the natural equivalent, as in the [Cloudflare R2 adapter](#a-cloudflare-r2-adapter) below. Leave it out only when the destination is disposable or pruned elsewhere.

## Formatting

Content arrives already formatted, so an adapter never handles [`pretty`](/docs/settings#pretty) itself. Prettifying happens before the adapter is called, so every destination receives identical bytes.

## An adapter for tests

The smallest useful adapter keeps pages in memory, which makes generated output straightforward to assert against:

```js
const pages = new Map();

export const memoryOutputAdapter = {
  writeFile: async (filePath, content) => {
    pages.set(filePath, content);
  },
  readFile: async (filePath) => pages.get(filePath),
  ensureDir: async (dirPath, options) => {
    if (options?.forceEmpty !== true) {
      return;
    }

    for (const filePath of pages.keys()) {
      if (filePath.startsWith(dirPath)) {
        pages.delete(filePath);
      }
    }
  },
};
```

This supports read-back, so every preset works against it.

## A Cloudflare R2 adapter

[graphql-markdown/demo-astro-r2](https://github.com/graphql-markdown/demo-astro-r2) is a live example: it generates straight into an R2 bucket and builds an Astro/Starlight site that reads the pages back out at build time. It reaches the bucket through Wrangler's R2 binding rather than the S3 API, but the adapter contract is the same.

The example below publishes the generated pages to a [Cloudflare R2](https://developers.cloudflare.com/r2/) bucket instead of writing them to disk, using R2's S3-compatible API:

```js
const path = require("node:path");
const {
  S3Client,
  PutObjectCommand,
  GetObjectCommand,
  ListObjectsV2Command,
  DeleteObjectsCommand,
} = require("@aws-sdk/client-s3");

const rootPath = "./docs";
const baseURL = "schema";

const BUCKET = "docs";
const r2 = new S3Client({
  region: "auto",
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
  },
});

// Object keys, derived as described in "Paths are keys" above.
const toKey = (location) =>
  path
    .relative(path.resolve(rootPath), path.resolve(location))
    .split(path.sep)
    .join("/");

module.exports = {
  // ...
  rootPath,
  baseURL,
  outputAdapter: {
    writeFile: async (filePath, content) => {
      await r2.send(
        new PutObjectCommand({
          Bucket: BUCKET,
          Key: toKey(filePath),
          Body: content,
          ContentType: "text/markdown",
        }),
      );
    },
    // Required: the formatters that post-process their own output read each
    // page back. A missing object is "there is nothing here", not a failure.
    readFile: async (filePath) => {
      try {
        const object = await r2.send(
          new GetObjectCommand({ Bucket: BUCKET, Key: toKey(filePath) }),
        );
        return await object.Body.transformToString();
      } catch (error) {
        if (error.name === "NoSuchKey") {
          return undefined;
        }
        throw error;
      }
    },
    // R2 has no directories, so there is nothing to create. The work worth
    // doing is honouring `forceEmpty`: without it, pages for types deleted
    // from the schema would stay in the bucket forever.
    ensureDir: async (dirPath, options) => {
      if (options?.forceEmpty !== true) {
        return;
      }

      // S3 prefix matching is literal, not directory aware: without the
      // trailing delimiter, clearing `schema` would also delete `schema-v2/`.
      const dirKey = toKey(dirPath);
      const Prefix = dirKey === "" ? "" : `${dirKey}/`;
      let ContinuationToken;

      do {
        const listed = await r2.send(
          new ListObjectsV2Command({
            Bucket: BUCKET,
            Prefix,
            ContinuationToken,
          }),
        );

        if (listed.KeyCount) {
          await r2.send(
            new DeleteObjectsCommand({
              Bucket: BUCKET,
              Delete: {
                Objects: listed.Contents.map(({ Key }) => ({ Key })),
              },
            }),
          );
        }

        ContinuationToken = listed.IsTruncated
          ? listed.NextContinuationToken
          : undefined;
      } while (ContinuationToken);
    },
  },
};
```

## Limitations

Two things are worth knowing before you rely on an adapter in an automated pipeline.

### A failed hook does not fail the process

If a formatter's post-processing throws — an adapter rejecting the write of mdBook's `SUMMARY.md`, say — the error is logged and the run reports that the output is incomplete, but the process still exits `0`. Handler errors are collected rather than raised, so one failing hook does not abort a generation that otherwise succeeded.

A pipeline that must not publish incomplete documentation should not treat a zero exit status as sufficient. Check the log for the incomplete-output line, or assert on what actually landed in the destination — for an object store, that the page count matches the number of types, and that any navigation file the preset needs is present.

### State is kept per adapter instance, not per run

Two pieces of bookkeeping live for as long as the adapter object does, rather than for the length of a run:

- DocFX records which directories it has already given an "Overview" entry, so the check runs once per directory rather than once per page.
- The first page that cannot be read back is reported once, so a write-only destination does not repeat the same error for every page.

Generating once per process — which is what the CLI and every framework plugin do — is unaffected. Calling `generateDocFromSchema` repeatedly inside one process while passing the *same* adapter object carries that state into the later runs: a second run over a directory cleared by [`force`](/docs/settings#force) can leave its `toc.yml` without the "Overview" entry, and a destination that still cannot serve reads stays quiet after the first report.

Construct a new adapter object per run to avoid it. An adapter that holds an expensive client can keep the client in a shared scope and return a fresh wrapper object around it.

## Generation still runs under Node

`outputAdapter` changes where documentation is written, not what runs it. `@graphql-markdown/core` and its dependencies use Node built-ins, so generation happens under Node — in a build step or a CI job — and the adapter publishes the result to its destination.

---

## Schema loading


GraphQL-Markdown use external loaders for loading GraphQL schemas (see [full list](https://github.com/ardatan/graphql-tools/tree/master/packages/loaders)).

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

```ts
// highlight-start
type LoaderOption = {
  [name: ClassName]: PackageName | PackageConfig;
};
// highlight-end

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 title="shell"
npm install @graphql-tools/graphql-file-loader
```

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

```js title="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 title="shell"
npm install @graphql-tools/url-loader
```

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

```js title="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](/docs/troubleshooting) in case of error ['UrlLoader' does not exist in type 'LoaderOption'.ts](/docs/troubleshooting#urlloader-does-not-exist-in-type-loaderoptionts).

:::

## 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 title="shell"
npm install @graphql-tools/code-file-loader
```

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

```js title="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](https://pothos-graphql.dev/), [TypeGraphQL](https://typegraphql.com/), and [NestJS](https://docs.nestjs.com/graphql/quick-start).

---

## Settings


All settings can be set via plugin options in your config file and overridden with CLI flags. Use `formatter` when you want GraphQL-Markdown to target a supported formatter-based documentation ecosystem, and see [configuration](/docs/configuration) for the different config methods.

## `--config`

Print the resolved configuration used for generating documentation. This CLI flag is used for debugging purposes.

| Setting | CLI flag   | Default |
| :------ | :--------- | :------ |
|         | `--config` | `null`  |

Example:

```bash
npx docusaurus graphql-to-doc --config
```

## `baseURL`

The base URL used by Docusaurus. It will also be used as the folder name under [`rootPath`](#rootpath) for the generated documentation.

| Setting   | CLI flag               | Default  |
| --------- | ---------------------- | -------- |
| `baseURL` | `-b, --base <baseURL>` | `schema` |

## `customDirective`

Use this option to render directive information for types (see [custom directive](/docs/advanced/custom-directive)).

| Setting           | CLI flag        | Default     |
| ----------------- | --------------- | ----------- |
| `customDirective` | _not supported_ | `undefined` |

## `diffMethod`

The method to be used for identifying changes in the schema for triggering the documentation generation.

The possible values are:

- `FORCE`: skip diff, always generate documentation, also triggered by [`force`](#force) setting.
- `NONE`: skip diff (same as `FORCE`).
- `SCHEMA-DIFF`: use [GraphQL Inspector](https://graphql-inspector.com) to identify 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).

| Setting      | CLI flag                  | Default |
| ------------ | ------------------------- | ------- |
| `diffMethod` | `-d, --diff <diffMethod>` | `NONE`  |

:::info

The package `@graphql-markdown/diff` is required for using `diffMethod`.
If the package is missing, then the change detection is always skipped.

```shell
npm install @graphql-markdown/diff
```

:::

## `docOptions`

Use these options to tweak some of the static documentation generator features:

- `categorySort`: control how categories are sorted in the sidebar. Can be `"natural"` for alphabetical sorting or a custom compare function. When enabled, folder names are automatically prefixed with zero-padded order numbers (e.g., `01-objects`, `02-queries`). When not set, the order depends on document generator folders sorting and no prefixes are added.
- `frontMatter`: set custom front matter entries as key/value. If set to `false`, then it will disable the frontmatter and print a level 1 title as the page title.
- `index`: enable/disable the index page for categories/groups, see [Docusaurus documentation](https://docusaurus.io/docs/sidebar/items#generated-index-page) &mdash; **ONLY FOR DOCUSAURUS**
- `sectionHeaderId`: enable/disable the generation of custom header IDs for permalinks. The syntax depends on the formatter: `### Section {/* #ID */}` for Docusaurus 3.10 and later (see [Strict Heading IDs](https://docusaurus.io/blog/releases/3.10#strict-heading-ids) and [heading IDs](https://docusaurus.io/docs/markdown-features/toc#heading-ids)), `### Section [#ID]` for Fumadocs, and the classic `### Section {#ID}` for the other formatters. Starlight and Vocs have no custom header ID syntax, so the classic one is escaped as `### Section \{#ID\}` to keep the page valid MDX, and is only resolved if a remark plugin such as `remark-custom-heading-id` is configured. Override `formatMDXPermalink` in a [custom formatter](#formatter) to change it.

| Setting                      | CLI flag        | Default |
| ---------------------------- | --------------- | ------- |
| `docOptions.categorySort`    | _not supported_ | -       |
| `docOptions.frontMatter`     | _not supported_ | `{}`    |
| `docOptions.index`           | `--index`       | `false` |
| `docOptions.sectionHeaderId` | `--noSectionId` | `true`  |

```js title="docusaurus.config.js"
plugins: [
    [
      "@graphql-markdown/docusaurus",
       /** @type {import('@graphql-markdown/types').ConfigOptions} */
       {
        schema: "./schema/swapi.graphql",
        rootPath: "./docs",
        baseURL: "swapi",
        homepage: "./docs/swapi.md",
        // highlight-start
        docOptions: {
          frontMatter: {
            pagination_next: null, // disable page navigation next
            pagination_prev: null, // disable page navigation previous
            hide_table_of_contents: true, // disable page table of content
          },
          index: true, // enable generated index pages, same as CLI flag --index
          categorySort: "natural", // sort categories alphabetically and prefix with order numbers (01-objects, 02-queries, etc.)
          sectionHeaderId: false, // disable custom section header IDs (restores previous behavior)
        },
        // highlight-end
        loaders: {
          GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
        },
      },
    ],
  ],
```

:::info[Compatibility between options]

The `categorySort` option works seamlessly with:

- **`hierarchy` option**: Works with all hierarchy types (`api`, `entity`, `flat`)
- **`groupByDirective` option**: When using custom groups, categories are sorted based on group names and prefixed accordingly
- **`deprecated` option**: Deprecated categories are sorted along with other categories

**Example with groupByDirective:**

```js
docOptions: {
  categorySort: "natural",      // Sort groups alphabetically and prefix with order numbers
},
groupByDirective: {
  directive: "doc",
  field: "category",
  fallback: "Common",
}
```

This generates folder names like: `01-common`, `02-internal`, `03-public`

:::

## `force`

Force generating documentation in an empty folder and set [`diffMethod`](#diffmethod) to `FORCE`. If the folder located at `rootPath/baseURL` is not empty, then the plugin will delete the folder recursively and recreate it.

| Setting | CLI flag      | Default |
| ------- | ------------- | ------- |
| `force` | `-f, --force` | `false` |

## `groupByDirective`

Use a GraphQL directive for creating documentation categories (see [documentation categories](/docs/advanced/group-by-directive)).

| Setting            | CLI flag                                                                        | Default     |
| ------------------ | ------------------------------------------------------------------------------- | ----------- |
| `groupByDirective` | <code>--groupByDirective &lt;&#64;directive(field&#124;=fallback)></code>       | `undefined` |

## `homepage`

The location of the landing page to be used for the documentation, relative to the current workspace (see [custom homepage](/docs/advanced/homepage)). The file will be copied to the root folder of the generated documentation.

The plugin provides a default page in `assets/generated`.

| Setting    | CLI flag                    | Default        |
| ---------- | --------------------------- | -------------- |
| `homepage` | `-h, --homepage <homepage>` | `generated.md` |

:::tip

Set `homepage: false` to disable the homepage generation.

:::

:::info

The GraphQL-Markdown template for Docusaurus provides a customized homepage located at `static/index.md`.

:::

## `id`

The identifier of the configuration instance. It is used for supporting [additional schemas](/docs/advanced/additional-schema): each instance gets its own command `graphql-to-doc:<id>`, and it maps to the [GraphQL Config](/docs/configuration#graphql-config) project of the same name.

| Setting | CLI flag        | Default     |
| ------- | --------------- | ----------- |
| `id`    | _not supported_ | `default`   |

## `linkRoot`

The root for links in documentation. It depends on the entry for the schema main page in the Docusaurus sidebar.

| Setting    | CLI flag                | Default |
| ---------- | ----------------------- | ------- |
| `linkRoot` | `-l, --link <linkRoot>` | `/`     |

## `loaders`

GraphQL schema loaders to use (see [schema loading](/docs/advanced/schema-loading)).

| Setting   | CLI flag        | Default |
| --------- | --------------- | ------- |
| `loaders` | _not supported_ | `{ }`   |

## `formatter`

Provide a custom module for formatting output content. You can also use built-in formatter presets from [`@graphql-markdown/formatters`](https://github.com/graphql-markdown/graphql-markdown/tree/main/packages/formatters).

| Setting     | CLI flag      | Default                            |
| ----------- | ------------- | ---------------------------------- |
| `formatter` | `--formatter` | `undefined`                        |

:::note

The `mdxParser` setting and `--mdxParser` CLI flag are deprecated aliases for `formatter` / `--formatter`. They still work but emit a deprecation warning. Migrate to `formatter`.

:::

:::caution

The `--formatter` and `--mdxParser` CLI flags are only registered when the CLI is set up with a default formatter package, which is what `@graphql-markdown/docusaurus` does. The standalone `gqlmd` command does not expose them, so set `formatter` in your configuration file instead.

:::

:::info

`@graphql-markdown/docusaurus` comes with `@graphql-markdown/formatters/docusaurus` by default.

:::

The custom module can export individual formatter functions:

| Export                     | Type                                      | Description                       |
| -------------------------- | ----------------------------------------- | --------------------------------- |
| `formatMDXBadge`           | `(badge: { text, classname? }) => string` | Format type badges                |
| `formatMDXAdmonition`      | `(admonition, meta?) => string`           | Format callout/warning blocks     |
| `formatMDXBullet`          | `(text?: string) => string`               | Format bullet point separators    |
| `formatMDXDetails`         | `(option) => string`                      | Format collapsible sections       |
| `formatMDXFrontmatter`     | `(props?, formatted?) => string`          | Format page frontmatter           |
| `formatMDXLink`            | `(link) => { text, url }`                 | Transform type links              |
| `formatMDXNameEntity`      | `(name, parentType?) => string`           | Format named entity references    |
| `formatMDXPermalink`       | `(id) => string`                          | Format section header permalinks  |
| `formatMDXSpecifiedByLink` | `(url) => string`                         | Format scalar specification links |

For detailed examples on formatter functions, see **[Integration with Frameworks](/docs/advanced/integration-with-frameworks)**.

Additionally, the module can export:

| Export           | Type     | Description                                    |
| ---------------- | -------- | ---------------------------------------------- |
| `mdxDeclaration` | `string` | Import statements prepended to generated files |
| `mdxExtension`   | `string` | Custom file extension (defaults to `.mdx`)     |

The custom module can also export lifecycle hooks for customizing the generation process, see **[Hooks Recipes](/docs/advanced/hook-recipes)**.

```js title="docusaurus.config.js"
plugins: [
    [
      "@graphql-markdown/docusaurus",
       /** @type {import('@graphql-markdown/types').ConfigOptions} */
       {
        schema: "./schema/swapi.graphql",
        rootPath: "./docs",
        baseURL: "swapi",
        homepage: "./docs/swapi.md",
        // highlight-start
        formatter: "./lib/custom-mdx.cjs",
        // highlight-end
        loaders: {
          GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
        }
      },
    ],
  ],
```

## `metatags`

Set page metadata in `<html>`, `<head>` using [Docusaurus head metadata](https://docusaurus.io/docs/markdown-features/head-metadata).

Meta tags are provided as a list of metadata objects, eg `[{ name: "robots", content: "noindex" }]` for `<meta name="robots" content="noindex" />`.

| Setting    | CLI flag        | Default |
| ---------- | --------------- | ------- |
| `metatags` | _not supported_ | `[]`    |

```js title="docusaurus.config.js"
plugins: [
    [
      "@graphql-markdown/docusaurus",
       /** @type {import('@graphql-markdown/types').ConfigOptions} */
       {
        schema: "./schema/swapi.graphql",
        rootPath: "./docs",
        baseURL: "swapi",
        homepage: "./docs/swapi.md",
        // highlight-start
        metatags: [
          { name: "robots", content: "noindex" }, // <meta name="robots" content="noindex" />
          { charset: "utf-8" }, // <meta charset="utf-8" />
        ],
        // highlight-end
        loaders: {
          GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
        }
      },
    ],
  ],
```

## `onlyDocDirective`

The schema directive/s is used for selecting types to be rendered in the documentation.

The CLI flag supports multiple values separated by a space character, eg `--only @stable @beta`.

| Setting            | CLI flag                 | Default |
| ------------------ | ------------------------ | ------- |
| `onlyDocDirective` | `--only <@directive...>` | `[]`    |

See also [`skipDocDirective`](#skipdocdirective).

:::info

It only applies to types with a location compatible with the directive, i.e. if the `onlyDocDirective` cannot be applied to a type (e.g. `ENUM`), then the type will be displayed.

:::

## `outputAdapter`

The destination for generated documentation. By default pages are written to the local filesystem under [`rootPath`](#rootpath)/[`baseURL`](#baseurl). Set an adapter to send them somewhere else instead — a CMS storage API, an object store, an in-memory map — without forking the renderer.

| Setting         | CLI flag | Default          |
| --------------- | -------- | ---------------- |
| `outputAdapter` | none     | local filesystem |

An adapter must provide `writeFile` and `readFile`, and may provide `ensureDir`:

```ts
interface OutputAdapter {
  writeFile: (filePath: string, content: string) => Promise<void>;
  readFile: (filePath: string) => Promise<string | undefined>;
  ensureDir?: (
    dirPath: string,
    options?: { forceEmpty?: boolean },
  ) => Promise<void>;
}
```

See **[Output Adapter](/docs/advanced/output-adapter)** for the full contract and worked examples: [when each method is called](/docs/advanced/output-adapter#when-each-method-is-called), [how paths map onto keys](/docs/advanced/output-adapter#paths-are-keys), [which formatters read their output back](/docs/advanced/output-adapter#reading-back), why [omitting `ensureDir`](/docs/advanced/output-adapter#deleted-types) leaves pages for deleted types behind, and the [limitations](/docs/advanced/output-adapter#limitations) worth knowing before relying on one in a pipeline.

## `printTypeOptions`

Use these options to toggle the type of information rendered on pages:

- `deprecated`: option for displaying deprecated entities (fields, values, operations).
  - `default`: deprecated entities are displayed with other entities.
  - `group`: deprecated entities are grouped.
  - `skip`: deprecated entities are not displayed (same as [`skipDocDirective`](#skipdocdirective)).
- `exampleSection`: configure example rendering based on directive data (see [Examples](/docs/advanced/examples)).
- `hierarchy`: option for type folder structure:
  - `api`: folder structure by operations (`Operations` group) and types `Types` group based on GraphQL entity types.
  - `entity`: folder structure by GraphQL entity types (eg. queries, mutations, scalars, objects...).
  - `flat`: no folder structure (override [`groupByDirective`](#groupbydirective)).
  - _Namespaced operations are supported by default and generated as nested operation paths (See [Namespaced Operations](/docs/advanced/namespaced-operations))._
- `parentTypePrefix`: prefix field names with the parent type name.
- `typeBadges`: add field type attributes badges.

| Setting                             | CLI flag                | Default   |
| ----------------------------------- | ----------------------- | --------- |
| `printTypeOptions.deprecated`       | `--deprecated <option>` | `default` |
| `printTypeOptions.exampleSection`   | n/a                     | —         |
| `printTypeOptions.hierarchy`        | `--hierarchy`           | `api`     |
| `printTypeOptions.parentTypePrefix` | `--noParentType`        | `true`    |
| `printTypeOptions.typeBadges`       | `--noTypeBadges`        | `true`    |

:::tip

Use [`beforeComposePageTypeHook`](/docs/advanced/hook-recipes) to control section visibility and order.

:::

```js title="docusaurus.config.js"
plugins: [
    [
      "@graphql-markdown/docusaurus",
       /** @type {import('@graphql-markdown/types').ConfigOptions} */
       {
        schema: "./schema/swapi.graphql",
        rootPath: "./docs",
        baseURL: "swapi",
        homepage: "./docs/swapi.md",
        // highlight-start
        printTypeOptions: {
          deprecated: "group", // group deprecated entities, same as CLI flag --deprecated group
          exampleSection: {
            field: "example", // use directive field for example rendering
          },
          hierarchy: "entity",  // disable type API grouping, same as CLI flag --hierarchy entity
          parentTypePrefix: false, // disable parent prefix, same as CLI flag --noParentType
          typeBadges: false, // disable type attribute badges, same as CLI flag --noTypeBadges
        },
        formatter: require.resolve("./custom-mdx.cjs"), // use hook-based section composition
        // highlight-end
        loaders: {
          GraphQLFileLoader: "@graphql-tools/graphql-file-loader" // local file schema
        }
      },
    ],
  ],
```

```js title="custom-mdx.cjs"
const DocusaurusMDX = require("@graphql-markdown/docusaurus/mdx");

const beforeComposePageTypeHook = async (event) => {
  // Hide code and relations sections
  event.output = event.output.filter((key) => key !== "code" && key !== "relations");
};

module.exports = {
  ...DocusaurusMDX,
  beforeComposePageTypeHook,
};
```

:::danger

Declaring a different option type in the CLI flag `hierarchy` and the config file `hierarchy` will generate an error.

:::

:::tip

`api` option for `hierarchy` can use customized group names (defaults are `operations` and `types`) by passing an object instead of `api` using the group name as key for the new name:

```js title="docusaurus.config.js"
plugins: [
    [
      "@graphql-markdown/docusaurus",
       /** @type {import('@graphql-markdown/types').ConfigOptions} */
       {
        // highlight-start
        printTypeOptions: {
          hierarchy: { // no customization 'hierarchy: "api"' (default)
            api: { // enable useApiGroup with custom groups name
              operations: "api", // rename the group 'operations' to 'api'
              //group 'types' left unchanged
            }
          }
        },
        // highlight-end
      },
    ],
  ],
```

:::

:::info

See **[customize deprecated sections](/docs/advanced/custom-deprecated-section)** to customize the rendering of `printTypeOptions.deprecated: "group"`.

:::

## `pretty`

Use [`prettier`](https://prettier.io) to format generated files.

| Setting  | CLI flag   | Default |
| -------- | ---------- | ------- |
| `pretty` | `--pretty` | `false` |

:::info

The `prettier` package has to be installed separately. If the package is not present locally, then the formatting will always be skipped.

:::

## `rootPath`

The output root path for the generated documentation, relative to the current workspace.
It works with [`baseURL`](#baseurl), and the final path will be `rootPath/baseURL`.

| Setting    | CLI flag                | Default  |
| ---------- | ----------------------- | -------- |
| `rootPath` | `-r, --root <rootPath>` | `./docs` |

## `schema`

The GraphQL schema location.

| Setting  | CLI flag                | Default            |
| -------- | ----------------------- | ------------------ |
| `schema` | `-s, --schema <schema>` | `./schema.graphql` |

## `skipDocDirective`

The schema directive/s is used for skipping types from documentation.

The CLI flag supports multiple values separated by a space character, eg `--skip @noDoc @deprecated`.

| Setting            | CLI flag                 | Default |
| ------------------ | ------------------------ | ------- |
| `skipDocDirective` | `--skip <@directive...>` | `[]`    |

See also [`onlyDocDirective`](#onlydocdirective).

:::danger

Declaring the same type in both `onlyDocDirective` and `skipDocDirective` will generate an error.

:::

:::info

Types with `@deprecated` directive can also be skipped using the setting **[`printTypeOptions.deprecated: "skip"`](#printtypeoptions)** or the flag `--deprecated skip`.

:::

## `tmpDir`

The folder used for storing schema copy and signature is used by [`diffMethod`](#diffmethod) setting.

| Setting  | CLI flag             | Default          |
| -------- | -------------------- | ---------------- |
| `tmpDir` | `-t, --tmp <tmpDir>` | _OS temp folder_ |

---

## Troubleshooting


## Duplicate "graphql" modules cannot be used at the same time

Add a `resolutions` entry to your `package.json`:

```json title="package.json"
"resolutions": 
{
  "graphql": "16.14.2"
}
```

## Unable to find any GraphQL type definitions

There are several potential solutions:

1. Change the temporary folder location:
```js
{
  tmpDir: "./.docusaurus"
}
```

2. Disable schema diff feature:
```js
{
  diffMethod: "NONE" 
}
```

3. Check file permissions on the temporary directory

## Schema Loading Issues

1. Ensure required loaders are installed:
```shell
npm install @graphql-tools/url-loader @graphql-tools/json-file-loader
```

2. Verify loader configuration:
```js
{
  loaders: {
    UrlLoader: "@graphql-tools/url-loader",
    JsonFileLoader: "@graphql-tools/json-file-loader"
  }
}
```

## "UrlLoader" does not exist in type "LoaderOption".ts

*Reported in [#2213](https://github.com/graphql-markdown/graphql-markdown/issues/2213).*

```
Object literal may only specify known properties, and 'UrlLoader' does not exist in type 'LoaderOption'.ts(2353)
core.d.ts(128, 3): The expected type comes from property 'loaders' which is declared here on type 'ConfigOptions'
```

Cast the `loaders` as LoaderOption

```ts
loaders: {
  UrlLoader: {
    module: "@graphql-tools/url-loader",
    options: {
      headers: {
        Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
      },
    },
  },
} as LoaderOption,
```

## Memory Issues During Generation

For large schemas, try:

1. Increase Node.js memory limit:
```shell
NODE_OPTIONS=--max-old-space-size=4096 npx docusaurus graphql-to-doc
```

## Getting Help

If you're still having issues:

1. Check the [GitHub issues](https://github.com/graphql-markdown/graphql-markdown/issues)
2. File a new issue with:
   - Your configuration
   - Schema size/complexity
   - Error messages
   - Node.js and package versions

---

## introspection

Library for introspecting a GraphQL schema.
The entry point method is [getSchemaMap](#getschemamap).

## IntrospectionError \{#introspectionerror\}

Defined in: [packages/graphql/src/introspection.ts:51](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L51)

### Example

```ts

```

### Extends

- `Error`

### Constructors

#### Constructor

```ts
new IntrospectionError(message?): IntrospectionError;
```

Defined in: node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1080

##### Parameters

###### message?

`string`

##### Returns

[`IntrospectionError`](#introspectionerror)

##### Inherited from

```ts
Error.constructor;
```

#### Constructor

```ts
new IntrospectionError(message?, options?): IntrospectionError;
```

Defined in: node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1080

##### Parameters

###### message?

`string`

###### options?

`ErrorOptions`

##### Returns

[`IntrospectionError`](#introspectionerror)

##### Inherited from

```ts
Error.constructor;
```

---

## \_getFields() \{#\_getfields\}

```ts
function _getFields<T, V>(
  type,
  processor?,
  fallback?,
): Record<string, unknown> | V;
```

Defined in: [packages/graphql/src/introspection.ts:340](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L340)

**`Internal`**

Returns the fields from a GraphQL schema type.

see [getOperation](#getoperation), [getFields](#getfields)

### Type Parameters

#### T

`T`

#### V

`V`

### Parameters

#### type

`T`

the GraphQL schema type to parse.

#### processor?

(`fieldMap`) => `V`

optional callback function to parse the fields map.

#### fallback?

`V`

optional fallback value, `undefined` if not set.

### Returns

`Record`&lt;`string`, `unknown`&gt; \| `V`

a map of fields as k/v records, or `fallback` value if no fields available.

---

## getDirective() \{#getdirective\}

```ts
function getDirective(entity, directives): GraphQLDirective[];
```

Defined in: [packages/graphql/src/introspection.ts:251](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L251)

Returns a schema entity's list of directives matching a defined set.

### Parameters

#### entity

`unknown`

a GraphQL schema entity.

#### directives

`Maybe`&lt;`GraphQLDirective`[]&gt;

a directive name or a list of directive names.

### Returns

`GraphQLDirective`[]

a list of GraphQL directives matching the set, else `false`.

---

## getDirectiveLocationForASTPath() \{#getdirectivelocationforastpath\}

```ts
function getDirectiveLocationForASTPath(appliedTo): DirectiveLocation;
```

Defined in: [packages/graphql/src/introspection.ts:169](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L169)

### Parameters

#### appliedTo

`Maybe`&lt;`ASTNode`&gt;

### Returns

`DirectiveLocation`

---

## getFields() \{#getfields\}

```ts
function getFields(type): unknown[];
```

Defined in: [packages/graphql/src/introspection.ts:604](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L604)

Returns fields map for a GraphQL schema type.

see [getSchemaMap](#getschemamap)

### Parameters

#### type

`unknown`

the GraphQL schema type to parse.

### Returns

`unknown`[]

a list of fields of type object.

---

## getOperation() \{#getoperation\}

```ts
function getOperation(
  operationType?,
  operationKind?,
): Record<string, GraphQLOperationType>;
```

Defined in: [packages/graphql/src/introspection.ts:567](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L567)

**`Internal`**

Returns fields map for a GraphQL operation type (query, mutation, subscription...).

see [getSchemaMap](#getschemamap)

### Parameters

#### operationType?

`unknown`

the operation type to parse.

#### operationKind?

`Maybe`&lt;`OperationKind`&gt;

optional explicit operation kind.

### Returns

`Record`&lt;`string`, `GraphQLOperationType`&gt;

a map of fields as k/v records.

---

## getSchemaMap() \{#getschemamap\}

```ts
function getSchemaMap(schema): SchemaMap;
```

Defined in: [packages/graphql/src/introspection.ts:682](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L682)

Returns an introspection map of the GraphQL schema.
This is the entry point for GraphQL-Markdown schema parsing features.

### Parameters

#### schema

`Maybe`&lt;`GraphQLSchema`&gt;

a GraphQL schema.

### Returns

`SchemaMap`

a schema map by GraphQL entities (see SchemaEntity).

### Example

```js
import { buildSchema } from "graphql";
import { getSchemaMap } from "@graphql-markdown/utils/graphql";

const schema = buildSchema(`
  interface Record {
    id: String!
  }
  type StudyItem implements Record {
    id: String!
    subject: String!
    duration: Int!
  }
  type Query {
    getStudyItems(subject: String): [StudyItem!]
    getStudyItem(id: String!): StudyItem
  }
  type Mutation {
    addStudyItem(subject: String!, duration: Int!): StudyItem
  }
  type Subscription {
    listStudyItems: [StudyItem!]
  }
`);

const schemaTypeMap = getSchemaMap(schema);

// expected result: {
//   queries: {
//     getStudyItems: GraphQLField,
//     getStudyItem: GraphQLField,
//   },
//   mutations: {
//     addStudyItem: GraphQLField,
//   },
//   subscriptions: {
//     listStudyItems: GraphQLField,
//   }
//   directives: {
//     include: GraphQLDirective,
//     skip: GraphQLDirective,
//     deprecated: GraphQLDirective,
//     specifiedBy: GraphQLDirective,
//   objects: {
//     StudyItem: GraphQLObjectType,
//   unions: {},
//   interfaces: {
//     Record: GraphQLInterfaceType,
//   enums: {},
//   inputs: {},
//   scalars: {
//     String: GraphQLScalarType,
//     Int: GraphQLScalarType,
//     Boolean: GraphQLScalarType,
//   }
// }
```

---

## getTypeDirectiveArgValue() \{#gettypedirectiveargvalue\}

```ts
function getTypeDirectiveArgValue(
  directive,
  node,
  argName,
): Maybe<string | Record<string, unknown>>;
```

Defined in: [packages/graphql/src/introspection.ts:312](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L312)

Returns one directive's argument's value linked to a GraphQL schema type.
It calls [getTypeDirectiveValues](#gettypedirectivevalues) and returns a matching record.

### Parameters

#### directive

`GraphQLDirective`

a GraphQL directive defined in the schema.

#### node

`unknown`

the GraphQL schema type to parse.

#### argName

`string`

the name of the GraphQL directive argument to fetch the value from.

### Returns

`Maybe`&lt;`string` \| `Record`&lt;`string`, `unknown`&gt;&gt;

a record k/v with `argName` as key and the argument's value.

---

## getTypeDirectiveValues() \{#gettypedirectivevalues\}

```ts
function getTypeDirectiveValues(
  directive,
  type,
): Maybe<Record<string, unknown>>;
```

Defined in: [packages/graphql/src/introspection.ts:281](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L281)

Returns all directive's arguments' values linked to a GraphQL schema type.

### Parameters

#### directive

`GraphQLDirective`

a GraphQL directive defined in the schema.

#### type

`unknown`

the GraphQL schema type to parse.

### Returns

`Maybe`&lt;`Record`&lt;`string`, `unknown`&gt;&gt;

a record k/v with arguments' name as keys and arguments' value.

---

## getTypeFromSchema() \{#gettypefromschema\}

```ts
function getTypeFromSchema<T>(schema, type): Maybe<Record<string, T>>;
```

Defined in: [packages/graphql/src/introspection.ts:67](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L67)

**`Internal`**

Returns a map of GraphQL named types from a schema for a defined GraphQL type.
When parsing the entities, internal GraphQL entities (starting with `__`) are excluded.

### Type Parameters

#### T

`T`

### Parameters

#### schema

`Maybe`&lt;`GraphQLSchema`&gt;

a GraphQL schema.

#### type

`unknown`

a GraphQL type, eg `GraphQLObjectType`.

### Returns

`Maybe`&lt;`Record`&lt;`string`, `T`&gt;&gt;

a map of GraphQL named types for the matching GraphQL type, or `undefined` if no match.

### See

[getSchemaMap](#getschemamap)

---

## getTypeName() \{#gettypename\}

```ts
function getTypeName(type, defaultName?): string;
```

Defined in: [packages/graphql/src/introspection.ts:402](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L402)

Resolves the name of a GraphQL schema type.

### Parameters

#### type

`unknown`

the GraphQL schema type to parse.

#### defaultName?

`string` = `""`

optional fallback value if the name resolution fails.

### Returns

`string`

the type's name, or `defaultName`.

---

## hasAstNode() \{#hasastnode\}

```ts
function hasAstNode<T>(node): node is AstNodeType<T>;
```

Defined in: [packages/graphql/src/introspection.ts:113](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L113)

**`Internal`**

Type guard for type with an AST node property.

### Type Parameters

#### T

`T`

### Parameters

#### node

`T`

a GraphQL schema named type.

### Returns

`node is AstNodeType<T>`

`true` if the entity has an AST node property, else `false`.

---

## hasDirective() \{#hasdirective\}

```ts
function hasDirective(entity, directives, fallback?): boolean;
```

Defined in: [packages/graphql/src/introspection.ts:216](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L216)

Checks if a schema entity as a directive belonging to a defined set.

### Parameters

#### entity

`unknown`

a GraphQL schema entity.

#### directives

`Maybe`&lt;`GraphQLDirective`[]&gt;

a directive name or a list of directive names.

#### fallback?

`boolean` = `false`

default value if the entity type is not a valid location for directives.

### Returns

`boolean`

`true` if the entity has at least one directive matching, else `false`.

---

## isValidDirectiveLocation() \{#isvaliddirectivelocation\}

```ts
function isValidDirectiveLocation(entity, directive): boolean;
```

Defined in: [packages/graphql/src/introspection.ts:191](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/introspection.ts#L191)

Check if a directive can be applied to specific schema entity location.

### Parameters

#### entity

`unknown`

a GraphQL schema entity.

#### directive

`GraphQLDirective`

a directive name.

### Returns

`boolean`

`true` if the entity is a valid directive location, else `false`.

---

## cli

This module provides the CLI functionality for generating documentation from GraphQL schemas.
It exports utilities to run the documentation generator both programmatically and via CLI.

## See

[GraphQL Markdown Documentation](https://graphql-markdown.dev)

## GraphQLMarkdownCliType \{#graphqlmarkdownclitype\}

```ts
type GraphQLMarkdownCliType = Command;
```

Defined in: [index.ts:32](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/cli/src/index.ts#L32)

Type representing the GraphQL Markdown CLI.

### See

[GraphQL Markdown Documentation](https://graphql-markdown.dev)

---

## getGraphQLMarkdownCli() \{#getgraphqlmarkdowncli\}

```ts
function getGraphQLMarkdownCli(
  options,
  loggerModule?,
  customFormatter?,
): Command;
```

Defined in: [index.ts:89](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/cli/src/index.ts#L89)

Configures and returns the GraphQL Markdown CLI.

### Parameters

#### options

`ConfigOptions`

Options for configuring the GraphQL Markdown CLI.

#### loggerModule?

`string`

Optional logger module to use.

#### customFormatter?

`string`

Optional default formatter package name. When provided, registers
`--formatter` and `--mdxParser` (deprecated) flags with this value as the default.

### Returns

`Command`

The configured CLI instance.

### Example

```typescript
const cli = getGraphQLMarkdownCli(
  { id: "custom" },
  "custom-logger",
  "@graphql-markdown/formatters/docusaurus",
);
await cli.parseAsync(process.argv);
```

---

## runGraphQLMarkdown() \{#rungraphqlmarkdown\}

```ts
function runGraphQLMarkdown(options, cliOptions, loggerModule?): Promise<void>;
```

Defined in: [index.ts:50](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/cli/src/index.ts#L50)

Runs the GraphQL Markdown CLI to generate documentation from a GraphQL schema.

### Parameters

#### options

`ConfigOptions`

Options for configuring the GraphQL Markdown CLI.

#### cliOptions

`CliOptions`

Command-line options passed to the CLI.

#### loggerModule?

`string`

Optional logger module to use.

### Returns

`Promise`&lt;`void`&gt;

### Example

```typescript
await runGraphQLMarkdown(
  { id: "custom" },
  { schema: "./schema.graphql", root: "./docs" },
  "custom-logger",
);
```

---

## main

Entry point for the GraphQL Markdown CLI.
Loads configuration from graphql-config and sets up command-line interface.

## EXTENSION_NAME \{#extension_name\}

```ts
const EXTENSION_NAME: "graphql-markdown";
```

Defined in: [main.ts:23](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/cli/src/main.ts#L23)

Name of the GraphQL Markdown extension for graphql-config

---

## graphQLConfigExtension \{#graphqlconfigextension\}

```ts
const graphQLConfigExtension: GraphQLExtensionDeclaration;
```

Defined in: [main.ts:29](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/cli/src/main.ts#L29)

GraphQL config extension declaration for GraphQL Markdown

### Returns

Extension configuration object

---

## config

Configuration management for GraphQL Markdown.

This module handles all aspects of configuration including:

- Loading and merging configuration from multiple sources
- Validating configuration values
- Providing defaults for missing options
- Processing special configuration options (directives, deprecated items, etc)

The configuration follows this precedence (highest to lowest):

1. CLI arguments
2. Config file options
3. GraphQL Config options
4. Default values

## DeprecatedOption \{#deprecatedoption\}

Defined in: [core/src/config.ts:98](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L98)

Options for handling deprecated items in the schema.

- DEFAULT: Show deprecated items normally
- GROUP: Group deprecated items separately
- SKIP: Exclude deprecated items from documentation

### Example

```typescript
const deprecatedHandling = DeprecatedOption.GROUP;
```

### Enumeration Members

#### DEFAULT \{#default\}

```ts
DEFAULT: "default";
```

Defined in: [core/src/config.ts:99](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L99)

#### GROUP \{#group\}

```ts
GROUP: "group";
```

Defined in: [core/src/config.ts:100](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L100)

#### SKIP \{#skip\}

```ts
SKIP: "skip";
```

Defined in: [core/src/config.ts:101](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L101)

---

## DiffMethod \{#diffmethod\}

Defined in: [core/src/config.ts:80](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L80)

Diff methods used to determine how schema changes are processed.

- NONE: No diffing is performed
- FORCE: Force regeneration of documentation regardless of schema changes

### Example

```typescript
const diffMethod = DiffMethod.FORCE;
```

### Enumeration Members

#### FORCE \{#force\}

```ts
FORCE: "FORCE";
```

Defined in: [core/src/config.ts:82](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L82)

#### NONE \{#none\}

```ts
NONE: "NONE";
```

Defined in: [core/src/config.ts:81](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L81)

---

## TypeHierarchy \{#typehierarchy\}

Defined in: [core/src/config.ts:62](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L62)

Type hierarchy options for organizing schema documentation.

- API: Groups types by their role in the API (Query, Mutation, etc.)
- ENTITY: Groups types by their entity relationships
- FLAT: No grouping, all types in a flat structure

### Example

```typescript
const hierarchy = TypeHierarchy.API;
```

### Enumeration Members

#### API \{#api\}

```ts
API: "api";
```

Defined in: [core/src/config.ts:63](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L63)

#### ENTITY \{#entity\}

```ts
ENTITY: "entity";
```

Defined in: [core/src/config.ts:64](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L64)

#### FLAT \{#flat\}

```ts
FLAT: "flat";
```

Defined in: [core/src/config.ts:65](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L65)

---

## ASSET_HOMEPAGE_LOCATION \{#asset_homepage_location\}

```ts
const ASSET_HOMEPAGE_LOCATION: string;
```

Defined in: [core/src/config.ts:119](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L119)

Location of the default homepage template.

---

## DEFAULT_HIERARCHY \{#default_hierarchy\}

```ts
const DEFAULT_HIERARCHY: object;
```

Defined in: [core/src/config.ts:130](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L130)

Default hierarchy configuration using the API hierarchy type.

### Type Declaration

#### api \{#api-1\}

```ts
api: object = {};
```

---

## DEFAULT_OPTIONS \{#default_options\}

```ts
const DEFAULT_OPTIONS: Readonly<
  Pick<
    ConfigOptions,
    "customDirective" | "groupByDirective" | "loaders" | "outputAdapter"
  > &
    Required<
      Omit<
        ConfigOptions,
        | "customDirective"
        | "formatter"
        | "groupByDirective"
        | "loaders"
        | "mdxParser"
        | "outputAdapter"
        | "printTypeOptions"
      >
    >
> &
  object;
```

Defined in: [core/src/config.ts:142](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L142)

Default configuration options used when no user options are provided.
These values serve as fallbacks for any missing configuration.

### Type Declaration

#### printTypeOptions

```ts
printTypeOptions: Required<
  Omit<ConfigPrintTypeOptions, "exampleSection" | "hierarchy">
> & object;
```

##### Type Declaration

###### exampleSection

```ts
exampleSection: ConfigPrintTypeOptions["exampleSection"];
```

###### hierarchy

```ts
hierarchy: Required<Pick<TypeHierarchyObjectType, API>>;
```

### See

Options for the complete configuration interface

---

## DOCS_URL \{#docs_url\}

```ts
const DOCS_URL: "https://graphql-markdown.dev/docs";
```

Defined in: [core/src/config.ts:108](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L108)

Documentation website URL for reference in error messages and help text.

---

## PACKAGE_NAME \{#package_name\}

```ts
const PACKAGE_NAME: "@graphql-markdown/docusaurus";
```

Defined in: [core/src/config.ts:114](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L114)

Default package name used for temporary directory creation and identification.

---

## buildConfig() \{#buildconfig\}

```ts
function buildConfig(configFileOpts, cliOpts?, id?): Promise<Options>;
```

Defined in: [core/src/config.ts:790](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L790)

### Parameters

#### configFileOpts

`Maybe`&lt;`ConfigOptions`&gt;

#### cliOpts?

`Maybe`&lt;`CliOptions`&gt;

#### id?

`Maybe`&lt;`string`&gt; = `"default"`

### Returns

`Promise`&lt;`Options`&gt;

---

## getCustomDirectives() \{#getcustomdirectives\}

```ts
function getCustomDirectives(
  customDirectiveOptions,
  skipDocDirective?,
): Maybe<CustomDirective>;
```

Defined in: [core/src/config.ts:402](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L402)

Processes custom directives, filtering out any that should be skipped.
Validates that each custom directive has the correct format with required functions.

### Parameters

#### customDirectiveOptions

`Maybe`&lt;`CustomDirective`&gt;

The custom directive configuration object

#### skipDocDirective?

`Maybe`&lt;`DirectiveName`[]&gt;

Array of directive names that should be skipped

### Returns

`Maybe`&lt;`CustomDirective`&gt;

The filtered custom directives object, or `undefined` if empty/invalid

### Throws

Error if a custom directive has an invalid format

### Example

```typescript
// Valid custom directive with descriptor function
const customDirectives = {
  example: {
    tag: (value) => `Example: ${value}`,
  },
  note: {
    descriptor: () => "Note items",
  },
};

// Filter out the "example" directive, keeping "note"
const filteredDirectives = getCustomDirectives(customDirectives, ["example"]);
console.log(filteredDirectives); // { note: { descriptor: [Function] } }

// Invalid format - will throw an error
getCustomDirectives({ example: { invalid: true } }, []);
// Error: Wrong format for plugin custom directive "example"...
```

### See

[DOCS_URL](#docs_url)/advanced/custom-directive for custom directive format documentation

---

## getDiffMethod() \{#getdiffmethod\}

```ts
function getDiffMethod(diff): TypeDiffMethod;
```

Defined in: [core/src/config.ts:457](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L457)

### Parameters

#### diff

`TypeDiffMethod`

### Returns

`TypeDiffMethod`

---

## getDocDirective() \{#getdocdirective\}

```ts
function getDocDirective(name): DirectiveName;
```

Defined in: [core/src/config.ts:226](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L226)

Retrieves a directive name from a string by parsing and validating the format.
Directive names should be prefixed with '@' (e.g., '@example').

### Parameters

#### name

`Maybe`&lt;`DirectiveName`&gt;

The directive name as a string, which should follow the format '@directiveName'

### Returns

`DirectiveName`

The validated directive name without the '@' prefix

### Throws

Error if the directive name format is invalid

### Example

```typescript
const directive = getDocDirective("@example");
console.log(directive); // "example"

// Invalid - will throw an error
getDocDirective("example"); // Error: Invalid "example"
```

---

## getDocOptions() \{#getdocoptions\}

```ts
function getDocOptions(cliOpts?, configOptions?): Required<ConfigDocOptions>;
```

Defined in: [core/src/config.ts:490](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L490)

Builds the document options by merging CLI options, config file options, and defaults.
Handles index generation flag and front matter configuration.

### Parameters

#### cliOpts?

`Maybe`&lt;`CliOptions`&gt;

CLI options for document generation

#### configOptions?

`Maybe`&lt;`ConfigDocOptions`&gt;

Config file options for document generation

### Returns

`Required`&lt;`ConfigDocOptions`&gt;

The resolved document options with all required fields

### Example

```typescript
const cliOptions = { index: true };
const configOptions = { frontMatter: { sidebar_label: "API" } };

const docOptions = getDocOptions(cliOptions, configOptions);
console.log(docOptions);
// {
//   index: true,
//   frontMatter: { sidebar_label: 'API' }
// }
```

---

## getForcedDiffMethod() \{#getforceddiffmethod\}

```ts
function getForcedDiffMethod(): TypeDiffMethod;
```

Defined in: [core/src/config.ts:448](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L448)

Returns FORCE as the diff method.
This function is used when documentation should be forcefully regenerated.

### Returns

`TypeDiffMethod`

The FORCE diff method

### Example

```typescript
const method = getForcedDiffMethod();
console.log(method); // "FORCE"
```

### See

[DiffMethod](#diffmethod) for available diff methods

---

## getOnlyDocDirectives() \{#getonlydocdirectives\}

```ts
function getOnlyDocDirectives(cliOpts, configFileOpts): DirectiveName[];
```

Defined in: [core/src/config.ts:257](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L257)

Retrieves the list of "only" directives from CLI and config options.
These directives specify which schema elements should be included in the documentation.

### Parameters

#### cliOpts

`Maybe`&lt;`CliOptions`&gt;

CLI options containing "only" directives

#### configFileOpts

`Maybe`&lt;`Pick`&lt;`ConfigOptions`, `"onlyDocDirective"`&gt;&gt;

Config file options containing "onlyDocDirective"

### Returns

`DirectiveName`[]

An array of validated "only" directives (without '@' prefix)

### Example

```typescript
const cliOptions = { only: ["@example", "@internal"] };
const configOptions = { onlyDocDirective: ["@auth"] };

const onlyDirectives = getOnlyDocDirectives(cliOptions, configOptions);
console.log(onlyDirectives); // ["example", "internal", "auth"]
```

### See

[getDocDirective](#getdocdirective) for directive name validation

---

## getSkipDocDirectives() \{#getskipdocdirectives\}

```ts
function getSkipDocDirectives(cliOpts, configFileOpts): DirectiveName[];
```

Defined in: [core/src/config.ts:292](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L292)

Retrieves the list of "skip" directives from CLI and config options.
These directives specify which schema elements should be excluded from the documentation.
Additionally, if deprecated handling is set to SKIP, adds the "deprecated" directive.

### Parameters

#### cliOpts

`Maybe`&lt;`CliOptions`&gt;

CLI options containing "skip" directives

#### configFileOpts

`Maybe`&lt;`Pick`&lt;`ConfigOptions`, `"printTypeOptions"` \| `"skipDocDirective"`&gt;&gt;

Config file options containing "skipDocDirective" and potentially "printTypeOptions.deprecated"

### Returns

`DirectiveName`[]

An array of validated "skip" directives (without '@' prefix)

### Example

```typescript
const cliOptions = { skip: ["@internal"], deprecated: "skip" };
const configOptions = { skipDocDirective: ["@auth"] };

const skipDirectives = getSkipDocDirectives(cliOptions, configOptions);
console.log(skipDirectives); // ["internal", "auth", "deprecated"]
```

### See

- [getDocDirective](#getdocdirective) for directive name validation
- [DeprecatedOption](#deprecatedoption) for deprecated handling options

---

## getTypeHierarchyOption() \{#gettypehierarchyoption\}

```ts
function getTypeHierarchyOption(
  cliOption?,
  configOption?,
): Maybe<Partial<Record<TypeHierarchyValueType, TypeHierarchyTypeOptions>>>;
```

Defined in: [core/src/config.ts:546](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L546)

Resolves the type hierarchy configuration by merging CLI and config file options.
Validates that CLI and config don't specify conflicting hierarchy types.

### Parameters

#### cliOption?

`Maybe`&lt;`TypeHierarchyValueType`&gt;

The hierarchy option specified via CLI (string value)

#### configOption?

`Maybe`&lt;`TypeHierarchyType`&gt;

The hierarchy option from the config file (string or object)

### Returns

`Maybe`&lt;`Partial`&lt;`Record`&lt;`TypeHierarchyValueType`, `TypeHierarchyTypeOptions`&gt;&gt;&gt;

The resolved type hierarchy object

### Throws

Error if CLI and config specify conflicting hierarchy types

### Example

```typescript
// Using hierarchy from CLI (string format)
const hierarchy1 = getTypeHierarchyOption("api", undefined);
console.log(hierarchy1); // { api: {} }

// Using hierarchy from config (object format)
const hierarchy2 = getTypeHierarchyOption(undefined, {
  entity: { User: ["posts"] },
});
console.log(hierarchy2); // { entity: { User: ["posts"] } }

// Error case - conflicting hierarchies
getTypeHierarchyOption("api", { entity: {} });
// Error: Hierarchy option mismatch in CLI flag 'api' and config 'entity'
```

### See

[TypeHierarchy](#typehierarchy) for available hierarchy types

---

## getVisibilityDirectives() \{#getvisibilitydirectives\}

```ts
function getVisibilityDirectives(cliOpts, configFileOpts): object;
```

Defined in: [core/src/config.ts:346](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L346)

Combines and validates visibility directives (only and skip) from both CLI and config sources.
Ensures that no directive appears in both "only" and "skip" lists simultaneously.

### Parameters

#### cliOpts

`Maybe`&lt;`CliOptions`&gt;

CLI options containing "only" and "skip" directives

#### configFileOpts

`Maybe`&lt;`Pick`&lt;`ConfigOptions`, `"onlyDocDirective"` \| `"printTypeOptions"` \| `"skipDocDirective"`&gt;&gt;

Config file options containing directive configurations

### Returns

`object`

An object with validated "onlyDocDirective" and "skipDocDirective" arrays

#### onlyDocDirective

```ts
onlyDocDirective: DirectiveName[];
```

#### skipDocDirective

```ts
skipDocDirective: DirectiveName[];
```

### Throws

Error if the same directive appears in both "only" and "skip" lists

### Example

```typescript
const cliOptions = { only: ["@example"], skip: ["@internal"] };
const configOptions = { onlyDocDirective: ["@auth"] };

const visibilityDirectives = getVisibilityDirectives(cliOptions, configOptions);
console.log(visibilityDirectives);
// {
//   onlyDocDirective: ["example", "auth"],
//   skipDocDirective: ["internal"]
// }

// Invalid - will throw an error
getVisibilityDirectives({ only: ["@example"], skip: ["@example"] }, {}); // Error: The same directive cannot be declared in 'onlyDocDirective' and 'skipDocDirective'.
```

### See

[getOnlyDocDirectives](#getonlydocdirectives) and [getSkipDocDirectives](#getskipdocdirectives) for directive retrieval

---

## parseDeprecatedDocOptions() \{#parsedeprecateddocoptions\}

```ts
function parseDeprecatedDocOptions(
  _cliOpts?,
  _configOptions?,
): Record<string, never>;
```

Defined in: [core/src/config.ts:462](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L462)

### Parameters

#### \_cliOpts?

`Maybe`&lt;`CliOptions`&gt;

#### \_configOptions?

`Maybe`&lt;`ConfigDocOptions`&gt;

### Returns

`Record`&lt;`string`, `never`&gt;

---

## parseDeprecatedFormatterOption() \{#parsedeprecatedformatteroption\}

```ts
function parseDeprecatedFormatterOption(
  cliOpts?,
  configOptions?,
): Maybe<string>;
```

Defined in: [core/src/config.ts:591](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L591)

### Parameters

#### cliOpts?

`Maybe`&lt;`CliOptions`&gt;

#### configOptions?

`Maybe`&lt;`ConfigOptions`&gt;

### Returns

`Maybe`&lt;`string`&gt;

---

## parseDeprecatedPrintTypeOptions() \{#parsedeprecatedprinttypeoptions\}

```ts
function parseDeprecatedPrintTypeOptions(
  _cliOpts?,
  _configOptions?,
): Record<string, never>;
```

Defined in: [core/src/config.ts:612](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L612)

### Parameters

#### \_cliOpts?

`Maybe`&lt;`CliOptions`&gt;

#### \_configOptions?

`Maybe`&lt;`ConfigPrintTypeOptions`&gt;

### Returns

`Record`&lt;`string`, `never`&gt;

---

## parseGroupByOption() \{#parsegroupbyoption\}

```ts
function parseGroupByOption(groupOptions): Maybe<GroupByDirectiveOptions>;
```

Defined in: [core/src/config.ts:701](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L701)

Parses and validates the groupByDirective option string format.
The format should be @directive(field|=fallback) where:

- directive: Name of the directive to group by
- field: Name of the field in the directive to use for grouping
- fallback: (Optional) Fallback group name for items without the directive

### Parameters

#### groupOptions

`unknown`

The group directive option as a string

### Returns

`Maybe`&lt;`GroupByDirectiveOptions`&gt;

A parsed `GroupByDirectiveOptions` object or `undefined` if invalid

### Throws

Error if the groupByDirective format is invalid

### Example

```typescript
// Basic usage with directive and field
const groupBy1 = parseGroupByOption("@tag(name)");
console.log(groupBy1);
// { directive: "tag", field: "name", fallback: "Miscellaneous" }

// With custom fallback group
const groupBy2 = parseGroupByOption("@category(name|=Other)");
console.log(groupBy2);
// { directive: "category", field: "name", fallback: "Other" }

// Invalid format - will throw an error
parseGroupByOption("invalid-format");
// Error: Invalid "invalid-format"
```

---

## parseHomepageOption() \{#parsehomepageoption\}

```ts
function parseHomepageOption(cliHomepage, configHomepage): Maybe<string>;
```

Defined in: [core/src/config.ts:722](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/config.ts#L722)

### Parameters

#### cliHomepage

`Maybe`&lt;`string` \| `false`&gt;

#### configHomepage

`Maybe`&lt;`string` \| `false`&gt;

### Returns

`Maybe`&lt;`string`&gt;

---

## homepage(Const)

## DEFAULT_HOMEPAGE_TEMPLATE \{#default_homepage_template\}

```ts
const DEFAULT_HOMEPAGE_TEMPLATE: "---\nid: schema\nslug: ##baseURL##\ntitle: Schema Documentation\nsidebar_position: 1\nhide_table_of_contents: true\npagination_next: null\npagination_prev: null\nsidebar_class_name: navbar__toggle\n---\n\nThis documentation has been automatically generated from the GraphQL schema with GraphQL-Markdown.\n";
```

Defined in: [core/src/const/homepage.ts:15](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/const/homepage.ts#L15)

**`Internal`**

The built-in homepage template, inlined.

The same content ships as `assets/generated.md` so anyone can point
`homepage` at it, copy it, or diff against it. Inlining it here means the
default path never touches the filesystem: rendering the homepage was the
last filesystem _read_ on the render path, and a write-only output adapter
has no way to satisfy one.

`assets/generated.md` remains the canonical artifact. A unit test asserts the
two are identical, so they cannot drift.

---

## patterns

Regular expressions and string patterns used throughout the core package.

This module centralizes all regex patterns and constants to ensure consistency
and simplify maintenance when patterns need to be updated.

## CONFIG_CONSTANTS \{#config_constants\}

```ts
const CONFIG_CONSTANTS: object;
```

Defined in: [core/src/const/patterns.ts:115](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/const/patterns.ts#L115)

String constants used for configuration parsing and defaults.

### Type Declaration

#### DEFAULT_GROUP \{#default_group\}

```ts
readonly DEFAULT_GROUP: "Miscellaneous";
```

Default fallback group name used when groupByDirective is configured.
Items without the grouping directive are assigned to this group.

---

## PATTERNS \{#patterns\}

```ts
const PATTERNS: object;
```

Defined in: [core/src/const/patterns.ts:20](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/const/patterns.ts#L20)

Central repository of regex patterns used for configuration parsing and string transformation.

### Type Declaration

#### CASE_TRANSITION \{#case_transition\}

```ts
readonly CASE_TRANSITION: RegExp;
```

Matches transitions between lowercase/digits and uppercase letters.
Used to insert spaces in camelCase strings (e.g., "userId" → "user Id").

##### Pattern

`([a-z]+|\d+)([A-Z])`

##### Example

```ts
- "userId" matches → insert space between "id" and "U" → "user Id"
- "HTTPServer" does not match (no lowercase/digit before uppercase)
- "get2Users" matches → insert space between "2" and "U" → "get 2 Users"
```

#### DIGIT_LETTER_TRANSITION \{#digit_letter_transition\}

```ts
readonly DIGIT_LETTER_TRANSITION: RegExp;
```

Matches transitions from digits to letters.
Used to insert spaces between numbers and letters (e.g., "2k" → "2 k").

##### Pattern

`(\d+)([a-z])`

##### Example

```ts
- "2k" matches → "2 k"
- "123abc" matches → "123 abc"
- "2K" does not match (K is uppercase)
```

#### DIRECTIVE_NAME \{#directive_name\}

```ts
readonly DIRECTIVE_NAME: RegExp;
```

Matches directive names with named capture groups.
Captures the directive name after the @ symbol.

##### Pattern

`^\@(?<directive>\w+)$`

##### Example

```ts
- "@tag" matches → directive: "tag"
- "@myDirective" matches → directive: "myDirective"
- "@" does not match
- "tag" does not match
```

#### GROUP_BY_DIRECTIVE \{#group_by_directive\}

```ts
readonly GROUP_BY_DIRECTIVE: RegExp;
```

Matches group-by directive format with directive name, field, and optional fallback.
Groups: (1) directive name, (2) field name, (3) optional fallback

##### Pattern

`^\@(\w+)\((\w+)(?:\|=(\w+))?\)$`

##### Example

```ts
- "@tag(name)" matches → ["@tag(name)", "tag", "name", undefined]
- "@category(type|=Other)" matches → ["@category(type|=Other)", "category", "type", "Other"]
- "@tag()" does not match
- "tag(name)" does not match
```

#### LETTER_DIGIT_TRANSITION \{#letter_digit_transition\}

```ts
readonly LETTER_DIGIT_TRANSITION: RegExp;
```

Matches transitions from letters to digits.
Used to insert spaces between letters and numbers (e.g., "user1" → "user 1").

##### Pattern

`([a-z]+)(\d)`

##### Example

```ts
- "user1" matches → "user 1"
- "abc123" matches → "abc 123"
- "U1" does not match (U is uppercase)
```

#### NUMERIC_PREFIX \{#numeric_prefix\}

```ts
readonly NUMERIC_PREFIX: RegExp;
```

Matches numeric prefix for sorted categories (e.g., "01-query" → "query").
Used to extract category names from numbered folder names.

Pattern: `^\d{2}-`

##### Example

```typescript
- "01-query" matches → remove "01-" → "query"
- "02-mutations" matches → remove "02-" → "mutations"
- "query" does not match
- "1-query" does not match (only 1 digit)
```

#### WORD_BOUNDARY \{#word_boundary\}

```ts
readonly WORD_BOUNDARY: RegExp;
```

Matches word boundaries (non-alphanumeric characters) for string splitting.
Used globally to split strings on any non-alphanumeric character.

##### Pattern

`[^0-9A-Za-z]+`

##### Example

```ts
- "hello-world" split → ["hello", "world"]
- "hello_world" split → ["hello", "world"]
- "hello world" split → ["hello", "world"]
```

### Example

```typescript
import { PATTERNS } from "@graphql-markdown/core/const/patterns";

const match = PATTERNS.DIRECTIVE_NAME.exec("@myDirective");
```

---

## diff

Diff utilities for detecting schema changes between builds.

## Schema

### hasChanges() \{#haschanges\}

```ts
function hasChanges(schema, tmpDir, diffMethod, diffModule?): Promise<boolean>;
```

Defined in: [core/src/diff.ts:67](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/diff.ts#L67)

Determines if there are changes in the GraphQL schema by using a specified diff method and module.

#### Parameters

##### schema

`GraphQLSchema`

The GraphQL schema to check for changes.

##### tmpDir

`string`

The temporary directory to store intermediate files during the diff process.

##### diffMethod

`Maybe`&lt;`DiffMethodName`&gt;

The name of the diff method to use. Must be a string or `null`.

##### diffModule?

`Maybe`&lt;`string`&gt; = `"@graphql-markdown/diff"`

The module to import for performing the diff. Defaults to `@graphql-markdown/diff`.

#### Returns

`Promise`&lt;`boolean`&gt;

A promise that resolves to `true` if changes are detected or if the diff method/module is invalid, otherwise `false`.

#### Examples

```typescript
import { hasChanges } from "./diff";
import { buildSchema } from "graphql";

const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

const changesDetected = await hasChanges(schema, "/tmp", "methodName");
console.log(changesDetected); // true or false
```

**Using with a custom diff module**

```typescript
import { hasChanges } from "./diff";

const schema = getMySchema();
const result = await hasChanges(
  schema,
  "/tmp/schema-diff",
  "breaking",
  "./my-custom-diff-module",
);
```

#### Throws

Will log a warning if the specified diff module cannot be found.

#### See

- DiffMethodName for available diff methods
- FunctionCheckSchemaChanges for the signature of the function imported from the diff module

#### Since

1.0.0

---

## validation

Configuration validation utilities for directive and configuration options.

Provides type guard functions and validators for checking configuration object shapes,
function types, and property existence patterns commonly used across the codebase.

## hasDescriptor() \{#hasdescriptor\}

```ts
function hasDescriptor(
  config,
): config is Record<"descriptor", (args: unknown[]) => unknown>;
```

Defined in: [core/src/directives/validation.ts:40](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/directives/validation.ts#L40)

Type guard to check if an object has a `descriptor` function property.

Validates that the object is a proper type object and contains a function named `descriptor`.

### Parameters

#### config

`unknown`

The configuration object to check

### Returns

`config is Record<"descriptor", (args: unknown[]) => unknown>`

True if config has a descriptor function property

### Example

```typescript
if (hasDescriptor(option)) {
  // option.descriptor is guaranteed to be a function
  const result = option.descriptor(directive);
}
```

---

## hasTag() \{#hastag\}

```ts
function hasTag(config): config is Record<"tag", (args: unknown[]) => unknown>;
```

Defined in: [core/src/directives/validation.ts:67](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/directives/validation.ts#L67)

Type guard to check if an object has a `tag` function property.

Validates that the object is a proper type object and contains a function named `tag`.

### Parameters

#### config

`unknown`

The configuration object to check

### Returns

`config is Record<"tag", (args: unknown[]) => unknown>`

True if config has a tag function property

### Example

```typescript
if (hasTag(option)) {
  // option.tag is guaranteed to be a function
  const result = option.tag(directive);
}
```

---

## isGroupsObject() \{#isgroupsobject\}

```ts
function isGroupsObject(groups): groups is Record<string, string>;
```

Defined in: [core/src/directives/validation.ts:155](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/directives/validation.ts#L155)

Type guard to check if a value is a configuration group object.

Validates that the value is a type object (not null, not array, not primitive).

### Parameters

#### groups

`unknown`

The groups value to check

### Returns

`groups is Record<string, string>`

True if groups is an object mapping (not an array)

### Example

```typescript
if (isGroupsObject(options.groups)) {
  // groups is an object with configuration overrides
  folderNames = { ...API_GROUPS, ...groups };
}
```

---

## isInvalidFunctionProperty() \{#isinvalidfunctionproperty\}

```ts
function isInvalidFunctionProperty(
  config,
  property,
): config is Record<string, unknown>;
```

Defined in: [core/src/directives/validation.ts:198](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/directives/validation.ts#L198)

Type guard to check if a descriptor or tag property is NOT a function.

Used for validation to detect invalid configuration where descriptor or tag
are defined but are not callable functions.

### Parameters

#### config

`unknown`

The configuration object to check

#### property

`"descriptor"` \| `"tag"`

The property name to check ("descriptor" or "tag")

### Returns

`config is Record<string, unknown>`

True if the property exists but is not a function

### Example

```typescript
if (isInvalidFunctionProperty(option, "descriptor")) {
  throw new Error("descriptor must be a function");
}
```

---

## isLoaderString() \{#isloaderstring\}

```ts
function isLoaderString(loader): loader is string;
```

Defined in: [core/src/directives/validation.ts:177](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/directives/validation.ts#L177)

Type guard to check if a value is a loader module name (string).

Validates that the value is a string representing a module name for dynamic loading.

### Parameters

#### loader

`unknown`

The loader value to check

### Returns

`loader is string`

True if loader is a string module name

### Example

```typescript
if (isLoaderString(loaders[name])) {
  // loaders[name] is a string module name that needs wrapping
  loaders[name] = { module: loaders[name], options };
}
```

---

## isPath() \{#ispath\}

```ts
function isPath(path): path is string;
```

Defined in: [core/src/directives/validation.ts:135](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/directives/validation.ts#L135)

Type guard to check if a value is a valid non-empty path string.

Validates that the value is a string and not empty, suitable for file paths or URLs.

### Parameters

#### path

`unknown`

The path value to check

### Returns

`path is string`

True if path is a non-empty string

### Example

```typescript
if (isPath(folderPath)) {
  // folderPath is guaranteed to be a non-empty string
  const fullPath = join(basePath, folderPath);
}
```

---

## isSchemaObject() \{#isschemaobject\}

```ts
function isSchemaObject(schema): schema is Record<string, unknown>;
```

Defined in: [core/src/directives/validation.ts:113](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/directives/validation.ts#L113)

Type guard to check if a value is a schema object (key-value mapping).

Validates that the value is a type object, not null, not an array, and can be treated as a schema map.

### Parameters

#### schema

`unknown`

The schema value to check

### Returns

`schema is Record<string, unknown>`

True if schema is an object mapping (not an array)

### Example

```typescript
if (isSchemaObject(projectConfig.schema)) {
  // Extract first key from schema map
  const key = Object.keys(schema)[0];
}
```

---

## isSchemaString() \{#isschemastring\}

```ts
function isSchemaString(schema): schema is string;
```

Defined in: [core/src/directives/validation.ts:93](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/directives/validation.ts#L93)

Type guard to check if a value is a schema string.

Validates that the value is a string representing a GraphQL schema path or URL.

### Parameters

#### schema

`unknown`

The schema value to check

### Returns

`schema is string`

True if schema is a string

### Example

```typescript
if (isSchemaString(config.schema)) {
  // config.schema is a string path/URL
  const schemaUrl = config.schema;
}
```

---

## event-emitter

## Events

### EmitResult \{#emitresult\}

Defined in: [core/src/event-emitter.ts:9](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/event-emitter.ts#L9)

Result object returned when emitting a cancellable event.

#### Properties

##### defaultPrevented \{#defaultprevented\}

```ts
defaultPrevented: boolean;
```

Defined in: [core/src/event-emitter.ts:20](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/event-emitter.ts#L20)

Whether any handler called preventDefault() on the event.
Only applicable if the event is cancellable.

##### errors \{#errors\}

```ts
errors: Error[];
```

Defined in: [core/src/event-emitter.ts:14](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/event-emitter.ts#L14)

Array of errors that occurred during handler execution.
Handlers continue executing even if previous handlers throw errors.

---

### getEvents() \{#getevents\}

```ts
function getEvents(): CancellableEventEmitter;
```

Defined in: [core/src/event-emitter.ts:172](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/event-emitter.ts#L172)

Get the singleton event emitter instance.

Creates the instance on first call, then returns the same instance on subsequent calls.
This ensures all parts of the application share the same event bus.

#### Returns

`CancellableEventEmitter`

The singleton CancellableEventEmitter instance

#### Example

```typescript
// In generator.ts
const events = getEvents();
events.on("beforeLoadSchema", handler);

// In renderer.ts - same instance!
const events = getEvents();
await events.emitAsync("beforeLoadSchema", event);
```

---

### resetEvents() \{#resetevents\}

```ts
function resetEvents(): void;
```

Defined in: [core/src/event-emitter.ts:196](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/event-emitter.ts#L196)

Reset the event emitter singleton.

Removes all event listeners and clears the instance.
The next call to getEvents() will create a fresh instance.

**Important:** This should only be used in tests to ensure test isolation.

#### Returns

`void`

#### Example

```typescript
// In test setup
afterEach(() => {
  resetEvents();
  jest.restoreAllMocks();
});
```

---

## event-handlers

MDX event handler registration functionality.

This module provides utilities for registering MDX module event handlers
with the event emitter system. It maps event names to callback names and
automatically detects and registers matching callbacks from MDX modules.

## registerMDXEventHandlers() \{#registermdxeventhandlers\}

```ts
function registerMDXEventHandlers(mdxModule): void;
```

Defined in: [core/src/event-handlers.ts:35](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/event-handlers.ts#L35)

Registers MDX module lifecycle event handlers with the event emitter.

Automatically detects and registers any lifecycle hook functions defined in the mdxModule
that match the event callback naming convention. Logs registered handlers at debug level.

Note: Format functions (formatMDXBadge, etc.) are NOT registered as events.
They are pure transformations handled via the Formatter interface directly.

### Parameters

#### mdxModule

`unknown`

The MDX module that may contain event callback functions

### Returns

`void`

### Example

```typescript
const mdxModule = {
  beforeLoadSchemaHook: async (event) => {
    console.log("Loading schema...");
  },
  afterRenderTypeEntitiesHook: async (event) => {
    console.log("Rendered:", event.data.name);
  },
};
registerMDXEventHandlers(mdxModule);
```

---

## event-map

Event callback mapping configuration.

This module defines the mappings between event names and their corresponding
callback names in MDX modules. Kept separate to avoid circular dependencies.

## EVENT_CALLBACK_MAP \{#event_callback_map\}

```ts
const EVENT_CALLBACK_MAP: object;
```

Defined in: [core/src/event-map.ts:25](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/event-map.ts#L25)

Event callback mapping configuration.
Maps event names to their corresponding callback names in mdxModule.

Note: Format functions (formatMDXBadge, formatMDXAdmonition, etc.) are NOT included here.
They are pure transformations handled via the Formatter interface, not events.

### Type Declaration

#### diff:afterCheck \{#diffaftercheck\}

```ts
readonly diff:afterCheck: "afterCheckDiffHook" = "afterCheckDiffHook";
```

#### diff:beforeCheck \{#diffbeforecheck\}

```ts
readonly diff:beforeCheck: "beforeCheckDiffHook" = "beforeCheckDiffHook";
```

#### print:afterPrintCode \{#printafterprintcode\}

```ts
readonly print:afterPrintCode: "afterPrintCodeHook" = "afterPrintCodeHook";
```

#### print:afterPrintType \{#printafterprinttype\}

```ts
readonly print:afterPrintType: "afterPrintTypeHook" = "afterPrintTypeHook";
```

#### print:beforeComposePageType \{#printbeforecomposepagetype\}

```ts
readonly print:beforeComposePageType: "beforeComposePageTypeHook" = "beforeComposePageTypeHook";
```

#### print:beforePrintCode \{#printbeforeprintcode\}

```ts
readonly print:beforePrintCode: "beforePrintCodeHook" = "beforePrintCodeHook";
```

#### print:beforePrintType \{#printbeforeprinttype\}

```ts
readonly print:beforePrintType: "beforePrintTypeHook" = "beforePrintTypeHook";
```

#### render:afterGenerateIndexMetafile \{#renderaftergenerateindexmetafile\}

```ts
readonly render:afterGenerateIndexMetafile: "afterGenerateIndexMetafileHook" = "afterGenerateIndexMetafileHook";
```

#### render:afterRenderFiles \{#renderafterrenderfiles\}

```ts
readonly render:afterRenderFiles: "afterRenderFilesHook" = "afterRenderFilesHook";
```

#### render:afterRenderHomepage \{#renderafterrenderhomepage\}

```ts
readonly render:afterRenderHomepage: "afterRenderHomepageHook" = "afterRenderHomepageHook";
```

#### render:afterRenderRootTypes \{#renderafterrenderroottypes\}

```ts
readonly render:afterRenderRootTypes: "afterRenderRootTypesHook" = "afterRenderRootTypesHook";
```

#### render:afterRenderTypeEntities \{#renderafterrendertypeentities\}

```ts
readonly render:afterRenderTypeEntities: "afterRenderTypeEntitiesHook" = "afterRenderTypeEntitiesHook";
```

#### render:beforeGenerateIndexMetafile \{#renderbeforegenerateindexmetafile\}

```ts
readonly render:beforeGenerateIndexMetafile: "beforeGenerateIndexMetafileHook" = "beforeGenerateIndexMetafileHook";
```

#### render:beforeRenderHomepage \{#renderbeforerenderhomepage\}

```ts
readonly render:beforeRenderHomepage: "beforeRenderHomepageHook" = "beforeRenderHomepageHook";
```

#### render:beforeRenderRootTypes \{#renderbeforerenderroottypes\}

```ts
readonly render:beforeRenderRootTypes: "beforeRenderRootTypesHook" = "beforeRenderRootTypesHook";
```

#### render:beforeRenderTypeEntities \{#renderbeforerendertypeentities\}

```ts
readonly render:beforeRenderTypeEntities: "beforeRenderTypeEntitiesHook" = "beforeRenderTypeEntitiesHook";
```

#### schema:afterLoad \{#schemaafterload\}

```ts
readonly schema:afterLoad: "afterLoadSchemaHook" = "afterLoadSchemaHook";
```

#### schema:beforeLoad \{#schemabeforeload\}

```ts
readonly schema:beforeLoad: "beforeLoadSchemaHook" = "beforeLoadSchemaHook";
```

---

## diff-check

Diff checking event class.

## Events

### DiffCheckEvent \{#diffcheckevent\}

Defined in: [core/src/events/diff-check.ts:15](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/diff-check.ts#L15)

Event emitted before/after checking schema differences.

#### Extends

- [`DataEvent`](../../utils/events.md#abstract-dataevent)&lt;\{
  `outputDir?`: `string`;
  `schema?`: `unknown`;
  `schemaHasChanges?`: `boolean`;
  \}&gt;

#### Constructors

##### Constructor

```ts
new DiffCheckEvent(data, options?): DiffCheckEvent;
```

Defined in: [core/src/events/diff-check.ts:20](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/diff-check.ts#L20)

###### Parameters

###### data

###### outputDir?

`string`

###### schema?

`unknown`

###### schemaHasChanges?

`boolean`

###### options?

[`CancellableEventOptions`](../../utils/events.md#cancellableeventoptions)

###### Returns

[`DiffCheckEvent`](#diffcheckevent)

###### Overrides

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`constructor`](../../utils/events.md#constructor-1)

#### Properties

##### data \{#data\}

```ts
readonly data: object;
```

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

###### outputDir?

```ts
optional outputDir?: string;
```

###### schema?

```ts
optional schema?: unknown;
```

###### schemaHasChanges?

```ts
optional schemaHasChanges?: boolean;
```

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`data`](../../utils/events.md#data)

#### Accessors

##### defaultAction \{#defaultaction\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: utils/dist/events.d.ts:78

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultAction`](../../utils/events.md#defaultaction-1)

##### defaultPrevented \{#defaultprevented\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: utils/dist/events.d.ts:82

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultPrevented`](../../utils/events.md#defaultprevented-1)

##### propagationStopped \{#propagationstopped\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: utils/dist/events.d.ts:86

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`propagationStopped`](../../utils/events.md#propagationstopped-1)

#### Methods

##### preventDefault() \{#preventdefault\}

```ts
preventDefault(): void;
```

Defined in: utils/dist/events.d.ts:91

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`preventDefault`](../../utils/events.md#preventdefault-1)

##### runDefaultAction() \{#rundefaultaction\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: utils/dist/events.d.ts:100

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`runDefaultAction`](../../utils/events.md#rundefaultaction-1)

##### stopPropagation() \{#stoppropagation\}

```ts
stopPropagation(): void;
```

Defined in: utils/dist/events.d.ts:96

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`stopPropagation`](../../utils/events.md#stoppropagation-1)

---

## diff-events

Diff checking event constants.

## DiffEvents \{#diffevents\}

```ts
const DiffEvents: object;
```

Defined in: [core/src/events/diff-events.ts:10](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/diff-events.ts#L10)

Event names for diff checking lifecycle.

### Type Declaration

#### AFTER_CHECK \{#after_check\}

```ts
readonly AFTER_CHECK: "diff:afterCheck" = "diff:afterCheck";
```

Emitted after checking schema differences

#### BEFORE_CHECK \{#before_check\}

```ts
readonly BEFORE_CHECK: "diff:beforeCheck" = "diff:beforeCheck";
```

Emitted before checking schema differences

---

## generate-index-metafile-events

Generate index metafile event constants.

## GenerateIndexMetafileEvents \{#generateindexmetafileevents\}

```ts
const GenerateIndexMetafileEvents: object;
```

Defined in: [core/src/events/generate-index-metafile-events.ts:10](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/generate-index-metafile-events.ts#L10)

Event names for generating index metafile.

### Type Declaration

#### AFTER_GENERATE \{#after_generate\}

```ts
readonly AFTER_GENERATE: "render:afterGenerateIndexMetafile" = "render:afterGenerateIndexMetafile";
```

Emitted after generating index metafile

#### BEFORE_GENERATE \{#before_generate\}

```ts
readonly BEFORE_GENERATE: "render:beforeGenerateIndexMetafile" = "render:beforeGenerateIndexMetafile";
```

Emitted before generating index metafile

---

## generate-index-metafile

Generate index metafile event class.

## Events

### GenerateIndexMetafileEvent \{#generateindexmetafileevent\}

Defined in: [core/src/events/generate-index-metafile.ts:16](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/generate-index-metafile.ts#L16)

Event emitted before/after generating index metafile.

#### Extends

- [`DataEvent`](../../utils/events.md#abstract-dataevent)&lt;\{
  `category`: `string`;
  `dirPath`: `string`;
  `options?`: `Record`&lt;`string`, `unknown`&gt;;
  `outputAdapter?`: `OutputAdapter`;
  \}&gt;

#### Constructors

##### Constructor

```ts
new GenerateIndexMetafileEvent(data, options?): GenerateIndexMetafileEvent;
```

Defined in: [core/src/events/generate-index-metafile.ts:23](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/generate-index-metafile.ts#L23)

###### Parameters

###### data

###### category

`string`

###### dirPath

`string`

###### options?

`Record`&lt;`string`, `unknown`&gt;

###### outputAdapter?

`OutputAdapter`

###### options?

[`CancellableEventOptions`](../../utils/events.md#cancellableeventoptions)

###### Returns

[`GenerateIndexMetafileEvent`](#generateindexmetafileevent)

###### Overrides

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`constructor`](../../utils/events.md#constructor-1)

#### Properties

##### data \{#data\}

```ts
readonly data: object;
```

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

###### category

```ts
category: string;
```

###### dirPath

```ts
dirPath: string;
```

###### options?

```ts
optional options?: Record<string, unknown>;
```

###### outputAdapter?

```ts
optional outputAdapter?: OutputAdapter;
```

Destination the metafile must be written to.

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`data`](../../utils/events.md#data)

#### Accessors

##### defaultAction \{#defaultaction\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: utils/dist/events.d.ts:78

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultAction`](../../utils/events.md#defaultaction-1)

##### defaultPrevented \{#defaultprevented\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: utils/dist/events.d.ts:82

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultPrevented`](../../utils/events.md#defaultprevented-1)

##### propagationStopped \{#propagationstopped\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: utils/dist/events.d.ts:86

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`propagationStopped`](../../utils/events.md#propagationstopped-1)

#### Methods

##### preventDefault() \{#preventdefault\}

```ts
preventDefault(): void;
```

Defined in: utils/dist/events.d.ts:91

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`preventDefault`](../../utils/events.md#preventdefault-1)

##### runDefaultAction() \{#rundefaultaction\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: utils/dist/events.d.ts:100

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`runDefaultAction`](../../utils/events.md#rundefaultaction-1)

##### stopPropagation() \{#stoppropagation\}

```ts
stopPropagation(): void;
```

Defined in: utils/dist/events.d.ts:96

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`stopPropagation`](../../utils/events.md#stoppropagation-1)

---

## print-type-events

Print type event constants.

Events emitted during the printing phase of type documentation generation.
These events allow interception and modification of the generated code output.

## PrintTypeEvents \{#printtypeevents\}

```ts
const PrintTypeEvents: object;
```

Defined in: [core/src/events/print-type-events.ts:25](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/print-type-events.ts#L25)

Event names for printing type documentation.

### Type Declaration

#### AFTER_PRINT_CODE \{#after_print_code\}

```ts
readonly AFTER_PRINT_CODE: "print:afterPrintCode" = "print:afterPrintCode";
```

Emitted after generating the code block for a type (output can be modified)

#### AFTER_PRINT_TYPE \{#after_print_type\}

```ts
readonly AFTER_PRINT_TYPE: "print:afterPrintType" = "print:afterPrintType";
```

Emitted after generating the full type documentation (output can be modified)

#### BEFORE_COMPOSE_PAGE_TYPE \{#before_compose_page_type\}

```ts
readonly BEFORE_COMPOSE_PAGE_TYPE: "print:beforeComposePageType" = "print:beforeComposePageType";
```

Emitted before composing page sections (can modify section content)

#### BEFORE_PRINT_CODE \{#before_print_code\}

```ts
readonly BEFORE_PRINT_CODE: "print:beforePrintCode" = "print:beforePrintCode";
```

Emitted before generating the code block for a type

#### BEFORE_PRINT_TYPE \{#before_print_type\}

```ts
readonly BEFORE_PRINT_TYPE: "print:beforePrintType" = "print:beforePrintType";
```

Emitted before generating the full type documentation

### Example

```typescript
import { getEvents, PrintTypeEvents } from "@graphql-markdown/core";
import { PrintCodeEvent } from "@graphql-markdown/printer-legacy";

const events = getEvents();
events.on(PrintTypeEvents.AFTER_PRINT_CODE, (event: PrintCodeEvent) => {
  // Modify the generated code
  event.output = event.output.toUpperCase();
});
```

---

## render-files-events

Render files event constants.

## RenderFilesEvents \{#renderfilesevents\}

```ts
const RenderFilesEvents: object;
```

Defined in: [core/src/events/render-files-events.ts:10](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-files-events.ts#L10)

Event names fired once after all output files (entities + homepage) are written.

### Type Declaration

#### AFTER_RENDER \{#after_render\}

```ts
readonly AFTER_RENDER: "render:afterRenderFiles" = "render:afterRenderFiles";
```

Emitted after all files have been written

---

## render-files

Render files event class.

## Events

### RenderFilesEvent \{#renderfilesevent\}

Defined in: [core/src/events/render-files.ts:16](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-files.ts#L16)

Event emitted after all output files (entities + homepage) have been written.

#### Extends

- [`DataEvent`](../../utils/events.md#abstract-dataevent)&lt;\{
  `baseURL`: `string`;
  `outputAdapter?`: `OutputAdapter`;
  `outputDir`: `string`;
  `pages`: `unknown`;
  `rootDir`: `string`;
  \}&gt;

#### Constructors

##### Constructor

```ts
new RenderFilesEvent(data, options?): RenderFilesEvent;
```

Defined in: [core/src/events/render-files.ts:24](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-files.ts#L24)

###### Parameters

###### data

###### baseURL

`string`

###### outputAdapter?

`OutputAdapter`

###### outputDir

`string`

###### pages

`unknown`

###### rootDir

`string`

###### options?

[`CancellableEventOptions`](../../utils/events.md#cancellableeventoptions)

###### Returns

[`RenderFilesEvent`](#renderfilesevent)

###### Overrides

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`constructor`](../../utils/events.md#constructor-1)

#### Properties

##### data \{#data\}

```ts
readonly data: object;
```

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

###### baseURL

```ts
baseURL: string;
```

###### outputAdapter?

```ts
optional outputAdapter?: OutputAdapter;
```

Destination the pages were written to; use it for any summary file.

###### outputDir

```ts
outputDir: string;
```

###### pages

```ts
pages: unknown;
```

###### rootDir

```ts
rootDir: string;
```

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`data`](../../utils/events.md#data)

#### Accessors

##### defaultAction \{#defaultaction\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: utils/dist/events.d.ts:78

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultAction`](../../utils/events.md#defaultaction-1)

##### defaultPrevented \{#defaultprevented\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: utils/dist/events.d.ts:82

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultPrevented`](../../utils/events.md#defaultprevented-1)

##### propagationStopped \{#propagationstopped\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: utils/dist/events.d.ts:86

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`propagationStopped`](../../utils/events.md#propagationstopped-1)

#### Methods

##### preventDefault() \{#preventdefault\}

```ts
preventDefault(): void;
```

Defined in: utils/dist/events.d.ts:91

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`preventDefault`](../../utils/events.md#preventdefault-1)

##### runDefaultAction() \{#rundefaultaction\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: utils/dist/events.d.ts:100

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`runDefaultAction`](../../utils/events.md#rundefaultaction-1)

##### stopPropagation() \{#stoppropagation\}

```ts
stopPropagation(): void;
```

Defined in: utils/dist/events.d.ts:96

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`stopPropagation`](../../utils/events.md#stoppropagation-1)

---

## render-homepage-events

Render homepage event constants.

## RenderHomepageEvents \{#renderhomepageevents\}

```ts
const RenderHomepageEvents: object;
```

Defined in: [core/src/events/render-homepage-events.ts:10](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-homepage-events.ts#L10)

Event names for rendering homepage.

### Type Declaration

#### AFTER_RENDER \{#after_render\}

```ts
readonly AFTER_RENDER: "render:afterRenderHomepage" = "render:afterRenderHomepage";
```

Emitted after rendering homepage

#### BEFORE_RENDER \{#before_render\}

```ts
readonly BEFORE_RENDER: "render:beforeRenderHomepage" = "render:beforeRenderHomepage";
```

Emitted before rendering homepage

---

## render-homepage

Render homepage event class.

## Events

### RenderHomepageEvent \{#renderhomepageevent\}

Defined in: [core/src/events/render-homepage.ts:15](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-homepage.ts#L15)

Event emitted before/after rendering homepage.

#### Extends

- [`DataEvent`](../../utils/events.md#abstract-dataevent)&lt;\{
  `outputDir`: `string`;
  \}&gt;

#### Constructors

##### Constructor

```ts
new RenderHomepageEvent(data, options?): RenderHomepageEvent;
```

Defined in: [core/src/events/render-homepage.ts:18](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-homepage.ts#L18)

###### Parameters

###### data

###### outputDir

`string`

###### options?

[`CancellableEventOptions`](../../utils/events.md#cancellableeventoptions)

###### Returns

[`RenderHomepageEvent`](#renderhomepageevent)

###### Overrides

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`constructor`](../../utils/events.md#constructor-1)

#### Properties

##### data \{#data\}

```ts
readonly data: object;
```

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

###### outputDir

```ts
outputDir: string;
```

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`data`](../../utils/events.md#data)

#### Accessors

##### defaultAction \{#defaultaction\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: utils/dist/events.d.ts:78

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultAction`](../../utils/events.md#defaultaction-1)

##### defaultPrevented \{#defaultprevented\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: utils/dist/events.d.ts:82

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultPrevented`](../../utils/events.md#defaultprevented-1)

##### propagationStopped \{#propagationstopped\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: utils/dist/events.d.ts:86

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`propagationStopped`](../../utils/events.md#propagationstopped-1)

#### Methods

##### preventDefault() \{#preventdefault\}

```ts
preventDefault(): void;
```

Defined in: utils/dist/events.d.ts:91

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`preventDefault`](../../utils/events.md#preventdefault-1)

##### runDefaultAction() \{#rundefaultaction\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: utils/dist/events.d.ts:100

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`runDefaultAction`](../../utils/events.md#rundefaultaction-1)

##### stopPropagation() \{#stoppropagation\}

```ts
stopPropagation(): void;
```

Defined in: utils/dist/events.d.ts:96

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`stopPropagation`](../../utils/events.md#stoppropagation-1)

---

## render-root-types-events

Render root types event constants.

## RenderRootTypesEvents \{#renderroottypesevents\}

```ts
const RenderRootTypesEvents: object;
```

Defined in: [core/src/events/render-root-types-events.ts:10](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-root-types-events.ts#L10)

Event names for rendering root types.

### Type Declaration

#### AFTER_RENDER \{#after_render\}

```ts
readonly AFTER_RENDER: "render:afterRenderRootTypes" = "render:afterRenderRootTypes";
```

Emitted after rendering root types

#### BEFORE_RENDER \{#before_render\}

```ts
readonly BEFORE_RENDER: "render:beforeRenderRootTypes" = "render:beforeRenderRootTypes";
```

Emitted before rendering root types

---

## render-root-types

Render root types event class.

## Events

### RenderRootTypesEvent \{#renderroottypesevent\}

Defined in: [core/src/events/render-root-types.ts:15](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-root-types.ts#L15)

Event emitted before/after rendering root types.

#### Extends

- [`DataEvent`](../../utils/events.md#abstract-dataevent)&lt;\{
  `rootTypes`: `unknown`;
  \}&gt;

#### Constructors

##### Constructor

```ts
new RenderRootTypesEvent(data, options?): RenderRootTypesEvent;
```

Defined in: [core/src/events/render-root-types.ts:18](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-root-types.ts#L18)

###### Parameters

###### data

###### rootTypes

`unknown`

###### options?

[`CancellableEventOptions`](../../utils/events.md#cancellableeventoptions)

###### Returns

[`RenderRootTypesEvent`](#renderroottypesevent)

###### Overrides

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`constructor`](../../utils/events.md#constructor-1)

#### Properties

##### data \{#data\}

```ts
readonly data: object;
```

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

###### rootTypes

```ts
rootTypes: unknown;
```

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`data`](../../utils/events.md#data)

#### Accessors

##### defaultAction \{#defaultaction\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: utils/dist/events.d.ts:78

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultAction`](../../utils/events.md#defaultaction-1)

##### defaultPrevented \{#defaultprevented\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: utils/dist/events.d.ts:82

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultPrevented`](../../utils/events.md#defaultprevented-1)

##### propagationStopped \{#propagationstopped\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: utils/dist/events.d.ts:86

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`propagationStopped`](../../utils/events.md#propagationstopped-1)

#### Methods

##### preventDefault() \{#preventdefault\}

```ts
preventDefault(): void;
```

Defined in: utils/dist/events.d.ts:91

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`preventDefault`](../../utils/events.md#preventdefault-1)

##### runDefaultAction() \{#rundefaultaction\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: utils/dist/events.d.ts:100

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`runDefaultAction`](../../utils/events.md#rundefaultaction-1)

##### stopPropagation() \{#stoppropagation\}

```ts
stopPropagation(): void;
```

Defined in: utils/dist/events.d.ts:96

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`stopPropagation`](../../utils/events.md#stoppropagation-1)

---

## render-type-entities-events

Render type entities event constants.

## RenderTypeEntitiesEvents \{#rendertypeentitiesevents\}

```ts
const RenderTypeEntitiesEvents: object;
```

Defined in: [core/src/events/render-type-entities-events.ts:10](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-type-entities-events.ts#L10)

Event names for rendering type entities.

### Type Declaration

#### AFTER_RENDER \{#after_render\}

```ts
readonly AFTER_RENDER: "render:afterRenderTypeEntities" = "render:afterRenderTypeEntities";
```

Emitted after rendering type entities

#### BEFORE_RENDER \{#before_render\}

```ts
readonly BEFORE_RENDER: "render:beforeRenderTypeEntities" = "render:beforeRenderTypeEntities";
```

Emitted before rendering type entities

---

## render-type-entities

Render type entities event class.

## Events

### RenderTypeEntitiesEvent \{#rendertypeentitiesevent\}

Defined in: [core/src/events/render-type-entities.ts:16](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-type-entities.ts#L16)

Event emitted before/after rendering type entities.

#### Extends

- [`DataEvent`](../../utils/events.md#abstract-dataevent)&lt;\{
  `baseURL`: `string`;
  `filePath`: `string`;
  `name`: `string`;
  `outputAdapter?`: `OutputAdapter`;
  `outputDir`: `string`;
  \}&gt;

#### Constructors

##### Constructor

```ts
new RenderTypeEntitiesEvent(data, options?): RenderTypeEntitiesEvent;
```

Defined in: [core/src/events/render-type-entities.ts:24](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/render-type-entities.ts#L24)

###### Parameters

###### data

###### baseURL

`string`

###### filePath

`string`

###### name

`string`

###### outputAdapter?

`OutputAdapter`

###### outputDir

`string`

###### options?

[`CancellableEventOptions`](../../utils/events.md#cancellableeventoptions)

###### Returns

[`RenderTypeEntitiesEvent`](#rendertypeentitiesevent)

###### Overrides

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`constructor`](../../utils/events.md#constructor-1)

#### Properties

##### data \{#data\}

```ts
readonly data: object;
```

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

###### baseURL

```ts
baseURL: string;
```

###### filePath

```ts
filePath: string;
```

###### name

```ts
name: string;
```

###### outputAdapter?

```ts
optional outputAdapter?: OutputAdapter;
```

Destination the page was written to; use it to read the page back.

###### outputDir

```ts
outputDir: string;
```

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`data`](../../utils/events.md#data)

#### Accessors

##### defaultAction \{#defaultaction\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: utils/dist/events.d.ts:78

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultAction`](../../utils/events.md#defaultaction-1)

##### defaultPrevented \{#defaultprevented\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: utils/dist/events.d.ts:82

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultPrevented`](../../utils/events.md#defaultprevented-1)

##### propagationStopped \{#propagationstopped\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: utils/dist/events.d.ts:86

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`propagationStopped`](../../utils/events.md#propagationstopped-1)

#### Methods

##### preventDefault() \{#preventdefault\}

```ts
preventDefault(): void;
```

Defined in: utils/dist/events.d.ts:91

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`preventDefault`](../../utils/events.md#preventdefault-1)

##### runDefaultAction() \{#rundefaultaction\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: utils/dist/events.d.ts:100

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`runDefaultAction`](../../utils/events.md#rundefaultaction-1)

##### stopPropagation() \{#stoppropagation\}

```ts
stopPropagation(): void;
```

Defined in: utils/dist/events.d.ts:96

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`stopPropagation`](../../utils/events.md#stoppropagation-1)

---

## schema-events

Schema loading event constants.

## SchemaEvents \{#schemaevents\}

```ts
const SchemaEvents: object;
```

Defined in: [core/src/events/schema-events.ts:10](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/schema-events.ts#L10)

Event names for schema loading lifecycle.

### Type Declaration

#### AFTER_LOAD \{#after_load\}

```ts
readonly AFTER_LOAD: "schema:afterLoad" = "schema:afterLoad";
```

Emitted after loading GraphQL schema

#### AFTER_MAP \{#after_map\}

```ts
readonly AFTER_MAP: "schema:afterMap" = "schema:afterMap";
```

Emitted after mapping GraphQL schema

#### BEFORE_LOAD \{#before_load\}

```ts
readonly BEFORE_LOAD: "schema:beforeLoad" = "schema:beforeLoad";
```

Emitted before loading GraphQL schema

#### BEFORE_MAP \{#before_map\}

```ts
readonly BEFORE_MAP: "schema:beforeMap" = "schema:beforeMap";
```

Emitted before mapping GraphQL schema

---

## schema-load

Schema loading event class.

## Events

### SchemaEvent \{#schemaevent\}

Defined in: [core/src/events/schema-load.ts:16](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/schema-load.ts#L16)

Event emitted before/after loading a GraphQL schema.

#### Extends

- [`DataEvent`](../../utils/events.md#abstract-dataevent)&lt;\{
  `rootTypes?`: `Maybe`&lt;`SchemaMap`&gt;;
  `schema?`: `Maybe`&lt;`GraphQLSchema`&gt;;
  `schemaLocation?`: `string`;
  \}&gt;

#### Constructors

##### Constructor

```ts
new SchemaEvent(data, options?): SchemaEvent;
```

Defined in: [core/src/events/schema-load.ts:21](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/events/schema-load.ts#L21)

###### Parameters

###### data

###### rootTypes?

`Maybe`&lt;`SchemaMap`&gt;

###### schema?

`Maybe`&lt;`GraphQLSchema`&gt;

###### schemaLocation?

`string`

###### options?

[`CancellableEventOptions`](../../utils/events.md#cancellableeventoptions)

###### Returns

[`SchemaEvent`](#schemaevent)

###### Overrides

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`constructor`](../../utils/events.md#constructor-1)

#### Properties

##### data \{#data\}

```ts
readonly data: object;
```

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

###### rootTypes?

```ts
optional rootTypes?: Maybe<SchemaMap>;
```

###### schema?

```ts
optional schema?: Maybe<GraphQLSchema>;
```

###### schemaLocation?

```ts
optional schemaLocation?: string;
```

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`data`](../../utils/events.md#data)

#### Accessors

##### defaultAction \{#defaultaction\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: utils/dist/events.d.ts:78

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultAction`](../../utils/events.md#defaultaction-1)

##### defaultPrevented \{#defaultprevented\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: utils/dist/events.d.ts:82

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`defaultPrevented`](../../utils/events.md#defaultprevented-1)

##### propagationStopped \{#propagationstopped\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: utils/dist/events.d.ts:86

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`propagationStopped`](../../utils/events.md#propagationstopped-1)

#### Methods

##### preventDefault() \{#preventdefault\}

```ts
preventDefault(): void;
```

Defined in: utils/dist/events.d.ts:91

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`preventDefault`](../../utils/events.md#preventdefault-1)

##### runDefaultAction() \{#rundefaultaction\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: utils/dist/events.d.ts:100

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`runDefaultAction`](../../utils/events.md#rundefaultaction-1)

##### stopPropagation() \{#stoppropagation\}

```ts
stopPropagation(): void;
```

Defined in: utils/dist/events.d.ts:96

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Inherited from

[`DataEvent`](../../utils/events.md#abstract-dataevent).[`stopPropagation`](../../utils/events.md#stoppropagation-1)

---

## events

Event system for GraphQL-Markdown.

---

## generator

Core generator functionality for GraphQL Markdown documentation.

This module contains the main functionality for generating markdown documentation
from GraphQL schemas. It handles schema loading, processing, and markdown generation
through appropriate printers and renderers.

## checkSchemaDifferences() \{#checkschemadifferences\}

```ts
function checkSchemaDifferences(
  schema,
  schemaLocation,
  diffMethod,
  tmpDir,
): Promise<boolean>;
```

Defined in: [core/src/generator.ts:270](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/generator.ts#L270)

Checks if there are differences in the GraphQL schema compared to a previous version.

### Parameters

#### schema

`GraphQLSchema`

The GraphQL schema to check for differences.

#### schemaLocation

`string`

The location/path of the schema file for logging purposes.

#### diffMethod

`Maybe`&lt;`TypeDiffMethod`&gt;

The method to use for detecting differences. If set to `NONE`, changes detection is skipped.

#### tmpDir

`string`

The temporary directory path used for storing and comparing schema versions.

### Returns

`Promise`&lt;`boolean`&gt;

A promise that resolves to `true` if changes are detected or if diff method is `NONE`,
or `false` if no changes are detected.

### Remarks

When no changes are detected, a log message is generated indicating that the schema is unchanged.

---

## generateDocFromSchema() \{#generatedocfromschema\}

```ts
function generateDocFromSchema(options): Promise<void>;
```

Defined in: [core/src/generator.ts:343](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/generator.ts#L343)

Main entry point for generating Markdown documentation from a GraphQL schema.

This function coordinates the entire documentation generation process:

- Loads and validates the schema
- Checks for schema changes if diffing is enabled
- Processes directives and groups
- Initializes printers and renderers
- Generates markdown files

### Parameters

#### options

`GeneratorOptions`

Complete configuration for the documentation generation

### Returns

`Promise`&lt;`void`&gt;

Promise that resolves when documentation is fully generated

---

## getFormatterFromMDXModule() \{#getformatterfrommdxmodule\}

```ts
function getFormatterFromMDXModule(
  mdxModule,
  meta?,
): Partial<Formatter> | undefined;
```

Defined in: [core/src/generator.ts:174](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/generator.ts#L174)

**`Internal`**

Extracts a formatter from an MDX module.

Checks for formatter functions in the following order:

1. A `createMDXFormatter` factory function (for internal/advanced usage)
2. Individual exported formatter functions (e.g., `formatMDXBadge`, `formatMDXAdmonition`)

### Parameters

#### mdxModule

`unknown`

The loaded MDX module that may contain formatter exports

#### meta?

`MetaInfo`

Optional metadata to pass to the formatter factory

### Returns

`Partial`&lt;`Formatter`&gt; \| `undefined`

A partial Formatter with the found functions, or undefined if none found

---

## getMDXModuleProperty() \{#getmdxmoduleproperty\}

```ts
function getMDXModuleProperty<T>(mdxModule, propertyName): T | undefined;
```

Defined in: [core/src/generator.ts:137](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/generator.ts#L137)

**`Internal`**

Gets a property from an MDX module, checking both the module directly and `module.default`.

This handles the differences between ESM and CommonJS module exports when dynamically importing.

### Type Parameters

#### T

`T`

### Parameters

#### mdxModule

`unknown`

The loaded MDX module

#### propertyName

`string`

The name of the property to extract

### Returns

`T` \| `undefined`

The property value if found, otherwise undefined

---

## loadGraphqlSchema() \{#loadgraphqlschema\}

```ts
function loadGraphqlSchema(
  schemaLocation,
  loadersList,
): Promise<Maybe<GraphQLSchema>>;
```

Defined in: [core/src/generator.ts:238](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/generator.ts#L238)

**`Internal`**

Loads a GraphQL schema from the specified location using configured document loaders.

### Parameters

#### schemaLocation

`string`

The location/path of the GraphQL schema to load (e.g., file path, URL, or glob pattern).

#### loadersList

`Maybe`&lt;`LoaderOption`&gt;

Optional loader configuration for customizing how the schema is loaded.

### Returns

`Promise`&lt;`Maybe`&lt;`GraphQLSchema`&gt;&gt;

A promise that resolves to the loaded GraphQL schema, or undefined if:

- The loaders cannot be initialized
- An error occurs during schema loading

---

## loadMDXModule() \{#loadmdxmodule\}

```ts
function loadMDXModule(mdxParser): Promise<unknown>;
```

Defined in: [core/src/generator.ts:95](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/generator.ts#L95)

**`Internal`**

Asynchronously loads an MDX module dynamically.

### Parameters

#### mdxParser

`Maybe`&lt;`string` \| `PackageName`&gt;

The MDX parser package name or path to import. Can be null or undefined.

### Returns

`Promise`&lt;`unknown`&gt;

A promise that resolves to the imported module, or undefined if:

- The mdxParser parameter is null or undefined
- An error occurs during import (logs a warning and returns undefined)

---

## resolveSkipAndOnlyDirectives() \{#resolveskipandonlydirectives\}

```ts
function resolveSkipAndOnlyDirectives(
  onlyDocDirective,
  skipDocDirective,
  schema,
): GraphQLDirective[][];
```

Defined in: [core/src/generator.ts:302](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/generator.ts#L302)

Resolves and retrieves GraphQL directive objects from the schema based on their names.

Takes two lists of directive names (for "only" and "skip" documentation directives),
looks them up in the provided GraphQL schema, and returns the resolved directive objects.

### Parameters

#### onlyDocDirective

`Maybe`&lt;`DirectiveName` \| `DirectiveName`[]&gt;

A directive name or array of directive names for "only" documentation filtering

#### skipDocDirective

`Maybe`&lt;`DirectiveName` \| `DirectiveName`[]&gt;

A directive name or array of directive names for "skip" documentation filtering

#### schema

`GraphQLSchema`

The GraphQL schema to resolve directives from

### Returns

`GraphQLDirective`[][]

A tuple containing two arrays: the first with resolved "only" directives,
the second with resolved "skip" directives. Only defined directives are included.

---

## graphql-config

GraphQL Markdown configuration utilities

This module provides utilities for loading and processing GraphQL configuration
using the graphql-config package.

## graphQLConfigExtension \{#graphqlconfigextension\}

```ts
const graphQLConfigExtension: GraphQLExtensionDeclaration;
```

Defined in: [core/src/graphql-config.ts:47](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/graphql-config.ts#L47)

GraphQL extension declaration for graphql-config.

### Returns

The extension configuration object with name property.

### Example

```typescript
// In graphql-config setup
const config = await loadConfig({
  extensions: [graphQLConfigExtension],
});
```

---

## loadConfiguration() \{#loadconfiguration\}

```ts
function loadConfiguration(
  id,
  options?,
  throwOptions?,
): Promise<Maybe<Readonly<ExtensionProjectConfig>>>;
```

Defined in: [core/src/graphql-config.ts:144](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/graphql-config.ts#L144)

Loads the GraphQL Markdown configuration from graphql-config.

This function attempts to load the GraphQL config and extract the
GraphQL Markdown extension configuration for the specified project ID.
It also normalizes schema configurations.

### Parameters

#### id

`Maybe`&lt;`string`&gt;

The project ID to load configuration for.

#### options?

`Maybe`&lt;`PackageOptionsConfig`&gt;

Optional package options to apply.

#### throwOptions?

`ThrowOptions` = `DEFAULT_THROW_OPTIONS`

Options for controlling throw behavior.

### Returns

`Promise`&lt;`Maybe`&lt;`Readonly`&lt;`ExtensionProjectConfig`&gt;&gt;&gt;

The extension project configuration if found, otherwise `undefined`.

### Throws

Will throw an error if throwOnMissing or throwOnEmpty is true and
the corresponding condition is met.

### Example

```typescript
// Basic usage
const config = await loadConfiguration("my-project");

// With options and throw behavior
const config = await loadConfiguration(
  "my-project",
  { baseDir: "./src" },
  { throwOnMissing: true, throwOnEmpty: false },
);
```

---

## setLoaderOptions() \{#setloaderoptions\}

```ts
function setLoaderOptions(loaders, options): LoaderOption;
```

Defined in: [core/src/graphql-config.ts:96](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/graphql-config.ts#L96)

Sets loader options for GraphQL Markdown loaders.

This function takes a LoaderOption object and merges the provided options
with any existing options for each loader.

### Parameters

#### loaders

`LoaderOption`

The loader configuration object.

#### options

`PackageOptionsConfig`

The package options to apply to loaders.

### Returns

`LoaderOption`

The updated loader configuration.

### Example

```typescript
const loaders = {
  TypeScriptLoader: {
    module: "@graphql-markdown/typescript-loader",
    options: { baseDir: "./src" },
  },
};
const options = { outputDir: "./docs" };
const updatedLoaders = setLoaderOptions(loaders, options);
// Result: loaders with { baseDir: "./src", outputDir: "./docs" }
```

---

## builder

Option builder for handling CLI/config/default option precedence.

This utility provides a fluent interface for merging options from multiple
sources (CLI, config file, defaults) with consistent precedence rules:

1. CLI options (highest priority)
2. Config file options
3. Default values (lowest priority)

Precedence is enforced semantically via the setIfProvided() method,
regardless of the order in which methods are called. Each value tracks its
source, and only higher-precedence sources can override existing values.

Eliminates repetitive if/coalesce patterns throughout the codebase.

## OptionBuilder \{#optionbuilder\}

Defined in: [core/src/options/builder.ts:49](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/options/builder.ts#L49)

Builder for constructing options from multiple sources with priority precedence.

Precedence is enforced semantically via source tracking, not by call order.
CLI values always override config values, which always override defaults,
regardless of the order in which methods are called.

### Example

```typescript
const options = new OptionBuilder<MyOptions>()
  // Add in order: default -> config -> cli
  .addDefault(false, "pretty")
  .addFromConfig(undefined, "pretty")
  .addFromCli(true, "pretty") // CLI overrides default
  .addDefault("/", "baseURL")
  .addFromConfig("/api", "baseURL") // Config overrides default
  .addFromCli(undefined, "baseURL")
  .build();
// Result: { pretty: true, baseURL: "/api" }
```

### Type Parameters

#### T

`T` _extends_ `Record`&lt;`string`, `unknown`&gt;

The type of the options object being built

### Constructors

#### Constructor

```ts
new OptionBuilder<T>(): OptionBuilder<T>;
```

##### Returns

[`OptionBuilder`](#optionbuilder)&lt;`T`&gt;

### Methods

#### addDefault() \{#adddefault\}

```ts
addDefault<K>(value, key): this;
```

Defined in: [core/src/options/builder.ts:73](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/options/builder.ts#L73)

Adds a default value (lowest priority).
Sets a value that can be overwritten by config or CLI options.
This method can be called at any time; precedence is enforced semantically.

##### Type Parameters

###### K

`K` _extends_ `string` \| `number` \| `symbol`

##### Parameters

###### value

`Maybe`&lt;`T`\[`K`\]&gt;

The default value

###### key

`K`

The key to store the value under

##### Returns

`this`

This builder for method chaining

##### Example

```typescript
builder.addDefault(3000, "port");
```

#### addFromCli() \{#addfromcli\}

```ts
addFromCli<K>(value, key): this;
```

Defined in: [core/src/options/builder.ts:109](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/options/builder.ts#L109)

Adds a value from CLI options if provided (highest priority).
Can override both default and config values for this key.
This method can be called at any time; precedence is enforced semantically.

##### Type Parameters

###### K

`K` _extends_ `string` \| `number` \| `symbol`

##### Parameters

###### value

`Maybe`&lt;`T`\[`K`\]&gt;

The CLI option value

###### key

`K`

The key to store the value under

##### Returns

`this`

This builder for method chaining

##### Example

```typescript
builder.addFromCli(cliOpts.port, "port");
```

#### addFromConfig() \{#addfromconfig\}

```ts
addFromConfig<K>(value, key): this;
```

Defined in: [core/src/options/builder.ts:91](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/options/builder.ts#L91)

Adds a value from config file if provided (medium priority).
Can override default values if the config value exists.
This method can be called at any time; precedence is enforced semantically.

##### Type Parameters

###### K

`K` _extends_ `string` \| `number` \| `symbol`

##### Parameters

###### value

`Maybe`&lt;`T`\[`K`\]&gt;

The config file option value

###### key

`K`

The key to store the value under

##### Returns

`this`

This builder for method chaining

##### Example

```typescript
builder.addFromConfig(config.port, "port");
```

#### build() \{#build\}

```ts
build(): Partial<T>;
```

Defined in: [core/src/options/builder.ts:190](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/options/builder.ts#L190)

Returns the built options object with all accumulated values.
The object contains all keys that were set during the building process.

Note: The returned object may be a partial object containing only the keys
that were set. Callers should handle potentially missing properties.
Returns a defensive copy of the object to prevent external mutations of
internal state. Arrays and objects are shallow-copied to protect against
external modifications.

##### Returns

`Partial`&lt;`T`&gt;

The constructed options object with type `Partial<T>` (may not have all properties of `T`)

#### get() \{#get\}

```ts
get<K>(key): T[K] | undefined;
```

Defined in: [core/src/options/builder.ts:167](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/options/builder.ts#L167)

Gets the current value for a key without building.
Useful for conditional logic during building.
Returns a shallow copy for arrays and objects to prevent external mutations.
Note: Nested objects and arrays are not deep copied.

##### Type Parameters

###### K

`K` _extends_ `string` \| `number` \| `symbol`

##### Parameters

###### key

`K`

The key to get

##### Returns

`T`\[`K`\] \| `undefined`

The current value for the key, or `undefined` if not set

#### transform() \{#transform\}

```ts
transform<K>(key, fn): this;
```

Defined in: [core/src/options/builder.ts:126](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/options/builder.ts#L126)

Transforms a value using a function if the key exists.
Useful for processing values after they've been set.

##### Type Parameters

###### K

`K` _extends_ `string` \| `number` \| `symbol`

##### Parameters

###### key

`K`

The key to transform

###### fn

(`v`) => `T`\[`K`\]

Function that transforms the current value

##### Returns

`this`

This builder for method chaining

##### Example

```typescript
builder.transform("path", (p) => resolve(p));
```

#### transformIf() \{#transformif\}

```ts
transformIf<K>(
   key,
   predicate,
   fn
): this;
```

Defined in: [core/src/options/builder.ts:147](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/options/builder.ts#L147)

Conditionally applies a transformation if a predicate is true.
Useful for applying different transformations based on other values.

##### Type Parameters

###### K

`K` _extends_ `string` \| `number` \| `symbol`

##### Parameters

###### key

`K`

The key to potentially transform

###### predicate

(`merged`) => `boolean`

Function that determines if transformation should apply

###### fn

(`v`) => `T`\[`K`\]

Function that transforms the value if predicate is true

##### Returns

`this`

This builder for method chaining

##### Example

```typescript
builder.transformIf(
  "path",
  () => force,
  (p) => resolve(p),
);
```

---

## printer

Printer loader helpers for bootstrapping GraphQL-Markdown renderers.

## getPrinter() \{#getprinter\}

```ts
function getPrinter(
  config?,
  options?,
  formatter?,
  mdxDeclaration?,
  eventEmitter?,
): Promise<typeof IPrinter>;
```

Defined in: [core/src/printer.ts:65](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/printer.ts#L65)

Loads and initializes a printer module for GraphQL schema documentation.

This function resolves the specified printer module and initializes it
with the provided configuration and options. The printer is responsible for rendering
GraphQL schema documentation in the desired format.

### Parameters

#### config?

`Maybe`&lt;`PrinterConfig`&gt;

Configuration for the printer including schema, baseURL, and linkRoot

#### options?

`Maybe`&lt;`PrinterOptions`&gt;

Additional options for customizing the printer's behavior

#### formatter?

`Partial`&lt;`Formatter`&gt;

Optional formatter functions for customizing output format (e.g., MDX)

#### mdxDeclaration?

`Maybe`&lt;`string`&gt;

#### eventEmitter?

`Maybe`&lt;`PrinterEventEmitter`&gt;

### Returns

`Promise`&lt;_typeof_ `IPrinter`&gt;

A promise that resolves to the initialized Printer instance

### Throws

Will throw an error if config is not provided

### Example

```typescript
import { getPrinter } from "@graphql-markdown/core";
import { buildSchema } from "graphql";

const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

const printer = await getPrinter(
  {
    schema,
    baseURL: "/docs",
    linkRoot: "graphql",
  },
  {
    printTypeOptions: { deprecated: "group" },
  },
);

const queryType = schema.getQueryType();
if (queryType) {
  const output = await printer.printType("Query", queryType);
}
```

---

## renderer

## Renderer \{#renderer\}

Defined in: [core/src/renderer.ts:354](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L354)

Core renderer class responsible for generating documentation files from GraphQL schema entities.
Handles the conversion of schema types to markdown/MDX documentation with proper organization.

HIERARCHY LEVELS WHEN categorySort IS ENABLED:

- Level 0 (root): Query, Mutation, Subscription, Custom Groups → 01-Query, 02-Mutation, etc.
- Level 1 (under root): Specific types within each root → 01-Objects, 02-Enums, etc.

Each level has its own CategoryPositionManager that restarts numbering at 1.

### Example

```ts

```

### Constructors

#### Constructor

```ts
new Renderer(
   printer,
   outputDir,
   baseURL,
   group,
   prettify,
   docOptions,
   mdxExtension,
   outputAdapter?
): Renderer;
```

Defined in: [core/src/renderer.ts:380](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L380)

Creates a new Renderer instance.

##### Parameters

###### printer

_typeof_ `IPrinter`

The printer instance used to convert GraphQL types to markdown

###### outputDir

`string`

Directory where documentation will be generated

###### baseURL

`string`

Base URL for the documentation

###### group

`Maybe`&lt;`Partial`&lt;`Record`&lt;`SchemaEntity`, `Record`&lt;`string`, `Maybe`&lt;`string`&gt;&gt;&gt;&gt;&gt;

Optional grouping configuration for schema entities

###### prettify

`boolean`

Whether to format the generated markdown

###### docOptions

`Maybe`&lt;`RendererDocOptions`&gt;

Additional documentation options

###### mdxExtension

`string`

Optional MDX file extension to use

###### outputAdapter?

`Maybe`&lt;`OutputAdapter`&gt; = `undefined`

Destination for generated pages; defaults to the local filesystem

##### Returns

[`Renderer`](#renderer)

##### Example

```ts

```

### Properties

#### baseURL \{#baseurl\}

```ts
readonly baseURL: string;
```

Defined in: [core/src/renderer.ts:357](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L357)

#### group \{#group\}

```ts
readonly group: Maybe<Partial<Record<SchemaEntity, Record<string, Maybe<string>>>>>;
```

Defined in: [core/src/renderer.ts:355](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L355)

#### mdxExtension \{#mdxextension\}

```ts
readonly mdxExtension: string;
```

Defined in: [core/src/renderer.ts:360](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L360)

#### options \{#options\}

```ts
readonly options: Maybe<RendererDocOptions>;
```

Defined in: [core/src/renderer.ts:359](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L359)

#### outputAdapter \{#outputadapter\}

```ts
readonly outputAdapter: OutputAdapter;
```

Defined in: [core/src/renderer.ts:361](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L361)

#### outputDir \{#outputdir\}

```ts
readonly outputDir: string;
```

Defined in: [core/src/renderer.ts:356](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L356)

#### prettify \{#prettify\}

```ts
readonly prettify: boolean;
```

Defined in: [core/src/renderer.ts:358](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L358)

### Methods

#### generateCategoryMetafileType() \{#generatecategorymetafiletype\}

```ts
generateCategoryMetafileType(
   type,
   name,
   rootTypeName
): Promise<string>;
```

Defined in: [core/src/renderer.ts:485](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L485)

Generates the directory path and metafiles for a specific schema entity type.
Creates the appropriate directory structure based on configuration options.

##### Parameters

###### type

`unknown`

The schema entity type

###### name

`string`

The name of the schema entity

###### rootTypeName

`SchemaEntity`

The root type name this entity belongs to

##### Returns

`Promise`&lt;`string`&gt;

The generated directory path

##### Example

```ts

```

#### generateIndexMetafile() \{#generateindexmetafile\}

```ts
generateIndexMetafile(
   dirPath,
   category,
   options?
): Promise<void>;
```

Defined in: [core/src/renderer.ts:430](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L430)

Generates an index metafile for a category directory if MDX support is available.

##### Parameters

###### dirPath

`string`

The directory path where the index should be created

###### category

`string`

The category name

###### options?

[`CategoryMetafileOptions`](#categorymetafileoptions)

Configuration options for the index

##### Returns

`Promise`&lt;`void`&gt;

Promise that resolves when the index is generated

##### Example

```typescript
await renderer.generateIndexMetafile("docs/types", "Types", {
  collapsible: true,
  collapsed: false,
});
```

#### preCollectCategories() \{#precollectcategories\}

```ts
preCollectCategories(rootTypeNames): void;
```

Defined in: [core/src/renderer.ts:776](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L776)

Pre-collects all category names that will be generated during rendering.
This allows the position manager to assign consistent positions before
any files are written.

HIERARCHY LEVELS:

- Root level: Query, Mutation, Subscription, Deprecated (when grouped), custom root groups
- Nested level: operations/types (API groups), custom groups under roots

CRITICAL: Categories registered must match the NAMES USED BY THE PRINTER
when generating links. The printer uses plural forms from ROOT_TYPE_LOCALE:
"operations", "objects", "directives", "enums", "inputs", "interfaces",
"mutations", "queries", "scalars", "subscriptions", "unions"

NOT the folder names: "operations", "types"

##### Parameters

###### rootTypeNames

`string`[]

Array of root type names from the schema

##### Returns

`void`

#### renderHomepage() \{#renderhomepage\}

```ts
renderHomepage(homepageLocation): Promise<void>;
```

Defined in: [core/src/renderer.ts:826](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L826)

Renders the homepage for the documentation from a template file.
Replaces placeholders in the template with actual values.

##### Parameters

###### homepageLocation

`Maybe`&lt;`string`&gt;

Path to the homepage template file

##### Returns

`Promise`&lt;`void`&gt;

Promise that resolves when the homepage is rendered

##### Example

```ts

```

#### renderRootTypes() \{#renderroottypes\}

```ts
renderRootTypes(rootTypeName, type): Promise<Maybe<Maybe<Category>[]>>;
```

Defined in: [core/src/renderer.ts:569](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L569)

Renders all types within a root type category (e.g., all Query types).

##### Parameters

###### rootTypeName

`SchemaEntity`

The name of the root type (e.g., "Query", "Mutation")

###### type

`unknown`

The type object containing all entities to render

##### Returns

`Promise`&lt;`Maybe`&lt;`Maybe`&lt;`Category`&gt;[]&gt;&gt;

Array of rendered categories or undefined

##### Example

```ts

```

#### renderTypeEntities() \{#rendertypeentities\}

```ts
renderTypeEntities(
   dirPath,
   name,
   type,
   operationNamespaceParts?
): Promise<Maybe<Category>>;
```

Defined in: [core/src/renderer.ts:636](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L636)

Renders documentation for a specific type entity and saves it to a file.

##### Parameters

###### dirPath

`string`

The directory path where the file should be saved

###### name

`string`

The name of the type entity

###### type

`unknown`

The type entity to render

###### operationNamespaceParts?

`string`[]

##### Returns

`Promise`&lt;`Maybe`&lt;`Category`&gt;&gt;

The category information for the rendered entity or undefined

##### Example

```ts

```

---

## CategoryMetafileOptions \{#categorymetafileoptions\}

Defined in: [core/src/renderer.ts:221](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L221)

Configuration options for category metafiles in the documentation.
These options control the appearance and behavior of category sections in the sidebar.

CategoryMetafileOptions

### Example

```typescript
const options: CategoryMetafileOptions = {
  collapsible: true,
  collapsed: false,
  sidebarPosition: SidebarPosition.FIRST,
  styleClass: CATEGORY_STYLE_CLASS.API,
};
```

### Properties

#### collapsed? \{#collapsed\}

```ts
optional collapsed?: boolean;
```

Defined in: [core/src/renderer.ts:223](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L223)

Whether the category should be initially collapsed

#### collapsible? \{#collapsible\}

```ts
optional collapsible?: boolean;
```

Defined in: [core/src/renderer.ts:222](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L222)

Whether the category should be collapsible in the sidebar

#### sidebarPosition? \{#sidebarposition\}

```ts
optional sidebarPosition?: number;
```

Defined in: [core/src/renderer.ts:224](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L224)

Custom position in the sidebar (lower numbers appear first)

#### styleClass? \{#styleclass\}

```ts
optional styleClass?: string;
```

Defined in: [core/src/renderer.ts:225](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L225)

CSS class to apply to the category for styling

---

## API_GROUPS \{#api_groups\}

```ts
const API_GROUPS: Required<ApiGroupOverrideType>;
```

Defined in: [core/src/renderer.ts:125](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L125)

Default group names for API types and non-API types.
This constant provides the base folder structure for organizing GraphQL schema entities.
Can be overridden via ApiGroupOverrideType in configuration.

### Example

```typescript
// Default structure
const defaultGroups = API_GROUPS;
// { operations: "operations", types: "types" }

// With custom override
const customGroups = { ...API_GROUPS, operations: "queries-and-mutations" };
```

### See

[getApiGroupFolder](#getapigroupfolder) For usage with type categorization

---

## getApiGroupFolder() \{#getapigroupfolder\}

```ts
function getApiGroupFolder(type, groups?): string;
```

Defined in: [core/src/renderer.ts:147](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L147)

Determines the appropriate folder for a GraphQL schema entity based on its type.

### Parameters

#### type

`unknown`

The GraphQL schema entity to categorize

#### groups?

`Maybe`&lt;`boolean` \| `ApiGroupOverrideType`&gt;

Optional custom group naming configuration

### Returns

`string`

The folder name where the entity should be placed

### Example

```typescript
// With default groups
const folder = getApiGroupFolder(queryType); // Returns "operations"

// With custom groups
const folder = getApiGroupFolder(objectType, { operations: "queries" }); // Returns appropriate folder
```

---

## getRenderer() \{#getrenderer\}

```ts
function getRenderer(
  printer,
  outputDir,
  baseURL,
  group,
  prettify,
  docOptions,
  mdxExtension,
  outputAdapter?,
): Promise<Renderer>;
```

Defined in: [core/src/renderer.ts:1079](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L1079)

Factory function to create and initialize a Renderer instance.
Creates the output directory and returns a configured renderer.

### Parameters

#### printer

_typeof_ `IPrinter`

The printer instance to use for rendering types

#### outputDir

`string`

The output directory for generated documentation

#### baseURL

`string`

The base URL for the documentation

#### group

`Maybe`&lt;`Partial`&lt;`Record`&lt;`SchemaEntity`, `Record`&lt;`string`, `Maybe`&lt;`string`&gt;&gt;&gt;&gt;&gt;

Optional grouping configuration

#### prettify

`boolean`

Whether to prettify the output markdown

#### docOptions

`Maybe`&lt;`RendererDocOptions`&gt;

Additional documentation options

#### mdxExtension

`string`

Extension to use for MDX files

#### outputAdapter?

`Maybe`&lt;`OutputAdapter`&gt; = `undefined`

### Returns

`Promise`&lt;[`Renderer`](#renderer)&gt;

A configured Renderer instance

### Example

```typescript
const renderer = await getRenderer(
  myPrinter,
  "./docs",
  "/api",
  groupConfig,
  true,
  { force: true, index: true },
);
```

---

## logHandlerErrors() \{#loghandlererrors\}

```ts
function logHandlerErrors(eventName, errors): void;
```

Defined in: [core/src/renderer.ts:335](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/core/src/renderer.ts#L335)

Reports errors thrown by event handlers.

Handler errors are collected rather than thrown, so without this they are
dropped and the formatter's post-processing silently does nothing.

### Parameters

#### eventName

`string`

Name of the emitted event

#### errors

`Error`[]

Errors collected from the handlers

### Returns

`void`

---

## diff(Api)

Schema comparison module for GraphQL Markdown.
Provides utilities to compare GraphQL schemas and detect changes.

## CompareMethod \{#comparemethod\}

Defined in: [index.ts:32](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/diff/src/index.ts#L32)

Comparison methods used to determine if a schema has changed.

### Enumeration Members

#### DIFF \{#diff\}

```ts
DIFF: "SCHEMA-DIFF";
```

Defined in: [index.ts:34](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/diff/src/index.ts#L34)

Compare schemas by diffing the content

#### FORCE \{#force\}

```ts
FORCE: "FORCE";
```

Defined in: [index.ts:38](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/diff/src/index.ts#L38)

Force regeneration regardless of changes

#### HASH \{#hash\}

```ts
HASH: "SCHEMA-HASH";
```

Defined in: [index.ts:36](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/diff/src/index.ts#L36)

Compare schemas by comparing hash values

#### NONE \{#none\}

```ts
NONE: "NONE";
```

Defined in: [index.ts:40](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/diff/src/index.ts#L40)

Skip comparison and assume no changes

---

## checkSchemaChanges \{#checkschemachanges\}

```ts
const checkSchemaChanges: FunctionCheckSchemaChanges;
```

Defined in: [index.ts:80](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/diff/src/index.ts#L80)

Checks if a schema has changed compared to a previous version.
Uses either diff or hash-based comparison methods based on the method parameter.

### Param

**schema**

The current GraphQL schema

### Param

**outputDir**

Directory where schema or hash files will be saved

### Param

**method**

Comparison method to use (defaults to DIFF)

### Returns

A promise resolving to a boolean indicating whether the schema has changed

---

## SCHEMA_HASH_FILE \{#schema_hash_file\}

```ts
const SCHEMA_HASH_FILE: ".schema";
```

Defined in: [index.ts:25](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/diff/src/index.ts#L25)

File name for storing schema hash

---

## SCHEMA_REF \{#schema_ref\}

```ts
const SCHEMA_REF: "schema.graphql";
```

Defined in: [index.ts:27](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/diff/src/index.ts#L27)

File name for storing schema reference

---

## getDiff() \{#getdiff\}

```ts
function getDiff(schemaNew, schemaOldLocation): Promise<Change<any>[]>;
```

Defined in: [index.ts:61](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/diff/src/index.ts#L61)

Compares a new schema against an existing schema file and returns the differences.

### Parameters

#### schemaNew

`GraphQLSchema`

The new GraphQL schema to compare

#### schemaOldLocation

`string`

File path to the old schema

### Returns

`Promise`&lt;`Change`&lt;`any`&gt;[]&gt;

A promise resolving to an array of schema changes

---

## getSchemaHash() \{#getschemahash\}

```ts
function getSchemaHash(schema): string;
```

Defined in: [index.ts:49](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/diff/src/index.ts#L49)

Generates a SHA-256 hash for a GraphQL schema.

### Parameters

#### schema

`GraphQLSchema`

The GraphQL schema to generate a hash for

### Returns

`string`

A SHA-256 hash string representing the schema

---

## index

Docusaurus integration for running GraphQL-Markdown and wiring CLI commands.

## default() \{#default\}

```ts
function default(_, options): Promise<Plugin>;
```

Defined in: [docusaurus/src/index.ts:28](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/docusaurus/src/index.ts#L28)

Docusaurus plugin wrapper that wires GraphQL-Markdown into the build,
optionally running the CLI during `docusaurus build` and registering
the `graphql-to-doc` command on the local CLI.

### Parameters

#### \_

`LoadContext`

Load context (unused).

#### options

`ConfigOptions` & `Partial`&lt;`PluginOptions`&gt;

GraphQL-Markdown CLI options plus Docusaurus plugin options.

### Returns

`Promise`&lt;`Plugin`&gt;

A configured Docusaurus plugin instance.

---

## category

## beforeGenerateIndexMetafileHook() \{#beforegenerateindexmetafilehook\}

```ts
function beforeGenerateIndexMetafileHook(event): Promise<void>;
```

Defined in: [docusaurus/src/mdx/category.ts:27](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/docusaurus/src/mdx/category.ts#L27)

Hook that materializes a `_category_.yml` file before Docusaurus indexes
a directory, ensuring generated bundles have labels, ordering, and
optional generated-index metadata even when the folder was produced by the CLI.

### Parameters

#### event

Hook payload containing the target directory, category name, and generator options.

##### data

\{
`category`: `string`;
`dirPath`: `string`;
`options?`: `Record`&lt;`string`, `unknown`&gt;;
`outputAdapter?`: `OutputAdapter`;
\}

##### data.category

`string`

##### data.dirPath

`string`

##### data.options?

`Record`&lt;`string`, `unknown`&gt;

##### data.outputAdapter?

`OutputAdapter`

### Returns

`Promise`&lt;`void`&gt;

---

## mdx

## createMDXFormatter \{#createmdxformatter\}

```ts
const createMDXFormatter: (meta?) => Formatter;
```

Defined in: formatters/dist/docusaurus/index.d.ts:91

Creates a Docusaurus formatter.
Captures `meta` in closure so `formatMDXAdmonition` can detect the Docusaurus version.

### Parameters

#### meta?

`Maybe`&lt;`MetaInfo`&gt;

Optional metadata used to detect Docusaurus version

### Returns

`Formatter`

A complete Formatter implementation for Docusaurus MDX output

---

## formatMDXAdmonition \{#formatmdxadmonition\}

```ts
const formatMDXAdmonition: ({ text, title, type }, meta) => MDXString;
```

Defined in: formatters/dist/docusaurus/index.d.ts:26

Formats an admonition using Docusaurus native `:::type` callout syntax.
Detects Docusaurus v2 (via `meta`) and uses `:::caution` instead of `:::warning`.

### Parameters

#### \{ text, title, type \}

`AdmonitionType`

#### meta

`Maybe`&lt;`MetaInfo`&gt;

Optional metadata used to detect Docusaurus version

### Returns

`MDXString`

Formatted admonition string

---

## formatMDXBadge \{#formatmdxbadge\}

```ts
const formatMDXBadge: ({ text, classname }) => MDXString;
```

Defined in: formatters/dist/docusaurus/index.d.ts:18

Formats a badge using the inline `<Badge>` component defined in `mdxDeclaration`.
Appends a CSS class derived from `classname` (e.g. `badge--deprecated`).

### Parameters

#### \{ text, classname \}

`Badge`

### Returns

`MDXString`

Formatted Badge component string

---

## formatMDXBullet \{#formatmdxbullet\}

```ts
const formatMDXBullet: (text?) => MDXString;
```

Defined in: formatters/dist/docusaurus/index.d.ts:32

Formats a bullet point using the inline `<Bullet/>` component defined in `mdxDeclaration`.

### Parameters

#### text?

`string`

Optional text to append after the bullet

### Returns

`MDXString`

Formatted Bullet component string

---

## formatMDXDetails \{#formatmdxdetails\}

```ts
const formatMDXDetails: ({ dataOpen, dataClose }) => MDXString;
```

Defined in: formatters/dist/docusaurus/index.d.ts:40

Formats a collapsible block as an HTML `<details>` element with
toggle labels that swap via the `hidden` attribute.
Text is escaped so curly braces and angle brackets don't break MDX.

### Parameters

#### \{ dataOpen, dataClose, \}

`CollapsibleOption`

### Returns

`MDXString`

Formatted details element string

---

## formatMDXFrontmatter \{#formatmdxfrontmatter\}

```ts
const formatMDXFrontmatter: (_props, formatted) => MDXString;
```

Defined in: formatters/dist/docusaurus/index.d.ts:68

Formats YAML front matter wrapped in `---` delimiters.

### Parameters

#### \_props

`Maybe`&lt;`FrontMatterOptions`&gt;

Front matter options (unused)

#### formatted

`Maybe`&lt;`string`[]&gt;

Pre-formatted front matter lines

### Returns

`MDXString`

Formatted front matter block, or empty string if no lines provided

---

## formatMDXLink \{#formatmdxlink\}

```ts
const formatMDXLink: ({ text, url }) => TypeLink;
```

Defined in: formatters/dist/docusaurus/index.d.ts:61

Appends `.mdx` to internal link URLs.

### Parameters

#### \{ text, url \}

`TypeLink`

### Returns

`TypeLink`

Link with `.mdx` extension appended to the URL

---

## formatMDXNameEntity \{#formatmdxnameentity\}

```ts
const formatMDXNameEntity: (name, parentType?) => MDXString;
```

Defined in: formatters/dist/docusaurus/index.d.ts:55

Formats a named entity as an inline `<code>` element with the parent type
in normal weight and the entity name in bold.
Text is escaped so curly braces don't break MDX.

### Parameters

#### name

`string`

Entity name

#### parentType?

`Maybe`&lt;`string`&gt;

Optional parent type name for qualified references

### Returns

`MDXString`

Formatted JSX code element string

---

## formatMDXSpecifiedByLink \{#formatmdxspecifiedbylink\}

```ts
const formatMDXSpecifiedByLink: (url) => MDXString;
```

Defined in: formatters/dist/docusaurus/index.d.ts:46

Formats a "specified by" link using the inline `<SpecifiedBy>` component.

### Parameters

#### url

`string`

URL to the specification

### Returns

`MDXString`

Formatted SpecifiedBy component string

---

## mdxDeclaration \{#mdxdeclaration\}

```ts
const mdxDeclaration: MDXString;
```

Defined in: formatters/dist/docusaurus/index.d.ts:11

MDX component definitions prepended to every generated file.

---

## defaults

Default formatter implementations shared across multiple formatter packages.

These functions provide the standard/baseline rendering behaviour.
Individual formatters import what they need and override only what differs.

## formatMDXAdmonition() \{#formatmdxadmonition\}

```ts
function formatMDXAdmonition(admonition, _meta): MDXString;
```

Defined in: [defaults.ts:42](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/defaults.ts#L42)

Formats an admonition as an HTML `<fieldset>` element with `gqlmd-mdx-admonition-*` CSS classes.

### Parameters

#### admonition

`AdmonitionType`

Admonition data with text, title, type, and optional icon

#### \_meta

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`MDXString`

Formatted admonition string

---

## formatMDXBadge() \{#formatmdxbadge\}

```ts
function formatMDXBadge(badge): MDXString;
```

Defined in: [defaults.ts:32](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/defaults.ts#L32)

Formats a badge using an HTML `<mark>` element with a `gqlmd-mdx-badge` CSS class.

### Parameters

#### badge

`Badge`

Badge data containing the text to display

### Returns

`MDXString`

Formatted badge string

---

## formatMDXBullet() \{#formatmdxbullet\}

```ts
function formatMDXBullet(text?): MDXString;
```

Defined in: [defaults.ts:54](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/defaults.ts#L54)

Formats a bullet point separator using a `<span>` with a `gqlmd-mdx-bullet` CSS class.

### Parameters

#### text?

`string` = `""`

Optional text to append after the bullet

### Returns

`MDXString`

Formatted bullet string

---

## formatMDXDetails() \{#formatmdxdetails\}

```ts
function formatMDXDetails(option): MDXString;
```

Defined in: [defaults.ts:64](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/defaults.ts#L64)

Formats a collapsible block as an HTML `<details>` element with a `gqlmd-mdx-details` CSS class.
The summary label is uppercase; the close label is rendered as `<em>`.

### Parameters

#### option

`CollapsibleOption`

Configuration for open/close label text

### Returns

`MDXString`

Formatted details element string

---

## formatMDXEscapedPermalink() \{#formatmdxescapedpermalink\}

```ts
function formatMDXEscapedPermalink(id): MDXString;
```

Defined in: [defaults.ts:138](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/defaults.ts#L138)

Formats a permalink for a section header using the classic `{#id}` syntax,
escaped so that it stays valid MDX.

MDX parses an unescaped `{` as the start of an expression, and `{#id}` is not
a valid one, so presets generating `.mdx` pages must use this variant.

### Parameters

#### id

`string`

The ID of the section header

### Returns

`MDXString`

Formatted permalink string

### Example

```js
formatMDXEscapedPermalink("my-id"); // \{#my-id\}
```

---

## formatMDXFrontmatter() \{#formatmdxfrontmatter\}

```ts
function formatMDXFrontmatter(_props, formatted): MDXString;
```

Defined in: [defaults.ts:77](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/defaults.ts#L77)

Formats YAML front matter wrapped in `---` delimiters.

### Parameters

#### \_props

`Maybe`&lt;`FrontMatterOptions`&gt;

Front matter options (unused)

#### formatted

`Maybe`&lt;`string`[]&gt;

Pre-formatted front matter lines

### Returns

`MDXString`

Formatted front matter block, or empty string if no lines provided

---

## formatMDXLink() \{#formatmdxlink\}

```ts
function formatMDXLink(link): TypeLink;
```

Defined in: [defaults.ts:93](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/defaults.ts#L93)

Formats a type link — returns the link unchanged (identity passthrough).

### Parameters

#### link

`TypeLink`

The `TypeLink` object to format

### Returns

`TypeLink`

The unmodified `TypeLink` object

---

## formatMDXNameEntity() \{#formatmdxnameentity\}

```ts
function formatMDXNameEntity(name, parentType?): MDXString;
```

Defined in: [defaults.ts:103](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/defaults.ts#L103)

Formats a named entity using `<span>` and `<code>` elements with `gqlmd-mdx-entity-*` CSS classes.

### Parameters

#### name

`string`

Entity name

#### parentType?

`Maybe`&lt;`string`&gt;

Optional parent type name for qualified references

### Returns

`MDXString`

Formatted entity reference string

---

## formatMDXPermalink() \{#formatmdxpermalink\}

```ts
function formatMDXPermalink(id): MDXString;
```

Defined in: [defaults.ts:152](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/defaults.ts#L152)

Formats a permalink for a section header using the classic `{#id}` syntax.

This is the syntax supported by most Markdown-based generators (Hugo,
mdBook, DocFX, MkDocs with `attr_list`). Presets targeting a framework that
expects another syntax override this function.

### Parameters

#### id

`string`

The ID of the section header

### Returns

`MDXString`

Formatted permalink string

---

## formatMDXSpecifiedByLink() \{#formatmdxspecifiedbylink\}

```ts
function formatMDXSpecifiedByLink(url): MDXString;
```

Defined in: [defaults.ts:119](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/defaults.ts#L119)

Formats a "specified by" link as an HTML `<span>` with a `gqlmd-mdx-specifiedby` CSS class
containing an anchor that opens in a new tab.

### Parameters

#### url

`string`

URL to the specification

### Returns

`MDXString`

Formatted specification link string

---

## docfx

DocFX formatter for GraphQL documentation output.

Produces Markdown compatible with Microsoft DocFX.
Uses DocFX alert syntax for admonitions and injects the required
`uid` front matter field for cross-reference resolution.

## afterRenderTypeEntitiesHook \{#afterrendertypeentitieshook\}

```ts
const afterRenderTypeEntitiesHook: RenderTypeEntitiesHook;
```

Defined in: [docfx/index.ts:401](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docfx/index.ts#L401)

---

## BADGE_CLASS_MAP \{#badge_class_map\}

```ts
const BADGE_CLASS_MAP: Record<string, string>;
```

Defined in: [docfx/index.ts:56](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docfx/index.ts#L56)

Maps graphql-markdown badge classnames to Bootstrap 5 contextual badge classes.

---

## mdxExtension \{#mdxextension\}

```ts
const mdxExtension: ".md";
```

Defined in: [docfx/index.ts:155](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docfx/index.ts#L155)

The file extension used for MDX files in DocFX output.

---

## createMDXFormatter() \{#createmdxformatter\}

```ts
function createMDXFormatter(_meta?): Formatter;
```

Defined in: [docfx/index.ts:138](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docfx/index.ts#L138)

Creates a DocFX formatter.

### Parameters

#### \_meta?

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`Formatter`

A complete Formatter implementation for DocFX output

---

## formatMDXAdmonition() \{#formatmdxadmonition\}

```ts
function formatMDXAdmonition(admonition, _meta): MDXString;
```

Defined in: [docfx/index.ts:79](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docfx/index.ts#L79)

Formats an admonition using DocFX alert syntax (`> [!TYPE]`).

### Parameters

#### admonition

`AdmonitionType`

Admonition data with text, title, and type

#### \_meta

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`MDXString`

Formatted admonition string

---

## formatMDXBadge() \{#formatmdxbadge\}

```ts
function formatMDXBadge(badge): MDXString;
```

Defined in: [docfx/index.ts:67](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docfx/index.ts#L67)

Formats a badge using Bootstrap 5 badge classes available in DocFX's modern template.

### Parameters

#### badge

`Badge`

Badge data containing text and optional classname

### Returns

`MDXString`

Formatted badge string

---

## formatMDXFrontmatter() \{#formatmdxfrontmatter\}

```ts
function formatMDXFrontmatter(props, formatted): MDXString;
```

Defined in: [docfx/index.ts:95](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docfx/index.ts#L95)

Formats YAML front matter, injecting a `uid` field required by DocFX
for cross-reference resolution between pages.

### Parameters

#### props

`Maybe`&lt;`FrontMatterOptions`&gt;

Front matter options; `id` is used as the DocFX `uid` value

#### formatted

`Maybe`&lt;`string`[]&gt;

Pre-formatted front matter lines

### Returns

`MDXString`

Formatted front matter block, or empty string if no lines provided

---

## formatMDXLink() \{#formatmdxlink\}

```ts
function formatMDXLink(link): TypeLink;
```

Defined in: [docfx/index.ts:121](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docfx/index.ts#L121)

Returns the link unchanged — DocFX resolves `.md` links natively.

### Parameters

#### link

`TypeLink`

Link data with URL and text

### Returns

`TypeLink`

The link unchanged

---

## docusaurus

Docusaurus MDX formatter for GraphQL documentation output.

Produces MDX markup compatible with Docusaurus v2 and v3,
using Badge, Bullet, SpecifiedBy components and native admonition syntax.

## mdxDeclaration \{#mdxdeclaration\}

```ts
const mdxDeclaration: MDXString;
```

Defined in: [docusaurus/index.ts:43](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L43)

MDX component definitions prepended to every generated file.

---

## createMDXFormatter() \{#createmdxformatter\}

```ts
function createMDXFormatter(meta?): Formatter;
```

Defined in: [docusaurus/index.ts:201](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L201)

Creates a Docusaurus formatter.
Captures `meta` in closure so `formatMDXAdmonition` can detect the Docusaurus version.

### Parameters

#### meta?

`Maybe`&lt;`MetaInfo`&gt;

Optional metadata used to detect Docusaurus version

### Returns

`Formatter`

A complete Formatter implementation for Docusaurus MDX output

---

## formatMDXAdmonition() \{#formatmdxadmonition\}

```ts
function formatMDXAdmonition(admonition, meta): MDXString;
```

Defined in: [docusaurus/index.ts:72](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L72)

Formats an admonition using Docusaurus native `:::type` callout syntax.
Detects Docusaurus v2 (via `meta`) and uses `:::caution` instead of `:::warning`.

### Parameters

#### admonition

`AdmonitionType`

Admonition data with text, title, and type

#### meta

`Maybe`&lt;`MetaInfo`&gt;

Optional metadata used to detect Docusaurus version

### Returns

`MDXString`

Formatted admonition string

---

## formatMDXBadge() \{#formatmdxbadge\}

```ts
function formatMDXBadge(badge): MDXString;
```

Defined in: [docusaurus/index.ts:59](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L59)

Formats a badge using the inline `<Badge>` component defined in `mdxDeclaration`.
Appends a CSS class derived from `classname` (e.g. `badge--deprecated`).

### Parameters

#### badge

`Badge`

Badge data containing text and optional classname

### Returns

`MDXString`

Formatted Badge component string

---

## formatMDXBullet() \{#formatmdxbullet\}

```ts
function formatMDXBullet(text?): MDXString;
```

Defined in: [docusaurus/index.ts:90](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L90)

Formats a bullet point using the inline `<Bullet/>` component defined in `mdxDeclaration`.

### Parameters

#### text?

`string` = `""`

Optional text to append after the bullet

### Returns

`MDXString`

Formatted Bullet component string

---

## formatMDXDetails() \{#formatmdxdetails\}

```ts
function formatMDXDetails(option): MDXString;
```

Defined in: [docusaurus/index.ts:101](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L101)

Formats a collapsible block as an HTML `<details>` element with
toggle labels that swap via the `hidden` attribute.
Text is escaped so curly braces and angle brackets don't break MDX.

### Parameters

#### option

`CollapsibleOption`

Configuration for open/close label text

### Returns

`MDXString`

Formatted details element string

---

## formatMDXFrontmatter() \{#formatmdxfrontmatter\}

```ts
function formatMDXFrontmatter(_props, formatted): MDXString;
```

Defined in: [docusaurus/index.ts:153](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L153)

Formats YAML front matter wrapped in `---` delimiters.

### Parameters

#### \_props

`Maybe`&lt;`FrontMatterOptions`&gt;

Front matter options (unused)

#### formatted

`Maybe`&lt;`string`[]&gt;

Pre-formatted front matter lines

### Returns

`MDXString`

Formatted front matter block, or empty string if no lines provided

---

## formatMDXLink() \{#formatmdxlink\}

```ts
function formatMDXLink(link): TypeLink;
```

Defined in: [docusaurus/index.ts:140](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L140)

Appends `.mdx` to internal link URLs.

### Parameters

#### link

`TypeLink`

Link data with URL and text

### Returns

`TypeLink`

Link with `.mdx` extension appended to the URL

---

## formatMDXNameEntity() \{#formatmdxnameentity\}

```ts
function formatMDXNameEntity(name, parentType?): MDXString;
```

Defined in: [docusaurus/index.ts:127](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L127)

Formats a named entity as an inline `<code>` element with the parent type
in normal weight and the entity name in bold.
Text is escaped so curly braces don't break MDX.

### Parameters

#### name

`string`

Entity name

#### parentType?

`Maybe`&lt;`string`&gt;

Optional parent type name for qualified references

### Returns

`MDXString`

Formatted JSX code element string

---

## formatMDXPermalink() \{#formatmdxpermalink\}

```ts
function formatMDXPermalink(id, meta?): MDXString;
```

Defined in: [docusaurus/index.ts:179](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L179)

Formats a permalink for a section header.

Docusaurus 3.10 introduced a heading id syntax based on a native MDX comment,
and deprecated the classic one. The braces of the comment must NOT be escaped:
the heading id is extracted from a real MDX expression node, so an escaped
token would be rendered as text. Older versions only support the classic
syntax, whose braces must be escaped to remain valid MDX.

### Parameters

#### id

`string`

The ID of the section header

#### meta?

`Maybe`&lt;`MetaInfo`&gt;

Optional metadata used to detect the Docusaurus version

### Returns

`MDXString`

Formatted permalink string

### See

https://docusaurus.io/blog/releases/3.10#strict-heading-ids

---

## formatMDXSpecifiedByLink() \{#formatmdxspecifiedbylink\}

```ts
function formatMDXSpecifiedByLink(url): MDXString;
```

Defined in: [docusaurus/index.ts:115](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/docusaurus/index.ts#L115)

Formats a "specified by" link using the inline `<SpecifiedBy>` component.

### Parameters

#### url

`string`

URL to the specification

### Returns

`MDXString`

Formatted SpecifiedBy component string

---

## fumadocs

Fumadocs formatter for GraphQL documentation output.

Produces MDX compatible with Next.js Fumadocs using its native
Callout component for admonitions and Material UI Chip for badges.

## mdxDeclaration \{#mdxdeclaration\}

```ts
const mdxDeclaration: MDXString;
```

Defined in: [fumadocs/index.ts:44](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/fumadocs/index.ts#L44)

MDX import statement prepended to every generated file to register Fumadocs and MUI components.

---

## mdxExtension \{#mdxextension\}

```ts
const mdxExtension: ".mdx";
```

Defined in: [fumadocs/index.ts:41](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/fumadocs/index.ts#L41)

File extension used for generated pages.

---

## createMDXFormatter() \{#createmdxformatter\}

```ts
function createMDXFormatter(_meta?): Formatter;
```

Defined in: [fumadocs/index.ts:98](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/fumadocs/index.ts#L98)

Creates a Fumadocs formatter.

### Parameters

#### \_meta?

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`Formatter`

A complete Formatter implementation for Fumadocs MDX output

---

## formatMDXAdmonition() \{#formatmdxadmonition\}

```ts
function formatMDXAdmonition(admonition, _meta): MDXString;
```

Defined in: [fumadocs/index.ts:67](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/fumadocs/index.ts#L67)

Formats an admonition using the Fumadocs `<Callout>` component.
Maps `warning` type to `warn`; all other types use `info`.

### Parameters

#### admonition

`AdmonitionType`

Admonition data with text, title, and type

#### \_meta

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`MDXString`

Formatted Fumadocs Callout component string

---

## formatMDXBadge() \{#formatmdxbadge\}

```ts
function formatMDXBadge(badge): MDXString;
```

Defined in: [fumadocs/index.ts:55](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/fumadocs/index.ts#L55)

Formats a badge using the Material UI `<Chip>` component.
Maps `DEPRECATED` classname to `warning` color; all others use `info`.

### Parameters

#### badge

`Badge`

Badge data containing text and optional classname

### Returns

`MDXString`

Formatted MUI Chip component string

---

## formatMDXLink() \{#formatmdxlink\}

```ts
function formatMDXLink(link): TypeLink;
```

Defined in: [fumadocs/index.ts:81](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/fumadocs/index.ts#L81)

Returns the link unchanged — Fumadocs routes `page.mdx` to `page` so
links must not include the `.mdx` extension.

### Parameters

#### link

`TypeLink`

Link data with URL and text

### Returns

`TypeLink`

Unmodified link

---

## formatMDXPermalink() \{#formatmdxpermalink\}

```ts
function formatMDXPermalink(id): MDXString;
```

Defined in: [fumadocs/index.ts:36](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/fumadocs/index.ts#L36)

Formats a permalink for a section header using the Fumadocs `[#id]` syntax.

### Parameters

#### id

`string`

The ID of the section header

### Returns

`MDXString`

Formatted permalink string

### See

https://www.fumadocs.dev/docs/headless/mdx/headings

---

## honkit

HonKit formatter for GraphQL documentation output.

Produces plain Markdown compatible with HonKit static site generator.
Internal links are converted to .html paths.

## \_\_default \{#\_\_default\}

```ts
const __default: object;
```

Defined in: [honkit/index.ts:32](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/index.ts#L32)

### Type Declaration

#### formatMDXBullet \{#formatmdxbullet\}

```ts
formatMDXBullet: (text) => MDXString;
```

Formats a bullet point separator using a `<span>` with a `gqlmd-mdx-bullet` CSS class.

##### Parameters

###### text?

`string` = `""`

Optional text to append after the bullet

##### Returns

`MDXString`

Formatted bullet string

#### formatMDXPermalink \{#formatmdxpermalink\}

```ts
formatMDXPermalink: (id) => MDXString;
```

Formats a permalink for a section header using the classic `{#id}` syntax.

This is the syntax supported by most Markdown-based generators (Hugo,
mdBook, DocFX, MkDocs with `attr_list`). Presets targeting a framework that
expects another syntax override this function.

##### Parameters

###### id

`string`

The ID of the section header

##### Returns

`MDXString`

Formatted permalink string

---

## mdxExtension \{#mdxextension\}

```ts
const mdxExtension: ".md";
```

Defined in: [honkit/index.ts:35](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/index.ts#L35)

File extension used for generated pages — HonKit renders plain Markdown to HTML.

---

## createMDXFormatter() \{#createmdxformatter\}

```ts
function createMDXFormatter(_meta?): Formatter;
```

Defined in: [honkit/index.ts:173](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/index.ts#L173)

Creates a HonKit formatter.

### Parameters

#### \_meta?

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`Formatter`

A complete Formatter implementation for HonKit output

---

## formatMDXAdmonition() \{#formatmdxadmonition\}

```ts
function formatMDXAdmonition(admonition, _meta): MDXString;
```

Defined in: [honkit/index.ts:64](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/index.ts#L64)

Formats an admonition as a Markdown blockquote with a bold prefix label.
Maps `warning` type to `WARNING`; all other types use `INFO`.

### Parameters

#### admonition

`AdmonitionType`

Admonition data with text, title, and type

#### \_meta

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`MDXString`

Formatted blockquote string

---

## formatMDXBadge() \{#formatmdxbadge\}

```ts
function formatMDXBadge(badge): MDXString;
```

Defined in: [honkit/index.ts:50](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/index.ts#L50)

Formats a badge as an inline HTML `<span>` with a shared default style.
Users can customize badge colors by providing their own `formatMDXBadge` implementation.

### Parameters

#### badge

`Badge`

Badge data containing text

### Returns

`MDXString`

Formatted inline HTML span string

---

## formatMDXDetails() \{#formatmdxdetails\}

```ts
function formatMDXDetails(option): MDXString;
```

Defined in: [honkit/index.ts:77](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/index.ts#L77)

Formats a collapsible block as an HTML `<details>` element.

### Parameters

#### option

`CollapsibleOption`

Configuration for open/close label text

### Returns

`MDXString`

Formatted details element string

---

## formatMDXFrontmatter() \{#formatmdxfrontmatter\}

```ts
function formatMDXFrontmatter(props, formatted): MDXString;
```

Defined in: [honkit/index.ts:93](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/index.ts#L93)

Formats YAML front matter and appends an H1 heading derived from the `title` prop.
Merges `props` entries with `formatted` lines (formatted lines take precedence).
Returns empty string if `props` is empty or absent — HonKit renders front matter
without a title as literal YAML content.

### Parameters

#### props

`Maybe`&lt;`FrontMatterOptions`&gt;

Front matter options; `title` is used to generate the H1 heading

#### formatted

`Maybe`&lt;`string`[]&gt;

Pre-formatted front matter lines that override props values

### Returns

`MDXString`

Formatted front matter block with optional H1, or empty string

---

## formatMDXLink() \{#formatmdxlink\}

```ts
function formatMDXLink(link): TypeLink;
```

Defined in: [honkit/index.ts:122](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/index.ts#L122)

Converts internal link URLs to `.html` paths for HonKit static output.
Absolute paths without an `.html` extension are suffixed with `.html`.
External URLs and fragment-only links are returned unchanged.

### Parameters

#### link

`TypeLink`

Link data with URL and text

### Returns

`TypeLink`

Link with `.html` extension applied to absolute internal paths

---

## formatMDXNameEntity() \{#formatmdxnameentity\}

```ts
function formatMDXNameEntity(name, parentType?): MDXString;
```

Defined in: [honkit/index.ts:151](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/index.ts#L151)

Formats a named entity as plain text (no markup).
HonKit renders plain Markdown — no JSX or code spans needed.

### Parameters

#### name

`string`

Entity name

#### parentType?

`Maybe`&lt;`string`&gt;

Optional parent type name for qualified references

### Returns

`MDXString`

Formatted entity reference string

---

## formatMDXSpecifiedByLink() \{#formatmdxspecifiedbylink\}

```ts
function formatMDXSpecifiedByLink(url): MDXString;
```

Defined in: [honkit/index.ts:164](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/honkit/index.ts#L164)

Formats a "specified by" link as plain text with the raw URL.
HonKit does not render custom JSX components.

### Parameters

#### url

`string`

URL to the specification

### Returns

`MDXString`

Formatted specification text string

---

## hugo

Hugo formatter for GraphQL documentation output.

Produces Markdown compatible with Hugo static site generator.
Uses GitHub-style alerts (Hugo 0.132+) for admonitions and
strips file extensions from internal links to match Hugo's URL routing.

## beforeGenerateIndexMetafileHook \{#beforegenerateindexmetafilehook\}

```ts
const beforeGenerateIndexMetafileHook: GenerateIndexMetafileHook;
```

Defined in: [hugo/index.ts:182](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/hugo/index.ts#L182)

Lifecycle hook that generates a Hugo-compatible `_index.md` section index file.
The file is (re)created on every run with YAML frontmatter:

- `title`: the start-cased category name
- `type: docs`: required by the Hugo Book theme for sidebar rendering
- `bookCollapseSection: true`: collapses the section in the Hugo Book theme sidebar by default

### Param

**event**

Hook event whose `data` contains `dirPath` (target directory) and `category` (section name)

---

## mdxExtension \{#mdxextension\}

```ts
const mdxExtension: ".md";
```

Defined in: [hugo/index.ts:172](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/hugo/index.ts#L172)

File extension used for generated pages — Hugo uses standard Markdown (.md) files.

---

## createMDXFormatter() \{#createmdxformatter\}

```ts
function createMDXFormatter(_meta?): Formatter;
```

Defined in: [hugo/index.ts:157](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/hugo/index.ts#L157)

Creates a Hugo formatter.

### Parameters

#### \_meta?

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`Formatter`

A complete Formatter implementation for Hugo output

---

## formatMDXAdmonition() \{#formatmdxadmonition\}

```ts
function formatMDXAdmonition(text, _meta): MDXString;
```

Defined in: [hugo/index.ts:78](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/hugo/index.ts#L78)

Formats an admonition using Hugo GitHub-style alert syntax (`> [!TYPE]`).
Requires Hugo 0.132 or later.

### Parameters

#### text

`AdmonitionType`

The admonition body text

#### \_meta

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`MDXString`

Formatted blockquote alert string

---

## formatMDXBadge() \{#formatmdxbadge\}

```ts
function formatMDXBadge(badge): MDXString;
```

Defined in: [hugo/index.ts:65](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/hugo/index.ts#L65)

Formats a badge as a styled span element.

### Parameters

#### badge

`Badge`

Badge data containing the display text

### Returns

`MDXString`

HTML `<span>` string with the `gqlmd-badge` class

---

## formatMDXDetails() \{#formatmdxdetails\}

```ts
function formatMDXDetails(dataOpen): MDXString;
```

Defined in: [hugo/index.ts:93](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/hugo/index.ts#L93)

Formats a collapsible block as an HTML `<details>` element.

### Parameters

#### dataOpen

`CollapsibleOption`

Label shown when the section is collapsed (used as `<summary>` text)

### Returns

`MDXString`

HTML `<details>`/`<summary>` block string

---

## formatMDXFrontmatter() \{#formatmdxfrontmatter\}

```ts
function formatMDXFrontmatter(props, formatted): MDXString;
```

Defined in: [hugo/index.ts:109](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/hugo/index.ts#L109)

Formats YAML front matter wrapped in `---` delimiters, with page title rendered as H1 heading.
Falls back to serializing `props` via [formatFrontMatterObject](../utils/frontmatter.md#formatfrontmatterobject) when `formatted` is not provided.
The title is extracted from the frontmatter lines and also rendered as a visible `# Title` heading,
since Hugo does not automatically display the frontmatter `title` field as page content.

### Parameters

#### props

`Maybe`&lt;`FrontMatterOptions`&gt;

Front matter options used as fallback when `formatted` is not provided

#### formatted

`Maybe`&lt;`string`[]&gt;

Pre-formatted front matter lines produced by the printer

### Returns

`MDXString`

Formatted front matter block with H1 title heading, or empty string if no data

---

## formatMDXLink() \{#formatmdxlink\}

```ts
function formatMDXLink(text): TypeLink;
```

Defined in: [hugo/index.ts:138](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/hugo/index.ts#L138)

Strips the `.md` extension from internal links.
Hugo serves pages at extensionless URLs — links with `.md` would 404 in the built site.

### Parameters

#### text

`TypeLink`

Display text for the link

### Returns

`TypeLink`

Link object with the cleaned URL

---

## mdbook

mdBook formatter for GraphQL documentation output.

Produces Markdown compatible with Rust's mdBook static site generator.
Front matter is suppressed because mdBook renders it as literal content.
Admonitions use mdBook's native `> [!TYPE]` syntax.
Exports `afterRenderFilesHook` to build `SUMMARY.md` after all pages are written.

## afterRenderFilesHook \{#afterrenderfileshook\}

```ts
const afterRenderFilesHook: RenderFilesHook;
```

Defined in: [mdbook/index.ts:209](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mdbook/index.ts#L209)

Builds `src/SUMMARY.md` after all pages have been written.

mdBook requires every page to be listed in `SUMMARY.md` before the site can
be built. This hook collects all rendered pages from the event, groups them
by top-level section (Operations / Types) and category, then writes the file.

---

## afterRenderTypeEntitiesHook \{#afterrendertypeentitieshook\}

```ts
const afterRenderTypeEntitiesHook: RenderTypeEntitiesHook;
```

Defined in: [mdbook/index.ts:164](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mdbook/index.ts#L164)

Rewrites absolute generated doc links to page-relative `.md` paths after each page is rendered.

mdBook resolves links relative to the book source root, so absolute paths
like `/graphql/types/scalars/id.md` are rendered as `/graphql/types/scalars/id.html`
in the output HTML — which breaks when the book is served under a subdirectory
(e.g. `https://example.com/demo-mdbook/`).
Converting them to relative paths (e.g. `../../scalars/id.md`) makes links
work correctly regardless of where the book is hosted.

---

## mdxExtension \{#mdxextension\}

```ts
const mdxExtension: ".md" = ".md";
```

Defined in: [mdbook/index.ts:105](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mdbook/index.ts#L105)

mdBook expects `.md` files; override the default `.mdx` extension.

---

## createMDXFormatter() \{#createmdxformatter\}

```ts
function createMDXFormatter(_meta?): Formatter;
```

Defined in: [mdbook/index.ts:175](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mdbook/index.ts#L175)

Creates an mdBook formatter.

### Parameters

#### \_meta?

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`Formatter`

A complete Formatter implementation for mdBook output

---

## formatMDXAdmonition() \{#formatmdxadmonition\}

```ts
function formatMDXAdmonition(admonition, _meta): MDXString;
```

Defined in: [mdbook/index.ts:63](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mdbook/index.ts#L63)

Formats an admonition using mdBook's native admonition syntax (`> [!TYPE]`).
Uses `type` for the admonition tag and `title` as an optional override label.

### Parameters

#### admonition

`AdmonitionType`

Admonition data with text, title, and type

#### \_meta

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`MDXString`

Formatted admonition string

---

## formatMDXBadge() \{#formatmdxbadge\}

```ts
function formatMDXBadge(badge): MDXString;
```

Defined in: [mdbook/index.ts:52](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mdbook/index.ts#L52)

Formats a badge as Markdown bold text — mdBook has no badge component.

### Parameters

#### badge

`Badge`

Badge data containing text

### Returns

`MDXString`

Formatted bold text string

---

## formatMDXDetails() \{#formatmdxdetails\}

```ts
function formatMDXDetails(option): MDXString;
```

Defined in: [mdbook/index.ts:84](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mdbook/index.ts#L84)

Renders a deprecated section as a bold inline label.

A fixed heading level would break hierarchy when this section is nested
inside field entries at varying depths. Bold text is CommonMark-safe and
works at any nesting level without affecting the heading outline.

The output is split on `\r` to produce [openSection, closeSection] as the
printer expects — the deprecated items are inserted between the two halves.

### Parameters

#### option

`CollapsibleOption`

Configuration for the section label

### Returns

`MDXString`

Bold label + split marker

---

## formatMDXFrontmatter() \{#formatmdxfrontmatter\}

```ts
function formatMDXFrontmatter(_props, formatted): MDXString;
```

Defined in: [mdbook/index.ts:96](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mdbook/index.ts#L96)

Replaces front matter with an H1 title heading.
mdBook renders `---` YAML blocks as literal content, so front matter is
suppressed entirely. The page title is emitted as `# Title` instead.

### Parameters

#### \_props

`Maybe`&lt;`FrontMatterOptions`&gt;

#### formatted

`Maybe`&lt;`string`[]&gt;

### Returns

`MDXString`

`# Title\n` when a title is available, otherwise an empty string

---

## formatMDXLink() \{#formatmdxlink\}

```ts
function formatMDXLink(link): TypeLink;
```

Defined in: [mdbook/index.ts:112](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mdbook/index.ts#L112)

Returns the link unchanged — mdBook resolves `.md` links natively.

### Parameters

#### link

`TypeLink`

Link data with URL and text

### Returns

`TypeLink`

The link with `.md` appended to extensionless absolute paths

---

## mkdocs

MkDocs formatter for GraphQL documentation output.

Produces Markdown compatible with MkDocs admonitions, HTML details blocks,
and visible page headings.

## \_\_default \{#\_\_default\}

```ts
const __default: object;
```

Defined in: [mkdocs/index.ts:37](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/index.ts#L37)

### Type Declaration

#### formatMDXBullet \{#formatmdxbullet\}

```ts
formatMDXBullet: (text) => MDXString;
```

Formats a bullet point separator using a `<span>` with a `gqlmd-mdx-bullet` CSS class.

##### Parameters

###### text?

`string` = `""`

Optional text to append after the bullet

##### Returns

`MDXString`

Formatted bullet string

#### formatMDXLink \{#formatmdxlink\}

```ts
formatMDXLink: (link) => TypeLink;
```

Formats a type link — returns the link unchanged (identity passthrough).

##### Parameters

###### link

`TypeLink`

The `TypeLink` object to format

##### Returns

`TypeLink`

The unmodified `TypeLink` object

#### formatMDXPermalink \{#formatmdxpermalink\}

```ts
formatMDXPermalink: (id) => MDXString;
```

Formats a permalink for a section header using the classic `{#id}` syntax.

This is the syntax supported by most Markdown-based generators (Hugo,
mdBook, DocFX, MkDocs with `attr_list`). Presets targeting a framework that
expects another syntax override this function.

##### Parameters

###### id

`string`

The ID of the section header

##### Returns

`MDXString`

Formatted permalink string

---

## afterRenderTypeEntitiesHook \{#afterrendertypeentitieshook\}

```ts
const afterRenderTypeEntitiesHook: RenderTypeEntitiesHook;
```

Defined in: [mkdocs/index.ts:158](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/index.ts#L158)

Lifecycle hook that rewrites generated absolute GraphQL-Markdown links
into page-relative `.md` links compatible with MkDocs validation.

### Param

**event**

Hook payload containing the current file path and renderer output context

---

## mdxExtension \{#mdxextension\}

```ts
const mdxExtension: ".md";
```

Defined in: [mkdocs/index.ts:151](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/index.ts#L151)

File extension used for generated pages — MkDocs uses standard Markdown (.md) files.

---

## createMDXFormatter() \{#createmdxformatter\}

```ts
function createMDXFormatter(_meta?): Formatter;
```

Defined in: [mkdocs/index.ts:171](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/index.ts#L171)

Creates an MkDocs Material formatter.

### Parameters

#### \_meta?

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`Formatter`

A complete Formatter implementation for MkDocs Material output

---

## formatMDXAdmonition() \{#formatmdxadmonition\}

```ts
function formatMDXAdmonition(admonition, _meta): MDXString;
```

Defined in: [mkdocs/index.ts:92](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/index.ts#L92)

Formats an admonition using MkDocs Material `!!!` block syntax.
Content is indented by 4 spaces as required by the spec.

### Parameters

#### admonition

`AdmonitionType`

Admonition data with text, title, and type

#### \_meta

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`MDXString`

Formatted admonition string

---

## formatMDXBadge() \{#formatmdxbadge\}

```ts
function formatMDXBadge(badge): MDXString;
```

Defined in: [mkdocs/index.ts:81](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/index.ts#L81)

Formats a badge as an inline HTML mark element.

### Parameters

#### badge

`Badge`

Badge data containing text and optional classname

### Returns

`MDXString`

Formatted badge string

---

## formatMDXDetails() \{#formatmdxdetails\}

```ts
function formatMDXDetails(option): MDXString;
```

Defined in: [mkdocs/index.ts:106](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/index.ts#L106)

Formats a collapsible block as an HTML `<details>` element.

### Parameters

#### option

`CollapsibleOption`

Configuration for open/close label text

### Returns

`MDXString`

Formatted collapsible string

---

## formatMDXFrontmatter() \{#formatmdxfrontmatter\}

```ts
function formatMDXFrontmatter(_props, formatted): MDXString;
```

Defined in: [mkdocs/index.ts:119](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/index.ts#L119)

Formats page title as a visible H1 heading.

### Parameters

#### \_props

`Maybe`&lt;`FrontMatterOptions`&gt;

Front matter options (unused)

#### formatted

`Maybe`&lt;`string`[]&gt;

Pre-formatted front matter lines

### Returns

`MDXString`

Visible heading string, or empty string if no title is available

---

## formatMDXNameEntity() \{#formatmdxnameentity\}

```ts
function formatMDXNameEntity(name, parentType?): MDXString;
```

Defined in: [mkdocs/index.ts:133](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/index.ts#L133)

Formats a named entity as a backtick code span.

### Parameters

#### name

`string`

Entity name

#### parentType?

`Maybe`&lt;`string`&gt;

Optional parent type name for qualified references

### Returns

`MDXString`

Formatted entity reference string

---

## formatMDXSpecifiedByLink() \{#formatmdxspecifiedbylink\}

```ts
function formatMDXSpecifiedByLink(url): MDXString;
```

Defined in: [mkdocs/index.ts:146](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/mkdocs/index.ts#L146)

Formats a "specified by" link as a standard Markdown link.

### Parameters

#### url

`string`

URL to the specification

### Returns

`MDXString`

Formatted specification link string

---

## output

Output helpers for formatter lifecycle hooks.

Hooks post-process pages the renderer has already written, so they must go
through the same destination the renderer used. Reaching for the filesystem
directly works only as long as the default adapter is in play, and silently
misses every page when the output is redirected elsewhere.

## readOptionalOutput() \{#readoptionaloutput\}

```ts
function readOptionalOutput(
  filePath,
  outputAdapter,
): Promise<string | undefined>;
```

Defined in: [output.ts:84](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/output.ts#L84)

Reads a file the formatter maintains itself, where absence is expected.

Unlike [readOutput](#readoutput) this reports nothing when there is no content: a
navigation or metadata file legitimately does not exist until the formatter
creates it on the first page of a directory.

### Parameters

#### filePath

`string`

Path of the file to read

#### outputAdapter

`Maybe`&lt;`OutputAdapter`&gt;

Adapter carried by the hook event, if any

### Returns

`Promise`&lt;`string` \| `undefined`&gt;

The file content, or `undefined` when there is none

---

## readOutput() \{#readoutput\}

```ts
function readOutput(filePath, outputAdapter): Promise<string | undefined>;
```

Defined in: [output.ts:52](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/output.ts#L52)

Reads back a page the renderer has written, through its output destination.

The page was just written, so nothing coming back means the destination
cannot be read - a write-only adapter, a stubbed `readFile`, or a store that
is not read-your-writes consistent. Post-processing cannot run without it,
which is reported rather than silently skipped.

### Parameters

#### filePath

`string`

Path of the generated page

#### outputAdapter

`Maybe`&lt;`OutputAdapter`&gt;

Adapter carried by the hook event, if any

### Returns

`Promise`&lt;`string` \| `undefined`&gt;

The page content, or `undefined` if it cannot be read back

### Throws

An error the first time this adapter cannot read a page back, so the
skipped post-processing surfaces once instead of once per page.

---

## rewriteRenderedPage() \{#rewriterenderedpage\}

```ts
function rewriteRenderedPage(event, rewrite): Promise<void>;
```

Defined in: [output.ts:123](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/output.ts#L123)

Rewrites the content of a page a formatter has just rendered.

The read-modify-write around an `afterRenderTypeEntities` hook is identical
for every preset that post-processes its own output; only the rewriting
differs. Presets supply that and nothing else.

### Parameters

#### event

`unknown`

The hook event, carrying the page path and its destination

#### rewrite

(`content`, `filePath`, `outputDir`, `baseURL`) => `string`

Returns the new content, or the content unchanged to skip

### Returns

`Promise`&lt;`void`&gt;

---

## writeOutput() \{#writeoutput\}

```ts
function writeOutput(filePath, content, outputAdapter, dirPath?): Promise<void>;
```

Defined in: [output.ts:98](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/output.ts#L98)

Writes a file through the output destination, creating its directory first.

### Parameters

#### filePath

`string`

Path of the file to write

#### content

`string`

File content

#### outputAdapter

`Maybe`&lt;`OutputAdapter`&gt;

Adapter carried by the hook event, if any

#### dirPath?

`string`

### Returns

`Promise`&lt;`void`&gt;

---

## starlight

Astro Starlight formatter for GraphQL documentation output.

Produces MDX compatible with Astro Starlight using its native
Aside and Badge components. Includes lifecycle hooks for generating
index files for each category directory.

## formatMDXPermalink \{#formatmdxpermalink\}

```ts
const formatMDXPermalink: (id) => MDXString = formatMDXEscapedPermalink;
```

Defined in: [starlight/index.ts:41](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/starlight/index.ts#L41)

Formats a permalink for a section header, using the classic `{#id}` syntax
escaped to remain valid MDX.

Starlight has no built-in custom header id syntax, so the permalink is inert
unless a remark plugin such as `remark-custom-heading-id` is configured. Turn
it off with `docOptions.sectionHeaderId: false`.

Formats a permalink for a section header using the classic `{#id}` syntax,
escaped so that it stays valid MDX.

MDX parses an unescaped `{` as the start of an expression, and `{#id}` is not
a valid one, so presets generating `.mdx` pages must use this variant.

### Parameters

#### id

`string`

The ID of the section header

### Returns

`MDXString`

Formatted permalink string

### Example

```js
formatMDXEscapedPermalink("my-id"); // \{#my-id\}
```

### Param

**id**

The ID of the section header

### Returns

Formatted permalink string

---

## mdxDeclaration \{#mdxdeclaration\}

```ts
const mdxDeclaration: MDXString;
```

Defined in: [starlight/index.ts:47](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/starlight/index.ts#L47)

MDX import statement prepended to every generated file to register Starlight components.

---

## mdxExtension \{#mdxextension\}

```ts
const mdxExtension: ".mdx";
```

Defined in: [starlight/index.ts:44](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/starlight/index.ts#L44)

File extension used for generated pages.

---

## createMDXFormatter() \{#createmdxformatter\}

```ts
function createMDXFormatter(_meta?): Formatter;
```

Defined in: [starlight/index.ts:100](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/starlight/index.ts#L100)

Creates an Astro Starlight formatter.

### Parameters

#### \_meta?

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`Formatter`

A complete Formatter implementation for Starlight MDX output

---

## formatMDXAdmonition() \{#formatmdxadmonition\}

```ts
function formatMDXAdmonition(admonition, _meta): MDXString;
```

Defined in: [starlight/index.ts:69](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/starlight/index.ts#L69)

Formats an admonition using the Starlight `<Aside>` component.
Maps `warning` type to `caution`; all other types use `note`.

### Parameters

#### admonition

`AdmonitionType`

Admonition data with text, title, and type

#### \_meta

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`MDXString`

Formatted Starlight Aside component string

---

## formatMDXBadge() \{#formatmdxbadge\}

```ts
function formatMDXBadge(badge): MDXString;
```

Defined in: [starlight/index.ts:57](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/starlight/index.ts#L57)

Formats a badge using the Starlight `<Badge>` component.
Maps `DEPRECATED` classname to the `caution` variant; all others use `default`.

### Parameters

#### badge

`Badge`

Badge data containing text and optional classname

### Returns

`MDXString`

Formatted Starlight Badge component string

---

## formatMDXLink() \{#formatmdxlink\}

```ts
function formatMDXLink(link): TypeLink;
```

Defined in: [starlight/index.ts:83](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/starlight/index.ts#L83)

Returns the link unchanged — Starlight routes `page.mdx` to `page/` so
links must not include the `.mdx` extension.

### Parameters

#### link

`TypeLink`

Link data with URL and text

### Returns

`TypeLink`

Unmodified link

---

## version

Helpers for gating formatter output on the target framework version.

## FrameworkVersion \{#frameworkversion\}

Defined in: [version.ts:10](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/version.ts#L10)

A framework version, narrowed down to the parts used for comparison.

### Properties

#### major \{#major\}

```ts
major: number;
```

Defined in: [version.ts:11](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/version.ts#L11)

#### minor? \{#minor\}

```ts
optional minor?: number;
```

Defined in: [version.ts:12](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/version.ts#L12)

---

## isFrameworkVersion() \{#isframeworkversion\}

```ts
function isFrameworkVersion(meta, framework, version): boolean;
```

Defined in: [version.ts:109](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/version.ts#L109)

Checks that the generator framework declared in `meta` is `framework`, and
that its version matches `version`.

Only the parts carried by `version` are compared, so `{ major: 2 }` matches
any `2.x` release. An unknown, unparsable or mismatched framework version
returns `false`.

### Parameters

#### meta

`Maybe`&lt;`MetaInfo`&gt;

Optional metadata carrying the framework name and version

#### framework

`string`

The expected framework name, eg `"docusaurus"`

#### version

[`FrameworkVersion`](#frameworkversion)

The version to match

### Returns

`boolean`

`true` if the framework and its version match

### Example

```js
const meta = {
  generatorFrameworkName: "docusaurus",
  generatorFrameworkVersion: "2.4.3",
};

isFrameworkVersion(meta, "docusaurus", { major: 2 }); // true
isFrameworkVersion(meta, "docusaurus", { major: 3 }); // false
```

---

## isFrameworkVersionAtLeast() \{#isframeworkversionatleast\}

```ts
function isFrameworkVersionAtLeast(meta, framework, minVersion): boolean;
```

Defined in: [version.ts:140](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/version.ts#L140)

Checks that the generator framework declared in `meta` is `framework`, and
that its version is `minVersion` or above.

An unknown, unparsable or mismatched framework version returns `false`, so
callers fall back to the output supported by every version.

### Parameters

#### meta

`Maybe`&lt;`MetaInfo`&gt;

Optional metadata carrying the framework name and version

#### framework

`string`

The expected framework name, eg `"docusaurus"`

#### minVersion

[`FrameworkVersion`](#frameworkversion)

The minimum version required by the caller

### Returns

`boolean`

`true` if the framework matches and its version is high enough

### Example

```js
const meta = {
  generatorFrameworkName: "docusaurus",
  generatorFrameworkVersion: "3.10.2",
};

isFrameworkVersionAtLeast(meta, "docusaurus", { major: 3, minor: 10 }); // true
isFrameworkVersionAtLeast(meta, "docusaurus", { major: 4 }); // false
```

---

## vocs

Vocs formatter for GraphQL documentation output.

Produces MDX compatible with Vite/Vocs using its native callout syntax

## formatMDXPermalink \{#formatmdxpermalink\}

```ts
const formatMDXPermalink: (id) => MDXString = formatMDXEscapedPermalink;
```

Defined in: [vocs/index.ts:40](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/vocs/index.ts#L40)

Formats a permalink for a section header, using the classic `{#id}` syntax
escaped to remain valid MDX.

Vocs has no custom header id syntax, so the permalink is inert unless a
remark plugin is configured. Turn it off with
`docOptions.sectionHeaderId: false`.

Formats a permalink for a section header using the classic `{#id}` syntax,
escaped so that it stays valid MDX.

MDX parses an unescaped `{` as the start of an expression, and `{#id}` is not
a valid one, so presets generating `.mdx` pages must use this variant.

### Parameters

#### id

`string`

The ID of the section header

### Returns

`MDXString`

Formatted permalink string

### Example

```js
formatMDXEscapedPermalink("my-id"); // \{#my-id\}
```

### See

https://vocs.dev/docs/markdown

### Param

**id**

The ID of the section header

### Returns

Formatted permalink string

---

## mdxDeclaration \{#mdxdeclaration\}

```ts
const mdxDeclaration: MDXString;
```

Defined in: [vocs/index.ts:43](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/vocs/index.ts#L43)

MDX import statement and inline component definitions prepended to every generated file.

---

## mdxExtension \{#mdxextension\}

```ts
const mdxExtension: ".mdx";
```

Defined in: [vocs/index.ts:48](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/vocs/index.ts#L48)

File extension used for generated pages.

---

## createMDXFormatter() \{#createmdxformatter\}

```ts
function createMDXFormatter(_meta?): Formatter;
```

Defined in: [vocs/index.ts:124](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/vocs/index.ts#L124)

Creates a Vocs formatter.

### Parameters

#### \_meta?

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`Formatter`

A complete Formatter implementation for Vocs MDX output

---

## formatMDXAdmonition() \{#formatmdxadmonition\}

```ts
function formatMDXAdmonition(admonition, _meta): MDXString;
```

Defined in: [vocs/index.ts:68](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/vocs/index.ts#L68)

Formats an admonition using Vocs native callout syntax (`:::type[title]`).
Maps `warning` type to `warning`; all other types use `info`.

### Parameters

#### admonition

`AdmonitionType`

Admonition data with text, title, and type

#### \_meta

`Maybe`&lt;`MetaInfo`&gt;

Unused metadata parameter

### Returns

`MDXString`

Formatted Vocs callout string

---

## formatMDXBadge() \{#formatmdxbadge\}

```ts
function formatMDXBadge(badge): MDXString;
```

Defined in: [vocs/index.ts:56](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/vocs/index.ts#L56)

Formats a badge using Vocs native text directive (`:badge[...]`).
Maps `DEPRECATED` classname to `warning` color; all others use default.

### Parameters

#### badge

`Badge`

Badge data containing text and optional classname

### Returns

`MDXString`

Formatted Vocs badge string

---

## formatMDXBullet() \{#formatmdxbullet\}

```ts
function formatMDXBullet(text?): MDXString;
```

Defined in: [vocs/index.ts:81](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/vocs/index.ts#L81)

Formats a bullet point using the inline `<Bullet/>` component defined in `mdxDeclaration`.

### Parameters

#### text?

`string` = `""`

Optional text to append after the bullet

### Returns

`MDXString`

Formatted Bullet component string

---

## formatMDXLink() \{#formatmdxlink\}

```ts
function formatMDXLink(link): TypeLink;
```

Defined in: [vocs/index.ts:90](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/vocs/index.ts#L90)

Appends `.mdx` to internal link URLs.

### Parameters

#### link

`TypeLink`

Link data with URL and text

### Returns

`TypeLink`

Link with `.mdx` extension appended to the URL

---

## formatMDXNameEntity() \{#formatmdxnameentity\}

```ts
function formatMDXNameEntity(name, parentType?): MDXString;
```

Defined in: [vocs/index.ts:103](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/formatters/src/vocs/index.ts#L103)

Formats a named entity as a JSX span with styled code elements.

### Parameters

#### name

`string`

Entity name

#### parentType?

`Maybe`&lt;`string`&gt;

Optional parent type name for qualified references

### Returns

`MDXString`

Formatted JSX entity reference string

---

## directive

Library supporting `customDirective` for directive based customization.

## See

[Option `customDirective`](https://graphql-markdown.dev/docs/advanced/custom-directive)

## WILDCARD_DIRECTIVE \{#wildcard_directive\}

```ts
const WILDCARD_DIRECTIVE: "*";
```

Defined in: [packages/graphql/src/directive.ts:29](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L29)

Wildcard `*` character for matching any directive name.

See [getCustomDirectiveOptions](#getcustomdirectiveoptions), [isCustomDirective](#iscustomdirective)

---

## getConstDirectiveMap() \{#getconstdirectivemap\}

```ts
function getConstDirectiveMap(
  entity,
  customDirectiveMap,
): Maybe<CustomDirectiveMap>;
```

Defined in: [packages/graphql/src/directive.ts:249](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L249)

Returns a map of custom directives for a schema entity.

### Parameters

#### entity

`unknown`

a GraphQL schema entity.

#### customDirectiveMap

`Maybe`&lt;`CustomDirectiveMap`&gt;

a custom directive map (see [getCustomDirectives](#getcustomdirectives)).

### Returns

`Maybe`&lt;`CustomDirectiveMap`&gt;

A map of GraphQL directives matching the custom directives defined, else `undefined`.

### Example

```js
import { buildSchema } from "graphql";
import { getConstDirectiveMap } from "@graphql-markdown/utils/directive";

const schema = buildSchema(`
    directive @testA(
      arg: ArgEnum = ARGA
    ) on OBJECT | FIELD_DEFINITION

    directive @testB(
      argA: Int!,
      argB: [String!]
    ) on FIELD_DEFINITION

    enum ArgEnum {
      ARGA
      ARGB
      ARGC
    }

    type Test @testA {
      id: ID!
      fieldA: [String!]
        @testA(arg: ARGC)
        @testB(argA: 10, argB: ["testArgB"])
    }

    type TestWithoutDirective {
      id: ID!
    }
  `);

const customDirectives = {
  testA: {
    type: schema.getDirective("testA"),
    descriptor: (_, constDirectiveType) => `${constDirectiveType.name}`;
  },
};

const map = getConstDirectiveMap(schema.getType("Test"), customDirectives);
// Expected result: {
//   "descriptor": (_, constDirectiveType) => `${constDirectiveType.name}`,
//   "type": schema.getDirective("testA"),
// }

```

---

## getCustomDirectiveOptions() \{#getcustomdirectiveoptions\}

```ts
function getCustomDirectiveOptions(
  schemaDirectiveName,
  customDirectiveOptions,
): Maybe<Partial<Record<CustomDirectiveResolver, CustomDirectiveFunction>>>;
```

Defined in: [packages/graphql/src/directive.ts:77](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L77)

Returns a record set of custom handlers from a directive by name.

### Parameters

#### schemaDirectiveName

`DirectiveName`

the GraphQL directive name.

#### customDirectiveOptions

`CustomDirective`

the `customDirective` option.

### Returns

`Maybe`&lt;`Partial`&lt;`Record`&lt;`CustomDirectiveResolver`, `CustomDirectiveFunction`&gt;&gt;&gt;

a record set of custom handlers for the matching directive (or if `*` is declared), or `undefined` if no match.

### Example

```js
import { getCustomDirectiveOptions } from "@graphql-markdown/utils/directive";

const customDirectiveOptions = {
  "*": {
    descriptor: (_, constDirectiveType) => `Wildcard ${constDirectiveType.name}`;
  },
};

const customDirectives = getCustomDirectiveOptions("testB", customDirectiveOptions);

// Expected result: {
//   "descriptor": (_, constDirectiveType) => `Wildcard ${constDirectiveType.name}`,
//   "type": "@testB",
// }
```

---

## getCustomDirectives() \{#getcustomdirectives\}

```ts
function getCustomDirectives(
  schemaMap,
  customDirectiveOptions?,
): Maybe<CustomDirectiveMap>;
```

Defined in: [packages/graphql/src/directive.ts:151](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L151)

Returns a custom directives map with custom handlers from `customDirective`.

### Parameters

#### schemaMap

`Pick`&lt;`SchemaMap`, `"directives"`&gt;

the GraphQL schema map returned by getSchemaMap

#### customDirectiveOptions?

`Maybe`&lt;`CustomDirective`&gt;

the `customDirective` option.

### Returns

`Maybe`&lt;`CustomDirectiveMap`&gt;

a custom directive map, or `undefined` if no match.

### Example

```js
import { buildSchema } from "graphql";
import { getCustomDirectives } from "@graphql-markdown/utils/directive";

const schema = buildSchema(`
  directive @testA(
    arg: ArgEnum = ARGA
  ) on OBJECT | FIELD_DEFINITION
  directive @testB(
    argA: Int!,
    argB: [String!]
  ) on FIELD_DEFINITION
  enum ArgEnum {
    ARGA
    ARGB
    ARGC
  }
`);

const schemaMap = {
  directives: {
    testA: schema.getDirective("testA"),
    testB: schema.getDirective("testB"),
  },
};

const customDirectiveOptions = {
  testA: {
    descriptor: (_, constDirectiveType) => `Named directive ${constDirectiveType.name}`;
  },
  "*": {
    descriptor: (_, constDirectiveType) => `Wildcard ${constDirectiveType.name}`;
  },
};

const customDirectives = getCustomDirectives(schemaMap, customDirectiveOptions);

// Expected result: {
//   "testA": {
//     "descriptor": (_, constDirectiveType) => `Named directive ${constDirectiveType.name}`,
//     "type": "@testA",
//   },
//   "testB": {
//     "descriptor": (_, constDirectiveType) => `Wildcard ${constDirectiveType.name}`,
//     "type": "@testB",
//   },
// }
```

---

## isCustomDirective() \{#iscustomdirective\}

```ts
function isCustomDirective(
  schemaDirectiveName,
  customDirectiveOptions,
): boolean;
```

Defined in: [packages/graphql/src/directive.ts:40](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L40)

Checks if a directive name is referenced in `customDirective` option.

### Parameters

#### schemaDirectiveName

`DirectiveName`

the GraphQL directive name.

#### customDirectiveOptions

`CustomDirective`

the `customDirective` option.

### Returns

`boolean`

`true` if the directive is declared or `*` is declared in `customDirective` option, else `false`.

---

## formatter

Internal library of helpers for formatting GraphQL values.

## getFormattedDefaultValue() \{#getformatteddefaultvalue\}

```ts
function getFormattedDefaultValue<T>(entity): Maybe<string | T>;
```

Defined in: [packages/graphql/src/formatter.ts:130](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/formatter.ts#L130)

Returns a printable formatted value for a GraphQL type.
This is the generic function.

### Type Parameters

#### T

`T`

### Parameters

#### entity

`GraphQLSchemaEntity`&lt;`T`&gt;

the GraphQL schema entity processed.

### Returns

`Maybe`&lt;`string` \| `T`&gt;

a printable formatted value.

---

## group

Library supporting `groupByDirective` for grouping GraphQL schema entities.

## See

[Option `groupByDirective`](https://graphql-markdown.dev/docs/advanced/group-by-directive)

## getGroupName() \{#getgroupname\}

```ts
function getGroupName<T>(type, groupByDirective): Maybe<string>;
```

Defined in: [packages/graphql/src/group.ts:72](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/group.ts#L72)

Gets the group name for a schema type based on the directive information.

### Type Parameters

#### T

`T`

### Parameters

#### type

`T`

a GraphQL schema named type

#### groupByDirective

`Maybe`&lt;`GroupByDirectiveOptions`&gt;

the `groupByDirective` option.

### Returns

`Maybe`&lt;`string`&gt;

the group name matching the type, or `groupByDirective.fallback` if no match found.

### Example

```js
import { buildSchema } from "graphql";
import { getGroupName } from "@graphql-markdown/utils/groups";

const schema = buildSchema(`
  directive @doc(
    category: String
  ) on OBJECT | INPUT_OBJECT | UNION | ENUM | INTERFACE | FIELD_DEFINITION | ARGUMENT_DEFINITION
  type Unicorn {
    name: String!
  }
  type Bird @doc(category: "animal") {
    name: String!
  }
  type Fish {
    name: String!
  }
  type Elf @doc(category: "fantasy") {
    name: String!
  }
  type Query {
    Fish: [Fish!]! @doc(category: "animal")
  }
`);

const groupOptions = {
  fallback: "common",
  directive: "doc",
  field: "category",
};

getGroupName(schema.getType("Bird"), groupOptions); // Expected result: "animal"

getGroupName(schema.getType("Unicorn"), groupOptions); // Expected result: "common"
```

---

## getGroups() \{#getgroups\}

```ts
function getGroups(
  schemaMap,
  groupByDirective,
): Maybe<Partial<Record<SchemaEntity, Record<string, Maybe<string>>>>>;
```

Defined in: [packages/graphql/src/group.ts:173](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/group.ts#L173)

Parses a GraphQL schema to build a map of entities with matching `groupByDirective` option.

### Parameters

#### schemaMap

`SchemaMap`

the GraphQL schema map returned by getSchemaMap

#### groupByDirective

`Maybe`&lt;`GroupByDirectiveOptions`&gt;

the `groupByDirective` option.

### Returns

`Maybe`&lt;`Partial`&lt;`Record`&lt;`SchemaEntity`, `Record`&lt;`string`, `Maybe`&lt;`string`&gt;&gt;&gt;&gt;&gt;

a map of entities with matching group name.

### Example

```js
import { buildSchema } from "graphql";
import { getGroups } from "@graphql-markdown/utils/groups";

const schema = buildSchema(`
  directive @doc(
    category: String
  ) on OBJECT | INPUT_OBJECT | UNION | ENUM | INTERFACE | FIELD_DEFINITION | ARGUMENT_DEFINITION
  type Unicorn {
    name: String!
  }
  type Bird @doc(category: "animal") {
    name: String!
  }
  type Fish {
    name: String!
  }
  type Elf @doc(category: "fantasy") {
    name: String!
  }
  type Query {
    Fish: [Fish!]! @doc(category: "animal")
  }
`);

const schemaMap = {
  objects: schema.getTypeMap(),
  queries: schema.getQueryType()?.getFields(),
};

const groupOptions = {
  fallback: "common",
  directive: "doc",
  field: "category",
};

const groupsMap = getGroups(schemaMap, groupOptions);

// Expected result: {
//   "objects": {
//     "Bird": "animal",
//     "Boolean": "common",
//     "Elf": "fantasy",
//     "Fish": "common",
//     "Query": "common",
//     "String": "common",
//     "Unicorn": "common",
//   },
//   "queries": {
//     "Fish": "animal",
//   },
// }
```

---

## guard

Custom GraphQL type guards and property guards.

## executableDirectiveLocation() \{#executabledirectivelocation\}

```ts
function executableDirectiveLocation(directive): boolean;
```

Defined in: [packages/graphql/src/guard.ts:104](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/guard.ts#L104)

Checks if a directive is executable (related to operations).

### Parameters

#### directive

`GraphQLDirective`

a GraphQL directive.

### Returns

`boolean`

---

## instanceOf() \{#instanceof\}

```ts
function instanceOf<T>(obj, type): obj is () => T;
```

Defined in: [packages/graphql/src/guard.ts:58](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/guard.ts#L58)

Checks if a GraphQL named type is of generic type `T`.

### Type Parameters

#### T

`T`

a GraphQL type to check against, eg `GraphQLObjectType`.

### Parameters

#### obj

`unknown`

a GraphQL named type from the GraphQL schema.

#### type

() => `T`

the GraphQL type `T`.

### Returns

`obj is () => T`

---

## isApiType() \{#isapitype\}

```ts
function isApiType(type): boolean;
```

Defined in: [packages/graphql/src/guard.ts:140](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/guard.ts#L140)

Checks if a type belongs to API (operation related).

### Parameters

#### type

`unknown`

a GraphQL type.

### Returns

`boolean`

---

## isDeprecated() \{#isdeprecated\}

```ts
function isDeprecated<T>(obj): obj is DeprecatedType<T>;
```

Defined in: [packages/graphql/src/guard.ts:79](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/guard.ts#L79)

Checks if a GraphQL named type is deprecated.

### Type Parameters

#### T

`T`

a GraphQL type to check against, eg `GraphQLObjectType`.

### Parameters

#### obj

`T`

an instance of `T`.

### Returns

`obj is DeprecatedType<T>`

---

## isGraphQLFieldType() \{#isgraphqlfieldtype\}

```ts
function isGraphQLFieldType(
  type,
): type is GraphQLField<unknown, unknown, unknown>;
```

Defined in: [packages/graphql/src/guard.ts:39](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/guard.ts#L39)

Checks if a GraphQL named type is of type `GraphQLField`.

### Parameters

#### type

`unknown`

a GraphQL type.

### Returns

`type is GraphQLField<unknown, unknown, unknown>`

---

## isOperation() \{#isoperation\}

```ts
function isOperation(type): type is GraphQLOperationType;
```

Defined in: [packages/graphql/src/guard.ts:94](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/guard.ts#L94)

Checks if a GraphQL type a GraphQL operation (query, mutation, subscription).

### Parameters

#### type

`unknown`

a GraphQL type.

### Returns

`type is GraphQLOperationType`

---

## isSystemType() \{#issystemtype\}

```ts
function isSystemType(type): boolean;
```

Defined in: [packages/graphql/src/guard.ts:153](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/guard.ts#L153)

Checks if a type belongs to schema (schema type definition excluding operations related types).

### Parameters

#### type

`unknown`

a GraphQL type.

### Returns

`boolean`

---

## typeSystemDirectiveLocation() \{#typesystemdirectivelocation\}

```ts
function typeSystemDirectiveLocation(directive): boolean;
```

Defined in: [packages/graphql/src/guard.ts:127](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/guard.ts#L127)

Checks if a directive is system (related to schema definition).

### Parameters

#### directive

`GraphQLDirective`

a GraphQL directive.

### Returns

`boolean`

---

## loader

Library for GraphQL schema loading and `loaders` config processing.

## getDocumentLoaders() \{#getdocumentloaders\}

```ts
function getDocumentLoaders(loadersList): Promise<Maybe<LoadSchemaOptions>>;
```

Defined in: [packages/graphql/src/loader.ts:111](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/loader.ts#L111)

### Parameters

#### loadersList

`Maybe`&lt;`LoaderOption`&gt;

### Returns

`Promise`&lt;`Maybe`&lt;`LoadSchemaOptions`&gt;&gt;

---

## loadSchema() \{#loadschema\}

```ts
function loadSchema(schemaLocation, options): Promise<GraphQLSchema>;
```

Defined in: [packages/graphql/src/loader.ts:48](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/loader.ts#L48)

### Parameters

#### schemaLocation

`string`

#### options

`LoadSchemaConfig`

### Returns

`Promise`&lt;`GraphQLSchema`&gt;

---

## relation

Library for displaying relations between GraphQL schema entities.

## See

[Settings `printTypeOptions`](https://graphql-markdown.dev/docs/settings#printtypeoptions)

## getRelationOfField \{#getrelationoffield\}

```ts
const getRelationOfField: IGetRelation<RelationOfField>;
```

Defined in: [packages/graphql/src/relation.ts:169](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/relation.ts#L169)

Returns a map of fields and arguments where the GraphQL schema type matches the type.

### See

mapRelationOf

### Type Param

**T**

the type of the GraphQL schema type.

### Type Param

**R**

the return type of map of relations (see IGetRelation).

### Param

**type**

the GraphQL schema type being processed.

### Param

**schemaMap**

a GraphQL schema map (see getSchemaMap).

### Returns

a record map of fields and arguments relations.

---

## getRelationOfImplementation \{#getrelationofimplementation\}

```ts
const getRelationOfImplementation: IGetRelation<RelationOfImplementation>;
```

Defined in: [packages/graphql/src/relation.ts:371](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/relation.ts#L371)

Returns a map of types (unions or interfaces) where the GraphQL schema type is implemented.

### See

mapRelationOf

### Type Param

**T**

the type of the GraphQL schema type.

### Type Param

**R**

the return type of map of relations (see IGetRelation).

### Param

**type**

the GraphQL schema type being processed.

### Param

**schemaMap**

a GraphQL schema map (see getSchemaMap).

### Returns

a record map of unions or interfaces relations.

---

## getRelationOfInterface \{#getrelationofinterface\}

```ts
const getRelationOfInterface: IGetRelation<RelationOfInterface>;
```

Defined in: [packages/graphql/src/relation.ts:314](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/relation.ts#L314)

Returns a map of interfaces where the GraphQL schema type is extended.

### See

mapRelationOf

### Type Param

**T**

the type of the GraphQL schema type.

### Type Param

**R**

the return type of map of relations (see IGetRelation).

### Param

**type**

the GraphQL schema type being processed.

### Param

**schemaMap**

a GraphQL schema map (see getSchemaMap).

### Returns

a record map of interfaces relations.

---

## getRelationOfReturn \{#getrelationofreturn\}

```ts
const getRelationOfReturn: IGetRelation<GraphQLOperationType>;
```

Defined in: [packages/graphql/src/relation.ts:106](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/relation.ts#L106)

Returns a map of operations (queries, mutations, subscriptions) where the GraphQL schema type is the return type.

### See

mapRelationOf

### Type Param

**T**

the type of the GraphQL schema type.

### Type Param

**R**

the return type of map of relations (see IGetRelation).

### Param

**type**

the GraphQL schema type being processed.

### Param

**schemaMap**

a GraphQL schema map (see getSchemaMap).

### Returns

a record map of operations relations.

---

## getRelationOfUnion \{#getrelationofunion\}

```ts
const getRelationOfUnion: IGetRelation<GraphQLUnionType>;
```

Defined in: [packages/graphql/src/relation.ts:258](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/relation.ts#L258)

Returns a map of unions where the GraphQL schema type is part of it.

### See

mapRelationOf

### Type Param

**T**

the type of the GraphQL schema type.

### Type Param

**R**

the return type of map of relations (see IGetRelation).

### Param

**type**

the GraphQL schema type being processed.

### Param

**schemaMap**

a GraphQL schema map (see getSchemaMap).

### Returns

a record map of unions relations.

---

## descriptor

Custom directive `descriptor` helper.

## See

[Option `customDirective.[directive].descriptor`](https://graphql-markdown.dev/docs/advanced/custom-directive#descriptor)

## directiveDescriptor() \{#directivedescriptor\}

```ts
function directiveDescriptor(directive, type?, descriptionTemplate?): string;
```

Defined in: [directives/descriptor.ts:83](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/directives/descriptor.ts#L83)

Helper for rendering custom description from schema directive on type.
This is an example on how to build a custom `descriptor` callback.

### Parameters

#### directive

`GraphQLDirective`

the schema directive to parse.

#### type?

`unknown`

the schema type to be processed for generating a custom description.

#### descriptionTemplate?

`string`

optional template literal-like string for rendering the description (see [interpolate](../utils/interpolate.md#interpolate)), if not present then the directive description will be used.

### Returns

`string`

a custom description based on directive value.

### Example

```js
import { GraphQLDirective, GraphQLScalarType } from "graphql";
import { directiveDescriptor } from "@graphql-markdown/helpers/directives/descriptor";

const directive = new GraphQLDirective({
  name: "version",
  description: "Min version",
  locations: [],
  args: {
    major: { type: GraphQLInt, defaultValue: 0 },
    minor: { type: GraphQLInt, defaultValue: 0 },
    patch: { type: GraphQLInt, defaultValue: 0 },
  },
});

const type =
  new GraphQLScalarType() <
  string >
  {
    name: "FooBar",
    astNode: {
      kind: Kind.SCALAR_TYPE_DEFINITION,
      name: { kind: Kind.NAME, value: "FooBar" },
      directives: [
        {
          kind: Kind.DIRECTIVE,
          name: { kind: Kind.NAME, value: "version" },
          arguments: [
            {
              kind: Kind.ARGUMENT,
              name: { kind: Kind.NAME, value: "major" },
              value: { kind: Kind.INT, value: "2" },
            },
            {
              kind: Kind.ARGUMENT,
              name: { kind: Kind.NAME, value: "minor" },
              value: { kind: Kind.INT, value: "1" },
            },
            {
              kind: Kind.ARGUMENT,
              name: { kind: Kind.NAME, value: "patch" },
              value: { kind: Kind.INT, value: "3" },
            },
          ],
        },
      ],
    },
  };

directiveDescriptor(
  directive,
  type,
  "${description} is ${major}.${minor}.${patch}",
);
// Expected result: "Min version is 2.1.3"

directiveDescriptor(directive, type);
// Expected result: "Min version"

directiveDescriptor(
  directive,
  type,
  "Version should be at least ^${major}.${minor}.${patch}",
);
// Expected result: "Version should be at least ^2.1.3"
```

---

## tag

Custom directive `tag` helper.

## See

[Option `customDirective.[directive].tag`](https://graphql-markdown.dev/docs/advanced/custom-directive#tag)

## directiveTag() \{#directivetag\}

```ts
function directiveTag(directive, type?, classname?): Badge;
```

Defined in: [directives/tag.ts:51](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/directives/tag.ts#L51)

Helper for rendering custom description from schema directive on type.
This is an example on how to build a custom `tag` callback.

### Parameters

#### directive

`GraphQLDirective`

the schema directive to parse.

#### type?

`unknown`

the type being processed.

#### classname?

`string` = `"badge--secondary"`

optional CSS classname, `"badge--secondary"` by default.

### Returns

`Badge`

a custom description based on directive value.

### Example

```js
import { GraphQLDirective, GraphQLScalarType } from "graphql";
import { directiveTag } from "@graphql-markdown/helpers/directives/tag";

const directive = new GraphQLDirective({
  name: "auth",
  description: "Authentication required",
  locations: [],
});

const type =
  new GraphQLScalarType() <
  string >
  {
    name: "FooBar",
    astNode: {
      kind: Kind.SCALAR_TYPE_DEFINITION,
      name: { kind: Kind.NAME, value: "FooBar" },
      directives: [
        {
          kind: Kind.DIRECTIVE,
          name: { kind: Kind.NAME, value: "auth" },
        },
      ],
    },
  };

directiveTag(directive, type);
// Expected result: { text: "@auth", classname: "badge--secondary" }
```

---

## markdown

Shared markdown-oriented helpers used by formatter presets.

## appendExtensionToAbsolutePathWithoutExtension() \{#appendextensiontoabsolutepathwithoutextension\}

```ts
function appendExtensionToAbsolutePathWithoutExtension(url, extension): string;
```

Defined in: [formatters/markdown.ts:159](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/formatters/markdown.ts#L159)

Appends an extension only when URL is an absolute path without a file extension.

Fragment-only and already suffixed paths are returned unchanged.

### Parameters

#### url

`string`

Link URL to evaluate.

#### extension

`string`

Extension suffix to append when eligible.

### Returns

`string`

Updated or original URL depending on path shape.

---

## appendLinkExtension() \{#appendlinkextension\}

```ts
function appendLinkExtension(url, extension): string;
```

Defined in: [formatters/markdown.ts:146](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/formatters/markdown.ts#L146)

Appends an extension to a link URL.

### Parameters

#### url

`string`

Link URL to update.

#### extension

`string`

Extension suffix (for example `.mdx`).

### Returns

`string`

URL with appended extension.

---

## extractFrontmatterTitle() \{#extractfrontmattertitle\}

```ts
function extractFrontmatterTitle(formatted): string;
```

Defined in: [formatters/markdown.ts:64](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/formatters/markdown.ts#L64)

Extracts a title value from pre-formatted frontmatter lines.

### Parameters

#### formatted

`string`[] \| `null` \| `undefined`

Serialized frontmatter lines without delimiters.

### Returns

`string`

Parsed title value, or an empty string when no `title:` line exists.

---

## formatMarkdownFrontmatter() \{#formatmarkdownfrontmatter\}

```ts
function formatMarkdownFrontmatter(formatted, delimiter?, eol?): string;
```

Defined in: [formatters/markdown.ts:127](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/formatters/markdown.ts#L127)

Formats a markdown frontmatter block from preformatted lines.

### Parameters

#### formatted

`string`[] \| `null` \| `undefined`

Serialized frontmatter lines without delimiters.

#### delimiter?

`string` = `"---"`

Frontmatter delimiter marker.

#### eol?

`string` = "\n"

End-of-line separator.

### Returns

`string`

Complete frontmatter block or an empty string when input is absent.

---

## indentMarkdownLines() \{#indentmarkdownlines\}

```ts
function indentMarkdownLines(text, spaces, eol?): string;
```

Defined in: [formatters/markdown.ts:178](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/formatters/markdown.ts#L178)

Indents non-empty markdown lines by a fixed amount of spaces.

### Parameters

#### text

`string`

Multiline markdown block to indent.

#### spaces

`number`

Number of spaces to prepend to non-empty lines.

#### eol?

`string` = "\n"

Line separator used to split and join lines.

### Returns

`string`

Indented multiline string.

---

## mergeFrontmatterLines() \{#mergefrontmatterlines\}

```ts
function mergeFrontmatterLines(props, formatted): string[];
```

Defined in: [formatters/markdown.ts:84](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/formatters/markdown.ts#L84)

Merges frontmatter object entries with preformatted frontmatter lines.

Preformatted lines take precedence over object values when keys overlap.
Lines without a `key: value` shape and comment lines are ignored.

### Parameters

#### props

`Record`&lt;`string`, `unknown`&gt; \| `null` \| `undefined`

Frontmatter key-value object.

#### formatted

`string`[] \| `null` \| `undefined`

Serialized frontmatter lines without delimiters.

### Returns

`string`[]

Merged frontmatter lines in insertion order.

---

## parseFrontmatterTitleLine() \{#parsefrontmattertitleline\}

```ts
function parseFrontmatterTitleLine(line): string;
```

Defined in: [formatters/markdown.ts:34](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/formatters/markdown.ts#L34)

Parses a YAML-like frontmatter title line and returns its string value.

Accepts unquoted values (`title: My Title`) and quoted values
(`title: "My Title"` or `title: 'My Title'`).

### Parameters

#### line

`string`

Candidate frontmatter line.

### Returns

`string`

Parsed title value, or an empty string when the line is not a title.

---

## quoteMarkdownLines() \{#quotemarkdownlines\}

```ts
function quoteMarkdownLines(text, eol?): string;
```

Defined in: [formatters/markdown.ts:16](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/formatters/markdown.ts#L16)

Prefixes each line with a Markdown blockquote marker.

### Parameters

#### text

`string`

Multiline text to transform into blockquote content.

#### eol?

`string` = "\n"

Line separator used to split and join lines.

### Returns

`string`

Text where every line starts with `> `.

---

## interpolate

Helpers utility functions library.

## getObjPath() \{#getobjpath\}

```ts
function getObjPath(path, obj, fallback?): unknown;
```

Defined in: [utils/interpolate.ts:31](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/utils/interpolate.ts#L31)

**`Internal`**

Returns the value of the specified property or nested property of an object using a string path.

### Parameters

#### path

`Maybe`&lt;`string`&gt;

property path as string.

#### obj

`unknown`

the key/value record object.

#### fallback?

`unknown` = `""`

optional fallback value to be returned if the path cannot be resolved.

### Returns

`unknown`

the property value if the path is resolved, else returns the `fallback` value.

### Example

```js
import { getObjPath } from "@graphql-markdown/utils/object";

getObjPath("foo.bar", { foo: { bar: 42 } }); // Returns 42

getObjPath("foo.bak", { foo: { bar: 42 } }, "fallback"); // Returns "fallback"
```

---

## interpolate() \{#interpolate\}

```ts
function interpolate(template, variables, fallback?): string;
```

Defined in: [utils/interpolate.ts:64](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/helpers/src/utils/interpolate.ts#L64)

Interpolate a template literal-like string.

### Parameters

#### template

`string`

a string template literal-like.

#### variables

`Maybe`&lt;`Record`&lt;`string`, `unknown`&gt; & `object`&gt;

a record map of values with variable's name as key and `description` as directive's description.

#### fallback?

`string`

optional fallback value if a variable cannot be substituted.

### Returns

`string`

an interpolated new string from the template.

### Example

```js
const values = { foo: 42, bar: { value: "test" } };
const template = "${foo} is not ${bar.notfound}";

interpolate(template, values, "fallback"); // Expected result: "42 is not fallback",
```

---

## API


This section provides documentation of the GraphQL-Markdown API for NodeJS. For more details about each individual module, refer to the specific package documentation below.

## Packages

GraphQL-Markdown is organized into several packages:

- [@graphql-markdown/cli](/api/category/graphql-markdowncli/) - Command-line interface for generating documentation
- [@graphql-markdown/core](/api/category/graphql-markdowncore/) - Core functionality and base classes
- [@graphql-markdown/docusaurus](/api/category/graphql-markdowndocusaurus/) - Docusaurus plugin integration
- [@graphql-markdown/formatters](/api/category/graphql-markdownformatters/) - Formatter presets for all supported documentation frameworks
- [@graphql-markdown/graphql](/api/category/graphql-markdowngraphql/) - GraphQL schema utilities and helpers
- [@graphql-markdown/helpers](/api/category/graphql-markdownhelpers/) - Helper functions for documentation generation
- [@graphql-markdown/printer-legacy](/api/category/graphql-markdownprinter-legacy/) - Legacy markdown printer implementation
- [@graphql-markdown/utils](/api/category/graphql-markdownutils/) - Utility functions and helpers

## Installation

```bash
npm install @graphql-markdown/cli
# or with your preferred package manager
yarn add @graphql-markdown/cli
```

If you are targeting a formatter-based documentation stack such as Hugo, MkDocs, DocFX, or mdBook, also install `@graphql-markdown/formatters` and configure the `formatter` option.

## Basic Usage

Using the CLI:

```bash
graphql-markdown --schema ./schema.graphql --root ./docs
```

For programmatic usage, you can use the CLI package:

```typescript
import { runGraphQLMarkdown } from "@graphql-markdown/cli";

const config = {
  schema: "./schema.graphql",
  rootPath: "./docs",
};

await runGraphQLMarkdown(config);
```

## Contributing

This documentation is intended primarily for those interested in:

- Contributing to the GraphQL-Markdown codebase
- Developing custom documentation generators
- Extending the base functionality
- Understanding the internal architecture

---

## logger

Logger singleton module.

## LogLevel \{#loglevel\}

Defined in: [index.ts:23](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/logger/src/index.ts#L23)

Log levels supported by the logger.

### Remarks

The logger supports standard console methods plus custom 'success' level
for framework-specific integrations like Docusaurus.

### Enumeration Members

#### debug \{#debug\}

```ts
debug: "debug";
```

Defined in: [index.ts:24](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/logger/src/index.ts#L24)

#### error \{#error\}

```ts
error: "error";
```

Defined in: [index.ts:25](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/logger/src/index.ts#L25)

#### info \{#info\}

```ts
info: "info";
```

Defined in: [index.ts:26](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/logger/src/index.ts#L26)

#### log \{#log\}

```ts
log: "log";
```

Defined in: [index.ts:27](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/logger/src/index.ts#L27)

#### success \{#success\}

```ts
success: "success";
```

Defined in: [index.ts:28](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/logger/src/index.ts#L28)

#### warn \{#warn\}

```ts
warn: "warn";
```

Defined in: [index.ts:29](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/logger/src/index.ts#L29)

---

## \_\_internal \{#\_\_internal\}

```ts
const __internal: object;
```

Defined in: [index.ts:183](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/logger/src/index.ts#L183)

**`Internal`**

Internal helpers exported for testing purposes only.
Not part of the public API — do not use in application code.

### Type Declaration

#### hasLogMethod \{#haslogmethod\}

```ts
hasLogMethod: (instance, level) => instance is Record<string, (args: unknown[]) => unknown>;
```

Type guard to check if an object has a log method for a given level.

##### Parameters

###### instance

`unknown`

The object to check

###### level

\| `"debug"`
\| `"error"`
\| `"info"`
\| `"log"`
\| `"success"`
\| `"warn"`
\| [`LogLevel`](#loglevel)

The log level to verify

##### Returns

`instance is Record<string, (args: unknown[]) => unknown>`

`true` if the instance has a function at the given level, `false` otherwise

#### resolveLoggerInstance \{#resolveloggerinstance\}

```ts
resolveLoggerInstance: (instance) =>
  | Partial<Record<LogLevel, (...unknown) => void>>
  | undefined;
```

Resolve a logger instance from a module export.

##### Parameters

###### instance

`unknown`

The module export or object to resolve

##### Returns

\| `Partial`&lt;`Record`&lt;`LogLevel`, (...`unknown`) => `void`&gt;&gt;
\| `undefined`

The logger instance if found, or `undefined` if no valid logger is detected (the caller is responsible for falling back to `globalThis.console`)

##### Remarks

Handles various module export patterns:

- Direct logger instance: `{ info: () => {}, ... }`
- Default export: `{ default: { info: () => {}, ... } }`
- Named export: `{ logger: { info: () => {}, ... } }`

---

## log() \{#log-1\}

```ts
function log(message, level?): void;
```

Defined in: [index.ts:168](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/logger/src/index.ts#L168)

Logs a message by calling the active logger instance.

### Parameters

#### message

`string`

a string to be logged.

#### level?

\| `"debug"`
\| `"error"`
\| `"info"`
\| `"log"`
\| `"success"`
\| `"warn"`
\| [`LogLevel`](#loglevel)

optional log level, `"info"` by default.

### Returns

`void`

### Remarks

If a log level is not supported by the logger instance, then it defaults to `"info"`.

### Example

```js
import { log } from "@graphql-markdown/logger";

log("Info message"); // Expected console output "Info message"
```

---

## Logger() \{#logger\}

```ts
function Logger(moduleName?): Promise<void>;
```

Defined in: [index.ts:111](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/logger/src/index.ts#L111)

Instantiate a logger module.
By default, the logger module uses `globalThis.console`

### Parameters

#### moduleName?

`string`

optional name of the logger package.

### Returns

`Promise`&lt;`void`&gt;

### Example

```js
import Logger, { log } from "@graphql-markdown/logger";

log("Info message"); // Expected console output "Info message"

Logger("@docusaurus/logger");
log("Info message", "info"); // Expected Docusaurus log output "Info message"
```

---

## badge

Module for handling GraphQL type badges in MDX documentation.
Provides functionality to generate and format badges for different GraphQL types
and their properties like deprecation status, nullability, and relationships.

## CSS_BADGE_CLASSNAME \{#css_badge_classname\}

```ts
const CSS_BADGE_CLASSNAME: object;
```

Defined in: [printer-legacy/src/badge.ts:32](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/badge.ts#L32)

### Type Declaration

#### DEPRECATED \{#deprecated\}

```ts
DEPRECATED: string = "DEPRECATED";
```

#### NON_NULL \{#non_null\}

```ts
NON_NULL: string = "NON_NULL";
```

#### RELATION \{#relation\}

```ts
RELATION: string = "RELATION";
```

---

## formatBadges() \{#formatbadges\}

```ts
function formatBadges(badges, options): string | MDXString;
```

Defined in: [printer-legacy/src/badge.ts:120](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/badge.ts#L120)

Formats an array of badges into a space-joined MDX string.

### Parameters

#### badges

`Badge`[]

Array of badge objects to format

#### options

`PrintTypeOptions`

Options containing the formatter for badges

### Returns

`string` \| `MDXString`

Space-joined MDX string of all badges, or empty string if none

---

## getTypeBadges() \{#gettypebadges\}

```ts
function getTypeBadges(type, groups?): Badge[];
```

Defined in: [printer-legacy/src/badge.ts:45](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/badge.ts#L45)

Gets an array of badges for a given GraphQL type.

### Parameters

#### type

`unknown`

The GraphQL type to generate badges for

#### groups?

`Maybe`&lt;`Partial`&lt;`Record`&lt;`SchemaEntity`, `Record`&lt;`string`, `Maybe`&lt;`string`&gt;&gt;&gt;&gt;&gt;

Optional map of schema entities to their groups

### Returns

`Badge`[]

Array of Badge objects containing text and optional classnames

---

## printBadge() \{#printbadge\}

```ts
function printBadge(badge, options): MDXString;
```

Defined in: [printer-legacy/src/badge.ts:98](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/badge.ts#L98)

Formats a single badge into MDX string format.

### Parameters

#### badge

`Badge`

The badge object containing text and optional classname

#### options

`PrintTypeOptions`

Options containing the formatter for badges

### Returns

`MDXString`

Formatted MDX string representation of the badge

---

## printBadges() \{#printbadges\}

```ts
function printBadges(type, options): string | MDXString;
```

Defined in: [printer-legacy/src/badge.ts:140](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/badge.ts#L140)

Generates and formats all applicable badges for a GraphQL type.

### Parameters

#### type

`unknown`

The GraphQL type to generate badges for

#### options

`PrintTypeOptions`

Options for printing/formatting the badges

### Returns

`string` \| `MDXString`

Formatted MDX string containing all badges, or empty string if no badges or badges disabled

---

## code

Provides utility functions for generating code representations of GraphQL types
in Markdown format. This module handles the formatting of arguments and fields
with proper indentation and deprecation notices.

## printCodeArguments() \{#printcodearguments\}

```ts
function printCodeArguments(type, indentationLevel?): string;
```

Defined in: [printer-legacy/src/code.ts:41](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/code.ts#L41)

Generates a string representation of GraphQL arguments with proper formatting and indentation.

### Parameters

#### type

`unknown`

The GraphQL type object containing arguments to print

#### indentationLevel?

`number` = `1`

The level of indentation to apply (default: 1)

### Returns

`string`

A formatted string of arguments or an empty string if no arguments exist

### Example

```
printCodeArguments({ args: [{ name: 'id', type: 'ID!' }] })
// Returns:
// (
//   id: ID!
// )
```

---

## printCodeField() \{#printcodefield\}

```ts
function printCodeField(type, options?, indentationLevel?): string | MDXString;
```

Defined in: [printer-legacy/src/code.ts:87](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/code.ts#L87)

Generates a string representation of a GraphQL field including its arguments,
return type, and deprecation status.

### Parameters

#### type

`unknown`

The GraphQL field type object to print

#### options?

`PrintTypeOptions`

Optional configuration for printing the type

#### indentationLevel?

`number` = `0`

The level of indentation to apply (default: 0)

### Returns

`string` \| `MDXString`

A formatted string representing the field or an empty string if the field should not be printed

### Example

```
printCodeField({ name: 'user', type: 'User!', args: [{ name: 'id', type: 'ID!' }] })
// Returns: user(
//   id: ID!
// ): User!
```

---

## common

Common printer utility functions for handling descriptions, directives, and warnings.

## getCustomDirectivesText() \{#getcustomdirectivestext\}

```ts
function getCustomDirectivesText(type, options?): string;
```

Defined in: [printer-legacy/src/common.ts:34](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/common.ts#L34)

Prints documentation for custom directives applied to a type.

### Parameters

#### type

`unknown`

GraphQL type to get directives from

#### options?

`PrintTypeOptions`

Printer configuration options

### Returns

`string`

Formatted directive documentation string

---

## printDeprecation() \{#printdeprecation\}

```ts
function printDeprecation(type, options): string;
```

Defined in: [printer-legacy/src/common.ts:117](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/common.ts#L117)

Prints deprecation information for a GraphQL type if it is deprecated.

### Parameters

#### type

`unknown`

The GraphQL type to check for deprecation

#### options

`PrintTypeOptions`

Configuration options for printing

### Returns

`string`

Formatted deprecation warning as MDX string, or empty string if not deprecated

---

## printDescription() \{#printdescription\}

```ts
function printDescription(type, options, noText?): string | MDXString;
```

Defined in: [printer-legacy/src/common.ts:143](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/common.ts#L143)

Prints the complete description for a GraphQL type, including deprecation warnings and custom directives.

### Parameters

#### type

`unknown`

The GraphQL type to document

#### options

`PrintTypeOptions`

Configuration options for printing

#### noText?

`string`

Optional text to display when no description exists

### Returns

`string` \| `MDXString`

Combined description, deprecation notices, and custom directives as MDX content

---

## printWarning() \{#printwarning\}

```ts
function printWarning(warningConfig, options): string;
```

Defined in: [printer-legacy/src/common.ts:95](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/common.ts#L95)

Generates a warning message block in MDX format.

### Parameters

#### warningConfig

Warning configuration object with `text` and optional `title` properties

##### text?

`string`

##### title?

`string`

#### options

`PrintTypeOptions`

Configuration options for printing

### Returns

`string`

Formatted warning message as MDX string

---

## options

## SectionLevels \{#sectionlevels\}

Defined in: [printer-legacy/src/const/options.ts:31](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/options.ts#L31)

### Enumeration Members

#### LEVEL \{#level\}

```ts
LEVEL: "#";
```

Defined in: [printer-legacy/src/const/options.ts:37](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/options.ts#L37)

#### ~~NONE~~ \{#none\}

```ts
NONE: "";
```

Defined in: [printer-legacy/src/const/options.ts:36](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/options.ts#L36)

##### Deprecated

Use `SectionLevels.LEVEL` instead.

---

## TypeHierarchy \{#typehierarchy\}

Defined in: [printer-legacy/src/const/options.ts:24](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/options.ts#L24)

### Enumeration Members

#### API \{#api\}

```ts
API: "api";
```

Defined in: [printer-legacy/src/const/options.ts:25](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/options.ts#L25)

#### ENTITY \{#entity\}

```ts
ENTITY: "entity";
```

Defined in: [printer-legacy/src/const/options.ts:27](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/options.ts#L27)

#### FLAT \{#flat\}

```ts
FLAT: "flat";
```

Defined in: [printer-legacy/src/const/options.ts:28](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/options.ts#L28)

---

## DEFAULT_OPTIONS \{#default_options\}

```ts
const DEFAULT_OPTIONS: Required<
  Omit<
    PrintTypeOptions,
    | "collapsible"
    | "exampleSection"
    | "formatCategoryFolderName"
    | "groups"
    | "level"
    | "meta"
    | "onlyDocDirectives"
    | "parentType"
    | "schema"
    | "skipDocDirectives"
  >
> &
  object;
```

Defined in: [printer-legacy/src/const/options.ts:56](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/options.ts#L56)

Clean runtime options passed through the printer.

### Type Declaration

#### collapsible

```ts
collapsible: Maybe<CollapsibleOption>;
```

#### exampleSection

```ts
exampleSection: PrintTypeOptions["exampleSection"];
```

#### groups

```ts
groups: Maybe<SchemaEntitiesGroupMap>;
```

#### level

```ts
level: Maybe<SectionLevelValue>;
```

#### onlyDocDirectives

```ts
onlyDocDirectives: GraphQLDirective[];
```

#### parentType

```ts
parentType: Maybe<string>;
```

#### schema

```ts
schema: Maybe<GraphQLSchema>;
```

#### skipDocDirectives

```ts
skipDocDirectives: GraphQLDirective[];
```

---

## PRINT_TYPE_DEFAULT_OPTIONS \{#print_type_default_options\}

```ts
const PRINT_TYPE_DEFAULT_OPTIONS: Required<
  Omit<PrinterConfigPrintTypeOptions, "exampleSection">
> &
  object;
```

Defined in: [printer-legacy/src/const/options.ts:40](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/options.ts#L40)

### Type Declaration

#### exampleSection

```ts
exampleSection: PrintTypeOptions["exampleSection"];
```

---

## strings

String constants and helpers shared by the legacy printer when composing
Markdown fragments for GraphQL schemas.

## DEPRECATED \{#deprecated\}

```ts
const DEPRECATED: "deprecated";
```

Defined in: [printer-legacy/src/const/strings.ts:34](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/strings.ts#L34)

Label used when a schema element is flagged as deprecated.

---

## MARKDOWN_CODE_INDENTATION \{#markdown_code_indentation\}

```ts
const MARKDOWN_CODE_INDENTATION: "  ";
```

Defined in: utils/dist/markdown.d.ts:25

Standard indentation for code blocks (2 spaces).

---

## MARKDOWN_EOC \{#markdown_eoc\}

```ts
const MARKDOWN_EOC: "\n``\n";
```

Defined in: [printer-legacy/src/const/strings.ts:46](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/strings.ts#L46)

Helper for inserting the code-block end delimiter in generated Markdown.

---

## MARKDOWN_EOL \{#markdown_eol\}

```ts
const MARKDOWN_EOL: "\n";
```

Defined in: utils/dist/markdown.d.ts:9

End of line character for Markdown.

---

## MARKDOWN_EOP \{#markdown_eop\}

```ts
const MARKDOWN_EOP: string;
```

Defined in: utils/dist/markdown.d.ts:13

End of paragraph (double newline) for Markdown.

---

## MARKDOWN_SOC \{#markdown_soc\}

```ts
const MARKDOWN_SOC: "\n``graphql\n";
```

Defined in: [printer-legacy/src/const/strings.ts:50](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/strings.ts#L50)

Helper for inserting the code-block start delimiter targeting GraphQL syntax.

---

## NO_DESCRIPTION_TEXT \{#no_description_text\}

```ts
const NO_DESCRIPTION_TEXT: "No description";
```

Defined in: [printer-legacy/src/const/strings.ts:43](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/strings.ts#L43)

Default placeholder when no schema description is provided.

---

## NON_NULL \{#non_null\}

```ts
const NON_NULL: "non-null";
```

Defined in: [printer-legacy/src/const/strings.ts:37](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/strings.ts#L37)

Copy fragment describing a non-null GraphQL modifier.

---

## ROOT_TYPE_LOCALE \{#root_type_locale\}

```ts
const ROOT_TYPE_LOCALE: RootTypeLocale;
```

Defined in: [printer-legacy/src/const/strings.ts:19](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/const/strings.ts#L19)

Human-readable labels for each GraphQL root type used when rendering copy or badges.

---

## directive(Printer-legacy)

Provides utilities for handling and printing GraphQL directives in Markdown format

## getCustomDirectiveResolver() \{#getcustomdirectiveresolver\}

```ts
function getCustomDirectiveResolver(
  resolver,
  type,
  constDirectiveOption,
  fallback?,
): Maybe<string>;
```

Defined in: [printer-legacy/src/directive.ts:31](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/directive.ts#L31)

Resolves a custom directive using the provided resolver function

### Parameters

#### resolver

`CustomDirectiveResolver`

The resolver function name to execute

#### type

`unknown`

The GraphQL type to resolve the directive for

#### constDirectiveOption

`CustomDirectiveMapItem`

The directive configuration options

#### fallback?

`Maybe`&lt;`string`&gt;

Optional fallback value if resolution fails

### Returns

`Maybe`&lt;`string`&gt;

The resolved directive value or `fallback`/`undefined`

---

## getCustomTags() \{#getcustomtags\}

```ts
function getCustomTags(type, options): Badge[];
```

Defined in: [printer-legacy/src/directive.ts:127](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/directive.ts#L127)

Extracts custom tags from directives for a given type

### Parameters

#### type

`unknown`

The GraphQL type to get tags for

#### options

`PrintTypeOptions`

General printing options

### Returns

`Badge`[]

Array of badge configurations from directive tags

---

## printCustomDirective() \{#printcustomdirective\}

```ts
function printCustomDirective(
  type,
  constDirectiveOption,
  options,
): Maybe<string>;
```

Defined in: [printer-legacy/src/directive.ts:58](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/directive.ts#L58)

Prints a custom directive as a Markdown string

### Parameters

#### type

`unknown`

The GraphQL type to print the directive for

#### constDirectiveOption

`CustomDirectiveMapItem`

The directive configuration options

#### options

`PrintTypeOptions`

General printing options

### Returns

`Maybe`&lt;`string`&gt;

Formatted Markdown string for the directive or `undefined`

---

## printCustomDirectives() \{#printcustomdirectives\}

```ts
function printCustomDirectives(type, options): Maybe<PageSection>;
```

Defined in: [printer-legacy/src/directive.ts:86](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/directive.ts#L86)

Prints all custom directives for a type as a Markdown section

### Parameters

#### type

`unknown`

The GraphQL type to print directives for

#### options

`PrintTypeOptions`

General printing options

### Returns

`Maybe`&lt;[`PageSection`](events.md#pagesection)&gt;

A "Directives" PageSection, or undefined when no directives are printable

---

## printCustomTags() \{#printcustomtags\}

```ts
function printCustomTags(type, options): string | MDXString;
```

Defined in: [printer-legacy/src/directive.ts:159](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/directive.ts#L159)

Prints custom directive tags as Markdown badges

### Parameters

#### type

`unknown`

The GraphQL type to print tags for

#### options

`PrintTypeOptions`

General printing options

### Returns

`string` \| `MDXString`

Formatted Markdown string of badges or empty string

---

## events(Printer-legacy)

Print type event classes.

Event classes for print operations that allow handlers to modify the generated output.

## Events

### BeforeComposePageTypeEvent \{#beforecomposepagetypeevent\}

Defined in: [printer-legacy/src/events.ts:114](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/events.ts#L114)

Event emitted before composing page sections for a GraphQL type.

This event fires after section content is generated and before sections are joined into final output.
The `output` property contains an array of content section keys that will be included in the final page,
in addition to fixed header sections (`header`, `metatags`, `mdxDeclaration`) which are managed separately
by the printer and always prepended. Handlers can reorder, filter, or append to this array to control the
structure of the content portion of the page.

#### Example

```typescript
events.on(
  PrintTypeEvents.BEFORE_COMPOSE_PAGE_TYPE,
  (event: BeforeComposePageTypeEvent) => {
    // Move relations section before metadata
    const idx = event.output.indexOf("relations");
    if (idx > -1) {
      event.output.splice(idx, 1);
      const metaidx = event.output.indexOf("metadata");
      event.output.splice(metaidx, 0, "relations");
    }
  },
);
```

#### Extends

- [`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent)&lt;[`ComposePageTypeEventData`](#composepagetypeeventdata), keyof [`PageSections`](#pagesections)[]&gt;

#### Constructors

##### Constructor

```ts
new BeforeComposePageTypeEvent(
   data,
   initialOutput,
   options?
): BeforeComposePageTypeEvent;
```

Defined in: [printer-legacy/src/events.ts:118](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/events.ts#L118)

###### Parameters

###### data

[`ComposePageTypeEventData`](#composepagetypeeventdata)

###### initialOutput

keyof [`PageSections`](#pagesections)[]

###### options?

[`CancellableEventOptions`](../utils/events.md#cancellableeventoptions)

###### Returns

[`BeforeComposePageTypeEvent`](#beforecomposepagetypeevent)

###### Overrides

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`constructor`](../utils/events.md#constructor-2)

#### Properties

##### data \{#data\}

```ts
readonly data: ComposePageTypeEventData;
```

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`data`](../utils/events.md#data-1)

##### output \{#output\}

```ts
output: keyof PageSections[];
```

Defined in: utils/dist/events.d.ts:127

The generated output.
Handlers can modify this property to change the final result.

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`output`](../utils/events.md#output)

#### Accessors

##### defaultAction \{#defaultaction\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: utils/dist/events.d.ts:78

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`defaultAction`](../utils/events.md#defaultaction-2)

##### defaultPrevented \{#defaultprevented\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: utils/dist/events.d.ts:82

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`defaultPrevented`](../utils/events.md#defaultprevented-2)

##### propagationStopped \{#propagationstopped\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: utils/dist/events.d.ts:86

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`propagationStopped`](../utils/events.md#propagationstopped-2)

#### Methods

##### preventDefault() \{#preventdefault\}

```ts
preventDefault(): void;
```

Defined in: utils/dist/events.d.ts:91

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`preventDefault`](../utils/events.md#preventdefault-2)

##### runDefaultAction() \{#rundefaultaction\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: utils/dist/events.d.ts:100

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`runDefaultAction`](../utils/events.md#rundefaultaction-2)

##### stopPropagation() \{#stoppropagation\}

```ts
stopPropagation(): void;
```

Defined in: utils/dist/events.d.ts:96

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`stopPropagation`](../utils/events.md#stoppropagation-2)

---

### PrintCodeEvent \{#printcodeevent\}

Defined in: [printer-legacy/src/events.ts:48](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/events.ts#L48)

Event emitted around code block generation for a GraphQL type.

The `output` property is mutable, allowing event handlers to modify
the generated code before it's included in the documentation.

#### Example

```typescript
events.on(PrintTypeEvents.AFTER_PRINT_CODE, (event: PrintCodeEvent) => {
  // Add a comment to all generated code
  event.output = `# Auto-generated\n${event.output}`;
});
```

#### Extends

- [`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent)&lt;[`PrintCodeEventData`](#printcodeeventdata-1), `string`&gt;

#### Implements

- `IPrintCodeEvent`

#### Constructors

##### Constructor

```ts
new PrintCodeEvent(
   data,
   initialOutput,
   options?
): PrintCodeEvent;
```

Defined in: [printer-legacy/src/events.ts:52](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/events.ts#L52)

###### Parameters

###### data

[`PrintCodeEventData`](#printcodeeventdata-1)

###### initialOutput

`string`

###### options?

[`CancellableEventOptions`](../utils/events.md#cancellableeventoptions)

###### Returns

[`PrintCodeEvent`](#printcodeevent)

###### Overrides

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`constructor`](../utils/events.md#constructor-2)

#### Properties

##### data \{#data-1\}

```ts
readonly data: PrintCodeEventData;
```

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

###### Implementation of

```ts
IPrintCodeEvent.data;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`data`](../utils/events.md#data-1)

##### output \{#output-1\}

```ts
output: string;
```

Defined in: utils/dist/events.d.ts:127

The generated output.
Handlers can modify this property to change the final result.

###### Implementation of

```ts
IPrintCodeEvent.output;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`output`](../utils/events.md#output)

#### Accessors

##### defaultAction \{#defaultaction-1\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: utils/dist/events.d.ts:78

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Implementation of

```ts
IPrintCodeEvent.defaultAction;
```

###### Inherited from

[`PrintTypeEvent`](#printtypeevent).[`defaultAction`](#defaultaction-2)

##### defaultPrevented \{#defaultprevented-1\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: utils/dist/events.d.ts:82

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Implementation of

```ts
IPrintCodeEvent.defaultPrevented;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`defaultPrevented`](../utils/events.md#defaultprevented-2)

##### propagationStopped \{#propagationstopped-1\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: utils/dist/events.d.ts:86

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Implementation of

```ts
IPrintCodeEvent.propagationStopped;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`propagationStopped`](../utils/events.md#propagationstopped-2)

#### Methods

##### preventDefault() \{#preventdefault-1\}

```ts
preventDefault(): void;
```

Defined in: utils/dist/events.d.ts:91

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Implementation of

```ts
IPrintCodeEvent.preventDefault;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`preventDefault`](../utils/events.md#preventdefault-2)

##### runDefaultAction() \{#rundefaultaction-1\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: utils/dist/events.d.ts:100

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Implementation of

```ts
IPrintCodeEvent.runDefaultAction;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`runDefaultAction`](../utils/events.md#rundefaultaction-2)

##### stopPropagation() \{#stoppropagation-1\}

```ts
stopPropagation(): void;
```

Defined in: utils/dist/events.d.ts:96

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Implementation of

```ts
IPrintCodeEvent.stopPropagation;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`stopPropagation`](../utils/events.md#stoppropagation-2)

---

### PrintTypeEvent \{#printtypeevent\}

Defined in: [printer-legacy/src/events.ts:77](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/events.ts#L77)

Event emitted around full documentation generation for a GraphQL type.

The `output` property is mutable, allowing event handlers to modify
the complete generated documentation.

#### Example

```typescript
events.on(PrintTypeEvents.AFTER_PRINT_TYPE, (event: PrintTypeEvent) => {
  // Add a footer to all type documentation
  event.output = `${event.output}\n\n---\nGenerated by GraphQL-Markdown`;
});
```

#### Extends

- [`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent)&lt;[`PrintTypeEventData`](#printtypeeventdata-1), `Maybe`&lt;`MDXString`&gt;&gt;

#### Implements

- `IPrintTypeEvent`

#### Constructors

##### Constructor

```ts
new PrintTypeEvent(
   data,
   initialOutput,
   options?
): PrintTypeEvent;
```

Defined in: [printer-legacy/src/events.ts:81](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/events.ts#L81)

###### Parameters

###### data

[`PrintTypeEventData`](#printtypeeventdata-1)

###### initialOutput

`Maybe`&lt;`MDXString`&gt;

###### options?

[`CancellableEventOptions`](../utils/events.md#cancellableeventoptions)

###### Returns

[`PrintTypeEvent`](#printtypeevent)

###### Overrides

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`constructor`](../utils/events.md#constructor-2)

#### Properties

##### data \{#data-2\}

```ts
readonly data: PrintTypeEventData;
```

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

###### Implementation of

```ts
IPrintTypeEvent.data;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`data`](../utils/events.md#data-1)

##### output \{#output-2\}

```ts
output: Maybe;
```

Defined in: utils/dist/events.d.ts:127

The generated output.
Handlers can modify this property to change the final result.

###### Implementation of

```ts
IPrintTypeEvent.output;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`output`](../utils/events.md#output)

#### Accessors

##### defaultAction \{#defaultaction-2\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: utils/dist/events.d.ts:78

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Implementation of

```ts
IPrintTypeEvent.defaultAction;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`defaultAction`](../utils/events.md#defaultaction-2)

##### defaultPrevented \{#defaultprevented-2\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: utils/dist/events.d.ts:82

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Implementation of

```ts
IPrintTypeEvent.defaultPrevented;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`defaultPrevented`](../utils/events.md#defaultprevented-2)

##### propagationStopped \{#propagationstopped-2\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: utils/dist/events.d.ts:86

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Implementation of

```ts
IPrintTypeEvent.propagationStopped;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`propagationStopped`](../utils/events.md#propagationstopped-2)

#### Methods

##### preventDefault() \{#preventdefault-2\}

```ts
preventDefault(): void;
```

Defined in: utils/dist/events.d.ts:91

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Implementation of

```ts
IPrintTypeEvent.preventDefault;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`preventDefault`](../utils/events.md#preventdefault-2)

##### runDefaultAction() \{#rundefaultaction-2\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: utils/dist/events.d.ts:100

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Implementation of

```ts
IPrintTypeEvent.runDefaultAction;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`runDefaultAction`](../utils/events.md#rundefaultaction-2)

##### stopPropagation() \{#stoppropagation-2\}

```ts
stopPropagation(): void;
```

Defined in: utils/dist/events.d.ts:96

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Implementation of

```ts
IPrintTypeEvent.stopPropagation;
```

###### Inherited from

[`DataOutputEvent`](../utils/events.md#abstract-dataoutputevent).[`stopPropagation`](../utils/events.md#stoppropagation-2)

## Other

### ComposePageTypeEventData \{#composepagetypeeventdata\}

Defined in: [types/src/printer.d.ts:109](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L109)

Data payload for compose page type events.

#### Properties

##### name \{#name\}

```ts
readonly name: Maybe<string>;
```

Defined in: [types/src/printer.d.ts:113](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L113)

The name identifier for the type

##### options \{#options\}

```ts
readonly options: PrintTypeOptions;
```

Defined in: [types/src/printer.d.ts:115](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L115)

The print options in effect

##### sections \{#sections\}

```ts
readonly sections: PageSections;
```

Defined in: [types/src/printer.d.ts:117](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L117)

The map of all page sections (mutable in BEFORE event)

##### type \{#type\}

```ts
readonly type: unknown;
```

Defined in: [types/src/printer.d.ts:111](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L111)

The GraphQL type being composed

---

### PageSection \{#pagesection\}

Defined in: [types/src/printer.d.ts:24](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L24)

Represents a single section of a page with optional title and content.

#### Properties

##### content? \{#content\}

```ts
optional content?:
  | string
  | MDXString
  | PageSection
  | PageSection[];
```

Defined in: [types/src/printer.d.ts:30](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L30)

The section content

##### level? \{#level\}

```ts
optional level?: number;
```

Defined in: [types/src/printer.d.ts:28](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L28)

Optional section level for hierarchical structuring

##### title? \{#title\}

```ts
optional title?: string | MDXString;
```

Defined in: [types/src/printer.d.ts:26](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L26)

Optional title/heading for the section

---

### PageSections \{#pagesections\}

Defined in: [types/src/printer.d.ts:36](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L36)

Map of all available sections in a type page.

#### Indexable

```ts
[key: string]: Maybe<PageSection | PageHeader>
```

Additional custom sections can be added by event handlers

#### Properties

##### code? \{#code\}

```ts
optional code?: PageSection;
```

Defined in: [types/src/printer.d.ts:50](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L50)

GraphQL code block

##### customDirectives? \{#customdirectives\}

```ts
optional customDirectives?: PageSection;
```

Defined in: [types/src/printer.d.ts:52](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L52)

Custom directives

##### description? \{#description\}

```ts
optional description?: PageSection;
```

Defined in: [types/src/printer.d.ts:48](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L48)

Type description from GraphQL comments

##### example? \{#example\}

```ts
optional example?: PageSection;
```

Defined in: [types/src/printer.d.ts:56](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L56)

Usage examples

##### header? \{#header\}

```ts
optional header?: PageHeader;
```

Defined in: [types/src/printer.d.ts:40](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L40)

YAML frontmatter or top-level heading

##### mdxDeclaration? \{#mdxdeclaration\}

```ts
optional mdxDeclaration?: PageHeader;
```

Defined in: [types/src/printer.d.ts:44](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L44)

MDX import declarations

##### metadata? \{#metadata\}

```ts
optional metadata?: PageSection;
```

Defined in: [types/src/printer.d.ts:54](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L54)

Type metadata (fields, arguments, etc.)

##### metatags? \{#metatags\}

```ts
optional metatags?: PageHeader;
```

Defined in: [types/src/printer.d.ts:42](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L42)

HTML meta tags

##### relations? \{#relations\}

```ts
optional relations?: PageSection;
```

Defined in: [types/src/printer.d.ts:58](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L58)

Related types

##### tags? \{#tags\}

```ts
optional tags?: PageSection;
```

Defined in: [types/src/printer.d.ts:46](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L46)

Custom tags (e.g., @deprecated)

---

### PrintCodeEventData \{#printcodeeventdata-1\}

Defined in: [types/src/printer.d.ts:64](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L64)

Data payload for print code events.

#### Properties

##### options \{#options-1\}

```ts
readonly options: PrintTypeOptions;
```

Defined in: [types/src/printer.d.ts:70](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L70)

The print options in effect

##### type \{#type-1\}

```ts
readonly type: unknown;
```

Defined in: [types/src/printer.d.ts:66](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L66)

The GraphQL type being printed

##### typeName \{#typename\}

```ts
readonly typeName: string;
```

Defined in: [types/src/printer.d.ts:68](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L68)

The name of the type

---

### PrintTypeEventData \{#printtypeeventdata-1\}

Defined in: [types/src/printer.d.ts:76](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L76)

Data payload for print type events.

#### Properties

##### name \{#name-1\}

```ts
readonly name: Maybe<string>;
```

Defined in: [types/src/printer.d.ts:80](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L80)

The name identifier for the type

##### options \{#options-2\}

```ts
readonly options: PrintTypeOptions;
```

Defined in: [types/src/printer.d.ts:82](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L82)

The print options in effect

##### type \{#type-2\}

```ts
readonly type: unknown;
```

Defined in: [types/src/printer.d.ts:78](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/types/src/printer.d.ts#L78)

The GraphQL type being printed

---

## example

Module providing utilities for handling GraphQL example directives and printing example values.

## getDirectiveExampleOption() \{#getdirectiveexampleoption\}

```ts
function getDirectiveExampleOption(options): Maybe<TypeDirectiveExample>;
```

Defined in: [printer-legacy/src/example.ts:45](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/example.ts#L45)

Retrieves directive example options from the provided print type options.

### Parameters

#### options

`PrintTypeOptions`

Configuration options

### Returns

`Maybe`&lt;`TypeDirectiveExample`&gt;

The directive example configuration if valid, otherwise `undefined`

---

## printExample() \{#printexample\}

```ts
function printExample(type, options): Maybe<string>;
```

Defined in: [printer-legacy/src/example.ts:253](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/example.ts#L253)

Prints an example value for a given GraphQL type or operation.

### Parameters

#### type

`unknown`

The GraphQL type or operation to generate an example for

#### options

`PrintTypeOptions`

Configuration options for printing the example

### Returns

`Maybe`&lt;`string`&gt;

Stringified example if available, otherwise `undefined`

### Example

```ts
const example = printExample(type, { schema, exampleSection });
if (example) {
  console.log(example);
}
```

---

## formatter(Printer-legacy)

Formatter factories for GraphQL documentation output.

Provides factory functions to create formatters for different output targets.
The default formatter produces HTML-like markup suitable for most Markdown processors.

## createDefaultFormatter() \{#createdefaultformatter\}

```ts
function createDefaultFormatter(): Formatter;
```

Defined in: [printer-legacy/src/formatter.ts:41](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/formatter.ts#L41)

Creates a default formatter for documentation output.

The default formatter produces HTML-like markup with CSS classes
that can be styled with custom CSS. This is suitable for most
Markdown processors that support inline HTML.

### Returns

`Formatter`

A complete Formatter implementation

### Example

```typescript
import { createDefaultFormatter } from "@graphql-markdown/printer-legacy";

const formatter = createDefaultFormatter();
const badge = formatter.formatMDXBadge({ text: "Required" });
```

---

## frontmatter

Module for handling frontmatter generation in Markdown documents.
Provides utilities for formatting and printing frontmatter content.

## printFrontMatter() \{#printfrontmatter\}

```ts
function printFrontMatter(title, props, options): string;
```

Defined in: [printer-legacy/src/frontmatter.ts:21](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/frontmatter.ts#L21)

Generates a formatted frontmatter string for Markdown/MDX documents.

### Parameters

#### title

`string`

The title to be included in the frontmatter

#### props

`Maybe`&lt;`FrontMatterOptions`&gt;

Additional frontmatter properties to be included

#### options

`PrintTypeOptions`

Configuration options for printing

### Returns

`string`

Formatted frontmatter string, or empty string if formatting is disabled

---

## directive(Graphql)

Module for handling GraphQL directive printing and formatting.
Provides utilities to generate string representations of GraphQL directives
including their metadata, arguments, and locations.

## printCodeDirective() \{#printcodedirective\}

```ts
function printCodeDirective(type, options?): string;
```

Defined in: [printer-legacy/src/graphql/directive.ts:67](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/directive.ts#L67)

Generates a string representation of a complete GraphQL directive definition.

### Parameters

#### type

`GraphQLDirective`

The GraphQL directive to process

#### options?

`PrintDirectiveOptions`

Configuration options for printing the directive (optional)

### Returns

`string`

A formatted string containing the complete directive definition

---

## printDirectiveMetadata() \{#printdirectivemetadata\}

```ts
function printDirectiveMetadata(type, options): Maybe<PageSection>;
```

Defined in: [printer-legacy/src/graphql/directive.ts:49](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/directive.ts#L49)

Prints metadata information for a GraphQL directive, focusing on its arguments.

### Parameters

#### type

`GraphQLDirective`

The GraphQL directive to process

#### options

`PrintDirectiveOptions`

Configuration options for printing directive metadata

### Returns

`Maybe`&lt;[`PageSection`](../events.md#pagesection)&gt;

An "Arguments" PageSection, or undefined when no arguments are available

---

## enum

Provides utilities for printing GraphQL enum types to Markdown/MDX format

## printCodeEnum() \{#printcodeenum\}

```ts
function printCodeEnum(type, options?): string;
```

Defined in: [printer-legacy/src/graphql/enum.ts:47](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/enum.ts#L47)

Generates a GraphQL SDL code block for an enum type.

### Parameters

#### type

`unknown`

The GraphQL enum type to process

#### options?

`PrintTypeOptions`

Optional printing options that control directive handling

### Returns

`string`

A string containing the enum type definition in GraphQL SDL, or empty string if type is not an enum

---

## printEnumMetadata() \{#printenummetadata\}

```ts
function printEnumMetadata(type, options): Maybe<PageSection>;
```

Defined in: [printer-legacy/src/graphql/enum.ts:29](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/enum.ts#L29)

Prints the metadata section for a GraphQL enum type.

### Parameters

#### type

`unknown`

The GraphQL enum type to process

#### options

`PrintTypeOptions`

Options for printing the type

### Returns

`Maybe`&lt;[`PageSection`](../events.md#pagesection)&gt;

A "Values" PageSection, or undefined when `type` is not an enum

---

## input

Legacy printer helpers for rendering GraphQL input types.

## printCodeInput() \{#printcodeinput\}

```ts
function printCodeInput(type, options): string;
```

Defined in: [printer-legacy/src/graphql/input.ts:20](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/input.ts#L20)

Renders the Markdown code snippet for a GraphQL `input` type by delegating
to the generic object printer while forcing the `input` kind.

### Parameters

#### type

`unknown`

The GraphQL input definition or SDL node to print.

#### options

`PrintTypeOptions`

Printer options controlling headings, examples, and badges.

### Returns

`string`

Markdown code block representing the input signature.

---

## interface

Contains utilities for printing GraphQL interface types as Markdown documentation.

## printCodeInterface() \{#printcodeinterface\}

```ts
function printCodeInterface(type, options): string;
```

Defined in: [printer-legacy/src/graphql/interface.ts:23](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/interface.ts#L23)

Generates a code block representation of a GraphQL interface type.

### Parameters

#### type

`unknown`

The GraphQL interface type to print

#### options

`PrintTypeOptions`

Configuration options for printing the type

### Returns

`string`

A string containing the Markdown code block representation

---

## object

GraphQL Object Type printing utilities

## printCodeObject() \{#printcodeobject\}

```ts
function printCodeObject(type, options): string;
```

Defined in: [printer-legacy/src/graphql/object.ts:108](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/object.ts#L108)

Prints a GraphQL object type definition as a code block

### Parameters

#### type

`unknown`

The GraphQL type object to process

#### options

`PrintTypeOptions`

Printing options

### Returns

`string`

GraphQL object type definition as a code block string

---

## printCodeType() \{#printcodetype\}

```ts
function printCodeType(type, entity, options): string;
```

Defined in: [printer-legacy/src/graphql/object.ts:68](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/object.ts#L68)

Prints the GraphQL type definition as a code block

### Parameters

#### type

`unknown`

The GraphQL type object to process

#### entity

`string`

The entity type identifier (e.g., "type", "interface")

#### options

`PrintTypeOptions`

Printing options

### Returns

`string`

GraphQL type definition as a code block string

---

## printObjectMetadata() \{#printobjectmetadata\}

```ts
function printObjectMetadata(type, options): Maybe<PageSection[]>;
```

Defined in: [printer-legacy/src/graphql/object.ts:46](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/object.ts#L46)

Prints the complete metadata section for a GraphQL object type

### Parameters

#### type

`unknown`

The GraphQL type object to process

#### options

`PrintTypeOptions`

Printing options

### Returns

`Maybe`&lt;[`PageSection`](../events.md#pagesection)[]&gt;

Ordered metadata sections for fields and interfaces

---

## operation

Module for handling GraphQL operation printing functionality.
Provides utilities to print operation types, metadata, and code representations.

## printCodeOperation() \{#printcodeoperation\}

```ts
function printCodeOperation(type, options?): string | MDXString;
```

Defined in: [printer-legacy/src/graphql/operation.ts:94](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/operation.ts#L94)

Prints the code representation of an operation.

### Parameters

#### type

`unknown`

#### options?

`PrintTypeOptions`

### Returns

`string` \| `MDXString`

---

## printOperationMetadata() \{#printoperationmetadata\}

```ts
function printOperationMetadata(type, options): Maybe<PageSection[]>;
```

Defined in: [printer-legacy/src/graphql/operation.ts:45](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/operation.ts#L45)

Prints the operation metadata including arguments and type information.

### Parameters

#### type

`unknown`

The operation type to print metadata for

#### options

`PrintTypeOptions`

Print type options for customizing output

### Returns

`Maybe`&lt;[`PageSection`](../events.md#pagesection)[]&gt;

Ordered operation metadata sections, or undefined when `type` is not an operation

---

## scalar

Provides utility functions for handling GraphQL scalar types in markdown generation.

## printCodeScalar() \{#printcodescalar\}

```ts
function printCodeScalar(type, options?): string;
```

Defined in: [printer-legacy/src/graphql/scalar.ts:61](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/scalar.ts#L61)

Generates the GraphQL SDL representation of a scalar type.

### Parameters

#### type

`unknown`

The GraphQL scalar type object

#### options?

`PrintTypeOptions`

Options for printing type information (unused)

### Returns

`string`

SDL string representation of the scalar type

---

## printScalarMetadata() \{#printscalarmetadata\}

```ts
function printScalarMetadata(type, options): Maybe<PageSection>;
```

Defined in: [printer-legacy/src/graphql/scalar.ts:48](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/scalar.ts#L48)

Prints metadata information for a scalar type.
Currently only includes the specification URL if available.

### Parameters

#### type

`unknown`

The GraphQL scalar type object

#### options

`PrintTypeOptions`

Options for printing type information

### Returns

`Maybe`&lt;[`PageSection`](../events.md#pagesection)&gt;

A scalar metadata PageSection, or undefined when not available

---

## printSpecification() \{#printspecification\}

```ts
function printSpecification(type, options): Maybe<PageSection>;
```

Defined in: [printer-legacy/src/graphql/scalar.ts:20](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/scalar.ts#L20)

Generates markdown documentation for a scalar type's specification URL.

### Parameters

#### type

`unknown`

The GraphQL scalar type object

#### options

`PrintTypeOptions`

Options for printing type information

### Returns

`Maybe`&lt;[`PageSection`](../events.md#pagesection)&gt;

A specification PageSection, or undefined when no URL exists

---

## union

Module for handling GraphQL Union type printing operations.

## printCodeUnion() \{#printcodeunion\}

```ts
function printCodeUnion(type, options?): string;
```

Defined in: [printer-legacy/src/graphql/union.ts:43](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/union.ts#L43)

Generates GraphQL SDL code representation of a Union type.

### Parameters

#### type

`unknown`

The GraphQL type to process

#### options?

`PrintTypeOptions`

Configuration options for printing (unused)

### Returns

`string`

SDL string representation of the union type

---

## printUnionMetadata() \{#printunionmetadata\}

```ts
function printUnionMetadata(type, options): Maybe<PageSection>;
```

Defined in: [printer-legacy/src/graphql/union.ts:23](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/graphql/union.ts#L23)

Generates metadata documentation for a GraphQL Union type.

### Parameters

#### type

`unknown`

The GraphQL type to process

#### options

`PrintTypeOptions`

Configuration options for printing

### Returns

`Maybe`&lt;[`PageSection`](../events.md#pagesection)&gt;

A "Possible types" PageSection, or undefined when `type` is not a union

---

## graphql



---

## group(Printer-legacy)

Utility module for handling GraphQL schema entity grouping.

## getGroup() \{#getgroup\}

```ts
function getGroup(type, groups, typeCategory): string;
```

Defined in: [printer-legacy/src/group.ts:24](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/group.ts#L24)

Retrieves the group name for a given GraphQL type based on its category and group mapping.

### Parameters

#### type

`unknown`

The GraphQL type to get the group for

#### groups

`Maybe`&lt;`Partial`&lt;`Record`&lt;`SchemaEntity`, `Record`&lt;`string`, `Maybe`&lt;`string`&gt;&gt;&gt;&gt;&gt;

Mapping of schema entities to their group names

#### typeCategory

`Maybe`&lt;`SchemaEntity`&gt;

The category of the schema entity

### Returns

`string`

The slugified group name or empty string if no group is found

---

## link

Module for handling links and link-related operations in GraphQL Markdown printer.
Provides utilities for creating, formatting, and managing links to GraphQL types and operations.

## API_GROUPS \{#api_groups\}

```ts
const API_GROUPS: Required<ApiGroupOverrideType>;
```

Defined in: [printer-legacy/src/link.ts:52](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L52)

---

## getCategoryLocale() \{#getcategorylocale\}

```ts
function getCategoryLocale(type): Maybe<TypeLocale>;
```

Defined in: [printer-legacy/src/link.ts:103](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L103)

Gets the locale category for a given GraphQL type.

### Parameters

#### type

`unknown`

The GraphQL type to get the category for

### Returns

`Maybe`&lt;`TypeLocale`&gt;

The locale category for the type, or `undefined` if not found

---

## getLinkApiGroupFolder() \{#getlinkapigroupfolder\}

```ts
function getLinkApiGroupFolder(type, groups?): string;
```

Defined in: [printer-legacy/src/link.ts:193](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L193)

Gets the folder name for an API group based on the GraphQL type and group options.

### Parameters

#### type

`unknown`

The GraphQL type to get the folder name for

#### groups?

`Maybe`&lt;`boolean` \| `ApiGroupOverrideType`&gt;

The group options

### Returns

`string`

The folder name for the API group

---

## getLinkCategoryFolder() \{#getlinkcategoryfolder\}

```ts
function getLinkCategoryFolder(type, operationLocale?): Maybe<string>;
```

Defined in: [printer-legacy/src/link.ts:133](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L133)

Gets the folder name for a link category based on the GraphQL type and operation locale.

### Parameters

#### type

`unknown`

The GraphQL type to get the folder name for

#### operationLocale?

`Maybe`&lt;`TypeLocale`&gt;

The locale of the operation

### Returns

`Maybe`&lt;`string`&gt;

The folder name for the link category, or `undefined` if not found

---

## getRelationLink() \{#getrelationlink\}

```ts
function getRelationLink(category, type, options): Maybe<TypeLink>;
```

Defined in: [printer-legacy/src/link.ts:331](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L331)

Gets the link for a relation based on the category, type, and options.

### Parameters

#### category

`Maybe`&lt;`TypeLocale`&gt;

The locale category of the relation

#### type

`unknown`

The GraphQL type of the relation

#### options

`PrintLinkOptions`

Configuration options for link generation

### Returns

`Maybe`&lt;`TypeLink`&gt;

The link object for the relation, or `undefined` if not found

---

## hasOptionParentType() \{#hasoptionparenttype\}

```ts
function hasOptionParentType(options): boolean;
```

Defined in: [printer-legacy/src/link.ts:176](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L176)

Checks if the options include the `parentTypePrefix` attribute.

### Parameters

#### options

`PrintLinkOptions`

The options to check

### Returns

`boolean`

`true` if the options include `parentTypePrefix`, `false` otherwise

---

## hasOptionWithAttributes() \{#hasoptionwithattributes\}

```ts
function hasOptionWithAttributes(options): boolean;
```

Defined in: [printer-legacy/src/link.ts:165](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L165)

Checks if the options include the `withAttributes` attribute.

### Parameters

#### options

`PrintLinkOptions`

The options to check

### Returns

`boolean`

`true` if the options include `withAttributes`, `false` otherwise

---

## hasPrintableDirective() \{#hasprintabledirective\}

```ts
function hasPrintableDirective(type, options?): boolean;
```

Defined in: [printer-legacy/src/link.ts:64](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L64)

Checks if a type has printable directives based on the provided options.

### Parameters

#### type

`unknown`

The GraphQL type to check

#### options?

`Pick`&lt;`PrintTypeOptions`, `"deprecated"` \| `"onlyDocDirectives"` \| `"skipDocDirectives"`&gt;

Configuration options for directive printing (`deprecated`, `onlyDocDirectives`, `skipDocDirectives`)

### Returns

`boolean`

`true` if the type should be printed, `false` otherwise

---

## printLink() \{#printlink\}

```ts
function printLink<T>(arg, options): string;
```

Defined in: [printer-legacy/src/link.ts:403](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L403)

Prints a link for a GraphQL type based on the provided options.

### Type Parameters

#### T

`T`

### Parameters

#### arg

`Maybe`&lt;`TypeLink`&gt; \| `T`

The GraphQL type or link object to print a link for

#### options

`PrintLinkOptions`

Configuration options for link generation

### Returns

`string`

The formatted link as a string

---

## printLinkAttributes() \{#printlinkattributes\}

```ts
function printLinkAttributes(type, text?): string;
```

Defined in: [printer-legacy/src/link.ts:355](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L355)

Prints the attributes of a link based on the GraphQL type.

### Parameters

#### type

`unknown`

The GraphQL type to print attributes for

#### text?

`Maybe`&lt;`string`&gt; = `""`

The text to append attributes to

### Returns

`string`

The text with appended attributes

---

## printParentLink() \{#printparentlink\}

```ts
function printParentLink(type, options): string | MDXString;
```

Defined in: [printer-legacy/src/link.ts:447](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L447)

Prints a parent link for a GraphQL type based on the provided options.

### Parameters

#### type

`unknown`

The GraphQL type to print a parent link for

#### options

`PrintLinkOptions`

Configuration options for link generation

### Returns

`string` \| `MDXString`

The formatted parent link as a string or MDX string

---

## toLink() \{#tolink\}

```ts
function toLink(type, name, operation, options): TypeLink;
```

Defined in: [printer-legacy/src/link.ts:234](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/link.ts#L234)

Converts a GraphQL type to a link object.

### Parameters

#### type

`unknown`

The GraphQL type to convert

#### name

`string`

The name of the type

#### operation

`Maybe`&lt;`TypeLocale`&gt;

The locale of the operation

#### options

`PrintLinkOptions`

Configuration options for link generation

### Returns

`TypeLink`

The link object for the type

---

## printer(Printer-legacy)

GraphQL Schema Printer Module

This module provides functionality for printing GraphQL schema types into Markdown documentation.
It includes utilities for handling various GraphQL types, custom directives, and formatting options.

## Printer \{#printer\}

Defined in: [printer-legacy/src/printer.ts:181](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L181)

The Printer class implements the core functionality for generating Markdown documentation
from GraphQL schema types.

### Remarks

This class provides static methods for rendering different components of the documentation:

- Headers and frontmatter
- Type descriptions and code blocks
- Custom directives and metadata
- Examples and relations

### Example

```typescript
const printer = new Printer();
await printer.init(schema, "/docs", "graphql", options);
const docs = printer.printType("Query", queryType);
```

### Implements

- `IPrinter`

### Constructors

#### Constructor

```ts
new Printer(): Printer;
```

##### Returns

[`Printer`](#printer)

### Properties

#### printCustomDirectives \{#printcustomdirectives\}

```ts
readonly static printCustomDirectives: (type, options) => Maybe<PageSection>;
```

Defined in: [printer-legacy/src/printer.ts:190](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L190)

Prints custom directives

Prints all custom directives for a type as a Markdown section

##### Parameters

###### type

`unknown`

The GraphQL type to print directives for

###### options

`PrintTypeOptions`

General printing options

##### Returns

`Maybe`&lt;[`PageSection`](events.md#pagesection)&gt;

A "Directives" PageSection, or undefined when no directives are printable

#### printCustomTags \{#printcustomtags\}

```ts
readonly static printCustomTags: (type, options) => string | MDXString;
```

Defined in: [printer-legacy/src/printer.ts:195](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L195)

Prints custom tags

Prints custom directive tags as Markdown badges

##### Parameters

###### type

`unknown`

The GraphQL type to print tags for

###### options

`PrintTypeOptions`

General printing options

##### Returns

`string` \| `MDXString`

Formatted Markdown string of badges or empty string

#### printDescription \{#printdescription\}

```ts
readonly static printDescription: (type, options, noText?) => string | MDXString;
```

Defined in: [printer-legacy/src/printer.ts:185](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L185)

Prints type descriptions

Prints the complete description for a GraphQL type, including deprecation warnings and custom directives.

##### Parameters

###### type

`unknown`

The GraphQL type to document

###### options

`PrintTypeOptions`

Configuration options for printing

###### noText?

`string`

Optional text to display when no description exists

##### Returns

`string` \| `MDXString`

Combined description, deprecation notices, and custom directives as MDX content

### Accessors

#### eventEmitter \{#eventemitter\}

##### Get Signature

```ts
get static eventEmitter(): Maybe<PrinterEventEmitter>;
```

Defined in: [printer-legacy/src/printer.ts:215](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L215)

Optional event emitter for print events.
When set, the printer will emit events before/after printCode and printType,
allowing external code to intercept and modify the output.

###### Returns

`Maybe`&lt;`PrinterEventEmitter`&gt;

##### Set Signature

```ts
set static eventEmitter(eventEmitter): void;
```

Defined in: [printer-legacy/src/printer.ts:230](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L230)

###### Parameters

###### eventEmitter

`Maybe`&lt;`PrinterEventEmitter`&gt;

###### Returns

`void`

#### mdxDeclaration \{#mdxdeclaration\}

##### Get Signature

```ts
get static mdxDeclaration(): Readonly<Maybe<string>>;
```

Defined in: [printer-legacy/src/printer.ts:222](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L222)

Prints mdx modules import declaration

###### Returns

`Readonly`&lt;`Maybe`&lt;`string`&gt;&gt;

##### Set Signature

```ts
set static mdxDeclaration(mdxDeclaration): void;
```

Defined in: [printer-legacy/src/printer.ts:234](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L234)

###### Parameters

###### mdxDeclaration

`Readonly`&lt;`Maybe`&lt;`string`&gt;&gt;

###### Returns

`void`

#### options \{#options\}

##### Get Signature

```ts
get static options(): Readonly<Maybe<PrintTypeOptions>>;
```

Defined in: [printer-legacy/src/printer.ts:206](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L206)

Global printer configuration options

###### Returns

`Readonly`&lt;`Maybe`&lt;`PrintTypeOptions`&gt;&gt;

##### Set Signature

```ts
set static options(options): void;
```

Defined in: [printer-legacy/src/printer.ts:226](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L226)

###### Parameters

###### options

`Readonly`&lt;`Maybe`&lt;`PrintTypeOptions`&gt;&gt;

###### Returns

`void`

### Methods

#### init() \{#init\}

```ts
static init(
   schema,
   baseURL?,
   linkRoot?,
   options?,
   formatter?,
   mdxDeclaration?,
   eventEmitter?
): Promise<void>;
```

Defined in: [printer-legacy/src/printer.ts:249](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L249)

Initializes the printer with the given schema and configuration.

##### Parameters

###### schema

`Maybe`&lt;`GraphQLSchema`&gt;

GraphQL schema to generate documentation for

###### baseURL?

`Maybe`&lt;`string`&gt; = `"schema"`

Base URL path for documentation, e.g. '/docs'

###### linkRoot?

`Maybe`&lt;`string`&gt; = `"/"`

Root path for generating links between types

###### options?

`PrinterInitOptions` = `DEFAULT_INIT_OPTIONS`

Configuration options for the printer

###### formatter?

`Partial`&lt;`Formatter`&gt;

Optional formatter functions for customizing output format

###### mdxDeclaration?

`Maybe`&lt;`string`&gt;

Optional MDX import declaration

###### eventEmitter?

`Maybe`&lt;`PrinterEventEmitter`&gt;

Optional event emitter for print events interception

##### Returns

`Promise`&lt;`void`&gt;

#### printCode() \{#printcode\}

```ts
readonly static printCode(type, options): string;
```

Defined in: [printer-legacy/src/printer.ts:337](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L337)

Prints the GraphQL type definition as code block

##### Parameters

###### type

`unknown`

GraphQL type to print

###### options

`PrintTypeOptions`

Printer configuration options

##### Returns

`string`

Formatted code block string with type definition

#### printCodeAsync() \{#printcodeasync\}

```ts
readonly static printCodeAsync(
   type,
   typeName,
   options
): Promise<string>;
```

Defined in: [printer-legacy/src/printer.ts:393](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L393)

Prints the GraphQL type definition as code block with event emission support.

##### Parameters

###### type

`unknown`

GraphQL type to print

###### typeName

`string`

Name of the type being printed

###### options

`PrintTypeOptions`

Printer configuration options

##### Returns

`Promise`&lt;`string`&gt;

Promise resolving to formatted code block string with type definition

##### Remarks

This async version emits events before and after code generation:

- `print:beforePrintCode` - Emitted before generating code (can modify inputs or prevent default)
- `print:afterPrintCode` - Emitted after generating code (can modify output)

Event handlers can:

- Modify `event.data.options` in BEFORE to affect code generation
- Call `event.preventDefault()` in BEFORE to skip default generation and provide custom output
- Modify `event.output` in AFTER to change the final result

#### printExample() \{#printexample\}

```ts
readonly static printExample(type, options): Maybe<PageSection>;
```

Defined in: [printer-legacy/src/printer.ts:438](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L438)

Prints example usage of the type if available

##### Parameters

###### type

`unknown`

GraphQL type to generate example for

###### options

`PrintTypeOptions`

Printer configuration options

##### Returns

`Maybe`&lt;[`PageSection`](events.md#pagesection)&gt;

Example page section or undefined when no example is available

#### printHeader() \{#printheader\}

```ts
readonly static printHeader(
   id,
   title,
   options
): string;
```

Defined in: [printer-legacy/src/printer.ts:316](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L316)

Prints the header section of a type documentation

##### Parameters

###### id

`string`

Unique identifier for the type

###### title

`string`

Display title for the type

###### options

`PrintTypeOptions`

Printer configuration options

##### Returns

`string`

Formatted header string with optional frontmatter

#### printMetaTags() \{#printmetatags\}

```ts
readonly static printMetaTags(_type, options): string | MDXString;
```

Defined in: [printer-legacy/src/printer.ts:508](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L508)

Prints HTML meta tags for the documentation

##### Parameters

###### \_type

`unknown`

GraphQL type (unused)

###### options

`PrintTypeOptions`

Printer configuration options containing metatags

##### Returns

`string` \| `MDXString`

Formatted HTML meta tags string

#### printRelations() \{#printrelations\}

```ts
readonly static printRelations(type, options): string | MDXString;
```

Defined in: [printer-legacy/src/printer.ts:494](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L494)

Prints related type information

##### Parameters

###### type

`unknown`

GraphQL type to find relations for

###### options

`PrintTypeOptions`

Printer configuration options

##### Returns

`string` \| `MDXString`

Formatted relations section as MDX or plain string

#### printType() \{#printtype\}

```ts
readonly static printType(
   name,
   type,
   options?
): Promise<Maybe<MDXString>>;
```

Defined in: [printer-legacy/src/printer.ts:558](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L558)

Main method to print complete documentation for a GraphQL type

##### Parameters

###### name

`Maybe`&lt;`string`&gt;

Name identifier for the type

###### type

`unknown`

GraphQL type to generate documentation for

###### options?

`Maybe`&lt;`Partial`&lt;`PrintTypeOptions`&gt;&gt;

Optional printer configuration options

##### Returns

`Promise`&lt;`Maybe`&lt;`MDXString`&gt;&gt;

Complete documentation as MDX string or undefined if type should be skipped

##### Example

```typescript
const doc = await Printer.printType("User", UserType, {
  frontMatter: true,
});
```

##### Remarks

The method combines multiple sections:

- Header with frontmatter
- Meta tags
- Description
- Code definition
- Custom directives
- Type metadata
- Example usage
- Related types

When an event emitter is configured, emits events:

- `print:beforePrintType` - Before generating documentation
- `print:beforeComposePageType` - Before composing section order and final page output
- `print:afterPrintType` - After generating documentation (output can be modified)

#### printTypeMetadata() \{#printtypemetadata\}

```ts
readonly static printTypeMetadata(type, options): Maybe<
  | PageSection
  | PageSection[]>;
```

Defined in: [printer-legacy/src/printer.ts:461](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/printer.ts#L461)

Prints metadata information for a GraphQL type

##### Parameters

###### type

`unknown`

GraphQL type to print metadata for

###### options

`PrintTypeOptions`

Printer configuration options

##### Returns

`Maybe`&lt;
\| [`PageSection`](events.md#pagesection)
\| [`PageSection`](events.md#pagesection)[]&gt;

Metadata section (or section list) for supported types, otherwise undefined

---

## relation(Printer-legacy)

This module provides functionality to print relationships between GraphQL types,
including return types, member fields, and implementations, in a formatted MDX string output.

## getRootTypeLocaleFromString() \{#getroottypelocalefromstring\}

```ts
function getRootTypeLocaleFromString(text): Maybe<TypeLocale>;
```

Defined in: [printer-legacy/src/relation.ts:41](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/relation.ts#L41)

Converts a string representation of a root type to its corresponding `TypeLocale`

### Parameters

#### text

`string`

The string to convert to a `TypeLocale`

### Returns

`Maybe`&lt;`TypeLocale`&gt;

The matching `TypeLocale` if found, `undefined` otherwise

### Example

```ts
const locale = getRootTypeLocaleFromString("Query");
```

---

## printRelationOf() \{#printrelationof\}

```ts
function printRelationOf<T>(
  type,
  section,
  getRelation,
  options,
): string | MDXString;
```

Defined in: [printer-legacy/src/relation.ts:67](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/relation.ts#L67)

Prints the relation section for a specific type and relation category

### Type Parameters

#### T

`T`

Type of the relation

### Parameters

#### type

`unknown`

The GraphQL type to get relations for

#### section

`unknown`

The section title for the relation

#### getRelation

`Maybe`&lt;`IGetRelation`&lt;`T`&gt;&gt;

Function to retrieve relations of type T

#### options

`PrintTypeOptions`

Printing options for type formatting

### Returns

`string` \| `MDXString`

Formatted MDX string containing the relations or empty string if no relations found

### Throws

If the schema is not provided in options

### Example

```ts
const mdx = printRelationOf(type, "Member Of", getRelationOfField, options);
```

---

## printRelations() \{#printrelations\}

```ts
function printRelations(type, options): string | MDXString;
```

Defined in: [printer-legacy/src/relation.ts:136](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/relation.ts#L136)

Prints all relations (return types, member fields, and implementations) for a given type

### Parameters

#### type

`unknown`

The GraphQL type to get all relations for

#### options

`PrintTypeOptions`

Printing options for type formatting

### Returns

`string` \| `MDXString`

Formatted MDX string containing all relations or empty string if no relations found

### Throws

If the schema is not provided in options

### Example

```ts
const relations = printRelations(myType, {
  schema,
  formatMDXBullet: () => "* ",
});
```

---

## section

Module responsible for generating Markdown sections for GraphQL schema documentation.
Handles the printing of section items, metadata, and structured documentation content.

## printMetadataSection() \{#printmetadatasection\}

```ts
function printMetadataSection<T, V>(
  type,
  values,
  section,
  options,
): Maybe<PageSection>;
```

Defined in: [printer-legacy/src/section.ts:215](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/section.ts#L215)

Prints a metadata section with special handling for deprecated items.

### Type Parameters

#### T

`T`

Type of the parent element

#### V

`V`

Type of the values being printed

### Parameters

#### type

`T`

The parent type containing the metadata

#### values

`V` \| `V`[] \| readonly `V`[]

Values to include in the metadata section

#### section

`string`

Section title/header

#### options

`PrintTypeOptions`

Configuration options for printing

### Returns

`Maybe`&lt;[`PageSection`](events.md#pagesection)&gt;

Formatted MDX string containing the metadata section

---

## printSection() \{#printsection\}

```ts
function printSection<V>(values, section, options): Maybe<PageSection>;
```

Defined in: [printer-legacy/src/section.ts:162](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/section.ts#L162)

Prints a complete section with title and content.

### Type Parameters

#### V

`V`

Type of the values being printed

### Parameters

#### values

`V`[] \| readonly `V`[]

Array of values to include in the section

#### section

`string`

Section title/header

#### options

`PrintTypeOptions`

Configuration options for printing

### Returns

`Maybe`&lt;[`PageSection`](events.md#pagesection)&gt;

Formatted MDX string containing the complete section

---

## printSectionItem() \{#printsectionitem\}

```ts
function printSectionItem<T>(type, options): string | MDXString;
```

Defined in: [printer-legacy/src/section.ts:70](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/section.ts#L70)

Prints a single section item with its associated metadata.

### Type Parameters

#### T

`T`

Type of the GraphQL element being printed

### Parameters

#### type

`T`

The GraphQL type or field to print

#### options

`PrintTypeOptions`

Configuration options for printing

### Returns

`string` \| `MDXString`

Formatted MDX string containing the section item

---

## printSectionItems() \{#printsectionitems\}

```ts
function printSectionItems<V>(values, options): string | MDXString;
```

Defined in: [printer-legacy/src/section.ts:130](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/printer-legacy/src/section.ts#L130)

Prints an array of section items with consistent formatting.

### Type Parameters

#### V

`V`

Type of the values being printed

### Parameters

#### values

`V` \| `V`[]

Single value or array of values to print as section items

#### options

`PrintTypeOptions`

Configuration options for printing

### Returns

`string` \| `MDXString`

Formatted MDX string containing all section items

---

## array

Internal library of helpers for manipulating array and list.

## convertArrayToMapObject() \{#convertarraytomapobject\}

```ts
function convertArrayToMapObject<T>(list): Maybe<Record<string, T>>;
```

Defined in: [array.ts:75](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/array.ts#L75)

**`Internal`**

Returns a k/v object from an array of objects with a `name` property.

### Type Parameters

#### T

`T`

the type of objects the list contains.

### Parameters

#### list

`Maybe`&lt;`T`[]&gt;

the list of objects of type `{ name: any }` to be converted.

### Returns

`Maybe`&lt;`Record`&lt;`string`, `T`&gt;&gt;

an array of object values with `name` as key, or `undefined` if `list` is not a valid array.

### Example

```js
import { convertArrayToMapObject } from "@graphql-markdown/utils/array";

convertArrayToMapObject([
  { name: true },
  { name: "test" },
  { name: 123 },
  { name2: 1234 },
]);

// Expected result: {
//   true: { name: true },
//   test: { name: "test" },
//   "123": { name: 123 },
// }
```

---

## toArray() \{#toarray\}

```ts
function toArray(recordMap): Maybe<unknown[]>;
```

Defined in: [array.ts:35](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/array.ts#L35)

**`Internal`**

Returns an array of values from a k/v object.

### Parameters

#### recordMap

`Maybe`&lt;`Record`&lt;`string`, `unknown`&gt;&gt;

the key/value record object to be converted.

### Returns

`Maybe`&lt;`unknown`[]&gt;

an array of object values, or `undefined` if `recordMap` is not a valid object.

### Example

```js
import { toArray } from "@graphql-markdown/utils/array";

toArray({
  bool: true,
  string: "test",
  number: 123,
  array: ["one", "two"],
  child: { key: "value" },
});

// Expected result: [true, "test", 123, ["one", "two"], { key: "value" }]
```

---

## events(Utils)

Base event class and utilities for GraphQL-Markdown events.

## Events

### `abstract` CancellableEvent \{#abstract-cancellableevent\}

Defined in: [events.ts:55](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L55)

Base class for all cancellable events in GraphQL-Markdown.

Provides common functionality:

- preventDefault() to cancel default actions
- stopPropagation() to halt handler chain
- Configurable cancellability
- Optional default action function

#### Extended by

- [`DataEvent`](#abstract-dataevent)

#### Implements

- `ICancellableEvent`

#### Constructors

##### Constructor

```ts
new CancellableEvent(options?): CancellableEvent;
```

Defined in: [events.ts:88](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L88)

Creates a new CancellableEvent.

###### Parameters

###### options?

[`CancellableEventOptions`](#cancellableeventoptions)

Configuration options for the event

###### Returns

[`CancellableEvent`](#abstract-cancellableevent)

###### Remarks

options.cancellable controls whether this event can be cancelled (default: true).
options.defaultAction defines an optional function to execute as default action.

#### Accessors

##### defaultAction \{#defaultaction\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: [events.ts:110](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L110)

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Implementation of

```ts
ICancellableEvent.defaultAction;
```

##### defaultPrevented \{#defaultprevented\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: [events.ts:96](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L96)

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: [events.ts:117](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L117)

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Implementation of

```ts
ICancellableEvent.defaultPrevented;
```

##### propagationStopped \{#propagationstopped\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: [events.ts:103](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L103)

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: [events.ts:126](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L126)

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Implementation of

```ts
ICancellableEvent.propagationStopped;
```

#### Methods

##### preventDefault() \{#preventdefault\}

```ts
preventDefault(): void;
```

Defined in: [events.ts:136](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L136)

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Implementation of

```ts
ICancellableEvent.preventDefault;
```

##### runDefaultAction() \{#rundefaultaction\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: [events.ts:153](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L153)

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Implementation of

```ts
ICancellableEvent.runDefaultAction;
```

##### stopPropagation() \{#stoppropagation\}

```ts
stopPropagation(): void;
```

Defined in: [events.ts:146](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L146)

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Implementation of

```ts
ICancellableEvent.stopPropagation;
```

---

### `abstract` DataEvent \{#abstract-dataevent\}

Defined in: [events.ts:168](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L168)

Abstract base for events that carry a typed, read-only data payload.

#### Extends

- [`CancellableEvent`](#abstract-cancellableevent)

#### Extended by

- [`DataOutputEvent`](#abstract-dataoutputevent)
- [`DiffCheckEvent`](../core/events/diff-check.md#diffcheckevent)
- [`GenerateIndexMetafileEvent`](../core/events/generate-index-metafile.md#generateindexmetafileevent)
- [`RenderFilesEvent`](../core/events/render-files.md#renderfilesevent)
- [`RenderHomepageEvent`](../core/events/render-homepage.md#renderhomepageevent)
- [`RenderRootTypesEvent`](../core/events/render-root-types.md#renderroottypesevent)
- [`RenderTypeEntitiesEvent`](../core/events/render-type-entities.md#rendertypeentitiesevent)
- [`SchemaEvent`](../core/events/schema-load.md#schemaevent)

#### Type Parameters

##### TData

`TData`

Type of the event data payload.

#### Constructors

##### Constructor

```ts
new DataEvent<TData>(data, options?): DataEvent<TData>;
```

Defined in: [events.ts:172](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L172)

###### Parameters

###### data

`TData`

###### options?

[`CancellableEventOptions`](#cancellableeventoptions)

###### Returns

[`DataEvent`](#abstract-dataevent)&lt;`TData`&gt;

###### Overrides

[`CancellableEvent`](#abstract-cancellableevent).[`constructor`](#constructor)

#### Properties

##### data \{#data\}

```ts
readonly data: TData;
```

Defined in: [events.ts:170](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L170)

Read-only event data payload.

#### Accessors

##### defaultAction \{#defaultaction-1\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: [events.ts:110](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L110)

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Inherited from

[`CancellableEvent`](#abstract-cancellableevent).[`defaultAction`](#defaultaction)

##### defaultPrevented \{#defaultprevented-1\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: [events.ts:96](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L96)

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: [events.ts:117](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L117)

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`CancellableEvent`](#abstract-cancellableevent).[`defaultPrevented`](#defaultprevented)

##### propagationStopped \{#propagationstopped-1\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: [events.ts:103](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L103)

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: [events.ts:126](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L126)

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`CancellableEvent`](#abstract-cancellableevent).[`propagationStopped`](#propagationstopped)

#### Methods

##### preventDefault() \{#preventdefault-1\}

```ts
preventDefault(): void;
```

Defined in: [events.ts:136](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L136)

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Inherited from

[`CancellableEvent`](#abstract-cancellableevent).[`preventDefault`](#preventdefault)

##### runDefaultAction() \{#rundefaultaction-1\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: [events.ts:153](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L153)

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Inherited from

[`CancellableEvent`](#abstract-cancellableevent).[`runDefaultAction`](#rundefaultaction)

##### stopPropagation() \{#stoppropagation-1\}

```ts
stopPropagation(): void;
```

Defined in: [events.ts:146](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L146)

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Inherited from

[`CancellableEvent`](#abstract-cancellableevent).[`stopPropagation`](#stoppropagation)

---

### `abstract` DataOutputEvent \{#abstract-dataoutputevent\}

Defined in: [events.ts:186](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L186)

Abstract base for events that carry typed data and a mutable output value.

#### Extends

- [`DataEvent`](#abstract-dataevent)&lt;`TData`&gt;

#### Extended by

- [`BeforeComposePageTypeEvent`](../printer-legacy/events.md#beforecomposepagetypeevent)
- [`PrintCodeEvent`](../printer-legacy/events.md#printcodeevent)
- [`PrintTypeEvent`](../printer-legacy/events.md#printtypeevent)

#### Type Parameters

##### TData

`TData`

Type of the event data payload.

##### TOutput

`TOutput`

Type of the mutable output value.

#### Constructors

##### Constructor

```ts
new DataOutputEvent<TData, TOutput>(
   data,
   initialOutput,
   options?
): DataOutputEvent<TData, TOutput>;
```

Defined in: [events.ts:193](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L193)

###### Parameters

###### data

`TData`

###### initialOutput

`TOutput`

###### options?

[`CancellableEventOptions`](#cancellableeventoptions)

###### Returns

[`DataOutputEvent`](#abstract-dataoutputevent)&lt;`TData`, `TOutput`&gt;

###### Overrides

[`DataEvent`](#abstract-dataevent).[`constructor`](#constructor-1)

#### Properties

##### data \{#data-1\}

```ts
readonly data: TData;
```

Defined in: [events.ts:170](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L170)

Read-only event data payload.

###### Inherited from

[`DataEvent`](#abstract-dataevent).[`data`](#data)

##### output \{#output\}

```ts
output: TOutput;
```

Defined in: [events.ts:191](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L191)

The generated output.
Handlers can modify this property to change the final result.

#### Accessors

##### defaultAction \{#defaultaction-2\}

###### Get Signature

```ts
get defaultAction(): DefaultAction | undefined;
```

Defined in: [events.ts:110](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L110)

Gets the default action function if one was provided.

###### Returns

`DefaultAction` \| `undefined`

###### Inherited from

[`DataEvent`](#abstract-dataevent).[`defaultAction`](#defaultaction-1)

##### defaultPrevented \{#defaultprevented-2\}

###### Get Signature

```ts
get defaultPrevented(): boolean;
```

Defined in: [events.ts:96](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L96)

Gets whether the default action has been prevented.

###### Returns

`boolean`

###### Set Signature

```ts
set defaultPrevented(value): void;
```

Defined in: [events.ts:117](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L117)

Allows setting defaultPrevented to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](#abstract-dataevent).[`defaultPrevented`](#defaultprevented-1)

##### propagationStopped \{#propagationstopped-2\}

###### Get Signature

```ts
get propagationStopped(): boolean;
```

Defined in: [events.ts:103](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L103)

Gets whether propagation has been stopped.

###### Returns

`boolean`

###### Set Signature

```ts
set propagationStopped(value): void;
```

Defined in: [events.ts:126](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L126)

Allows setting propagationStopped to true directly.

###### Parameters

###### value

`boolean`

###### Returns

`void`

###### Inherited from

[`DataEvent`](#abstract-dataevent).[`propagationStopped`](#propagationstopped-1)

#### Methods

##### preventDefault() \{#preventdefault-2\}

```ts
preventDefault(): void;
```

Defined in: [events.ts:136](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L136)

Prevents the default action from executing.
Only works if the event is cancellable.

###### Returns

`void`

###### Inherited from

[`DataEvent`](#abstract-dataevent).[`preventDefault`](#preventdefault-1)

##### runDefaultAction() \{#rundefaultaction-2\}

```ts
runDefaultAction(): Promise<void>;
```

Defined in: [events.ts:153](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L153)

Executes the default action for an event if it hasn't been prevented.

###### Returns

`Promise`&lt;`void`&gt;

###### Inherited from

[`DataEvent`](#abstract-dataevent).[`runDefaultAction`](#rundefaultaction-1)

##### stopPropagation() \{#stoppropagation-2\}

```ts
stopPropagation(): void;
```

Defined in: [events.ts:146](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L146)

Stops propagation to remaining event handlers.
Handlers registered after the current one will not execute.

###### Returns

`void`

###### Inherited from

[`DataEvent`](#abstract-dataevent).[`stopPropagation`](#stoppropagation-1)

## Other

### CancellableEventOptions \{#cancellableeventoptions\}

Defined in: [events.ts:39](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L39)

#### Properties

##### cancellable? \{#cancellable\}

```ts
optional cancellable?: boolean;
```

Defined in: [events.ts:41](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L41)

##### defaultAction? \{#defaultaction-3\}

```ts
optional defaultAction?: DefaultAction;
```

Defined in: [events.ts:40](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L40)

---

### deepFreeze() \{#deepfreeze\}

```ts
function deepFreeze<T>(obj): T;
```

Defined in: [events.ts:23](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/events.ts#L23)

Deep freezes an object to make it immutable at runtime.
Recursively freezes all nested objects and arrays.

#### Type Parameters

##### T

`T` _extends_ `Record`&lt;`PropertyKey`, `any`&gt;

#### Parameters

##### obj

`T`

The object to freeze

#### Returns

`T`

The frozen object (same reference)

#### Example

```typescript
const data = { user: { name: "John" } };
deepFreeze(data);
data.user.name = "Jane"; // Throws error in strict mode
```

---

## frontmatter(Utils)

Routines for serializing data structures into Markdown frontmatter blocks.

## formatFrontMatterList() \{#formatfrontmatterlist\}

```ts
function formatFrontMatterList(prop, indentation?, prefix?): string[];
```

Defined in: [frontmatter.ts:84](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/frontmatter.ts#L84)

Formats an array into a front matter YAML-like structure as string array.

### Parameters

#### prop

`unknown`

The array to format.

#### indentation?

`number` = `0`

The current indentation level. Defaults to 0.

#### prefix?

`string` = `"- "`

The prefix for each list item. Defaults to "- ".

### Returns

`string`[]

An array of strings representing the formatted front matter list.

### Example

```typescript
const list = ["item1", "item2"];
formatFrontMatterList(list);
// [
//   "- item1",
//   "- item2"
// ]
```

---

## formatFrontMatterObject() \{#formatfrontmatterobject\}

```ts
function formatFrontMatterObject(props, indentation?, prefix?): string[];
```

Defined in: [frontmatter.ts:44](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/frontmatter.ts#L44)

Formats an object into a front matter YAML-like structure as string array.

### Parameters

#### props

`unknown`

The object to format.

#### indentation?

`number` = `0`

The current indentation level. Defaults to 0.

#### prefix?

`string`

An optional prefix for each line.

### Returns

`string`[]

An array of strings representing the formatted front matter.

### Example

```typescript
const obj = { title: "My Title", tags: ["tag1", "tag2"] };
formatFrontMatterObject(obj);
// [
//   "  title: My Title",
//   "  tags:",
//   "    - tag1",
//   "    - tag2"
// ]
```

---

## formatFrontMatterProp() \{#formatfrontmatterprop\}

```ts
function formatFrontMatterProp(prop, indentation?, prefix?): string[];
```

Defined in: [frontmatter.ts:127](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/frontmatter.ts#L127)

Formats a single property into a front matter YAML-like structure as string array.

### Parameters

#### prop

`unknown`

The property to format, represented as an object with a single key-value pair.

#### indentation?

`number` = `0`

The current indentation level. Defaults to 0.

#### prefix?

`string`

An optional prefix for the property.

### Returns

`string`[]

An array of strings representing the formatted front matter property.

### Example

```typescript
const prop = { title: "My Title" };
formatFrontMatterProp(prop);
// [
//   "title: My Title"
// ]
```

---

## fs

Library of helper functions for handling files and folders.

## fsOutputAdapter \{#fsoutputadapter\}

```ts
const fsOutputAdapter: OutputAdapter;
```

Defined in: [fs.ts:124](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/fs.ts#L124)

The default output destination: the local filesystem.

Used whenever no custom `outputAdapter` is configured, so the out-of-the-box
behaviour is unchanged. Content arrives already prettified - prettifying is
the renderer's job, not the destination's.

### Example

```js
import { fsOutputAdapter } from "@graphql-markdown/utils/fs";

await fsOutputAdapter.writeFile("./docs/api/query.md", "# Query");
```

---

## ensureDir() \{#ensuredir\}

```ts
function ensureDir(location, options?): Promise<void>;
```

Defined in: [fs.ts:61](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/fs.ts#L61)

Asynchronously create a folder structure if it does not exist.

### Parameters

#### location

`string`

folder structure in path format.

#### options?

`EnsureDirOptions`

### Returns

`Promise`&lt;`void`&gt;

### Example

```js
import { ensureDir } from "@graphql-markdown/utils/fs";

await ensureDir("./.temp/local");

// Creates both folders if they do not exists.
```

---

## fileExists() \{#fileexists\}

```ts
function fileExists(location): Promise<boolean>;
```

Defined in: [fs.ts:36](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/fs.ts#L36)

Asynchronously check if a file or folder exists at the path location.

### Parameters

#### location

`string`

file or folder location.

### Returns

`Promise`&lt;`boolean`&gt;

`true` if the path is valid, else `false` if not.

### Example

```js
import { fileExists } from "@graphql-markdown/utils/fs";

await fileExists("./.temp/local");

// Expected true if path is valid, false if not
```

---

## saveFile() \{#savefile\}

```ts
function saveFile(location, content, prettify?): Promise<void>;
```

Defined in: [fs.ts:98](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/fs.ts#L98)

Asynchronously save a file with a string content at specified location in local FS.
Override the file content if the file already exists.
The function calls `ensureDir(dirname(location))` to create the folder structure if missing.

### Parameters

#### location

`string`

file location.

#### content

`string`

data to be written into the file (UTF-8 string).

#### prettify?

`PrettifyCallbackFunction`

optional callback function for prettifying the content.

### Returns

`Promise`&lt;`void`&gt;

`true` if the path is valid, else `false` if not.

### Example

```js
import { saveFile } from "@graphql-markdown/utils/fs";

await saveFile("./.temp/local.md", "foobar");

// Created .temp folder if it does not exists, and save data into local.md
```

---

## guards

Type guard utilities for common validation patterns.

This module consolidates reusable type guards that are used throughout
the codebase for validating GraphQL schema objects and other entities.

## hasArrayProperty() \{#hasarrayproperty\}

### Call Signature

```ts
function hasArrayProperty<K>(obj, key): obj is Record<K, unknown[]>;
```

Defined in: [guards.ts:111](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L111)

Type guard to check if an object has an array property.

#### Type Parameters

##### K

`K` _extends_ `PropertyKey`

#### Parameters

##### obj

`unknown`

The object to check

##### key

`K`

The property name to look for

#### Returns

`obj is Record<K, unknown[]>`

`true` if the property exists and is an array, `false` otherwise

#### Example

```typescript
import { hasArrayProperty } from "@graphql-markdown/utils/guards";

if (hasArrayProperty(type, "args")) {
  // type.args is now typed as unknown[]
  console.log(type.args.length);
}
```

### Call Signature

```ts
function hasArrayProperty(obj, key): obj is Record<PropertyKey, unknown[]>;
```

Defined in: [guards.ts:116](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L116)

Type guard to check if an object has an array property.

#### Parameters

##### obj

`unknown`

The object to check

##### key

`PropertyKey`

The property name to look for

#### Returns

`obj is Record<PropertyKey, unknown[]>`

`true` if the property exists and is an array, `false` otherwise

#### Example

```typescript
import { hasArrayProperty } from "@graphql-markdown/utils/guards";

if (hasArrayProperty(type, "args")) {
  // type.args is now typed as unknown[]
  console.log(type.args.length);
}
```

---

## hasFunctionProperty() \{#hasfunctionproperty\}

### Call Signature

```ts
function hasFunctionProperty<K>(
  obj,
  key,
): obj is Record<K, (args: unknown[]) => unknown>;
```

Defined in: [guards.ts:213](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L213)

Type guard to check if an object has a function property.

#### Type Parameters

##### K

`K` _extends_ `PropertyKey`

#### Parameters

##### obj

`unknown`

The object to check

##### key

`K`

The property name to look for

#### Returns

`obj is Record<K, (args: unknown[]) => unknown>`

`true` if the property exists and is a function, `false` otherwise

#### Example

```typescript
import { hasFunctionProperty } from "@graphql-markdown/utils/guards";

if (hasFunctionProperty(directive, "descriptor")) {
  // directive.descriptor is now typed as a function
  directive.descriptor();
}
```

### Call Signature

```ts
function hasFunctionProperty(
  obj,
  key,
): obj is Record<PropertyKey, (args: unknown[]) => unknown>;
```

Defined in: [guards.ts:218](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L218)

Type guard to check if an object has a function property.

#### Parameters

##### obj

`unknown`

The object to check

##### key

`PropertyKey`

The property name to look for

#### Returns

`obj is Record<PropertyKey, (args: unknown[]) => unknown>`

`true` if the property exists and is a function, `false` otherwise

#### Example

```typescript
import { hasFunctionProperty } from "@graphql-markdown/utils/guards";

if (hasFunctionProperty(directive, "descriptor")) {
  // directive.descriptor is now typed as a function
  directive.descriptor();
}
```

---

## hasNonEmptyArrayProperty() \{#hasnonemptyarrayproperty\}

### Call Signature

```ts
function hasNonEmptyArrayProperty<K>(obj, key): obj is Record<K, unknown[]>;
```

Defined in: [guards.ts:145](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L145)

Type guard to check if an object has a non-empty array property.

#### Type Parameters

##### K

`K` _extends_ `PropertyKey`

#### Parameters

##### obj

`unknown`

The object to check

##### key

`K`

The property name to look for

#### Returns

`obj is Record<K, unknown[]>`

`true` if the property exists, is an array, and is non-empty, `false` otherwise

#### Example

```typescript
import { hasNonEmptyArrayProperty } from "@graphql-markdown/utils/guards";

if (hasNonEmptyArrayProperty(type, "args")) {
  // type.args is a non-empty array
  const firstArg = type.args[0];
}
```

### Call Signature

```ts
function hasNonEmptyArrayProperty(
  obj,
  key,
): obj is Record<PropertyKey, unknown[]>;
```

Defined in: [guards.ts:150](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L150)

Type guard to check if an object has a non-empty array property.

#### Parameters

##### obj

`unknown`

The object to check

##### key

`PropertyKey`

The property name to look for

#### Returns

`obj is Record<PropertyKey, unknown[]>`

`true` if the property exists, is an array, and is non-empty, `false` otherwise

#### Example

```typescript
import { hasNonEmptyArrayProperty } from "@graphql-markdown/utils/guards";

if (hasNonEmptyArrayProperty(type, "args")) {
  // type.args is a non-empty array
  const firstArg = type.args[0];
}
```

---

## hasProperties() \{#hasproperties\}

```ts
function hasProperties<K>(obj, ...keys): obj is Record<K, unknown>;
```

Defined in: [guards.ts:82](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L82)

Type guard to check if an object has multiple specific properties.

### Type Parameters

#### K

`K` _extends_ `PropertyKey`

### Parameters

#### obj

`unknown`

The object to check

#### keys

...`K`[]

The property names to look for

### Returns

`obj is Record<K, unknown>`

`true` if the object has all the properties, `false` otherwise

### Example

```typescript
import { hasProperties } from "@graphql-markdown/utils/guards";

if (hasProperties(type, "name", "description")) {
  // Both properties exist on type
  console.log(type.name, type.description);
}
```

---

## hasProperty() \{#hasproperty\}

### Call Signature

```ts
function hasProperty<K>(obj, key): obj is Record<K, unknown>;
```

Defined in: [guards.ts:48](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L48)

Type guard to check if an object has a specific property.

#### Type Parameters

##### K

`K` _extends_ `PropertyKey`

#### Parameters

##### obj

`unknown`

The object to check

##### key

`K`

The property name to look for

#### Returns

`obj is Record<K, unknown>`

`true` if the object has the property, `false` otherwise

#### Example

```typescript
import { hasProperty } from "@graphql-markdown/utils/guards";

if (hasProperty(type, "args")) {
  // type.args is now accessible
  console.log(type.args);
}
```

### Call Signature

```ts
function hasProperty(obj, key): obj is Record<PropertyKey, unknown>;
```

Defined in: [guards.ts:53](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L53)

Type guard to check if an object has a specific property.

#### Parameters

##### obj

`unknown`

The object to check

##### key

`PropertyKey`

The property name to look for

#### Returns

`obj is Record<PropertyKey, unknown>`

`true` if the object has the property, `false` otherwise

#### Example

```typescript
import { hasProperty } from "@graphql-markdown/utils/guards";

if (hasProperty(type, "args")) {
  // type.args is now accessible
  console.log(type.args);
}
```

---

## hasStringProperty() \{#hasstringproperty\}

### Call Signature

```ts
function hasStringProperty<K>(obj, key): obj is Record<K, string>;
```

Defined in: [guards.ts:179](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L179)

Type guard to check if an object has a string property.

#### Type Parameters

##### K

`K` _extends_ `PropertyKey`

#### Parameters

##### obj

`unknown`

The object to check

##### key

`K`

The property name to look for

#### Returns

`obj is Record<K, string>`

`true` if the property exists and is a string, `false` otherwise

#### Example

```typescript
import { hasStringProperty } from "@graphql-markdown/utils/guards";

if (hasStringProperty(type, "description")) {
  // type.description is now typed as string
  console.log(type.description.length);
}
```

### Call Signature

```ts
function hasStringProperty(obj, key): obj is Record<PropertyKey, string>;
```

Defined in: [guards.ts:184](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L184)

Type guard to check if an object has a string property.

#### Parameters

##### obj

`unknown`

The object to check

##### key

`PropertyKey`

The property name to look for

#### Returns

`obj is Record<PropertyKey, string>`

`true` if the property exists and is a string, `false` otherwise

#### Example

```typescript
import { hasStringProperty } from "@graphql-markdown/utils/guards";

if (hasStringProperty(type, "description")) {
  // type.description is now typed as string
  console.log(type.description.length);
}
```

---

## isNonEmptyArray() \{#isnonemptyarray\}

```ts
function isNonEmptyArray(value): value is unknown[];
```

Defined in: [guards.ts:246](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L246)

Type guard to check if a value is a non-empty array.

### Parameters

#### value

`unknown`

The value to check

### Returns

`value is unknown[]`

`true` if the value is an array with at least one element

### Example

```typescript
import { isNonEmptyArray } from "@graphql-markdown/utils/guards";

if (isNonEmptyArray(values)) {
  // values is now typed as unknown[] with at least one element
  console.log(values[0]);
}
```

---

## isTypeObject() \{#istypeobject\}

```ts
function isTypeObject(obj): obj is Record<string, unknown>;
```

Defined in: [guards.ts:27](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/guards.ts#L27)

Type guard to check if a value is an object but not an array.

### Parameters

#### obj

`unknown`

The value to check

### Returns

`obj is Record<string, unknown>`

`true` if the value is a non-null object but not an array, `false` otherwise

### Example

```typescript
import { isTypeObject } from "@graphql-markdown/utils/guards";

if (isTypeObject(value)) {
  // value is now typed as Record<string, unknown> and is not an array
  // (includes Date, Map, and other object types)
  console.log(Object.keys(value));
}
```

---

## markdown(Utils)

Shared Markdown constants used across packages.

## FRONT_MATTER_DELIMITER \{#front_matter_delimiter\}

```ts
const FRONT_MATTER_DELIMITER: "---";
```

Defined in: [markdown.ts:20](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/markdown.ts#L20)

Frontmatter delimiter for YAML frontmatter blocks.

---

## MARKDOWN_CODE_INDENTATION \{#markdown_code_indentation\}

```ts
const MARKDOWN_CODE_INDENTATION: "  ";
```

Defined in: [markdown.ts:30](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/markdown.ts#L30)

Standard indentation for code blocks (2 spaces).

---

## MARKDOWN_CODE_SNIPPET \{#markdown_code_snippet\}

```ts
const MARKDOWN_CODE_SNIPPET: "``";
```

Defined in: [markdown.ts:25](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/markdown.ts#L25)

Code snippet delimiter for fenced code blocks.

---

## MARKDOWN_EOL \{#markdown_eol\}

```ts
const MARKDOWN_EOL: "\n";
```

Defined in: [markdown.ts:10](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/markdown.ts#L10)

End of line character for Markdown.

---

## MARKDOWN_EOP \{#markdown_eop\}

```ts
const MARKDOWN_EOP: string;
```

Defined in: [markdown.ts:15](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/markdown.ts#L15)

End of paragraph (double newline) for Markdown.

---

## object(Utils)

Internal library of helpers for manipulating objects.

## isEmpty() \{#isempty\}

```ts
function isEmpty<T>(obj): obj is Exclude<unknown, T>;
```

Defined in: [object.ts:34](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/object.ts#L34)

**`Internal`**

Check if an object contains key/value records.

### Type Parameters

#### T

`T` _extends_ `Record`&lt;`string`, `unknown`&gt;

### Parameters

#### obj

`unknown`

the key/value record object.

### Returns

`obj is Exclude<unknown, T>`

`false` if the object is a valid k/v set of records, else `true`.

### Example

```js
import { isEmpty } from "@graphql-markdown/utils/object";

const obj = {
  bool: true,
  string: "test",
  number: 123,
  array: ["one", "two"],
  child: { key: "value" },
};

isEmpty(obj); // Returns false

isEmpty({}); // Returns true
```

---

## prettier

Internal library for prettifying files using `prettier`.

## prettify() \{#prettify\}

```ts
function prettify(content, parser): Promise<string | undefined>;
```

Defined in: [prettier.ts:25](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/prettier.ts#L25)

**`Internal`**

Prettify a string using

### Parameters

#### content

`string`

the string to be prettified.

#### parser

`string`

the `prettier` parser to use.

### Returns

`Promise`&lt;`string` \| `undefined`&gt;

a prettified string, or `undefined` if an error occurred.

### See

- [prettier.format](https://prettier.io/docs/en/api#prettierformatsource-options)
- [Prettier doc for the list of parsers](https://prettier.io/docs/en/options#parser)

### Remarks

This function logs a warning message on error.

---

## prettifyMarkdown() \{#prettifymarkdown\}

```ts
function prettifyMarkdown(content): Promise<string | undefined>;
```

Defined in: [prettier.ts:67](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/prettier.ts#L67)

**`Internal`**

Prettify a Markdown string using [prettify](#prettify) and `markdown` parser.

### Parameters

#### content

`string`

the string to be prettified.

### Returns

`Promise`&lt;`string` \| `undefined`&gt;

a prettified string, or `undefined` if an error occurred.

### Remarks

Same as `prettify(content, "mdx")`.

### See

[prettify](#prettify)

---

## string

Library of helpers for formatting strings.

## slugify \{#slugify\}

```ts
const slugify: (str) => string = kebabCase;
```

Defined in: [string.ts:283](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L283)

Returns a lowercase string with `-` as replacement for non alphanum characters using [stringCaseBuilder](#stringcasebuilder).

### Parameters

#### str

`Maybe`&lt;`string`&gt;

the string to be transformed.

### Returns

`string`

a string converted to start case, or an empty string if `str` is not a valid string.

### Example

```js
import { kebabCase } from "@graphql-markdown/utils/string";

kebabCase("The quick brown Fox");
// Expected result: "the-quick-brown-fox"
```

---

## toString \{#tostring\}

```ts
const toString: StringConstructor = String;
```

Defined in: [string.ts:293](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L293)

Returns a stringified version of the variable.

### Param

**variable**

the variable to be transformed.

### Returns

a string

---

## capitalize() \{#capitalize\}

```ts
function capitalize(str): string;
```

Defined in: [string.ts:224](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L224)

Returns a string in lowercase excepted for the 1st character capitalized using [firstUppercase](#firstuppercase).

### Parameters

#### str

`Maybe`&lt;`string`&gt;

the string to be transformed.

### Returns

`string`

a capitalized string, or an empty string if `str` is not a valid string.

### Example

```js
import { capitalize } from "@graphql-markdown/utils/string";

capitalize("the quick Brown Fox");
// Expected result: "The quick brown fox"
```

---

## escapeMDX() \{#escapemdx\}

```ts
function escapeMDX(str): string;
```

Defined in: [string.ts:177](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L177)

**`Internal`**

Returns a string with MDX special characters converted to HTML unicode using [toHTMLUnicode](#tohtmlunicode).
Characters within code notation should not be converted.
List of special characters: `{`, `<`, `>`, `}`

### Parameters

#### str

`unknown`

the string to be transformed.

### Returns

`string`

a string with MDX special characters replaced by HTML unicode equivalents.

### Example

```js
import { escapeMDX } from "@graphql-markdown/utils/string";

escapeMDX("{MDX} <special> characters");
// Expected result: "&#x007B;MDX&#x007D; &#x003C;special&#x003E; characters"

escapeMDX("`{MDX}` `<special>` characters");
// Expected result: "`{MDX}` `<special>` characters"
```

---

## firstUppercase() \{#firstuppercase\}

```ts
function firstUppercase(str): string;
```

Defined in: [string.ts:200](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L200)

Returns a string with the 1st character in uppercase.

### Parameters

#### str

`Maybe`&lt;`string`&gt;

the string to be transformed.

### Returns

`string`

a string with the 1st character in uppercase, or an empty string if `str` is not a valid string.

### Example

```js
import { firstUppercase } from "@graphql-markdown/utils/string";

firstUppercase("the quick Brown Fox");
// Expected result: "The quick Brown Fox"
```

---

## kebabCase() \{#kebabcase\}

```ts
function kebabCase(str): string;
```

Defined in: [string.ts:267](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L267)

Returns a lowercase string with `-` as replacement for non alphanum characters using [stringCaseBuilder](#stringcasebuilder).

### Parameters

#### str

`Maybe`&lt;`string`&gt;

the string to be transformed.

### Returns

`string`

a string converted to start case, or an empty string if `str` is not a valid string.

### Example

```js
import { kebabCase } from "@graphql-markdown/utils/string";

kebabCase("The quick brown Fox");
// Expected result: "the-quick-brown-fox"
```

---

## prune() \{#prune\}

```ts
function prune(str, substr?): string;
```

Defined in: [string.ts:58](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L58)

**`Internal`**

Returns a string pruned on both start and end, similar to `trim()` but with any substring.

### Parameters

#### str

`Maybe`&lt;`string`&gt;

the string to be pruned.

#### substr?

`string` = `""`

the substring to be removed from `str`.

### Returns

`string`

a pruned string, or an empty string if `str` is not a valid string.

### Example

```js
import { prune } from "@graphql-markdown/utils/string";

const text = "**The quick brown fox jumps over the lazy dog.**";

prune(text, "**");
// Expected result: "The quick brown fox jumps over the lazy dog."
```

---

## replaceDiacritics() \{#replacediacritics\}

```ts
function replaceDiacritics(str): string;
```

Defined in: [string.ts:27](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L27)

Replaces diacritics by non-diacritic equivalent characters.

### Parameters

#### str

`Maybe`&lt;`string`&gt;

the string to be transformed.

### Returns

`string`

a string with diacritic characters replaced, or an empty string if `str` is not a valid string.

-

### Example

```js
import { replaceDiacritics } from "@graphql-markdown/utils/string";

replaceDiacritics("Âéêś"); // Expected result: "Aees"
```

### See

[StackOverflow source](https://stackoverflow.com/a/37511463)

---

## startCase() \{#startcase\}

```ts
function startCase(str): string;
```

Defined in: [string.ts:246](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L246)

Applies [firstUppercase](#firstuppercase) using [stringCaseBuilder](#stringcasebuilder) to every word of a string with `space` character as separator.

### Parameters

#### str

`Maybe`&lt;`string`&gt;

the string to be transformed.

### Returns

`string`

a string converted to start case, or an empty string if `str` is not a valid string.

### Example

```js
import { startCase } from "@graphql-markdown/utils/string";

startCase("the quick Brown Fox");
// Expected result: "The Quick Brown Fox"
```

---

## stringCaseBuilder() \{#stringcasebuilder\}

```ts
function stringCaseBuilder(str, transformation?, separator?, splitter?): string;
```

Defined in: [string.ts:100](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L100)

**`Internal`**

Returns a string after applying a transformation function.
By default `splitter` expression will split the string into words, where non-alphanum chars are considered as word separators.
`separator` will be used for joining the words back together.
[prune](#prune) using `separator` is applied to the result of the transformation.

### Parameters

#### str

`Maybe`&lt;`string`&gt;

the string to be transformed.

#### transformation?

`Maybe`&lt;(`word`) => `string`&gt;

optional transformation callback function.

#### separator?

`string`

optional character separator for word-based transformation.

#### splitter?

`string` \| `RegExp`

optional regex or string rule for splitting string into word.

### Returns

`string`

a transformed string, or an empty string if `str` is not a valid string.

### Example

```js
import { stringCaseBuilder } from "@graphql-markdown/utils/string";

const text = "The quick brown fox jumps over the lazy dog.";
const transformation = (word: string): string => `*${word}*`

stringCaseBuilder(text, transformation, " ");
// Expected result: "*The* *quick* *brown* *fox* *jumps* *over* *the* *lazy* *dog*"
```

---

## toHTMLUnicode() \{#tohtmlunicode\}

```ts
function toHTMLUnicode(char): string;
```

Defined in: [string.ts:146](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/string.ts#L146)

**`Internal`**

Converts a character to its equivalent HTML unicode representation `&#x0000`.

### Parameters

#### char

`Maybe`&lt;`string`&gt;

the character to be transformed.

### Returns

`string`

a HTML unicode representation of `char`, or an empty string if `char` is not a valid string.

### Example

```js
import { toHTMLUnicode } from "@graphql-markdown/utils/string";

toHTMLUnicode("%"); // Expected result: "&#x0025;"
```

---

## url

Alias `path.posix` to normalize URL handling on Windows.

## RelativeGeneratedDocLinkOptions \{#relativegenerateddoclinkoptions\}

Defined in: [url.ts:15](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/url.ts#L15)

### Properties

#### baseURL \{#baseurl\}

```ts
baseURL: string;
```

Defined in: [url.ts:16](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/url.ts#L16)

#### currentFilePath \{#currentfilepath\}

```ts
currentFilePath: string;
```

Defined in: [url.ts:17](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/url.ts#L17)

#### extension? \{#extension\}

```ts
optional extension?: string;
```

Defined in: [url.ts:18](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/url.ts#L18)

#### outputDir \{#outputdir\}

```ts
outputDir: string;
```

Defined in: [url.ts:19](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/url.ts#L19)

#### targetUrlPath \{#targeturlpath\}

```ts
targetUrlPath: string;
```

Defined in: [url.ts:20](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/url.ts#L20)

---

## toRelativeGeneratedDocLink() \{#torelativegenerateddoclink\}

```ts
function toRelativeGeneratedDocLink(__namedParameters): string | undefined;
```

Defined in: [url.ts:34](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/utils/src/url.ts#L34)

Converts a generated absolute GraphQL-Markdown doc URL into a page-relative file path.
Returns `undefined` when the target URL does not belong to the configured `baseURL`.

### Parameters

#### \_\_namedParameters

[`RelativeGeneratedDocLinkOptions`](#relativegenerateddoclinkoptions)

### Returns

`string` \| `undefined`