v6.0.0

Features

• Add Rake task graphql-docs:generate for integration with Rails and other Ruby projects that use Rake. Supports both task arguments and environment variables for configuration. Can be used with Rake::Task["assets:precompile"].enhance(["graphql-docs:generate"]) to generate docs as part of the build process.
• Add support for running as a Rack app for easy integration with existing web applications
• Add resizable sidebar for better UX
• Add Dark Mode styles support
• Render deprecation info for queries and mutations

Improvements

• Replace jQuery with vanilla JavaScript for smaller bundle size and fewer dependencies
• Optimize packaged gem size and use system fonts for better performance
• Run CI against Ruby 4.0

Breaking Changes

• breaking: Upgrade commonmarker, html-pipeline, and gemoji dependencies, see BREAKING CHANGES section below

🚨 BREAKING CHANGES

This release upgrades three major dependencies with significant breaking changes.

Dependency Upgrades

• commonmarker: 0.23.x → 2.0.x - Complete API rewrite with improved performance and standards compliance
• html-pipeline: 2.14.x → 3.0.x - Simplified architecture, filter API changed
• gemoji: 3.0.x → 4.0.x - Updated emoji mappings
• Removed: extended-markdown-filter (no longer maintained, incompatible with html-pipeline 3)

Breaking Changes for Advanced Users

1. Custom html-pipeline filters no longer work

   • html-pipeline 3.x has a completely different filter API
   • If you configured custom filters via pipeline_config[:pipeline], they will not work
   • Migration: Rewrite custom filters using html-pipeline 3.x API (see html-pipeline migration guide)
   • The gem now handles markdown and emoji rendering directly

2. Custom Renderer API changes

   • If you implemented a custom renderer that directly uses CommonMarker:
   • Old API: CommonMarker.render_html(string, :UNSAFE)
   • New API: Commonmarker.parse(string).to_html(options: {render: {unsafe: true}})
   • Note the lowercase 'm' in Commonmarker in version 2.x

3. Table of Contents filter removed from defaults

   • The default TableOfContentsFilter is no longer applied
   • Migration: Implement a custom post-processing step if needed

What Still Works (and is Better!)

• ✅ GitHub Flavored Markdown (tables, strikethrough, autolinks, task lists)
• ✅ Emoji rendering - :emoji: syntax like :smile: works out of the box
• ✅ Header anchors (automatically generated with IDs)
• ✅ Safe and unsafe HTML rendering modes
• ✅ Code blocks with syntax highlighting
• ✅ All existing templates and layouts
• ✅ Faster markdown rendering
• ✅ More standards-compliant HTML output

Why Upgrade?

• Security: Updates to latest stable versions with security patches
• Performance: commonmarker 2.x is significantly faster and more standards-compliant
• Maintainability: All dependencies are actively maintained
• Modern: Uses current Ruby ecosystem standards

Migration Guide

For most users with default configuration, this upgrade should be seamless. Advanced users should check:

• Do you use custom pipeline_config[:pipeline] filters? → Rewrite for html-pipeline 3.x
• Do you have a custom Renderer subclass that calls CommonMarker directly? → Update API calls
• Run full test suite after upgrade
• Regenerate documentation and visually inspect output

New Contributors

• @infyomer made their first contribution in #161
• @a-f-may made their first contribution in #126

Full Changelog: v5.2.0...v6.0.0

v5.2.0

What's Changed

• Sidebar Search Filter by @denisahearn in #160

Full Changelog: v5.1.0...v5.2.0

v5.1.0

What's Changed

• List queries in sidebar by @denisahearn in #156
• Update test fixtures to use string descriptions where tested by @rmosolgo in #153
• 2 Space Indents by @DayreaverDoesThings in #154
• add logger and ostruct to gemspec by @brettchalupa in #155
• Address deprecation warnings with mutex_m and Sass @import by @brettchalupa in #159

New Contributors

• @rmosolgo made their first contribution in #153
• @DayreaverDoesThings made their first contribution in #154
• @denisahearn made their first contribution in #156

Full Changelog: v5.0.0...v5.1.0

v5.0.0

What's Changed

• breaking: The graphql gem 2.2.0+ breaks some of the parsing and displaying of comments from a GraphQL schema file
• breaking: Ruby 2.6, 2.7, 3.0 are no longer supported as they are End of Life (EOL)
• feat: CLI version flag: graphql-docs --version / graphql-docs -v
• fix: CLI now works outside of a Bundler project
• fix: test suite
• chore: switch to sess-embedded gem for more maintained dependency

New Contributors

• @jeromedalbert made their first contribution in #135
• @Leenday made their first contribution in #141
• @JoanLn made their first contribution in #146
• @ntkme made their first contribution in #148

Full Changelog: v4.0.0...v5.0.0

v4.0.0

This highlight of this major release of the graphql-docs is the new CLI that comes with the gem. Install the gem and quickly generate docs from your schema with:

graphql-docs schema.graphql

The CLI supports a limited subset of configuration options, so it's best used for quick generation. For full options, use the Rake task or library builder.

• Breaking change: drop support for Ruby 2.5 and earlier
• CLI with limited options, e.g. graphql-docs schema.graphql
• Dart Sass replaces Ruby Sass because Ruby Sass is deprecated — this is kinda breaking if you relied on Ruby Sass coming from the gem, but it's pretty compatible from my testing
• Fixes:
  • Upgrade commonmarker to latest ver to address security vulnerabilities
  • commonmarker pinned to version without security vulnerability
• Chores
  • Dev env refresh

View the v4.0.0 release on RubyGems.org.

v3.0.1

• fix: Relieves EscapeUtils.escape_html is deprecated. Use GCI.escapeHTML instead, it's faster deprecation warning until it gets released in an downstream dependency
• meta: Maintainership change from gjtorikian to brettchalupa

See #93 for more details of the changes in this release.

View the v3.0.1 release on RubyGems.org.

v2.0.0

• Support for new class-based schemas: #82

v1.9.0

• Support documenting directives (#72)

v1.8.0

• Add deprecation warnings to connections: #68

v1.7.0

• Support quote style comments: #65
• Support ERB templates for landing pages: #66