Skip to content

brianrepko/github-asciidoc-example

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

15 Commits
 
 
 
 
 
 

Repository files navigation

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).

class example

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

database example

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)

About

An example of asciidoc rendered on github (.adoc)

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published