Repository navigation
Render AsciiDoc admonitions with the same style as Markdown alerts (NOTE/TIP/IMPORTANT/WARNING/CAUTION) #2091
Description
Activity
When an AsciiDoc file (e.g.
README.adoc) is rendered bygithub/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:NoteThis 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/markupalready isolates the AsciiDoc rendering call inlib/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 defaultHtml5Converter) that overrides onlyconvert_admonition, and pass it as the:backend/:converterfor this call. The override would emit the samemarkdown-alert markdown-alert-<type>/markdown-alert-titlemarkup already used (and already styled) for Markdown alerts, instead of Asciidoctor'sadmonitionblocktable: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
%() end end (the appropriate inline SVG icon per type could be added to match the ones GitHub already uses for Markdown alerts)#{label}
#{node.content}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
.adocrender path) as a PR if that's a direction you'd be open to. Just let me know!@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 justconvert_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 🚀Reacted by Werner Fouché, Michael Baker and Ewan EdwardsThis 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.
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
I too noticed this issue and found it annoying! Maybe you could open a PR and then they'll give you attention?
When an AsciiDoc file (e.g.
README.adoc) is rendered bygithub/markup, admonition blocks (NOTE,TIP,IMPORTANT,WARNING,CAUTION) produce Asciidoctor's default HTML5 markup, which is a bare, unstyled<table>:renders as:
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:
which GitHub renders as:
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/markupalready isolates the AsciiDoc rendering call inlib/github/markups.rb:Rather than changing anything in Asciidoctor itself, github/markup could register a small custom HTML5 converter (a subclass of the default
Html5Converter) that overrides onlyconvert_admonition, and pass it as the:backend/:converterfor this call. The override would emit the samemarkdown-alert markdown-alert-<type>/markdown-alert-titlemarkup already used (and already styled) for Markdown alerts, instead of Asciidoctor'sadmonitionblocktable:(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
.adocrender path) as a PR if that's a direction you'd be open to. Just let me know!