% prezbuilder
% Guillaume Perréal
% 2020-05

# Présentation

- 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).
- Mode "dev" avec rechargement automatique de page.

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

# Installation

## Avec NPM

Prérequis :

- [node 10+](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)
- gulp-cli (`npm install --global gulp-cli`)

Installation :

```bash
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**.

```bash
docker login gitlab-registry.irstea.fr
docker pull gitlab-registry.irstea.fr/pole-is/tools/prezbuilder:master
```

## Avec Gitlab Pages

_A venir._

# 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.
- _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).

## Exemple

<div style="display:flex;width:100%;align-items:center">

<div style="flex-grow: 1">
Entrée:

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

</div>

<div style="margin: 1ex; font-size: 24pt">➩</div>

<div style="flex-grow: 1">
Sortie :

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

</div>

</div>

# 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 NPM

#### Build

```bash
prezbuilder build [répertoire_source [répertoire_sortie]]
```

#### Dev

```bash
prezbuilder dev [répertoire_source [répertoire_sortie]]
```

## Avec Docker

#### Build

Il faut mapper les répertoires /src et /public sur vos sources et le répertoire de sortie :

```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
```

#### 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
```

# Références

- [Documentation reveal.js](https://github.com/hakimel/reveal.js/#table-of-contents)
- [Documentation pandoc](https://pandoc.org/MANUAL.html)