rdv-info-markdown/README.md

title	date	id	tags
Rendez-vous de l'info scientifique sur markdown	2023-04-19T10:13:18+0200	20230419101340	rdv-info documentation markdown

Introduction à la prise de notes avec Markdown

Ce répertoire contient le matériel utilisé pour le rendez-vous de l'info scientifique sur Markdown proposés par la bibliothèque de l'Université de Genève.

Les sources du support de cours sont dans le fichier document.html.

La dernière version du support de cours au format PDF se trouve dans la dernière publication de version.

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 se fait avec la même licence.

Pré-requis

• pandoc.
• pagedjs-cli (npm install -g puppeteer pagedjs pagedjs-cli).
• Le modèle pagedjs pour la BUNIGE.

Les fichiers de ce modèle peuvent être téléchargés depuis la dernière publication de version du projet : https://git.milhit.ch/igor/bunige-pagedjs-template/releases/latest. L'archive ZIP vX.X.X.zip contient tout ce qui est nécessaire. Plus précisément, ce sont les fichiers suivants :

• ./template.html, le modèle HTML utilisé par pandoc ou pagedjs-cli.
• ./style.css avec les règles de style pour la mise en forme.
• ./static/bibliotheque-logo.svg et ./static/by-sa.svg, deux images utilisées sur la page d'accueil.
• ./paged.polyfill.js pour le support des fonctionnalité pagedjs.
• ./interface.css pour afficher le ficher HTML dans un navigateur avec l'interface web de pagedjs.
• ./reload-in-place.js, qui n'est pas strictement nécessaire, mais replace le fichier HTML là où on le consultait.

Génération du PDF

Le support de cours (./document.md) est rédigé au format markdown, en utilisant des fonctionnalités propres à la version Pandoc de markdown. La génération du PDF s'appuie sur pagedjs, un modèle HTML (template.html) et des règles de styles (styles.css). Le fichier des règles de style est commenté, ce qui devrait permettre de comprendre son fonctionnement.

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 --to=html \
       --template=template.html --css=style.css \
       --toc --toc-depth=2 --citeproc \
       --output=document.html document.md

• --to=html pour convertir vers du HTML.
• --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.
• --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 Chromium (ou Chrome) à l'URL http://localhost:8000. Pour l'impression, il est conseillé d'utiliser Chromium (ou Chrome). En effet, Firefox supporte un peu moins bien pagedjs, notamment pour l'impression en PDF. Pour éviter la coloration des liens déjà visités, la fonction « navigation privée » est bien utile.

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

Pour générer directement le PDF, deux possibilités s'ouvrent à vous, avec des résultats différents. Soit en utilisant pagedjs directement avec pandoc :

pandoc --citeproc \
       --to=pdf --pdf-engine=pagedjs-cli \
       --template=template.html --css=style.css \
       --toc --toc-depth=2 \
       --output=document.pdf document.md

Soit en utilisant pagedjs pour convertir le fichier HTML obtenu par pandoc plus haut :

pandoc --to=html \
       --template=template.html --css=style.css \
       --toc --toc-depth=2 --citeproc \
       --output=document.html document.md \
       && pagedjs-cli document.html \
       --css=../style.css \
       -o document.pdf