README

Table of Contents

• 1. What
  • 1.1. Preview
  • 1.2. Features
• 2. How
  • 2.1. How do I generate documents ?
  • 2.2. How do I migrate from existing Markdown documents ?
• 3. Why
  • 3.1. Why Asciidoc over Markdown ?
  • 3.2. Why a Mono-repo ?
  • 3.3. Why do Reveal.js themes all look pretty much the same ?
• 4. License

This is a live documentation generation stack, used for some Zenika training material. It is based on Asciidoc and/or Markdown. It is a mono-repository including both framework and documents.

0% knownledge in HTML/CSS/JS is required to produce/update a document, and still being able to include advanced capabilities. Guides are provided, see hosted content above.

1. What

1.1. Preview

Basic Asciidoc syntax and Advanced Reveal.js capabilities generated examples are hosted on GitLab pages.

Light theme slides	Dark theme slides
Plain HTML	PDF

1.2. Features

1.2.1. Documentation features

• Generate reveal.js, HTML and PDF documents from the same source without much care of the output type as a writer

• All features of Asciidoc implemented by Asciidoctor and transposed to hosted Reveal.js presentations containing associated HTML and PDF links

• All features of Asciidoctor-reveal which implements most features of reveal.js, especially step-by-step code highlighting

• Basic Markdown features

• All features of Asciidoctor-pdf

• All useful reveal.js plugins known to date (please contribute or advise if a key plugin is missing)

• Some C3JS (D3JS) chart-as-code addons (for Reveal.js & HTML only) for dynamic and interactive charts

• PlantUML diagrams with custom colors

• Other "as-code" addons oriented toward Reveal.js presentations

• Reveal.js themes are designed to be able to display any content (when reasonable sections size)

• There are light and dark Reveal.js themes switchable in-presentation with no awareness needed while writing documentation. All colors are designed to fit both, especially PlantUML colors

1.2.2. Generation features

• Support for Linux, MacOS and Windows

• There is a single generate.sh script to generate everything

• Generation uses Docker and is based on docker-asciidoctor image. A slightly modified version, to have an edge version of asciidoctor-reveal

• The script provides a way to live-reload generated content on modifications

• Using GitLab pipelines, result is generated and hosted on GitLab pages per branch using the GitLab cache mechanism

1.2.3. Organisation features

• Documents and framework are united in a mono-repo

• Documents are in folders under a category for better segregation of subjects

2. How

2.1. How do I generate documents ?

You can use generate.sh on Linux & MacOS (M1 supported). It also works on Windows using specific instructions for Git bash.

./generate.sh [all|<category/subject>] [all|html|reveal|pdf|zip] [live]

• Optional parameter 1 is the documents scope of the generation

  • all to generate all documents

  • <category/subject> is a 2 folders deep path to documents (all documents must match this layout)

• Optional parameter 2 is the type of document

  • reveal, html, pdf, zip or all

• Optional parameter 3 is live for live-reload in your favorite web browser

Examples

# generate html version of devops/kubernetes-user documents
./generate.sh devops/kubernetes-user html

# generate everything for every documents
./generate.sh
# equivalent to
./generate.sh all all

Slides, HTML and PDF are generated in build-docs folder. Target folder is cleaned each time to ensure update of generated content.

Note	This script is also used by CI

2.1.1. Live reload

Debian/Ubuntu

generate.sh provides a live reload solution based on inotifywait on Unix environment:

• Install inotify-tools

sudo apt-get install inotify-tools

• Generate at least once for the server to have files to serve

./generate.sh devops/kubernetes-user reveal

• Start a http server

cd build-docs
python3 -m http.server

• In another terminal, launch live reload mode

./generate.sh devops/kubernetes-user reveal live

You can now browse files from local server, for example http://localhost:8000/kubernetes-user.htm. Files are automatically refreshed in your browser, thanks to a JS script included in generated HTML.

Note	No Asciidoc built-in live reload for now, documentation present some alternatives but not for Reveal.js. Some other solutions involve VS Code extensions or Ruby in an open issue.

MS Windows

You can simulate a basic continuous regeneration every 5 seconds with this code running under any windows console (Windows or Windows+R and then type “cmd” and validate)

for /l %g in () do @(<ANY COMMAND> & timeout /t 5)

# In our case :
for /l %g in () do @(generate agile\kanban-1j reveal & timeout /t 5)

MacOS

Not yet supported, MR are welcome 🤓

2.2. How do I migrate from existing Markdown documents ?

This stack is more for new documents for people preferring Asciidoc. But an actual Markdown document can be migrated pretty fast.

Tip	For small text blocks there are online translation tools such as https://markdown2asciidoc.com/

2.2.1. Pre-requisite

Careful with | often not handled correctly if not in tables. Modify them first.

Ex: Pull|Merge changed to Pull/Merge

2.2.2. .md to .adoc automatically

Use preferably Kramdoc.

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 {} \;

2.2.3. Post-processing for Zenika trainings migration

• Delete agenda if any (use Table of Content, see examples)

• Replace in every .adoc files (VS Code regex style)

regex	from	to
yes	// .slide: class=".*"\n	<delete>
no	+++</figure>+++	<delete>
no	+++<div class="pb">++++++</div>+++	<delete>
yes	\{blank\}( \ )( +)( )+	<delete>
yes	^( )*\.\.\.$	<delete>
yes	,[0-9]+%	<delete>
yes	Notes :\r?\n((\r?\n(?!=).*)*)	ifdef::backend-revealjs[]\n[.notes]\n****$1\n****\nendif::backend-revealjs[]\n
yes	^(=== .*)\n\n// .slide: id="(.*)"	[#$2]\n$1
yes	\+\+<figure>+\+\++	\n\n
yes	<</([a-z])	<<$1
no	+  +	.
no	__	➡
no	➡➡	____
no	[.fa.fa-info-circle]##	NOTE:
no	=== TP	[.lab]\n=== TP

• Update links to chapters from numbers to cross references

3. Why

3.1. Why Asciidoc over Markdown ?

TLDR; standard Markdown is too poor as a lightweight markup language, and needs too many addons and custom development to fit HTML, Reveal.js and PDF.

Some elaborated articles :

• Compare AsciiDoc to Markdown

• Why you should use AsciiDoc to document your Software Solution

• Try AsciiDoc instead of Markdown

• AsciiDoc is the better Markdown

• Lightweight Markup Languages: This Is Why You Should Use AsciiDoc Over Regular Markdown

The current stack has been gathered and maintained by a single person in his spare time. Almost no development needed. this is hardly possible on markdown stacks with the same features coverage.

3.2. Why a Mono-repo ?

• Simplicity : To ease core modifications and generation in a single MR

• Modularity : To allow include in documents from one to another

3.3. Why do Reveal.js themes all look pretty much the same ?

There is no particular reason.

You don’t like the result ? It’s perfectly fine. You can change basic things like slide transition and background in-presentation. But, most important, you can contribute with any Reveal.js CSS you find/produce that fits your presentation style, just add it in the appropriate folder and import it at the beginning of your presentation.

Here is a list of nice Asciidoc-based Reveal.js slide decks, for inspiration :

• https://slides.codefx.org (monorepo : https://github.com/CodeFX-org/slides)

4. License

This project is licensed under the MIT License. See the LICENSE.adoc file for details.