AsciiDoc & doc-as-code Best Practices2020-01-28

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

COUETIL

Ὅ� (doc) add asciidoc docker generation sample on gitlab + add pipeline sh scripts

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

DemoSee 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 tagThis is now core in Asciidoctor ✌

{  "key" : "key", "value" : "value"}

source

[%collapsible%open]====[source, json]....{  "key" : "key", "value" : "value"}....====

4

init and closureHere 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

<!-- to generate asciidoc PDF + HTML documents --><!-- single usage : mvn generate-resources -Dadoc.skip=false [- -non-recursive] --><plugin>  <groupId>org.asciidoctor</groupId>  <artifactId>asciidoctor-maven-plugin</artifactId>  <!-- to increment versions, see pom.xml examples on Asciidoctor Github -->  <!-- 1.5.7 and 1.5.7.1 show too many warnings on PDF -->  <version>1.5.6</version>  <!-- if we don't want to execute in modules (this would work though) -->  <inherited>false</inherited>  <dependencies>  <dependency>  <groupId>org.asciidoctor</groupId>  <artifactId>asciidoctorj-pdf</artifactId>  <version>1.5.0-alpha.16</version>  </dependency>  <dependency>  <groupId>org.asciidoctor</groupId>  <artifactId>asciidoctorj-diagram</artifactId>  <version>1.5.9</version>  </dependency>  <!-- comment to use the default version -->  <dependency>  <groupId>org.jruby</groupId>  <artifactId>jruby-complete</artifactId>  <version>9.1.17.0</version>  </dependency>  <!-- comment to use the default version -->  <!-- <dependency>  <groupId>org.asciidoctor</groupId>  <artifactId>asciidoctorj</artifactId>  <version>1.5.7</version>  </dependency> -->  </dependencies>  <configuration>  <skip>${adoc.skip}</skip>  <sourceDirectory>src/docs/asciidoc</sourceDirectory>  <requires>  <require>asciidoctor-diagram</require>  <require>./src/docs/asciidoc/lib/c3js-block-macro.rb</require>  </requires>  <attributes><!-- common to all backends -->  <icons>font</icons><!-- for Font Awesome icons -->  <idseparator>-</idseparator>  <idprefix />  <experimental/><!-- kbd / menu / btn macros -->  <!-- custom -->  <source-dir>../../main/java</source-dir>  <test-dir>../../test/java</test-dir>

