Question 1

What is GraphQL-Markdown?

Accepted Answer

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.

Question 2

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

Accepted Answer

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.

Question 3

Can GraphQL-Markdown generate docs for custom directives?

Accepted Answer

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.

Question 4

How is GraphQL-Markdown different from SpectaQL or GraphDoc?

Accepted Answer

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.

Question 5

Is GraphQL-Markdown free to use?

Accepted Answer

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.

GraphQL-Markdown Showcase