Switch Commonmarker output

Joseph Fletcherrequested to merge
518886-switch-commonmarker-output into master

Switch Commonmarker output (github_pre_lang: false)

Part of: lang attribute must have a valid value
Depends on: Step 1 (CodeLanguageFilter refactoring) and Step 2 (html_gitlab.rb refactoring)

What does this MR do and why?

This MR introduces a feature flag to control how the GLFM markdown engine outputs language information for code blocks, preparing for the transition from invalid lang attributes to valid CSS classes.

Key Changes:

  • Adds feature flag use_css_language_classes (disabled by default)
  • When disabled: Outputs <pre lang="ruby"><code> (current behavior)
  • When enabled: Outputs <pre><code class="language-ruby"> (new behavior)
  • Refactors render_options method to evaluate feature flag at render time
  • Updates tests to cover both behaviors

Why this approach?

This feature flag enables safe, gradual rollout of the accessibility fix:

  1. Safe deployment: Flag disabled by default maintains current behavior
  2. Gradual testing: Can enable for specific projects to validate changes
  3. Easy rollback: Can disable flag if issues are discovered
  4. Preparation for Step 4: CodeLanguageFilter (refactored in Step 1) already handles CSS class extraction

How to set up and validate locally

  1. Test default behavior (flag disabled):

    # In Rails console
Feature.disabled?(:use_css_language_classes)  # Should be true
    • Code blocks should show: <pre lang="ruby"><code>

  2. Test new behavior (flag enabled):

    # Enable flag in Rails console
Feature.enable(:use_css_language_classes)
    • Code blocks should show: <pre><code class="language-ruby">

  3. Run tests:

    bundle exec rspec spec/lib/banzai/filter/markdown_filter_spec.rb

Verification

  • Feature flag disabled: Code blocks use lang attributes (current behavior)
  • Feature flag enabled: Code blocks use CSS classes (new behavior)
  • Math blocks follow same pattern as regular code blocks
  • All tests pass for both flag states
  • No behavior change with flag disabled (safe default)

Related

  • Previous steps: Step 1 (CodeLanguageFilter refactoring), Step 2 (html_gitlab.rb refactoring)
  • Next step: Step 4 - Replace lang with data-lang in Rouge and AsciiDoc formatters
  • Final goal: Replace invalid lang attributes with data-lang for WCAG compliance
  • Addresses accessibility violations where lang="ruby" is invalid HTML

Merge request reports