GitHub supports Asciidoctor markup. We can add a document to GitHub with the extension adoc and it is parsed and the resulting HTML is shown when we view the document in our web browser in a GitHub repository. In March 2016 Dan Allen tweeted about enabling admonition icons on GitHub. A follow-up tweet by Ted Bergeron mentioned more examples. In this post we see an example on how to use their suggestions. Normally we wouldn't see an icon, but we can use document attributes and assign an emoji for each admonition type. For example a note admonition icon is set with the document attribute note-caption. We can use a condition check to see if the document is rendered on GitHub and only then use the document attributes.

In the following example we assign icons to the different admonitions:

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

= Asciidoc on GitHub

[NOTE]
====
A sample note admonition.
We can use gemoji icons in the Asciidoctor markup.
We assign an icon name to the document
attributes `tip-caption`, `note-caption` and `important-caption`.
====

TIP: It works!

IMPORTANT: Asciidoctor is awesome, don't forget!

CAUTION: Don't forget to add the `...-caption` document attributes in the header of the document on GitHub.

WARNING: You have no reason not to use Asciidoctor.

Let's see the result on GitHub with a Gist or the following screenshot:

Written with Asciidoctor 1.5.2.

Original blog post