prezbuilder 1.1.0

Guillaume Perréal

2020-05

Présentation

  • Génère des présentations reveal.js à partir de fichiers en markdown.
  • Utilise le thème INRAE.
  • Génération de la présentation avec pandoc.
  • Conversion automatique de graphes créés avec draw.io, si drawio-desktop est installé.
  • Génération d’une version PDF avec wkhtmltopdf, s’il est installé.
  • Support des graphes mermaid.js intégrés.
  • Mode “dev” avec rechargement automatique de page.

La présentation que vous regardez a été générée avec prezbuilder !

Installation

Avec Docker

L’image gitlab-registry.irstea.fr/pole-is/tools/prezbuilder:1.1.0 contient une version préinstallée de prezbuilder avec pandoc et wkhtmltopdf, mais pas drawio.

Il faut s’authentifier sur la registry Docker de Gitlab si ce n’est pas déjà fait :

docker login gitlab-registry.irstea.fr

Ensuite, le plus simple est de récupérer le script prezbuilder-docker :

sudo wget https://gitlab.irstea.fr/pole-is/tools/prezbuilder/-/raw/1.1.0/bin/prezbuilder-docker?inline=false -O /usr/local/bin/prezbuilder-docker
sudo chmod a+rx /usr/local/bin/prezbuilder-docker

Avec Gitlab Pages

Le projet contient un modèle Gitlab CI à inclure dans .gitlab-ci.yml. Il définit un modèle de job .prezbuilder qui peut être utilisé comme job pages pour publier automatiquement les présentations de src. Il utilise l’image Docker, donc génère les PDF mais ne convertit pas les graphes drawio.

include:
  - project: pole-is/tools/prezbuilder
    ref: 1.1.0
    file: prezbuilder-ci.yml

pages:
  extends: .prezbuilder
  # Exemple: n'exécute ce job que pour les tags.
  # cf. https://docs.gitlab.com/ce/ci/yaml/README.html#rules
  rules:
    - if: $CI_COMMIT_TAG

Utilisation

prezbuild crée une (ou plusieurs) présentation(s) dans public/ à partir du contenu du répertoire src/.

Chaque présentation est écrite sous la forme d’un fichier au format Markdown nommés index.md. Il est possible d’ajouter des images aux formats PNG, JPG, GIF ou SVG à référencer depuis le fichier markdown.

Organisation des fichiers

Le répertoire src/ est parcouru récursivement, et les fichiers sont traités comme suit :

  • Les fichiers index.md sont convertis en présentation index.html.
  • Les fichiers .png, .jpg, .gif et .svg sont copiés tels quels.
  • S’il n’y a pas de fichier index.md à la racine, un index des présentations est généré.
  • Si drawio est installé, les fichiers .drawio sont convertis en fichiers .svg.
  • Si wkhtmltopdf est installé un fichier .pdf est généré par fichier index.md, avec le nom du répetoire parent (en sortie).

Exemple

Entrée:

src\
    pres1\
        index.md
        graph.drawio
    pres2\
        index.md
        photo.jpg
➩

Sortie :

public\
    index.html
    public.pdf
    pres1\
        index.html
        pres1.pdf
        graph.svg
    pres2\
        index.html
        pres2.pdf
        photo.jpg

Exécution

prezbuiler peut être exécuté selon deux modes :

  • build : une seule exécution.
    • pour produire les fichiers de la présentation.
  • dev : mode serveur avec live-reload,
    • présentation accessible sur http://localhost:3000,
    • mise à jour automatique sur modification des sources.

Avec Docker

Le script pour Docker s’utilise comme celui présenté de NodeJS :

Build

prezbuilder-docker build src public

Dev

prezbuilder-docker dev src public

Références