Update dependency @graphql-markdown/docusaurus to v1.34.0

[renovate]

This PR contains the following updates:

Package	Change	Age	Confidence
@graphql-markdown/docusaurus (source)	1.30.3 → 1.34.0

---

Release Notes

graphql-markdown/graphql-markdown (@​graphql-markdown/docusaurus)

v1.34.0

Compare Source

This release is a spring-cleaning pass across GraphQL-Markdown: clearing cobwebs from the tooling attic, tightening the generation pipeline, and shipping a few practical improvements along the way.

What's New

beforeComposePageTypeHook - Control page section layout

A new lifecycle hook lets you reorder, filter, or hide sections on any generated page before it is rendered. This supersedes the deprecated boolean options codeSection, relatedTypeSection, and exampleSection.

See the Hook Recipes documentation for usage examples.

Namespace wrapping in code snippets

Operations that belong to a namespace (introduced in 1.33.0) now render their code snippets wrapped in the correct namespace block, giving a more accurate representation of the schema structure.

Runtime deprecation warnings

Using deprecated CLI flags or config options (--noCode, --noRelatedType, --noExample, codeSection, relatedTypeSection) now emits a visible warning at runtime to help with migration.

Docusaurus <details> MDX implementation update

The Docusaurus package updates its MDX handling for <details> blocks to align with the current implementation.

Bug Fixes

• Namespace detection regression (#​2809): fields whose return type is the root operation type (for example, a Mutation field returning Mutation) were incorrectly classified as namespace containers. This caused those fields to be omitted from operation lists and the root type to be stripped from the objects map. Fixed in @graphql-markdown/graphql.

Breaking / Deprecations

• relatedTypeSection is deprecated - use beforeComposePageTypeHook to hide the related-types section.
• codeSection and boolean exampleSection are deprecated - use beforeComposePageTypeHook instead.
• options.runOnBuild is deprecated and will be removed in a future release. Use the graphql-to-doc CLI command instead.
• PrinterEvent enum is deprecated in favour of ICancellableEvent.
• Potential breaking change: all section printer functions now return structured PageSection objects instead of raw strings.

Internal / Architecture

• Event base classes (CancellableEvent, DataEvent, DataOutputEvent) moved from @graphql-markdown/core -> @graphql-markdown/utils, making them available to downstream consumers.
• Print event implementations (PrintCodeEvent, PrintTypeEvent, BeforeComposePageTypeEvent) moved to @graphql-markdown/printer-legacy.
• @graphql-markdown/types promoted from devDependencies -> dependencies across all packages.

Package Versions

Package	Version
@graphql-markdown/docusaurus	1.34.0
@graphql-markdown/core	1.20.0
@graphql-markdown/printer-legacy	1.15.0
@graphql-markdown/types	1.12.0
@graphql-markdown/utils	1.11.0
@graphql-markdown/graphql	1.2.1
@graphql-markdown/cli	0.7.1
@graphql-markdown/diff	1.1.14
@graphql-markdown/helpers	1.0.13
@graphql-markdown/logger	1.0.6

Full Changelog: graphql-markdown/graphql-markdown@1.33.0...1.34.0

[Changes][1.34.0]

v1.33.0

Compare Source

🌻 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: graphql-markdown/graphql-markdown@1.32.1...1.33.0

[Changes][1.33.0]

v1.32.1

Compare Source

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

[Changes][1.32.1]

v1.31.2

🐛 This release fixes broken packages from 1.31.0

[Changes][1.31.2]

v1.31.0

Compare Source

🎯 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: graphql-markdown/graphql-markdown@1.30.3...1.31.0

[Changes][1.31.0]

---

Configuration

📅 Schedule: (UTC)

• Branch creation
  • At any time (no schedule defined)
• Automerge
  • At any time (no schedule defined)

🚦 Automerge: Enabled.

♻ Rebasing: Whenever PR is behind base branch, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.

[github-actions]

Code Coverage Report: Only Changed Files listed

Package	Base Coverage	New Coverage	Difference
Overall Coverage	🟢 53.11%	🟢 53.11%	⚪ 0%

Minimum allowed coverage is 0%, this run produced 53.11%