fix: restore legacy CommonMarker compatibility for 6.1.1

[zkoppert]

Why

Existing CommonMarker 0.x installations cannot use the withdrawn 6.1.0 release without upgrading their parser. Markdown rendering raises NameError because that release calls the CommonMarker 2.x API unconditionally.

I restored the legacy API so consumers can adopt the RDoc 8 and reStructuredText fixes without changing their installed CommonMarker version. The number of affected installations is unknown.

What changed

I use the installed parser's API: CommonMarker.render_html for legacy installations and the existing Commonmarker.to_html adapter for modern installations. I preserve native legacy options, errors, and extension limits without changing modern rendering behavior.

I prepare 6.1.1, document the 6.1.0 withdrawal, and retain the RDoc 8 and reStructuredText fixes. CommonMarker remains optional; the default development bundle stays at 2.8.2.

I added real-parser regression tests, a full-suite CommonMarker 0.23.12 CI job, and a documented COMMONMARKER_VERSION development override.

I also disabled persisted checkout credentials and updated the pinned Ruby setup action while editing the workflow. Parser-override jobs resolve their dependencies without the default bundle cache.

Before and after

Scenario	Withdrawn 6.1.0	Candidate 6.1.1
Keep CommonMarker 0.23.12 installed	Markdown fails with NameError	Markdown renders without a parser upgrade
Legacy line-break, table-style, and strikethrough flags	Rendering fails before flags are applied	Native 6.0.0 behavior is preserved
Unsupported legacy extensions	Rendering fails at API lookup	The legacy parser reports its original validation error
Keep CommonMarker 2.8.2 installed	The modern adapter renders Markdown	The existing modern adapter remains in use

Alternatives considered

I chose direct API detection rather than reverting modern support or requiring a dependency upgrade. Each parser keeps its own behavior; this does not make legacy and modern output identical.

Testing

I ran the complete 71-test suite in a fresh Linux Codespace across five profiles. I tested CommonMarker 2.8.2 and 0.23.12 with RDoc 7.2/8.1, plus an unchanged public legacy fork. Every profile passed with 100% measured line and branch coverage.

I built and installed the candidate gem, then exercised real Markdown, RDoc, and reStructuredText rendering across four parser/RDoc profiles. All 15 legacy output/error comparisons matched the published 6.0.0 gem with the same unchanged parser.

I also exercised both public rendering APIs and the installed CLI, including frozen inputs, native parser errors, and Markdown rendering without CommonMarker installed.

Rollout

I'll publish 6.1.1 only after review, merge, and separate release approval. The historical v6.1.0 and v7.0.0 tags remain unchanged.

Consumers can retain their current CommonMarker pin and test the dependency update independently. If adoption fails, they can restore their previous github-markup pin.

What to watch after merge

I'll check the parser compatibility CI workflow. During adoption, watch the consuming application's Markdown-rendering errors, especially NameError and unexpected parser-option errors.

[Copilot]

🔵 Needs a closer look

The public rendering-path change and release preparation warrant final maintainer review.

1 open issue

• Document Ruby version compatible with CommonMarker 0.23.12 · New

What changed in this PR

Restores legacy CommonMarker compatibility for 6.1.1 while preserving the modern rendering adapter.

Changes:

• Detect and use the installed parser’s API.
• Add regression tests, legacy-parser CI coverage, and development overrides.
• Prepare 6.1.1 and document the 6.1.0 withdrawal.

File	Description
test/​test_helper.rb	Share constant-stubbing support.
test/​markdown_test.rb	Add parser compatibility regression tests.
test/​coverage_test.rb	Reuse the shared stubbing helper.
README.md	Document parser support and overrides.
lib/​github/​markup/​markdown.rb	Restore legacy API dispatch; clarify comments.
lib/​github-markup.rb	Set version to 6.1.1.
HISTORY.md	Record compatibility restoration and withdrawal.
Gemfile.lock	Update the local gem version.
Gemfile	Allow a CommonMarker version override.
CONTRIBUTING.md	Document legacy-parser testing commands.
.github/​workflows/​ci.yml	Add legacy coverage, adjust dependency resolution, and harden checkout configuration.

_{Review effort: Max}