Render AsciiDoc admonitions as Markdown alerts

lib/github/markup/asciidoctor_converter.rb

@@ -0,0 +1,29 @@
+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}" : ''
+        # 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 : %(<p>#{node.content}</p>)
+        %(<div#{id_attr} class="markdown-alert markdown-alert-#{name}#{role}">
+<p class="markdown-alert-title">#{title}</p>
+#{content}
+</div>)
+      end
+    end
+  end
+end

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(

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 _custom_ 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 <strong>simple</strong> 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 'A <em>custom</em> 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
+
   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')

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.

test/markups/README.admonitions.adoc.html

@@ -0,0 +1,33 @@
+<h1>Admonitions</h1>
+<div>
+<p>Note</p>
+<p>Useful information that users should know, even when <strong>skimming</strong> content.</p>
+</div>
+<div>
+<p>Tip</p>
+<p>Helpful advice for doing things better or more easily.</p>
+</div>
+<div>
+<p>Important</p>
+<p>Key information users need to know to achieve their goal.</p>
+</div>
+<div id="warning-id">
+<p>Before you continue</p>
+<div>
+<p>Urgent info that needs immediate user attention to avoid problems.</p>
+</div>
+<div>
+<ul>
+<li>
+<p>Back up your data</p>
+</li>
+<li>
+<p>Check your configuration</p>
+</li>
+</ul>
+</div>
+</div>
+<div>
+<p>Caution</p>
+<p>Advises about risks or negative outcomes of certain actions.</p>
+</div>

test/markups/README.asciidoc.html

@@ -24,16 +24,8 @@ <h2 id="first-section">First Section</h2>
 <h2 id="another-section">Another Section</h2>
 <div>
 <div>
-<table>
-<tr>
-<td>
-<div>Note</div>
-</td>
-<td>
-Here is some source code.
-</td>
-</tr>
-</table>
+<p>Note</p>
+<p>Here is some source code.</p>
 </div>
 <div>
 <div>