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 includes a site scaffolder for Nuxt and Docusaurus, an official Docusaurus integration, a Nuxt theme, and formatter presets for supported documentation ecosystems such as Hugo, MkDocs, DocFX, and mdBook.

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 and MDX files that you commit alongside your existing docs site, so you keep your theme, search, versioning, and navigation. It is a good fit for Docusaurus and Nuxt, and for supported formatter-based ecosystems such as Hugo, MkDocs, DocFX, and mdBook.

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