% prezbuilder 1.0.1
% 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/),
  _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 NodeJS

Prérequis :

- [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)
- 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:1.0.1 contient
une version préinstallée de prezbuilder avec pandoc et wkhtmltopdf, _mais pas
drawio_.

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

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

```yaml
include:
  - project: pole-is/tools/prezbuilder
    ref: 1.0.1
    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

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

#### Build

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

#### Dev

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

## Avec Docker

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:1.0.1 ${1:-build}
```

Ce script s'utilise comme celui présenté de NodeJS :

#### Build

```bash
prezbuilder build src public
```

#### Dev

```bash
prezbuilder dev src public
```

# Références

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