From 159d20c49cf6a29931ce72c60e398280558c8ce4 Mon Sep 17 00:00:00 2001 From: Guillaume Grossetie Date: Fri, 16 Oct 2026 09:34:04 +0200 Subject: [PATCH 1/2] Render AsciiDoc admonitions as Markdown alerts Use a custom Asciidoctor HTML5 converter that only overrides convert_admonition to emit the markdown-alert markup GitHub already styles for Markdown alerts, instead of an unstyled table. The converter is passed through the :converter option rather than registered for the html5 backend, so other Asciidoctor conversions in the same process are unaffected. Closes #2091 Co-Authored-By: Claude Opus 5.5 --- lib/github/markup/asciidoctor_converter.rb | 28 ++++++++++++++++++ lib/github/markups.rb | 3 +- test/markup_test.rb | 24 +++++++++++++++ test/markups/README.admonitions.adoc | 21 +++++++++++++ test/markups/README.admonitions.adoc.html | 34 ++++++++++++++++++++++ test/markups/README.asciidoc.html | 12 ++------ 6 files changed, 111 insertions(+), 11 deletions(-) create mode 100644 lib/github/markup/asciidoctor_converter.rb create mode 100644 test/markups/README.admonitions.adoc create mode 100644 test/markups/README.admonitions.adoc.html diff --git a/lib/github/markup/asciidoctor_converter.rb b/lib/github/markup/asciidoctor_converter.rb new file mode 100644 index 00000000..702b2bd1 --- /dev/null +++ b/lib/github/markup/asciidoctor_converter.rb @@ -0,0 +1,28 @@ +require "asciidoctor" +require "asciidoctor/converter/html5" + +module GitHub + module Markup + # HTML5 converter that renders admonitions (NOTE, TIP, IMPORTANT, WARNING, + # CAUTION) with the same markup as Markdown alerts, so they pick up the + # styles GitHub already ships for those. Every other node is converted by + # the built-in Asciidoctor HTML5 converter. + # + # The class is passed to Asciidoctor through the :converter option rather + # than registered for the html5 backend, so other Asciidoctor conversions + # in the same process are not affected. + class AsciidoctorConverter < ::Asciidoctor::Converter::Html5Converter + def convert_admonition(node) + id_attr = node.id ? %( id="#{node.id}") : '' + name = node.attr 'name' + role = node.role ? " #{node.role}" : '' + title_element = node.title? ? %(
#{node.title}
\n) : '' + content = node.content_model == :compound ? node.content : %(

#{node.content}

) + %( +

#{node.attr 'textlabel'}

+#{title_element}#{content} +) + end + end + end +end diff --git a/lib/github/markups.rb b/lib/github/markups.rb index 4b2f8e0e..f4c3e9fc 100644 --- a/lib/github/markups.rb +++ b/lib/github/markups.rb @@ -43,8 +43,9 @@ else attributes['outfilesuffix'] = '.adoc' end + require "github/markup/asciidoctor_converter" Asciidoctor::Compliance.unique_id_start_index = 1 - Asciidoctor.convert(content, :safe => :secure, :attributes => attributes) + Asciidoctor.convert(content, :safe => :secure, :attributes => attributes, :converter => GitHub::Markup::AsciidoctorConverter) end GitHub::Markup.command( diff --git a/test/markup_test.rb b/test/markup_test.rb index baa1dec2..7fb5f4ff 100644 --- a/test/markup_test.rb +++ b/test/markup_test.rb @@ -107,6 +107,30 @@ def test_rendering_by_symbol assert_match result, GitHub::Markup.render_s(GitHub::Markups::MARKUP_ASCIIDOC, markup).split.join end + def test_asciidoc_admonitions_render_as_markdown_alerts + html = GitHub::Markup.render('README.adoc', <<~ADOC) + NOTE: A *simple* note. + + [[tip-id]] + .A title + [TIP.custom-role] + ==== + A compound tip. + ==== + ADOC + doc = Nokogiri::HTML.fragment(html) + note, tip = doc.css('div.markdown-alert').to_a + assert_equal 'markdown-alert markdown-alert-note', note['class'] + assert_equal 'Note', note.at_css('> p.markdown-alert-title').text + assert_equal 'A simple note.', note.css('> p')[1].inner_html + assert_equal 'tip-id', tip['id'] + assert_equal 'markdown-alert markdown-alert-tip custom-role', tip['class'] + assert_equal 'Tip', tip.at_css('> p.markdown-alert-title').text + assert_equal 'A title', tip.at_css('> div.title').text + assert_equal 'A compound tip.', tip.at_css('> div.paragraph > p').text + assert_empty doc.css('.admonitionblock') + end + def test_raises_error_if_command_exits_non_zero GitHub::Markup.command(:doesntmatter, 'test/fixtures/fail.sh', /fail/, ['Java'], 'fail') assert GitHub::Markup.can_render?('README.java', 'stop swallowing errors') diff --git a/test/markups/README.admonitions.adoc b/test/markups/README.admonitions.adoc new file mode 100644 index 00000000..f584648e --- /dev/null +++ b/test/markups/README.admonitions.adoc @@ -0,0 +1,21 @@ += Admonitions + +NOTE: Useful information that users should know, even when *skimming* content. + +TIP: Helpful advice for doing things better or more easily. + +[IMPORTANT] +Key information users need to know to achieve their goal. + +[[warning-id]] +.Before you continue +[WARNING] +==== +Urgent info that needs immediate user attention to avoid problems. + +* Back up your data +* Check your configuration +==== + +[CAUTION.custom-role] +Advises about risks or negative outcomes of certain actions. diff --git a/test/markups/README.admonitions.adoc.html b/test/markups/README.admonitions.adoc.html new file mode 100644 index 00000000..40376f62 --- /dev/null +++ b/test/markups/README.admonitions.adoc.html @@ -0,0 +1,34 @@ +

Admonitions

+
+

Note

+

Useful information that users should know, even when skimming content.

+
+
+

Tip

+

Helpful advice for doing things better or more easily.

+
+
+

Important

+

Key information users need to know to achieve their goal.

+
+
+

Warning

+
Before you continue
+
+

Urgent info that needs immediate user attention to avoid problems.

+
+
+
    +
  • +

    Back up your data

    +
    • +
  • +

    Check your configuration

    +
    • +
+
+
+
+

Caution

+

Advises about risks or negative outcomes of certain actions.

+
\ No newline at end of file diff --git a/test/markups/README.asciidoc.html b/test/markups/README.asciidoc.html index 4e28204e..6c30ba84 100644 --- a/test/markups/README.asciidoc.html +++ b/test/markups/README.asciidoc.html @@ -24,16 +24,8 @@

First Section

Another Section

- - - - - -
-
Note
-		 -Here is some source code. -
+

Note

+

Here is some source code.

From a383ebe58624496cee9d33a327538065bdc556cf Mon Sep 17 00:00:00 2001 From: Guillaume Grossetie Date: Fri, 16 Oct 2026 09:40:05 +0200 Subject: [PATCH 2/2] Use the AsciiDoc block title as the alert title Match comrak's rendering of Markdown alerts with a custom title (`> [!TIP] Custom title`): the block title replaces the default label in markdown-alert-title instead of being emitted as a separate, unstyled div. Co-Authored-By: Claude Opus 5.5 --- lib/github/markup/asciidoctor_converter.rb | 7 ++++--- test/markup_test.rb | 6 +++--- test/markups/README.admonitions.adoc.html | 3 +-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/lib/github/markup/asciidoctor_converter.rb b/lib/github/markup/asciidoctor_converter.rb index 702b2bd1..8d6fed0b 100644 --- a/lib/github/markup/asciidoctor_converter.rb +++ b/lib/github/markup/asciidoctor_converter.rb @@ -16,11 +16,12 @@ def convert_admonition(node) id_attr = node.id ? %( id="#{node.id}") : '' name = node.attr 'name' role = node.role ? " #{node.role}" : '' - title_element = node.title? ? %(
#{node.title}
\n) : '' + # Like a Markdown alert with a custom title, the block title replaces the label. + title = node.title? ? node.title : (node.attr 'textlabel') content = node.content_model == :compound ? node.content : %(

