bunige-document/README.md

---
title: BUNIGE document
date: 2025-05-07T10:59:48+0200
id: 20250507105948
tags: ["modèle", "BUNIGE", "pagedjs"]
template_version: v1.0.1
---

# [Document utilisant le modèle BUNIGE][1]

Dépôt `git` modèle pour faciliter la création d'un document utilisant le modèle
de document proche de la charte de la BUNIGE, pour convertir des sources en
markdown avec Pagedjs.

## Tâches à réaliser pour adapter ce modèle

- [ ] Mettre à jour le YAML du README.
- [ ] Mettre à jour le titre de niveau 1 du README.
- [ ] Vérifier si le fichier `static/references.json` doit être modifié.
- [ ] Éditer les sources.
- [ ] Adapter les exemples de commandes des parties [`prévisualiser`][2] et
      [`génération du PDF`][3].

## Licence et réutilisation

La [licence][4] du projet est la licence *Creative Common by, share alike,
4.0 International*. Elle permet la diffusion et la modification du projet pour
autant que la responsabilité soit mentionnée et que le partage soit fait avec
la même licence.

## Requis

- `pandoc` (obligatoire).
- `pagedjs-cli` (obligatoire, voir la [documentation][5] pour l'installation).
- GNU Make et `watchexe` pour utiliser les [commandes][6].

## Mise à jour des fichiers du modèle

Il faut télécharger l'archive sur la page de la [dernière publication de
version][7] du projet du modèle de document. L'archive est nommée avec le
numéro de version correspondant.

```bash
curl -o modèle.zip https://git.milhit.ch/igor/bunige-pagedjs-template/releases/download/v0.2.0/v0.2.0.zip
unzip -f -o modèle.zip
rm modèle.zip
```

C'est ce que réaliste la commande `make update VERSION=VX.X.X` (voir les
[commandes][6] disponibles).

## Utilisation du modèle

Pour utiliser le modèle de document, il faut rédiger votre document dans un
fichier avec une extension `.md`, autrement dit un fichier au format texte
utilisant la syntaxe markdown. Pour cela, il est possible de s'aider de
l'[exemple][8] fournit dans le projet du modèle de document pour comprendre ce
qu'il est possible de faire.

## Utilisation 

### Structure du document

Le document est rédigé au format Markdown (plus précisément Pandoc Markdown).
Il est constitué d'un ou de plusieurs fichiers situés dans le dossier
[`sources`][9].

La syntaxe utilise des fonctionnalités propres à la version [Pandoc de
markdown][10]. La génération du PDF s'appuie sur la bibliothèque `pagedjs`, un
modèle HTML (`static/template.html`) et des règles de styles
(`static/styles.css`). Le fichier des règles de style est commenté, ce qui
devrait permettre de comprendre son fonctionnement.

### Prévisualiser

Pour générer le fichier HTML à servir par un serveur web pour le visualiser
dans le navigateur, il faut utiliser `pandoc` avec les paramètres suivants (à
adapter au fichier à générer) :

```bash
pandoc --standalone --to=html \
       --template=static/template.html --css=static/style.css \
       --toc --toc-depth=2 \
       --citeproc \
       --bibliography=static/references.json --csl=static=heg-iso-690.csl \
       -V static="./static" \
       --output=document.html \
       sources/document.md
```

- `--to=html` pour convertir vers du HTML.
- `--standalone` assure que toutes les dépendances externes sont bien
  intégrées dans le fichier généré.
- `--template=` et `--css=` indiquent quel modèle et feuille de style
  utiliser.
- `--toc` et `--toc-depth=2` génèrent la table des matière en n'allant pas plus
  loin que les titres de niveau 2.
- `--citeproc` indique qu'il faut tenir compte des citations et générer la
  bibliographie.
- `--bibliography=""` définit le chemin vers la base de données des références
  bibliographique et `--csl=""` donne le chemin vers le style de citation
  utilisé.
- `-V static=""` permet de définir le chemin relatif (du point de vue du
  fichier HTML fournit par le serveur web local).
- `--output=` précise l'endroit et le nom du fichier de sortie.

Une fois le fichier HTML généré, il faut lancer un serveur web depuis la racine
du projet, par exemple avec `python` :

```bash
python -m http.server
```

Puis, ouvrir un navigateur web à l'URL <http://localhost:8000/document.html>.

Cet affichage permet d'inspecter les règles CSS et de les modifier à la volée
pour comprendre comment améliorer le rendu, et d'imprimer la page web au format
PDF (`ctrl+p`).

### Génération du PDF

Pour générer directement le PDF, il faut lancer la commande `pandoc` suivante :

```bash
pandoc --embed-resources=true -V noscript=true \
       -V static="./static"
       --citeproc \
       --bibliography=static/references.json \
       --csl=static/heg-iso-690.csl
       --to=pdf --pdf-engine=pagedjs-cli \
       --template=static/template.html --css=static/style.css \
       --toc --toc-depth=2 \
       --output=document.pdf \
       sources/document.md
```

- `-V noscript=true`. `-V` permet d'ajouter des variables. La variable
  `noscript` vient du `template.html` et permet d'éviter d'ajouter les scripts
  utilisé pour la prévisualisation dans le navigateur.
- `--pdf-engine="pagedjs-cli"` indique à `pandoc` quel outil utiliser pour la
  construction du PDF.

## Commandes

Si `make` (GNU Make) est installé sur votre système, les commandes suivantes
sont disponibles :

- `make` ou `make pdf` : génère le PDF.
- `make html` : génère le HTML.
- `make watch` : génère le HTML et relance la génération si des fichiers
  sont modifiés (utilise `watchexe` qui doit aussi être installé).
- `make serve` : lance le serveur web python.
- `make clean` : supprime les fichiers HTML et PDF générés.
- `make update VERSION=VX.X.X` : mets à jour les fichiers du modèle de document
  en utilisant le numéro de version indiqué.

<!-- références -->

[1]: ./
[2]: #prévisualiser
[3]: #génération-du-pdf
[4]: ./LICENSE
[5]: https://gitlab.coko.foundation/pagedjs/pagedjs-cli#installation
[6]: #commandes
[7]: https://git.milhit.ch/igor/bunige-pagedjs-template/releases/latest
[8]: https://git.milhit.ch/igor/bunige-pagedjs-template/src/branch/main/example/example.md
[9]: ./sources/
[10]: https://pandoc.org/MANUAL.html#pandocs-markdown