AsciiDoc & doc-as-code Best Practices
2020-06-25 Table of Contents
Demo ...... 2
Editors ...... 2
Visual Studio Code...... 2
AsciidocFX ...... 2
Graphviz ...... 3
Inline icons...... 3
In PlantUml ...... 4
Custom code highlighter ...... 4
dropdown code snippet / details html tag ...... 4
init and closure ...... 5
Generation...... 5
Maven ...... 5
Gradle ...... 8
Docker ...... 9
Use in pipelines ...... 10
translations ...... 12
.doc to .adoc ...... 12
.md to .adoc ...... 12
Publish HTML & PDF to github ...... 13
Initialize Github space...... 13
Configure Maven plugin ...... 14
Confluence to Asciidoc ...... 14
Reveal.js...... 15
Examples ...... 15
Fullscreen on smartphone ...... 15
Generation ...... 15
Inline options ...... 15 Table 1. History
Date Author Detail
2020-01-28 bcouetil Ὅ (all) refactor detail tag to new collapsible asciidoc feature
2020-01-28 bcouetil Ὅ (core) update theme
2020-01-28 bcouetil Ὅ (core) remove sample and build with docker
2019-12-15 Benoît Ὅ (doc) add asciidoc docker generation sample on gitlab + add pipeline sh scripts COUETIL
2019-10-24 bcouetil Ὅ added asciidoctor generation using docker + gitlab deploy to k8s / aws
2019-07-23 bcouetil k8s updates + gitlab mono-repo yarn + openiconic
2019-05-09 bcouetil eks terraform+ hyperledger + k8s aliases + cert manager + k8s aws anonymous + k8s tools + gerrit replication
2019-04-22 bcouetil eks dashboard & deployment scale + unselectable $ before shell commands + fully working spotlight
2019-04-11 bcouetil k8s & aws-eks merge + k8s aws dashboard + k8s istio + jdk8 in CI + gitlab & nexus following lacroix exp + new backgrounds
2019-03-12 bcouetil asciidoc/gradle + new backgrounds + meme extension + k8s/aws/kubespray doc following lacroix experience + aws/eks/users/ci
2019-01-10 bcouetil reveal my asciidoc + last slide animated bubbles + updated reveal theme + css c3js fix + maven wrapper
2018-12-18 bcouetil Moved Gerrit plugin configuration from Jenkins to Gerrit page + Enhanced HTML CSS + Cropped some images + Improved PlantUML skin
2018-12-11 bcouetil - Added reveal plugins and background - Fixed reveal css following change in structure in asciidoc-reveal master (from previous version : 1.1.3) - Implemented Zenika layout in HTML and PDF - Reported back reveal-js enhancements
2018-11-28 bcouetil - Updated reveal css for all syntax elements, for both light and dark themes : asciidoc-syntax-quick-reference is now nicely output - Refactored light and dark css, extracting common items into reveal-zenika.css - Added syntax quick reference in all format generated and linked in asciidoc page
2018-11-13 bcouetil - Updated sample project with Reveal.js generation - Duplicated Reveal.js execution to have multiple styles - Compromised layout between 4/3 and 16/9 - Minor changes in Reveal.js css - Added some web comics
2018-11-02 bcouetil - reorganized asciidoc best practices - added some Geek & Poke images - reveal.js themes Zenika dark + light + parallax - updated asciidoc/reveal versions in pom.xml
2018-09-19 bcouetil - Sample asciidoctor maven project published on Github - Github & LinkedIn links - Sample project tree - new images + resizing and positioning
2018-08-29 bcouetil Asciidoc HTML look & feel changes
2018-08-24 bcouetil Icones added for download + favicon added for webpage
2018-08-23 bcouetil Initial commit
1 Demo
See advanced everything-as-code Reveal.js demo : Reveal my Asciidoc. Editors
Visual Studio Code
"asciidoc.preview.attributes": { "plantuml-server-url": "https://www.plantuml.com/plantuml", "imagesdir": "images", "toc": "auto" }
AsciidocFX
To help you to write your documentation, use AsciidocFX. It will allows you to visualize your documentation without having to generate the PDF. You can consider Visual Studio Code too, it has a nice plugin but with less features.
2 Download and install :
• AsciidocFX, to create and edit your documents • Graphviz, to add the extension for your AsciidocFX installation
Rules to produce AsciiDoc files : • File names are in kebab-case, except the type at the beginning • Use kbd:[myShortcut] for keyboard shortcuts • Use \btn[myButton] for buttons • High level title should be on new pages (use <<<)
Diagrams are generated using PlantUML. Here are some examples with Zenika’s style.
To show a in progress diagram to colleagues, you can generate a web link using PlantUml generator. There is also PlantText.
Graphviz
Graphviz has to be installed to use PlantUML diagrams.
On Windows • Download and install : http://www.graphviz.org/download/ • add bin directory to windows path ◦ C:\Program Files (x86)\Graphviz\bin Inline icons
• See https://asciidoctor.org/docs/user-manual/#icons • Font Awesome 4.6.3 Class Explorer : https://lab.artlung.com/font-awesome-sample/
3 ◦ no need for :icons: font to use font awesome-font for icons
In PlantUml
In PlantUml, OpenIconic can be used, see official documentation. Custom code highlighter
• To use a custom code highlighter, see the maven configuration in next paragraphs • Default highlight.js processor is too basic, instructions here to change • Highlight.js demo with all languages and all styles dropdown code snippet / details html tag
This is now core in Asciidoctor ✌
{ "key" : "key", "value" : "value" }
source
[%collapsible%open] ==== [source, json] .... { "key" : "key", "value" : "value" } .... ====
4 init and closure
Here are the sources of init.adoc and closure.adoc included in various sources in this documentation.
They are here for generic configuration and data accross files. Generation
Maven
5 Figure 1. File system tree pom.xml substract
6
7 /revealjs_plugins_configuration>
To generate locally, use the maven command :
mvn generate-resources --non-recursive
Gradle
Here is a build to generate Asciidoc HTML using Gradle (HTML only for now).
8 build.gradle
//$env:JAVA_HOME="C:\Program Files\Java\jdk1.8.0_201\";./gradlew asciidoctor -b .\build.adoc.gradle buildscript { dependencies { classpath 'org.asciidoctor:asciidoctorj-diagram:1.5.9' } }
plugins { id 'org.asciidoctor.convert' version '1.5.3' }
repositories { jcenter() }
//Copy first because asciidoc validates (target) css path before the copy asciidoctor.doFirst { copy { from file('src/docs/asciidoc') into file("$buildDir/asciidoc/html5") include '**/*.*' } }
asciidoctor { backends 'html5' requires 'asciidoctor-diagram' attributes \ 'build-gradle': file('build.asciidoc.gradle'), 'source-highlighter' : 'highlight.js', 'highlightjsdir' : 'lib/highlight', 'highlightjs-theme' : 'gruvbox-dark', 'imagesdir': 'images', 'toc': 'left', 'toclevels': 2, 'sectanchors': true, 'sectnums': true, 'favicon': 'themes/favicon.png', 'linkcss': true, 'stylesheet': 'html-arkea.css', 'stylesdir': 'themes/css', 'plantuml-config': 'themes/plantuml.cfg' }
To generate locally, use the gradle command :
gradlew asciidoctor -b build.adoc.gradle
Docker
To run asciidoctor locally, in a non Maven/Gradle project, we cas use the docker image, like we would do in a CI build.
Assuming that asciidoctor files are in $WORKSPACE/docs
9 rm -rf .build-docs # else plantuml diagrams won't be rebuilt cp -r docs .build-docs docker run --rm -v ${PWD}/.build-docs:/documents asciidoctor/docker-asciidoctor asciidoctor -r asciidoctor-diagram -a icons=font -a experimental=true -a source-highlighter=highlight.js -a highlightjsdir=themes/highlight -a highlightjs- theme=gruvbox-dark -a imagesdir=images -a toc=left -a toclevels=2 -a sectanchors=true -a sectnums=true -a favicon=themes/favicon.png -a linkcss=true -a stylesheet=html-project.css -a stylesdir=themes/css -a plantuml- config=themes/plantuml.cfg '*.adoc'
.build-docs folder is not created under docs, since we copy one into the other.
Use in pipelines
To use in Jenkins Pipelines, see Jenkins Best Practices
To use in Gitlab Pipelines, see Gitlab Best Practices scripts
Script to get history of *.adoc files from git, to be have an history table in pdf.
10 Example 1. asciidoc-history.sh
#!/bin/bash # # ASCIIDOC GIT HISTORY #
if [ "$#" -ne 1 ]; then echo "Usage : $0
echo "Getting last tag..." lastTag=`git describe --tags --abbrev=0`
for projectRoot in . cg-utils cg-msg-tracker cg-elastic do #create the history folder if not exist targetDir=$1/$projectRoot/target/generated-docs/history sourceFiles=$1/$projectRoot/src/docs/asciidoc/*.adoc mkdir --parents $targetDir for adocFile in $sourceFiles do echo "Getting git log for $adocFile file..." #get the log from git and write it in CSV in a saved history file, for asciidoc usage #"follow" helps not loosing history after file rename git log --follow --max-count=30 --date=short --pretty=format:\|%cd\|%an\|%s -- $adocFile > $targetDir/`basename $adocFile`.psv echo "...Successfully written $targetDir/`basename $adocFile`.psv" echo "Getting git diff since last tag ($lastTag) for $adocFile file..." #the four first lines are git diff data, not usefull for doc reader, we remove them git diff $lastTag.. -- $adocFile | tail -n +5 > $targetDir/`basename $adocFile`.diff echo "...Successfully written $targetDir/`basename $adocFile`.diff" done ls -lrt $targetDir done
Script to remove non-modified *.adoc files, to speed up building process if needed.
11 Example 2. asciidoc-only-modified.sh
#!/bin/bash
# #for adoc generation optimization # #Find adoc modified files and prepend them with "./" git diff origin/master --name-only | grep adoc | sed 's/.*/\.\/&/' > modified-adocs.list echo "Modified adoc files are :" cat modified-adocs.list echo "Deleting the others to speed up the build..." for file in `find . -type f -name "*.adoc" ! -path "*/_*"`; do grep $file modified-adocs.list >/dev/null if [ $? -eq 1 ]; then echo "rm -f $file" rm -f $file fi done translations
.doc to .adoc
If the initial documentation is of Microsoft Word, you have to first migrate it to AsciiDoc file.
Download and install pandoc.
To migrate a document, use it in command line
pandoc --from=docx --to=asciidoc --wrap=none --atx-headers --extract-media=images monDoc.docx > monDoc.adoc
.md to .adoc
Although pandoc can also be used, kramdoc gives better results.
Install Ruby and Kramdoc
sudo apt-get install ruby-full rename sudo gem install kramdown-asciidoc
Launch on a file
kramdoc --output=getting-started.adoc --imagesdir=ressources --lazy-ids --heading-offset=1 --wrap=ventilate getting- started.md
Launch on a folder
find ./ -name "*.md" -type f -exec sh -c 'kramdoc --imagesdir=ressources --lazy-ids --heading-offset=1 --wrap=ventilate --output=_includes/{}.adoc {}' \;
Rename files
find _includes -type f -name "*.adoc" -exec rename s/".md"/""/g {} \;
12 Publish HTML & PDF to github
Initialize Github space
mkdir docs cd docs git init git checkout --orphan gh-pages
Copy a first version of the site in the directory, then :
git add * git commit -m "initial site content" git remote add origin "https://github.com/NeVraX182/docs.git" git push --set-upstream origin gh-pages
13 Configure Maven plugin
Maven SCM plugin configuration
Confluence to Asciidoc
From Confluence HTML export :
• Go to the space and choose [Space tools] → [Content Tools] from the bottom of the sidebar • Choose [Export] (you may need to zoom out to see it) • Choose [HTML] • Click [Unselect All] and choose specific pages • Click [Export]
14 TODO: https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/_includes/ convert-from-confluence-xhtml.adoc
Reveal.js
See official documentation on Asciidoctor website.
Examples
Official examples here, especially the G2 Scoring one.
Personnal examples : see at the end of the homepage.
Fullscreen on smartphone
On Android, common browsers have adress bar preventing reveal.js sites to go fullscreen. To get a real fullscreen, install Full Screen Browser.
Generation
Maven plugin showed above include a reveal.js generation.
Inline options
Some options can be added in HTTP address :
• PRES-asciidoc.html?transition=convex • PRES-asciidoc-light.html?slideNumber=false • https://revealjs.com/?parallaxBackgroundImage=https%3A%2F%2Fs3.amazonaws.com%2Fhakim- static%2Freveal-js%2Freveal-parallax-1.jpg¶llaxBackgroundSize=2100px%20900px
15 16