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