Giter VIP home page Giter VIP logo

adoc-presentation-model's Introduction

README

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

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

preview light
preview dark

Plain HTML

PDF

preview html
preview pdf

1.2. Features

1.2.1. Documentation features

1.2.2. Generation features

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) and generate.bat on Windows.

./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 :

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 :

adoc-presentation-model's People

Contributors

bcouetil avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

adoc-presentation-model's Issues

D3 support?

Hey! I think this project is super awesome. I really like the "presentation as a code" approach. Are there any chances to also include some (easy) D3.js examples?

Thanks in advance.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.