What is GraphQL-Markdown?

GraphQL-Markdown is an open-source command-line tool and JavaScript/TypeScript library that auto-generates human-friendly Markdown and MDX documentation from any GraphQL schema. It supports Docusaurus out of the box and works with any MDX framework.

Does GraphQL-Markdown work with Apollo, Hasura, or custom GraphQL servers?

Yes. GraphQL-Markdown reads schemas from SDL files, introspection endpoints, or GraphQL config, so it works with Apollo Server, Hasura, GraphQL Yoga, and any server that exposes a standard GraphQL schema.

Can GraphQL-Markdown generate docs for custom directives?

Yes. You can document custom directives, group types by directive, and use directive metadata to drive deprecation notices, tags, access-control badges, and other custom sections in the generated output.

How is GraphQL-Markdown different from SpectaQL or GraphDoc?

SpectaQL and GraphDoc produce standalone HTML sites. GraphQL-Markdown produces Markdown/MDX files that you commit alongside your existing docs site, so you keep your theme, search, versioning, and navigation. It is ideal for teams already using Docusaurus, Astro, Next.js, or any MDX-based framework.

Is GraphQL-Markdown free to use?

Yes. GraphQL-Markdown is free and open-source under the MIT license. If you use it in production, consider planting a tree via the Treeware initiative to support the project.

events

Print type event classes.

Event classes for print operations that allow handlers to modify the generated output.

Events

BeforeComposePageTypeEvent

Defined in: printer-legacy/src/events.ts:114

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

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<ComposePageTypeEventData, keyof PageSections[]>

Constructors

Constructor

new BeforeComposePageTypeEvent(
   data,
   initialOutput,
   options?): BeforeComposePageTypeEvent;

Defined in: printer-legacy/src/events.ts:118

Parameters

Properties

data

readonly data: ComposePageTypeEventData;

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

Inherited from

DataOutputEvent.data

output

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.output

Accessors

defaultAction

Get Signature

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.defaultAction

defaultPrevented

Get Signature

get defaultPrevented(): boolean;

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

Returns

boolean

Set Signature

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.defaultPrevented

propagationStopped

Get Signature

get propagationStopped(): boolean;

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

Returns

boolean

Set Signature

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.propagationStopped

Methods

preventDefault()

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.preventDefault

runDefaultAction()

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<void>

Inherited from

DataOutputEvent.runDefaultAction

stopPropagation()

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.stopPropagation

PrintCodeEvent

Defined in: printer-legacy/src/events.ts:48

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

events.on(PrintTypeEvents.AFTER_PRINT_CODE, (event: PrintCodeEvent) => {
  // Add a comment to all generated code
  event.output = `# Auto-generated\n${event.output}`;
});

Extends

DataOutputEvent<PrintCodeEventData, string>

Implements

IPrintCodeEvent

Constructors

Constructor

new PrintCodeEvent(
   data,
   initialOutput,
   options?): PrintCodeEvent;

Defined in: printer-legacy/src/events.ts:52

Parameters

data

PrintCodeEventData

initialOutput

string

options?

CancellableEventOptions

Returns

PrintCodeEvent

Overrides

DataOutputEvent.constructor

Properties

data

readonly data: PrintCodeEventData;

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

Implementation of

IPrintCodeEvent.data;

Inherited from

DataOutputEvent.data

output

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

IPrintCodeEvent.output;

Inherited from

DataOutputEvent.output

Accessors

defaultAction

Get Signature

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

IPrintCodeEvent.defaultAction;

Inherited from

PrintTypeEvent.defaultAction

defaultPrevented

Get Signature

get defaultPrevented(): boolean;

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

Returns

boolean

Set Signature

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

IPrintCodeEvent.defaultPrevented;

Inherited from

DataOutputEvent.defaultPrevented

propagationStopped

Get Signature

get propagationStopped(): boolean;

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

Returns

boolean

Set Signature

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

IPrintCodeEvent.propagationStopped;

Inherited from

DataOutputEvent.propagationStopped

Methods

