index.md 3.87 KB
Newer Older
1
2
3
4
5
6
7
8
9
% 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/).
10
11
- 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).
12
13
14
15
16
17
- Mode "dev" avec rechargement automatique de page.

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

# Installation

Guillaume Perréal's avatar
Guillaume Perréal committed
18
## Avec NPM
19
20
21
22
23

Prérequis :

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

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

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

## Avec Docker

36
37
38
39
40
41
42
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
```
43
44
45
46
47
48
49
50
51
52

## Avec Gitlab Pages

_A venir._

# Utilisation

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

53
54
55
56
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.

57
58
59
60
61
62
## 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.
63
- _Optionel:_ les fichiers `.drawio` sont convertis en fichiers `.svg`.
64
- S'il n'y a pas de fichier `index.md` à la racine, un index des présentations est généré.
65
- _Optionel:_ un fichier `.pdf` est généré par fichier `index.md`, avec le nom du répetoire parent (en sortie).
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

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

109
110
111
112
113
114
115
116
117
118
# 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.

Guillaume Perréal's avatar
Guillaume Perréal committed
119
## Avec NPM
120

121
#### Build
122

123
```bash
Guillaume Perréal's avatar
Guillaume Perréal committed
124
prezbuilder build [répertoire_source [répertoire_sortie]]
125
126
```

127
#### Dev
128

129
```bash
Guillaume Perréal's avatar
Guillaume Perréal committed
130
prezbuilder dev [répertoire_source [répertoire_sortie]]
131
132
```

133
134
135
136
137
## Avec Docker

#### Build

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

139
140
```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
141
```
142
143
144
145
146
147

#### Dev

Il faut également mapper les ports 3000 et 35729 :

```bash
Guillaume Perréal's avatar
Guillaume Perréal committed
148
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
149
```
Guillaume Perréal's avatar
Guillaume Perréal committed
150
151
152
153
154

# Références

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