Repository navigation
Render AsciiDoc admonitions with the same style as Markdown alerts (NOTE/TIP/IMPORTANT/WARNING/CAUTION) #2091
Description
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!
Activity
galavizmoralessandrayesenia0-afk commentedon Jul 21, 2026
ggrossetie commentedon Aug 4, 2026
@zkoppert @TylerDixon Friendly ping on this one 😄
The current AsciiDoc admonition rendering on GitHub is subpar (bare unstyled table, no icon, no color, no visual distinction from surrounding text), but the fix could be quite small. As outlined above, overriding just
convert_admonitionin a small custom converter would let AsciiDoc admonitions reuse the exact markdown-alert* styling GitHub already ships for Markdown alerts. No new CSS, no changes needed in Asciidoctor itself. Since the five AsciiDoc admonition types map 1:1 onto the five Markdown alert types, this would be a low-risk, high-impact improvement to AsciiDoc rendering on GitHub. Happy to submit the PR if that's welcome, just say the word 🚀github-actions commentedon Oct 4, 2026
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
ggrossetie commentedon Oct 4, 2026
This issue is not stale, I'm just waiting for feedback from the maintainers before opening a PR. The proposed change is small and self-contained (a custom converter overriding only
convert_admonition), and I'm ready to submit it as soon as you confirm it's a direction you'd accept./cc @zkoppert @TylerDixon
doronbehar commentedon Oct 8, 2026
I too noticed this issue and found it annoying! Maybe you could open a PR and then they'll give you attention?