diff --git a/src/index.md b/src/index.md index 9f813fe3d8fed5d6a592e1cfa31433da04e39a63..c69b479e65336c6a1d1364c1c0db70bbfacf1a1b 100644 --- a/src/index.md +++ b/src/index.md @@ -7,19 +7,20 @@ - Génère des présentations [reveal.js](https://revealjs.com/) à partir de fichiers en markdown. - Utilise le [thème INRAE](https://gitlab.irstea.fr/pole-is/tools/reveal.js). - Génération de la présentation avec [pandoc](https://pandoc.org/). -- Conversion automatique de graphes créés avec [draw.io](https://app.diagrams.net/) (optionel). -- Génération d'une version PDF avec [wkhtmltopdf](https://wkhtmltopdf.org/) (optionel). +- Conversion automatique de graphes créés avec [draw.io](https://app.diagrams.net/), + _si drawio-desktop est installé_. +- Génération d'une version PDF avec [wkhtmltopdf](https://wkhtmltopdf.org/), _s'il est installé_. - Mode "dev" avec rechargement automatique de page. La présentation que vous regardez a été générée avec prezbuilder ! # Installation -## Avec NPM +## Avec NodeJS Prérequis : -- [node 10+](https://nodejs.org/fr/download/) +- [node 12](https://nodejs.org/fr/download/) - [pandoc](https://pandoc.org/installing.html) - [drawio-desktop](https://github.com/jgraph/drawio-desktop/releases/latest) (optionel) - [wkhtmltopdf](https://wkhtmltopdf.org/downloads.html) (optionel) @@ -33,8 +34,9 @@ npm install --global git+https://gitlab.irstea.fr/pole-is/tools/prezbuild.git ## Avec Docker -L'image gitlab-registry.irstea.fr/pole-is/tools/prezbuilder:master contient une version présinstalée -de prezbuilder **mais sans drawio**. +L'image gitlab-registry.irstea.fr/pole-is/tools/prezbuilder:master contient +une version préinstallée de prezbuilder avec pandoc et wkhtmltopdf, _mais pas +drawio_. ```bash docker login gitlab-registry.irstea.fr @@ -43,7 +45,25 @@ docker pull gitlab-registry.irstea.fr/pole-is/tools/prezbuilder:master ## Avec Gitlab Pages -_A venir._ +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. + +```yaml +include: + - project: pole-is/tools/prezbuilder + ref: master + file: prezbuilder-ci.yml + +pages: + extends: .prezbuilder + # Exemple: n'exécute ce job que pour la branche master. + # cf. https://docs.gitlab.com/ce/ci/yaml/README.html#rules + rules: + - if: $CI_COMMIT_BRANCH == "master" +``` # Utilisation @@ -60,9 +80,9 @@ Le répertoire `src/` est parcouru récursivement, et les fichiers sont traités - Les fichiers `index.md` sont convertis en présentation `index.html`. - Les fichiers `.png`, `.jpg`, `.gif` et `.svg` sont copiés tels quels. -- _Optionel:_ les fichiers `.drawio` sont convertis en fichiers `.svg`. - S'il n'y a pas de fichier `index.md` à la racine, un index des présentations est généré. -- _Optionel:_ un fichier `.pdf` est généré par fichier `index.md`, avec le nom du répetoire parent (en sortie). +- _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 @@ -116,7 +136,7 @@ prezbuiler peut être exécuté selon deux modes : - présentation accessible sur http://localhost:3000, - mise à jour automatique sur modification des sources. -## Avec NPM +## Avec NodeJS #### Build @@ -132,20 +152,25 @@ prezbuilder dev [répertoire_source [répertoire_sortie]] ## Avec Docker -#### Build +Il est recommandé de créer un script `prezbuilder` pour faciliter l'utilisation : + +```shell +#!/usr/bin/env bash +docker run --rm -t --init -u `id -u`:`id -g` -v `readlink ${2:-src}`:/src:ro -v `readlink ${3:-public}`:/public -p 3000:3000/tcp -p 35729:35729/tcp gitlab-registry.irstea.fr/pole-is/tools/prezbuilder:master ${1:-build} +``` -Il faut mapper les répertoires /src et /public sur vos sources et le répertoire de sortie : +Ce script s'utilise comme celui présenté de NodeJS : + +#### Build ```bash -docker run --rm -t --init -u $(id -u):$(id -g) -v $PWD/src:/src:ro -v $PWD/public:/public gitlab-registry.irstea.fr/pole-is/tools/prezbuilder:master build +prezbuilder build src public ``` #### Dev -Il faut également mapper les ports 3000 et 35729 : - ```bash -docker run --rm -t --init -u $(id -u):$(id -g) -v $PWD/src:/src:ro -p 3000:3000 -p 35729:35729 gitlab-registry.irstea.fr/pole-is/tools/prezbuilder:master dev +prezbuilder dev src public ``` # Références