Github Asciidoc Example

Welcome!

This is an example file of what you can do with asciidoc as rendered on github. It is basically a gist except that gists don’t render asciidoc like files do.

Admonitions

ℹ️	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.

💡

It works!

❗	Asciidoctor is awesome, don’t forget!

🔥	Don’t forget to add the …​-caption document attributes in the header of the document on GitHub.

⚠️	You have no reason not to use Asciidoctor.

Source Code Rendering

Here is an example of some R code.

par(mfrow=c(1, 2))  # divide graph area in 2 columns
boxplot(cars$speed, main="Speed", sub=paste("Outlier rows: ", boxplot.stats(cars$speed)$out))  # box plot for 'speed'
boxplot(cars$dist, main="Distance", sub=paste("Outlier rows: ", boxplot.stats(cars$dist)$out))  # box plot for 'distance'

Diagramming

Asciidoc has a diagramming plugin that renders either

• PlantUML

• ditaa

• GraphViz dot

However this is not turned on within Github.

If I was to include the following in my document:

@startuml
class Car
Driver - Car : drives >
Car *- Wheel : have 4 >
Car -- Person : < owns
@enduml

It renders as text.

@startuml class Car Driver - Car : drives > Car *- Wheel : have 4 > Car — Person : < owns @enduml

However, if I move that PlantUML to a seperate puml file, then I can use the PlantUML proxy server to render an included image (rendered below).

One advantage of the PlantUML proxy server is that is fully supports all PlantUML functions including some funky extensions used to do database diagrams.

Future additions

• TOCs

• Images

• Tables as an example of CSV/data layout

• Footnotes

• Lack of includes - include vs link

• Attributes

• Source Code - show rout output

• Source Code - add callouts

• Custom macros (menu, btn, kbd, and icon)