Skip to content

Commit c126c01

Browse files
committed
fix: restore legacy CommonMarker compatibility
I retain the existing CommonMarker 2.x adapter and delegate to the original render_html API when the legacy parser is installed. Existing installations keep their parser and its option behavior. I prepare version `6.1.1` with real-parser regression tests and a legacy full-suite CI job. The incompatible `6.1.0` release has been withdrawn. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6fe372b1-3ff6-4129-9d33-be564fb6a5f0 Signed-off-by: Zack Koppert <zkoppert@github.com>
1 parent a8fb5d1 commit c126c01

11 files changed

Lines changed: 160 additions & 25 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,15 @@ permissions:
99

1010
jobs:
1111
build:
12-
name: "Test / Ruby ${{ matrix.ruby }} / RDoc ${{ matrix.rdoc }}"
12+
name: "Test / Ruby ${{ matrix.ruby }} / RDoc ${{ matrix.rdoc }} / CommonMarker ${{ matrix.commonmarker }}"
1313
runs-on: ubuntu-latest
1414
env:
1515
RDOC_VERSION: "~> ${{ matrix.rdoc }}"
16+
COMMONMARKER_VERSION: "${{ matrix.commonmarker }}"
1617
strategy:
1718
matrix:
19+
commonmarker:
20+
- "~> 2.8.2"
1821
rdoc:
1922
- "7.2.0"
2023
ruby:
@@ -24,22 +27,27 @@ jobs:
2427
include:
2528
- ruby: "4.0"
2629
rdoc: "8.0"
30+
commonmarker: "~> 2.8.2"
31+
- ruby: "3.4"
32+
rdoc: "7.2.0"
33+
commonmarker: "0.23.12"
2734
fail-fast: false
2835

2936
steps:
3037
- name: Checkout
3138
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
3239
with:
3340
fetch-depth: 10
41+
persist-credentials: false
3442

35-
- uses: ruby/setup-ruby@a0102e0972be65f351c307e2d64b9314a57c8073 # v1
43+
- uses: ruby/setup-ruby@651ff0d62c5c79bed6d53ec518387aae20e72c1a # v1.329.0
3644
with:
3745
ruby-version: ${{ matrix.ruby }}
38-
bundler-cache: ${{ matrix.rdoc == '7.2.0' }}
46+
bundler-cache: ${{ matrix.rdoc == '7.2.0' && matrix.commonmarker == '~> 2.8.2' }}
3947

40-
- name: Install RDoc 8 dependencies
41-
if: matrix.rdoc == '8.0'
42-
run: bundle update rdoc
48+
- name: Resolve overridden parser dependencies
49+
if: matrix.rdoc != '7.2.0' || matrix.commonmarker != '~> 2.8.2'
50+
run: bundle update commonmarker rdoc
4351

4452
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
4553
with:

‎CONTRIBUTING.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,13 @@ CI tests RDoc 7.2 and 8.x. To test RDoc 8.x locally:
4242
$ RDOC_VERSION='~> 8.0' bundle update rdoc
4343
$ RDOC_VERSION='~> 8.0' bundle exec rake
4444

45+
CI also tests CommonMarker 0.23.12. To run the full suite with the legacy parser:
46+
47+
$ COMMONMARKER_VERSION=0.23.12 bundle update commonmarker
48+
$ COMMONMARKER_VERSION=0.23.12 bundle exec rake
49+
50+
Run these commands in a separate checkout to keep the default lockfile unchanged. You can combine `COMMONMARKER_VERSION` and `RDOC_VERSION` to test both overrides.
51+
4552
## Releasing a new version
4653

4754
If you are the current maintainer of this gem:

‎Gemfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ gemspec
44
gem "redcarpet", :platforms => :ruby
55
gem "kramdown", :platforms => :jruby
66
gem "RedCloth"
7-
gem "commonmarker", "~> 2.8.2"
7+
gem "commonmarker", ENV.fetch("COMMONMARKER_VERSION", "~> 2.8.2")
88
gem "rdoc", ENV.fetch("RDOC_VERSION", "~> 7.2.0")
99
gem "org-ruby", "0.9.12"
1010
gem "creole", "~>0.5.0"

‎Gemfile.lock‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
PATH
22
remote: .
33
specs:
4-
github-markup (6.1.0)
4+
github-markup (6.1.1)
55
rdoc (< 9)
66

77
GEM

