🌻 Your GraphQL docs are getting better with a 1st class support for namespaced operations and improved section permalink anchors.

What's New

• Nested operation namespaces are now supported, allowing operation trees to be rendered with dotted namespaces and structured output (#2717).

• Section links can now use predefined header IDs through docOptions.sectionHeaderId (enabled by default), with CLI opt-out via noSectionId (#2713).

Full Changelog: 1.32.1...1.33.0

🐛 This release fixes broken packages from 1.32.0 due to issues with introducing bun in the development flow.

Introducing Printer Hooks, giving you full control over the generated code and documentation output!

What's New

New lifecycle hooks allow you to intercept and modify the printer output:

• beforePrintCodeHook / afterPrintCodeHook - Customize code block generation
• beforePrintTypeHook / afterPrintTypeHook - Customize type documentation generation

Usage Example

const DocusaurusMDX = require("@graphql-markdown/docusaurus/mdx");

const afterPrintCodeHook = async (event) => {
  // Add response type information after operations
  event.output = `${event.output}\n\n<!-- Custom content -->`;
};

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

See the Hooks Recipes documentation for detailed examples including how to display response types for operations.

Other Changes

• 🐛 Fixed missing MDX import declaration in generated files when using custom mdxParser
• 📝 Updated documentation for hooks and framework integration
• ♻️ Moved to more event-driven architecture for better extensibility

Full Changelog: 1.31.0...1.32.0

🐛 This release fixes broken packages from 1.31.0

🎯 New Feature: Custom Category Sorting

We're excited to introduce the categorySort option, giving you full control over how your GraphQL documentation categories are organized in the sidebar!

What's New

The new categorySort option allows you to define custom ordering for auto-generated documentation categories. Choose between:

• "natural" - Alphabetical sorting of categories
• Custom compare function: define your own sorting logic (similar to Array.sort())

Bonus: When categorySort is enabled, folder names are automatically prefixed with zero-padded order numbers (e.g., 01-objects, 02-queries, 03-mutations), ensuring consistent ordering across your file explorer, IDE, and documentation sidebar.

Usage Examples

Simple Alphabetical Sorting

plugins: [
  [
    "@graphql-markdown/docusaurus",
    {
      schema: "./schema.graphql",
      rootPath: "./docs",
      baseURL: "api",
      // highlight-start
      docOptions: {
        categorySort: "natural", // Alphabetical sorting with auto-prefixing
      },
      // highlight-end
    },
  ],
];

Result: Categories are sorted alphabetically and folders are prefixed:

docs/api/
├── 01-objects/
├── 02-enums/
├── 03-queries/
└── 04-mutations/

Custom Sort Function

Define your own category ordering logic:

plugins: [
  [
    "@graphql-markdown/docusaurus",
    {
      schema: "./schema.graphql",
      rootPath: "./docs",
      baseURL: "api",
      // highlight-start
      docOptions: {
        categorySort: (a, b) => {
          // Custom order: queries first, then mutations, then everything else alphabetically
          const order = { queries: 1, mutations: 2 };
          const aOrder = order[a.toLowerCase()] || 999;
          const bOrder = order[b.toLowerCase()] || 999;
          
          if (aOrder !== bOrder) {
            return aOrder - bOrder;
          }
          return a.localeCompare(b); // Alphabetical for others
        },
      },
      // highlight-end
    },
  ],
];

Result: Custom-ordered categories with auto-prefixes:

docs/api/
├── 01-queries/
├── 02-mutations/
├── 03-enums/
└── 04-objects/

Works with Group-by-Directive

The categorySort option integrates seamlessly with the groupByDirective feature:

plugins: [
  [
    "@graphql-markdown/docusaurus",
    {
      schema: "./schema.graphql",
      rootPath: "./docs",
      baseURL: "api",
      // highlight-start
      groupByDirective: {
        directive: "doc",
        field: "category",
        fallback: "Common",
      },
      docOptions: {
        categorySort: "natural", // Sort custom groups alphabetically
      },
      // highlight-end
    },
  ],
];

Result: Custom groups are sorted and prefixed:

docs/api/
├── 01-authentication/
├── 02-common/
├── 03-payments/
└── 04-users/

Why Use Category Sorting?

• Better Organization: Control exactly how your API documentation is organized
• Consistent Experience: Same ordering across sidebar, file explorer, and IDE
• Flexible: Use built-in alphabetical sorting or define custom logic
• No Manual Work: Auto-prefixing eliminates the need to manually name folders with numbers

Documentation

For complete details and advanced use cases, see:

• Settings: docOptions.categorySort
• Configuration Cheatsheet

🎣 Preview: Enhanced Hooks & Event System

We're excited to introduce the foundation of a more extensible GraphQL-Markdown! This release migrates to native Node.js events and lays the groundwork for comprehensive hooks at every stage of the documentation generation lifecycle.

What's Here Now

• Lifecycle Event Hooks: Initial hooks for key generation stages (schema loading, rendering, index generation) using Node.js native EventEmitter
• Type-Safe Events: Full TypeScript definitions for safer custom implementations

What's Coming Next

This is just the beginning! Future releases will expose more hooks and events throughout the entire documentation generation process:

• Pre/post hooks for schema processing and validation
• Events during type discovery and categorization
• Hooks for frontmatter and metadata manipulation
• Integration points for custom renderers and formatters
• Real-time progress tracking and logging events

Our goal is to give you complete control over the documentation generation lifecycle, enabling deep customization at every step.

What You Can Do Today

The current hooks system allows you to:

• Generate custom index files for documentation categories
• Append metadata to rendered pages automatically

Example

Create custom index.md files using the new hooks:

import { join } from "node:path";
import { ensureDir, saveFile, startCase } from "@graphql-markdown/utils";

/**
 * Hook executed before generating index metadata files
 */
const beforeGenerateIndexMetafileHook = async ({ dirPath, category }) => {
  const filePath = join(dirPath, "index.md");
  const label = startCase(category);
  const content = `---\ntitle: "${label}"\n---\n\n`;
  
  await ensureDir(dirPath);
  await saveFile(filePath, content);
};

export { beforeGenerateIndexMetafileHook };

Configure in your Docusaurus plugin:

plugins: [
  [
    "@graphql-markdown/docusaurus",
    {
      schema: "./schema.graphql",
      mdxParser: "./custom-mdx.mjs", // Load your custom hooks
      // ... other options
    },
  ],
];

Documentation

For complete hook recipes and API reference:

• Hooks Recipes
• Events API Documentation

📦 Package Versions

This release includes updates to the following packages:

• @graphql-markdown/docusaurus@1.31.0
• @graphql-markdown/core@1.17.0
• @graphql-markdown/types@1.9.0
• @graphql-markdown/cli@0.5.0
• @graphql-markdown/printer-legacy@1.12.4
• @graphql-markdown/utils@1.9.1

Full Changelog: 1.30.3...1.31.0

🧼 Fix lost deep properties when merging object props from graphql-config with inline config, eg docOptions.frontMatter.

What's Changed

• 🐛 fix merging graphql-config with inline config by @edno in #2362

Full Changelog: 1.30.2...1.30.3

🧹 This release cleans up few bugs:

• front matter entities declared in Docusaurus plugin config not propagated to generated MDX files (#2341)
• GraphQL code formatting issue for operations using default values with input object fields (#2356)

What's Changed

• fix(deps): update graphql-tools monorepo by @renovate[bot] in #2287
• 📦 npm(deps): Bump @graphql-tools/load from 8.1.1 to 8.1.2 by @dependabot[bot] in #2300
• 📦 npm(deps): Bump @graphql-tools/graphql-file-loader from 8.0.21 to 8.0.22 by @dependabot[bot] in #2302
• chore(deps): update dependency @graphql-tools/graphql-file-loader to v8.1.0 by @renovate[bot] in #2353
• 🐛 fix issue with default values for object type fields by @edno in #2356
• 🐛 fix overwritten docOptions (Docusaurus plugin config) by @edno in #2357

Full Changelog: 1.30.1...1.30.2

🧽 Remove the "magic" warning when passing homepage:false (introduced in the build code by the AI assistant on build & publish).

Full Changelog: 1.30.0...1.30.1

🌟 This release improves prettier support config file and now uses MDX parser instead of Markdown, reported in #2236 by @PaulRBerg.
It also comes with a new configuration option for homepage that can now be set to false to disable its generation, reported in #2234 by @PaulRBerg.

What's Changed

• 🗒️ remove id: schema reference from homepage.md by @edno in #2245
• ✨ add support for disabling homepage by @edno in #2246
• 🐛 fix prettier support for mdx with config by @edno in #2255
• 🧪 fix utils.prettier tests by @edno in #2258

Full Changelog: 1.29.1...1.30.0

🐛 This release adds better support of special characters (e.g. _) in entity names, fixing issues like #2213 reported by @PaulRBerg.

📄 The documentation has also got its share of fixes, thanks to @PaulRBerg reports.

What's Changed

• 📝 more doc update in #2065
• 🐛 fix mdx compilation error when underscore used with entity name in #2215
• 📝 fix pretty param in config docs in #2220
• 📝 fix incorrect use of customDirective in example in #2221
• 📝 add troubleshooting info linked to #2213 in #2216

Full Changelog: 1.29.0...1.29.1