= README :toc: :toclevels: 2 :sectnums:
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.
WARNING: MS Windows generation files are not actively maintained and tested
== What
=== Preview
link:https://bcouetil.gitlab.io/asciidoc-stack/main/guides/guides/syntax-quick-reference.htm#/[Basic Asciidoc syntax] and link:https://bcouetil.gitlab.io/asciidoc-stack/main/guides/guides/reveal-my-asciidoc.htm#/[Advanced Reveal.js capabilities] generated examples are hosted on GitLab pages.
[cols="a,a", frame=none, grid=none] |=== | Light theme slides | Dark theme slides | image::preview-light.jpg[link="https://bcouetil.gitlab.io/asciidoc-stack/main/guides/guides/syntax-quick-reference.htm#/"] | image::preview-dark.jpg[link="https://bcouetil.gitlab.io/asciidoc-stack/main/guides/guides/reveal-my-asciidoc.htm#/"] | Plain HTML | PDF | image::preview-html.jpg[link="https://bcouetil.gitlab.io/asciidoc-stack/main/guides/guides/reveal-my-asciidoc.html"] | image::preview-pdf.jpg[link="https://bcouetil.gitlab.io/asciidoc-stack/main/guides/guides/reveal-my-asciidoc.pdf"] |===
=== Features
==== Documentation features
==== Generation features
==== Organisation features
== How
=== How do I generate documents ?
You can use generate.sh on Linux & MacOS (M1 supported) and generate.bat on Windows.
all to generate all documents
<category/subject> is a 2 folders deep path to documents (all documents must match this layout)reveal, html, pdf, zip or alllive for link:[live-reload] in your favorite web browser./generate.sh devops/kubernetes-user html
./generate.sh
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
==== Live reload
===== Debian/Ubuntu
generate.sh provides a live reload solution based on inotifywait on Unix environment:
inotify-tools[source,shell] sudo apt-get install inotify-tools
[source,shell] cd build-docs python3 -m http.server
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, link:https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[documentation present some alternatives] but not for Reveal.js. Some other solutions involve VS Code extensions or Ruby in an link:https://github.com/asciidoctor/asciidoctor-reveal.js/issues/248[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 @(
===== MacOS
Not yet supported, MR are welcome 🤓
=== 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/
==== Pre-requisite
Careful with | often not handled correctly if not in tables. Modify them first.
Ex: Pull|Merge changed to Pull/Merge
==== .md to .adoc automatically
Use preferably Kramdoc.
Although pandoc can link:https://matthewsetter.com/convert-markdown-to-asciidoc-withpandoc/[also be used], kramdoc gives link:https://matthewsetter.com/convert-markdown-to-asciidoc-with-kramdown-asciidoc/[better results].
.Install Ruby and Kramdoc [source, shell] sudo apt-get install ruby-full rename sudo gem install kramdown-asciidoc
.Launch on a file [source, shell] kramdoc --output=getting-started.adoc --imagesdir=ressources --lazy-ids --heading-offset=1 --wrap=ventilate getting-started.md
.Launch on a folder [source, shell] find ./ -name "*.md" -type f -exec sh -c 'kramdoc --imagesdir=ressources --lazy-ids --heading-offset=1 --wrap=ventilate --output=_includes/{}.adoc {}' \;
.Rename files [source, shell] find _includes -type f -name "*.adoc" -exec rename s/".md"/""/g {} \;
==== 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)
[cols="^,<3,<3",options="header"] |===
| regex | from | to
| yes | // .slide: class=".*"\n |
| no | {plus}{plus}{plus}</figure>{plus}{plus}{plus} |
| no | {plus}{plus}{plus}<div class="pb">{plus}{plus}{plus}{plus}{plus}{plus}</div>{plus}{plus}{plus} |
| yes | +\{blank\}( \+ )*( \+)( )*+ |
| yes | ^( )*\.\.\.$ |
| yes | ,[0-9]+% |
| 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 | {nbsp}{nbsp}{plus}{nbsp}{nbsp}{plus} | .
| no | __ | ➡
| no | ➡➡ | +____+
| no | [.fa.fa-info-circle]## | NOTE:
// TODO : say only in _slides/*
| no | === TP | [.lab]\n=== TP
|===
== Why
=== 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 :
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.
=== Why a Mono-repo ?
=== 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 :
////
Pour remplacer partout des blocs shells par des blocs monospace sous vscode
par
ifdef::solutions[] .solutions .... $2 ....
////