Render AsciiDoc admonitions with the same style as Markdown alerts (NOTE/TIP/IMPORTANT/WARNING/CAUTION)

[ggrossetie]

When an AsciiDoc file (e.g. README.adoc) is rendered by github/markup, admonition blocks (NOTE, TIP, IMPORTANT, WARNING, CAUTION) produce Asciidoctor's default HTML5 markup, which is a bare, unstyled <table>:

NOTE: This is a note.

renders as:

<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This is a note.
</td>
</tr>
</table>
</div>

Since github.com doesn't load Asciidoctor's stylesheet, this shows up as a plain, borderless table cell with the word "Note", no color, no icon, no visual distinction from the surrounding paragraph.

Compare this to the equivalent Markdown alert:

> [!NOTE]
> This is a note.

which GitHub renders as:

<div class="markdown-alert markdown-alert-note">
<p class="markdown-alert-title"><svg .../>Note</p>
<p>This is a note.</p>
</div>

This picks up GitHub's built-in .markdown-alert* CSS automatically (colored left border, icon, colored title). AsciiDoc's five admonition types map 1:1 onto the five Markdown alert types (NOTE, TIP, IMPORTANT, WARNING, CAUTION), so there's no semantic gap, just a rendering gap.

Proposal

github/markup already isolates the AsciiDoc rendering call in lib/github/markups.rb:

Asciidoctor.convert(content, :safe => :secure, :attributes => attributes)

Rather than changing anything in Asciidoctor itself, github/markup could register a small custom HTML5 converter (a subclass of the default Html5Converter) that overrides only convert_admonition, and pass it as the :backend/:converter for this call. The override would emit the same markdown-alert markdown-alert-<type> / markdown-alert-title markup already used (and already styled) for Markdown alerts, instead of Asciidoctor's admonitionblock table:

class GithubAdmonitionConverter < (Asciidoctor::Converter.for 'html5')
  register_for 'html5'

  def convert_admonition node
    name  = node.attr 'name'      # note, tip, important, warning, caution
    label = node.attr 'textlabel' # Note, Tip, Important, Warning, Caution
    %(<div class="markdown-alert markdown-alert-#{name}">
<p class="markdown-alert-title">#{label}</p>
#{node.content}
</div>)
  end
end

(the appropriate inline SVG icon per type could be added to match the ones GitHub already uses for Markdown alerts)

This requires no change to Asciidoctor itself and no new CSS on GitHub's side. It just reuses the classes/styles GitHub already ships for Markdown alerts.

I'm happy to contribute this change (the converter + wiring it into the .adoc render path) as a PR if that's a direction you'd be open to. Just let me know!

[galavizmoralessandrayesenia0-afk]

When an AsciiDoc file (e.g. README.adoc) is rendered by github/markup, admonition blocks (NOTE, TIP, IMPORTANT, WARNING, CAUTION) produce Asciidoctor's default HTML5 markup, which is a bare, unstyled <table>:

NOTE: This is a note.
renders as:

Note	This is a note.

Since github.com doesn't load Asciidoctor's stylesheet, this shows up as a plain, borderless table cell with the word "Note", no color, no icon, no visual distinction from the surrounding paragraph.

Compare this to the equivalent Markdown alert:

[!NOTE]
This is a note.
which GitHub renders as:

Note

This is a note.

This picks up GitHub's built-in `.markdown-alert*` CSS automatically (colored left border, icon, colored title). AsciiDoc's five admonition types map 1:1 onto the five Markdown alert types (NOTE, TIP, IMPORTANT, WARNING, CAUTION), so there's no semantic gap, just a rendering gap.

Proposal

github/markup already isolates the AsciiDoc rendering call in lib/github/markups.rb:

Asciidoctor.convert(content, :safe => :secure, :attributes => attributes)
Rather than changing anything in Asciidoctor itself, github/markup could register a small custom HTML5 converter (a subclass of the default Html5Converter) that overrides only convert_admonition, and pass it as the :backend/:converter for this call. The override would emit the same markdown-alert markdown-alert-<type> / markdown-alert-title markup already used (and already styled) for Markdown alerts, instead of Asciidoctor's admonitionblock table:

class GithubAdmonitionConverter < (Asciidoctor::Converter.for 'html5')
register_for 'html5'

def convert_admonition node
name = node.attr 'name' # note, tip, important, warning, caution
label = node.attr 'textlabel' # Note, Tip, Important, Warning, Caution
%(

#{label}

#{node.content}

) end end (the appropriate inline SVG icon per type could be added to match the ones GitHub already uses for Markdown alerts)

This requires no change to Asciidoctor itself and no new CSS on GitHub's side. It just reuses the classes/styles GitHub already ships for Markdown alerts.

I'm happy to contribute this change (the converter + wiring it into the .adoc render path) as a PR if that's a direction you'd be open to. Just let me know!