title	date	id	tags
Un modèle pagedjs pour la BUNIGE	2023-04-21T11:19:03+02:00	20230421111912	modèle pagedjs PDF BUNIGE

Un modèle pagedjs pour la BUNIGE

Licence

Ce projet est sous licence MIT.

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.

Il a pour objectif d'être ajouté rapidement à un projet utilisant paged.js 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.

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 : interface.css).
• 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.
• 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.
• pagedjc-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 ou Les titres.

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 :

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 :

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