‎HISTORY.md‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
1-
## 6.1.0 - 2026-10-16
1+
## 6.1.1 (unreleased)
22

3-
Version `6.1.0` replaces the withdrawn `7.0.0` release with the same runtime behavior and dependency requirements. The CommonMarker compatibility changes below remain in effect.
3+
### Bug Fixes
4+
5+
* I restored the CommonMarker 0.x API without requiring a parser upgrade. Existing 0.x installations retain their rendering flags, extension validation, and output behavior.
6+
* I retained CommonMarker 2.x support with its existing option behavior.
7+
* I added full-suite CI coverage for CommonMarker 0.23.12 alongside the default 2.8.2 dependency.
8+
9+
The RDoc 8 and reStructuredText fixes listed below remain included.
10+
11+
## 6.1.0 - 2026-10-16 (withdrawn)
12+
13+
I withdrew this release because it required a CommonMarker upgrade for existing 0.x installations. The `v6.1.0` tag remains available for traceability.
414

515
### Compatibility Changes
616

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ from this directory.
4848
Usage
4949
-----
5050

51+
Markdown rendering supports CommonMarker 0.x and 2.x. Keep the installed version to retain that parser's option behavior. Extensions follow the installed parser; 2.x-only extensions remain unavailable with 0.x.
52+
5153
Basic form:
5254

5355
```ruby
@@ -82,6 +84,8 @@ cd script
8284
./bootstrap
8385
```
8486

87+
The development bundle uses CommonMarker 2.8.2 by default. Set `COMMONMARKER_VERSION` to test another version, then resolve dependencies with `bundle update commonmarker`. See [Testing](CONTRIBUTING.md#testing) for commands.
88+
8589
Contributing
8690
------------
8791

‎lib/github-markup.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
module GitHub
22
module Markup
3-
VERSION = '6.1.0'
3+
VERSION = '6.1.1'
44
Version = VERSION
55
end
66
end

‎lib/github/markup/markdown.rb‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ class Markdown < Implementation
1111
[:tagfilter, :autolink, :table, :strikethrough],
1212
)
1313

14+
unless defined?(::Commonmarker) && ::Commonmarker.respond_to?(:to_html)
15+
next ::CommonMarker.render_html(content, [:GITHUB_PRE_LANG] + legacy_opts, legacy_exts)
16+
end
17+
1418
parse_options = {}
1519
# commonmarker 2.x changes several render defaults that diverge from cmark-gfm 0.x:
1620
# - hardbreaks defaults to true in 2.x but was false in 0.x.

‎test/coverage_test.rb‎

Lines changed: 2 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@
2222
require 'minitest/autorun'
2323

2424
class CoverageTest < Minitest::Test
25+
include ConstantStubbing
26+
2527
def test_version_constant_is_defined
2628
assert_kind_of String, GitHub::Markup::VERSION
2729
assert_equal GitHub::Markup::VERSION, GitHub::Markup::Version
@@ -342,20 +344,6 @@ def capture_commonmarker_call(options)
342344
captured
343345
end
344346

345-
def with_stub_const(path, value)
346-
parts = path.split("::")
347-
name = parts.pop
348-
parent = parts.inject(Object) { |mod, part| mod.const_get(part) }
349-
had_const = parent.const_defined?(name, false)
350-
original = parent.const_get(name) if had_const
351-
parent.send(:remove_const, name) if had_const
352-
parent.const_set(name, value)
353-
yield
354-
ensure
355-
parent.send(:remove_const, name) if parent.const_defined?(name, false)
356-
parent.const_set(name, original) if had_const
357-
end
358-
359347
def without_linguist
360348
had_const = Object.const_defined?(:Linguist, false)
361349
original = Object.const_get(:Linguist) if had_const