preventDefault()

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

IPrintCodeEvent.preventDefault;

Inherited from

DataOutputEvent.preventDefault

runDefaultAction()

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<void>

Implementation of

IPrintCodeEvent.runDefaultAction;

Inherited from

DataOutputEvent.runDefaultAction

stopPropagation()

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

IPrintCodeEvent.stopPropagation;

Inherited from

DataOutputEvent.stopPropagation

PrintTypeEvent

Defined in: printer-legacy/src/events.ts:77

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

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<PrintTypeEventData, Maybe<MDXString>>

Implements

IPrintTypeEvent

Constructors

Constructor

new PrintTypeEvent(
   data,
   initialOutput,
   options?): PrintTypeEvent;

Defined in: printer-legacy/src/events.ts:81

Parameters

data

PrintTypeEventData

initialOutput

Maybe<MDXString>

options?

CancellableEventOptions

Returns

PrintTypeEvent

Overrides

DataOutputEvent.constructor

Properties

data

readonly data: PrintTypeEventData;

Defined in: utils/dist/events.d.ts:111

Read-only event data payload.

Implementation of

IPrintTypeEvent.data;

Inherited from

DataOutputEvent.data

output

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

IPrintTypeEvent.output;

Inherited from

DataOutputEvent.output

Accessors

defaultAction

Get Signature

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

IPrintTypeEvent.defaultAction;

Inherited from

DataOutputEvent.defaultAction

defaultPrevented

Get Signature

get defaultPrevented(): boolean;

Defined in: utils/dist/events.d.ts:70

Gets whether the default action has been prevented.

Returns

boolean

Set Signature

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

IPrintTypeEvent.defaultPrevented;

Inherited from

DataOutputEvent.defaultPrevented

propagationStopped

Get Signature

get propagationStopped(): boolean;

Defined in: utils/dist/events.d.ts:74

Gets whether propagation has been stopped.

Returns

boolean

Set Signature

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

IPrintTypeEvent.propagationStopped;

Inherited from

DataOutputEvent.propagationStopped

Methods

preventDefault()

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

IPrintTypeEvent.preventDefault;

Inherited from

DataOutputEvent.preventDefault

runDefaultAction()

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<void>

Implementation of

IPrintTypeEvent.runDefaultAction;

Inherited from

DataOutputEvent.runDefaultAction

stopPropagation()

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

IPrintTypeEvent.stopPropagation;

Inherited from

DataOutputEvent.stopPropagation

Other

ComposePageTypeEventData

Defined in: types/src/printer.d.ts:114

Data payload for compose page type events.

Properties

name

readonly name: Maybe<string>;

Defined in: types/src/printer.d.ts:118

The name identifier for the type

options

readonly options: PrintTypeOptions;

Defined in: types/src/printer.d.ts:120

The print options in effect

sections

readonly sections: PageSections;

Defined in: types/src/printer.d.ts:122

The map of all page sections (mutable in BEFORE event)

type

readonly type: unknown;

Defined in: types/src/printer.d.ts:116

The GraphQL type being composed

PageSection

Defined in: types/src/printer.d.ts:24

Represents a single section of a page with optional title and content.

Properties

content?

optional content?:
  | string
  | MDXString
  | PageSection
  | PageSection[];

Defined in: types/src/printer.d.ts:30

The section content

level?

optional level?: number;

Defined in: types/src/printer.d.ts:28

Optional section level for hierarchical structuring

title?

optional title?: string | MDXString;

Defined in: types/src/printer.d.ts:26

Optional title/heading for the section

PageSections

Defined in: types/src/printer.d.ts:36

Map of all available sections in a type page.

Indexable

[key: string]: Maybe<PageSection | PageHeader>

Additional custom sections can be added by event handlers

Properties

code?

optional code?: PageSection;

Defined in: types/src/printer.d.ts:50

GraphQL code block

customDirectives?

optional customDirectives?: PageSection;

Defined in: types/src/printer.d.ts:52

Custom directives

description?

optional description?: PageSection;

