ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]
= 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.
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.
== 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:
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)