index.md 4.53 KB
Newer Older
Guillaume Perréal's avatar
Guillaume Perréal committed
1
% prezbuilder 1.0.1
2
3
4
5
6
7
8
9
% 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/).
10
11
12
- 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é_.
13
14
15
16
17
18
- Mode "dev" avec rechargement automatique de page.

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

# Installation

19
## Avec NodeJS
20
21
22

Prérequis :

23
- [node 12](https://nodejs.org/fr/download/)
24
- [pandoc](https://pandoc.org/installing.html)
25
26
- [drawio-desktop](https://github.com/jgraph/drawio-desktop/releases/latest) (optionel)
- [wkhtmltopdf](https://wkhtmltopdf.org/downloads.html) (optionel)
27
28
- gulp-cli (`npm install --global gulp-cli`)

Guillaume Perréal's avatar
Guillaume Perréal committed
29
Installation :
30

31
```bash
Guillaume Perréal's avatar
Guillaume Perréal committed
32
npm install --global git+https://gitlab.irstea.fr/pole-is/tools/prezbuild.git
33
34
35
36
```

## Avec Docker

Guillaume Perréal's avatar
Guillaume Perréal committed
37
L'image gitlab-registry.irstea.fr/pole-is/tools/prezbuilder:1.0.1 contient
38
39
une version préinstallée de prezbuilder avec pandoc et wkhtmltopdf, _mais pas
drawio_.
40
41
42

```bash
docker login gitlab-registry.irstea.fr
Guillaume Perréal's avatar
Guillaume Perréal committed
43
docker pull gitlab-registry.irstea.fr/pole-is/tools/prezbuilder:1.0.1
44
```
45
46
47

## Avec Gitlab Pages

48
49
50
51
52
53
54
55
56
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
Guillaume Perréal's avatar
Guillaume Perréal committed
57
    ref: 1.0.1
58
59
60
61
    file: prezbuilder-ci.yml

pages:
  extends: .prezbuilder
62
  # Exemple: n'exécute ce job que pour les tags.
63
64
  # cf. https://docs.gitlab.com/ce/ci/yaml/README.html#rules
  rules:
65
    - if: $CI_COMMIT_TAG
66
```
67
68
69
70
71
72

# Utilisation

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

73
74
75
76
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.

77
78
79
80
81
82
83
## 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é.
84
85
- _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).
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

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

129
130
131
132
133
134
135
136
137
138
# 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.

139
## Avec NodeJS
140

141
#### Build
142

143
```bash
Guillaume Perréal's avatar
Guillaume Perréal committed
144
prezbuilder build [répertoire_source [répertoire_sortie]]
145
146
```

147
#### Dev
148

149
```bash
Guillaume Perréal's avatar
Guillaume Perréal committed
150
prezbuilder dev [répertoire_source [répertoire_sortie]]
151
152
```

153
154
## Avec Docker

155
156
157
158
Il est recommandé de créer un script `prezbuilder` pour faciliter l'utilisation :

```shell
#!/usr/bin/env bash
Guillaume Perréal's avatar
Guillaume Perréal committed
159
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}
160
```
161

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

#### Build
165

166
```bash
167
prezbuilder build src public
168
```
169
170
171
172

#### Dev

```bash
173
prezbuilder dev src public
174
```
Guillaume Perréal's avatar
Guillaume Perréal committed
175
176
177
178
179

# Références

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