@graphql-markdown/formatters
Framework formatter presets for GraphQL-Markdown.
This package provides ready-to-use formatter presets for popular documentation frameworks, with each formatter in its own package subpath.
Installation
npm install @graphql-markdown/formatters
Usage
Use any formatter in your GraphQL-Markdown configuration:
schema: ./schema.graphql
extensions:
graphql-markdown:
rootPath: ./docs
baseURL: api
formatter: "@graphql-markdown/formatters/docusaurus"
Or programmatically:
import { runGraphQLMarkdown } from "@graphql-markdown/cli";
await runGraphQLMarkdown({
schema: "./schema.graphql",
rootPath: "./docs",
baseURL: "api",
formatter: "@graphql-markdown/formatters/docusaurus",
});
The legacy mdxParser setting still works as a deprecated alias, but new configurations should use formatter.
Supported formatters
Each formatter has its own setup guide:
| Framework | Package Path | Documentation |
|---|---|---|
| Astro Starlight | @graphql-markdown/formatters/starlight | Guide |
| DocFX | @graphql-markdown/formatters/docfx | Guide |
| Docusaurus | @graphql-markdown/formatters/docusaurus | Guide |
| HonKit | @graphql-markdown/formatters/honkit | Guide |
| Hugo | @graphql-markdown/formatters/hugo | Guide |
| mdBook | @graphql-markdown/formatters/mdbook | Guide |
| Generic MDX | @graphql-markdown/formatters/mdx | Guide |
| MkDocs | @graphql-markdown/formatters/mkdocs | Guide |
| Next.js + Fumadocs | @graphql-markdown/formatters/fumadocs | Guide |
| Vocs | @graphql-markdown/formatters/vocs | Guide |
Custom formatter
For frameworks not listed above, create a custom MDX module. See the Integration Guide for the full formatter contract, the formatMDXDetails \r delimiter invariant, and examples of extending a preset.
Documentation
Contributing
Add a new formatter
- Create the formatter module at
src/<name>/index.ts. - Create documentation at
src/<name>/README.md. - Export the formatter from
src/index.ts. - Add a package subpath export for
./<name>inpackage.jsonunderexports. - Add unit tests in
tests/unit/<name>/index.test.ts.
Formatter contract
A formatter module exports createMDXFormatter and any subset of the standard formatter functions (formatMDXBadge, formatMDXAdmonition, formatMDXBullet, formatMDXDetails, formatMDXFrontmatter, formatMDXLink, formatMDXNameEntity, formatMDXSpecifiedByLink). Optional exports include mdxDeclaration, mdxExtension, and lifecycle hooks.
See the Integration Guide for the full contract, type signatures, and the formatMDXDetails \r delimiter invariant.
Testing checklist
Add tests that verify:
- Each formatter function output for representative inputs.
createMDXFormatterreturns all required formatter methods.- Framework-specific behavior and edge cases (for example link extension mapping, frontmatter behavior, empty title fallback).
Run targeted tests while developing:
cd packages/formatters
bun run test:unit -- tests/unit/<name>/index.test.ts
Run package checks before opening a PR:
cd packages/formatters
bun run lint
bun run prettier
bun run test:unit
For repository-wide validation:
cd /path/to/graphql-markdown
bun run test
License
GraphQL-Markdown packages are 100% free and open-source, under the MIT license.
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest, you'll be creating employment for local families and restoring wildlife habitats.