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

Document utilisant le modèle BUNIGE

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 et génération du PDF.

Licence et réutilisation

La licence 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 pour l'installation).
• GNU Make et watchexe pour utiliser les commandes.

Mise à jour des fichiers du modèle

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

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

La syntaxe utilise des fonctionnalités propres à la version Pandoc de markdown. 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) :

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 :

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 :

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