Defined in: types/src/printer.d.ts:48

Type description from GraphQL comments

example?

optional example?: PageSection;

Defined in: types/src/printer.d.ts:56

Usage examples

optional header?: PageHeader;

Defined in: types/src/printer.d.ts:40

YAML frontmatter or top-level heading

mdxDeclaration?

optional mdxDeclaration?: PageHeader;

Defined in: types/src/printer.d.ts:44

MDX import declarations

metadata?

optional metadata?: PageSection;

Defined in: types/src/printer.d.ts:54

Type metadata (fields, arguments, etc.)

metatags?

optional metatags?: PageHeader;

Defined in: types/src/printer.d.ts:42

HTML meta tags

relations?

optional relations?: PageSection;

Defined in: types/src/printer.d.ts:58

Related types

tags?

optional tags?: PageSection;

Defined in: types/src/printer.d.ts:46

Custom tags (e.g., @deprecated)

PrintCodeEventData

Defined in: types/src/printer.d.ts:64

Data payload for print code events.

Properties

options

readonly options: PrintTypeOptions;

Defined in: types/src/printer.d.ts:70

The print options in effect

type

readonly type: unknown;

Defined in: types/src/printer.d.ts:66

The GraphQL type being printed

typeName

readonly typeName: string;

Defined in: types/src/printer.d.ts:68

The name of the type

PrintTypeEventData

Defined in: types/src/printer.d.ts:76

Data payload for print type events.

Properties

name

readonly name: Maybe<string>;

Defined in: types/src/printer.d.ts:80

The name identifier for the type

options

readonly options: PrintTypeOptions;

Defined in: types/src/printer.d.ts:82

The print options in effect

type

readonly type: unknown;

Defined in: types/src/printer.d.ts:78

The GraphQL type being printed

Events​

BeforeComposePageTypeEvent​

Example​

Extends​

Constructors​

Constructor​

Parameters​

data​

initialOutput​

options?​

Returns​

Overrides​

Properties​

data​

Inherited from​

output​

Inherited from​

Accessors​

defaultAction​

Get Signature​

Returns​

Inherited from​

defaultPrevented​

Get Signature​

Returns​

Set Signature​

Parameters​

value​

Returns​

Inherited from​

propagationStopped​

Get Signature​

Returns​

Set Signature​

Parameters​

value​

Returns​

Inherited from​

Methods​

preventDefault()​

Returns​

Inherited from​

runDefaultAction()​

Returns​

Inherited from​

stopPropagation()​

Returns​

Inherited from​

PrintCodeEvent​

Example​

Extends​

Implements​

Constructors​

Constructor​

Parameters​

data​

initialOutput​

options?​

Returns​

Overrides​

Properties​

data​

Implementation of​

Inherited from​

output​

Implementation of​

Inherited from​

Accessors​

defaultAction​

Get Signature​

Returns​

Implementation of​

Inherited from​

defaultPrevented​

Get Signature​

Returns​

Set Signature​

Parameters​

value​

Returns​

Events

BeforeComposePageTypeEvent

Example

Extends

Constructors

Constructor

Parameters

data

initialOutput

options?

Returns

Overrides

Properties

data

Inherited from

output

Inherited from

Accessors

defaultAction

Get Signature

Returns

Inherited from

defaultPrevented

Get Signature

Returns

Set Signature

Parameters

value

Returns

Inherited from

propagationStopped

Get Signature

Returns

Set Signature

Parameters

value

Returns

Inherited from

Methods

preventDefault()

Returns

Inherited from

runDefaultAction()

Returns

Inherited from

stopPropagation()

Returns

Inherited from

PrintCodeEvent

Example

Extends

Implements

Constructors

Constructor

Parameters

data

initialOutput

options?

Returns

Overrides

Properties

data

Implementation of

Inherited from

output

Implementation of

Inherited from

Accessors

defaultAction

Get Signature

Returns

Implementation of

Inherited from

defaultPrevented

Get Signature

Returns

Set Signature

Parameters

value

Returns