#{node.content}

) %( -

#{node.attr 'textlabel'}

-#{title_element}#{content} +

#{title}

+#{content}
) end end diff --git a/test/markup_test.rb b/test/markup_test.rb index 7fb5f4ff..ab4f239d 100644 --- a/test/markup_test.rb +++ b/test/markup_test.rb @@ -112,7 +112,7 @@ def test_asciidoc_admonitions_render_as_markdown_alerts NOTE: A *simple* note. [[tip-id]] - .A title + .A _custom_ title [TIP.custom-role] ==== A compound tip. @@ -125,8 +125,8 @@ def test_asciidoc_admonitions_render_as_markdown_alerts assert_equal 'A simple note.', note.css('> p')[1].inner_html assert_equal 'tip-id', tip['id'] assert_equal 'markdown-alert markdown-alert-tip custom-role', tip['class'] - assert_equal 'Tip', tip.at_css('> p.markdown-alert-title').text - assert_equal 'A title', tip.at_css('> div.title').text + assert_equal 'A custom title', tip.at_css('> p.markdown-alert-title').inner_html + assert_empty tip.css('div.title') assert_equal 'A compound tip.', tip.at_css('> div.paragraph > p').text assert_empty doc.css('.admonitionblock') end diff --git a/test/markups/README.admonitions.adoc.html b/test/markups/README.admonitions.adoc.html index 40376f62..02581d86 100644 --- a/test/markups/README.admonitions.adoc.html +++ b/test/markups/README.admonitions.adoc.html @@ -12,8 +12,7 @@

Admonitions

Key information users need to know to achieve their goal.

-

Warning

-
Before you continue
+

Before you continue

Urgent info that needs immediate user attention to avoid problems.