147 lines
5.4 KiB
Markdown
147 lines
5.4 KiB
Markdown
---
|
||
title: Un modèle pagedjs pour la BUNIGE
|
||
date: 2023-04-21T11:19:03+02:00
|
||
id: 20230421111912
|
||
tags: [modèle, pagedjs, PDF, BUNIGE]
|
||
---
|
||
|
||
# [Un modèle *pagedjs* pour la BUNIGE][1]
|
||
|
||
## Licence
|
||
|
||
Ce projet est sous [licence MIT][2].
|
||
|
||
## Description
|
||
|
||
Ce projet est un modèle et une mise en forme pour produire un PDF suivant la
|
||
charte de la [Bibliothèque de l'Université de Genève][3].
|
||
|
||
Il a pour objectif d'être ajouté rapidement à un projet utilisant [paged.js][4]
|
||
pour générer des PDF à partir d'un contenu en markdown.
|
||
|
||
## Usage
|
||
|
||
Une solution est de télécharger le répertoire `static/` à la racine de votre
|
||
propre projet. Vous pouvez faire ces téléchargement à la main, ou télécharger
|
||
le fichier `.zip` de la [publication de version][7].
|
||
|
||
Une autre méthode est de cloner le projet et de rédiger votre document au sein
|
||
de celui-ci.
|
||
|
||
## Structure du répertoire
|
||
|
||
Dans le répertoire `static/` se trouvent les fichiers nécessaires au modèle :
|
||
|
||
- Le modèle lui-même : `template.html`.
|
||
- La feuille de style qui rend possible l'interface web pour la
|
||
prévisualisation du document au format HTML : `interface.css` (fichier
|
||
faisant partie du projet [paged.js][4] : [interface.css][6]).
|
||
- Le fichier de style bibliographique qui fait partie à part entière du modèle,
|
||
car il est la norme utilisée par la charte : `heg-iso-690.csl`. Il est
|
||
extrait du répertoire des styles `.csl` :
|
||
[haute-ecole-de-gestion-de-geneve-iso-690.csl][5].
|
||
- Un fichier javascript avec le *polyfill* du projet `pagedjs`, afin d'éviter
|
||
de dépendre d'un CDN.
|
||
- Un fichier javascript qui permet de retrouver la bonne place dans la
|
||
visualisation du HTML servi lorsqu'on recharge la page, pratique en
|
||
développement.
|
||
|
||
Dans le dossier `example` se trouvent les sources pour pouvoir donner un
|
||
exemple :
|
||
|
||
- Le document markdown lui-même : `example.md`.
|
||
- Une liste de références bibliographiques au format BibLaTeX :
|
||
`references.bib`, exportées avec l'extension pour Zotero Better BibTeX.
|
||
|
||
## Requis
|
||
|
||
- `pandoc`.
|
||
- `pagedjs-cli`.
|
||
- Gnu Make, `watchexec` et python pour utiliser les facilités fournies par le
|
||
`Makefile`.
|
||
|
||
## Rédaction du document
|
||
|
||
Pour la rédaction du document, il est utile de se référer à la documentation de
|
||
la syntaxe markdown, mais aussi à la documentation de `pandoc`. Quelques points
|
||
sont données en exemples dans le fichier `example/example.md`, comme par
|
||
exemple [La police][8] ou [Les titres][9].
|
||
|
||
## Génération du PDF d'exemple
|
||
|
||
Lancer les commandes depuis le répertoire `./example`.
|
||
|
||
Pour générer le fichier HTML a visualiser dans le navigateur :
|
||
|
||
```bash
|
||
pandoc \
|
||
--citeproc --bibliography=references.bib --csl=../static/heg-iso-690.csl \
|
||
--template=../static/template.html --css=../static/style.css \
|
||
--toc --toc-depth=2 \
|
||
-V static=../static
|
||
--to=html --output=example.html example.md
|
||
```
|
||
|
||
- `--citeproc` assure que les références bibliographiques soient traitées.
|
||
- `--bibliography` indique où sont les références.
|
||
- `--csl` précise le style de citation utilisé.
|
||
- `--template=` et `--css=` définissent le modèle et les règles de style à
|
||
utiliser.
|
||
- `--toc` et `toc-depth=2` génèrent la table des matière en se limitant au 2e
|
||
niveau.
|
||
- `-V static=` est une variable permettant d'indiquer dans le fichier HTML le
|
||
chemin vers le dossier contenant les fichiers statiques. Il faut penser le
|
||
chemin depuis où le fichier HTML sera servi.
|
||
|
||
Puis lancer un serveur web à la racine du projet (par exemple avec `python -m
|
||
http.server`), et ouvrir le fichier HTML généré avec un navigateur web pour
|
||
pouvoir l'imprimer au format PDF.
|
||
|
||
Pour générer directement le PDF, en utilisant `pagedjs` au moyen de `pandoc` :
|
||
|
||
```bash
|
||
pandoc \
|
||
--citeproc --bibliography=references.bib --csl=../static/heg-iso-690.csl \
|
||
--to=pdf --pdf-engine=pagedjs-cli \
|
||
--css=../static/style.css \
|
||
--template=../static/template.html \
|
||
--toc --toc-depth=2 \
|
||
-V noscript=true -V static=../static
|
||
--output=example.pdf example.md
|
||
```
|
||
|
||
- `--pdf-engine=` impose `pagedjs-cli` pour la conversion en PDF.
|
||
- `-V noscript=true` permet d'indiquer que la feuille de style de l'interface
|
||
web de `pagedjs` et les scripts javascript utile dans le navigateur web ne
|
||
soient pas utilisés, car ils perturbent la conversion par `pandoc`.
|
||
|
||
## Commandes (`Makefile`)
|
||
|
||
Le `Makefile` offre les commandes suivantes :
|
||
|
||
- `make` ou `make pdf` construit le fichier PDF.
|
||
- `make html` construit le fichier HTML, prêt à être servi.
|
||
- `make watch` reconstruit le fichier HTML à chaque fois qu'un autre fichier
|
||
est modifié et enregistré.
|
||
- `make serve` utilise python pour démarrer un serveur web local.
|
||
- `make release` :
|
||
- Crée une archive du répertoire `static/` dans le dossier `release/` et
|
||
nomme l'archive avec la valeur de la dernière étiquette de l'historique
|
||
`git`.
|
||
- Construit le fichier PDF.
|
||
- Copie le PDF construit dans le dossier `release/` en le nommant avec la
|
||
même étiquette `git`.
|
||
- `make clean` vide le dossier `release/`.
|
||
|
||
<!-- références -->
|
||
|
||
[1]: ./
|
||
[2]: ./LICENSE
|
||
[3]: https://www.unige.ch/biblio/fr/ "Site officiel de la Bibliothèque de l'Université de Genève"
|
||
[4]: https://pagedjs.org/
|
||
[5]: https://raw.githubusercontent.com/citation-style-language/styles/blob/master/haute-ecole-de-gestion-de-geneve-iso-690.csl
|
||
[6]: https://gitlab.coko.foundation/pagedjs/interface-polyfill/-/raw/master/interface.css
|
||
[7]: https://git.milhit.ch/igor/bunige-pagedjs-template/releases/latest
|
||
[8]: ./example/example.md#police
|
||
[9]: ./example/example.md#titres
|