‎test/markdown_test.rb‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
2+
3+
require_relative "test_helper"
4+
require "github/markup"
5+
require "commonmarker"
6+
require "minitest/autorun"
7+
require "nokogiri"
8+
9+
class MarkdownTest < Minitest::Test
10+
include ConstantStubbing
11+
12+
def test_uses_legacy_api_when_modern_interface_is_unavailable
13+
legacy = Module.new
14+
legacy.define_singleton_method(:render_html) do |content, _options, _extensions|
15+
"<p>legacy #{content}</p>\n"
16+
end
17+
18+
with_stub_const("Commonmarker", Module.new) do
19+
with_stub_const("CommonMarker", legacy) do
20+
actual = GitHub::Markup::Markdown::MARKDOWN_GEMS.fetch("commonmarker").call("payload")
21+
assert_equal "<p>legacy payload</p>\n", actual
22+
end
23+
end
24+
end
25+
26+
def test_renders_through_both_public_entry_points
27+
assert_equal "<p>hello</p>\n", GitHub::Markup.render("raw.md", "hello")
28+
assert_equal "<p>hello</p>\n", GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, "hello")
29+
end
30+
31+
def test_preserves_code_language
32+
document = Nokogiri::HTML.fragment(GitHub::Markup.render("raw.md", "```ruby\nputs 1\n```\n"))
33+
assert_equal "ruby", document.at_css("pre")["lang"]
34+
assert_equal "puts 1\n", document.at_css("code").text
35+
end
36+
37+
def test_preserves_unsafe_html_and_footnotes_without_mutating_frozen_options
38+
options = {commonmarker_opts: [:UNSAFE, :FOOTNOTES].freeze}.freeze
39+
html = GitHub::Markup.render("raw.md", "hello <b>world</b>[^1]\n\n[^1]: note\n", options: options)
40+
document = Nokogiri::HTML.fragment(html)
41+
42+
assert_equal "world", document.at_css("b").text
43+
assert_equal "1", document.at_css("sup a").text
44+
assert_includes document.at_css("li p").text, "note"
45+
end
46+
47+
def test_nobreaks_preserves_the_installed_backends_behavior
48+
actual = GitHub::Markup.render("raw.md", "first\nsecond\n", options: {commonmarker_opts: [:NOBREAKS]})
49+
expected = legacy_commonmarker? ? "<p>first second</p>\n" : "<p>first\nsecond</p>\n"
50+
assert_equal expected, actual
51+
end
52+
53+
def test_conflicting_break_flags_preserve_the_installed_backends_precedence
54+
actual = GitHub::Markup.render("raw.md", "first\nsecond\n", options: {commonmarker_opts: [:HARDBREAKS, :NOBREAKS]})
55+
expected = legacy_commonmarker? ? "<p>first<br />\nsecond</p>\n" : "<p>first\nsecond</p>\n"
56+
assert_equal expected, actual
57+
58+
reverse = GitHub::Markup.render("raw.md", "first\nsecond\n", options: {commonmarker_opts: [:NOBREAKS, :HARDBREAKS]})
59+
assert_equal "<p>first<br />\nsecond</p>\n", reverse
60+
end
61+
62+
def test_table_style_option_and_frozen_extension_list
63+
content = "| left | right |\n| :--- | ---: |\n| a | b |\n"
64+
options = {commonmarker_opts: [:TABLE_PREFER_STYLE_ATTRIBUTES], commonmarker_exts: [:table].freeze}
65+
document = Nokogiri::HTML.fragment(GitHub::Markup.render("raw.md", content, options: options))
66+
67+
assert_equal ["left", "right"], document.css("th").map(&:text)
68+
attribute = legacy_commonmarker? ? "style" : "align"
69+
expected = legacy_commonmarker? ? "text-align: left" : "left"
70+
assert_equal expected, document.at_css("th")[attribute]
71+
end
72+
73+
def test_double_tilde_option_preserves_the_installed_backends_behavior
74+
options = {commonmarker_opts: [:STRIKETHROUGH_DOUBLE_TILDE], commonmarker_exts: [:strikethrough]}
75+
actual = GitHub::Markup.render("raw.md", "~one~ ~~two~~\n", options: options)
76+
expected = legacy_commonmarker? ? "<p>~one~ <del>two</del></p>\n" : "<p><del>one</del> <del>two</del></p>\n"
77+
assert_equal expected, actual
78+
end
79+
80+
def test_extensions_follow_the_installed_parsers_capabilities
81+
options = {commonmarker_exts: [:header_ids]}
82+
if legacy_commonmarker?
83+
error = assert_raises(ArgumentError) { GitHub::Markup.render("raw.md", "# Title", options: options) }
84+
assert_match(/extension header_ids not found/, error.message)
85+
else
86+
document = Nokogiri::HTML.fragment(GitHub::Markup.render("raw.md", "# Title", options: options))
87+
assert_equal "title", document.at_css("a[id]")["id"]
88+
end
89+
end
90+
91+
private
92+
93+
def legacy_commonmarker?
94+
Gem.loaded_specs.fetch("commonmarker").version < Gem::Version.new("1")
95+
end
96+
end

0 commit comments

Comments
 (0)