6

  <project-version>${project.version}</project-version>  <root-project-dir>${user.dir}</root-project-dir>  <history-dir>${project.build.directory}/generated-docs/history</history-dir>  <project-images-dir>${project.basedir}/src/main/resources/images</project-images-dir>  <!-- 'plantuml-config' for plantuml, 'salt-config' for salt, 'plantumlconfig' for both -->  <plantuml-config>themes/plantuml.cfg</plantuml-config>  </attributes>  </configuration>  <executions>  <execution>  <id>asciidoc-to-html</id>  <phase>generate-resources</phase>  <goals>  <goal>process-asciidoc</goal>  </goals>  <configuration>  <backend>html5</backend>  <!-- coderay, highlight.js, prettify -->  <!-- coderay/prettify have only a bright theme -->  <!-- prettify is nice but comments are red -->  <!-- pygments/rouge is not integrated yet : https://github.com/asciidoctor/asciidoctor/issues/1040 -->  <sourceHighlighter>highlight.js</sourceHighlighter>  <attributes>  <!-- local version to go beyond basic languages (for ex groovy) -->  <highlightjsdir>lib/highlight</highlightjsdir>  <!-- explore here https://highlightjs.org/static/demo/ -->  <highlightjs-theme>gruvbox-dark</highlightjs-theme>  <imagesdir>./images</imagesdir>  <toc>left</toc>  <toclevels>5</toclevels>  <sectnums/><!-- for sections to be numbered -->  <sectanchors>true</sectanchors>  <docinfo1>true</docinfo1>  <favicon>themes/favicon-white.png</favicon>  <linkcss />  <stylesheet>html-zenika.css</stylesheet>  <stylesdir>themes/css</stylesdir>  </attributes>  </configuration>  </execution>  <execution>  <id>asciidoc-to-revealjs</id>  <!-- after html because it's also an html -->  <phase>generate-resources</phase>  <goals>  <goal>process-asciidoc</goal>  </goals>  <configuration>  <backend>revealjs</backend>  <sourceDocumentName>PRES-asciidoc.adoc</sourceDocumentName>  <outputFile>${project.slides.directory}/PRES-asciidoc.html</outputFile>  <templateDir>${project.build.directory}/asciidoctor-reveal.js-${asciidoctor-revealjs.version}/templates</templateDir>  <attributes>  <source-highlighter>highlightjs</source-highlighter>  <highlightjs-theme>lib/highlight/styles/gruvbox-dark.min.css</highlightjs-theme>  <revealjsdir>reveal.js-${revealjs.version}</revealjsdir>  <!-- default closest to Zenika's graphic chart : -->  <!-- <revealjs_theme>blood</revealjs_theme> -->  <revealjs_customtheme>themes/reveal-zenika-dark.css</revealjs_customtheme>  <!-- none, fade, slide, convex, concave, zoom -->  <!-- dynamic : PRES-asciidoc.html?transition=convex -->  <revealjs_transition>slide</revealjs_transition>  <revealjs_slideNumber>true</revealjs_slideNumber>  <!-- does not work T_T only solution is put a favicon.ico in the root folder of the website -->  <!-- <favicon>themes/favicon.png</favicon> -->  <revealjs_width>1100</revealjs_width>  <revealjs_height>700</revealjs_height>  <revealjs_plugins>revealjs-plugins/revealjs-plugins.js</revealjs_plugins>  <revealjs_plugins_configuration>revealjs-plugins/revealjs-plugins-conf.js<

7

/revealjs_plugins_configuration>  </attributes>  </configuration>  </execution>  <execution>  <id>asciidoc-to-pdf</id>  <phase>generate-resources</phase>  <goals>  <goal>process-asciidoc</goal>  </goals>  <configuration>  <backend>pdf</backend>  <sourceHighlighter>rouge</sourceHighlighter>  <attributes>  <imagesdir>${project.build.directory}/generated-docs/images</imagesdir>  <toc />  <sectnums/><!-- for sections to be numbered -->  <toclevels>3</toclevels>  <pagenums />  <pdf-style>${user.dir}/src/docs/asciidoc/themes/pdf-theme.yml</pdf-style>  <pdf-fontsdir>${user.dir}/src/docs/asciidoc/themes/fonts/pdf</pdf-fontsdir>  </attributes>  </configuration>  </execution>  </executions></plugin>

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.gradlebuildscript {  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 copyasciidoctor.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 rebuiltcp -r docs .build-docsdocker run --rm -v ${PWD}/.build-docs:/documents asciidoctor/docker-asciidoctor asciidoctor -r asciidoctor-diagram -aicons=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 -afavicon=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 <workspaceDirectory>" >&2  exit 1fiif ! [ -e "$1" ]; then  echo "$1 not found" >&2  exit 1fiif ! [ -d "$1" ]; then  echo "$1 not a directory" >&2  exit 1fi

echo "Getting last tag..."lastTag=`git describe --tags --abbrev=0`

for projectRoot in . cg-utils cg-msg-tracker cg-elasticdo  #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 $targetDirdone

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.listecho "Modified adoc files are :"cat modified-adocs.listecho "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  fidone

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 renamesudo 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 docscd docsgit initgit 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

<plugin>  <groupId>org.apache.maven.plugins</groupId>  <artifactId>maven-scm-publish-plugin</artifactId>  <version>3.0.0</version>  <inherited>false</inherited>  <configuration>  <scmBranch>gh-pages</scmBranch>  <!-- token generated from github > settings > Developer settings > Personal access tokens > public_repo -->  <pubScmUrl>scm:git:https://USER:TOKEN@github.com/USER/docs.git</pubScmUrl>  <content>target/generated-docs</content>  </configuration></plugin>

Confluence to AsciidocFrom 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.jsSee 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&parallaxBackgroundSize=2100px%20900px

15

16