rdv-info-markdown/README.md

title	date	id	tags
Rendez-vous de l'info scientifique sur markdown	2023-04-19T10:13:18+02:00	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 intro/intro.html.

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

Pré-requis

• pandoc.
• pagedjs-cli (npm install -g puppeteer pagedjs pagedjs-cli).

Génération du PDF

Le support de cours est rédigé au format markdown, en utilisant des fonctionnalités propres au pandoc-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.

Lancer les commandes depuis le répertoire contenant le fichier source au format Markdown, à savoir ./intro.

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=intro.html intro.md

• --to=html pour convertir vers du HTML.
• --template= et --css= indiquent quels 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 où et à quel nom générer le 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 le navigateur Chromium (ou Chrome) à l'URL http://localhost:8000. 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 \
       --css=../style.css --toc --toc-depth=2 \
       --output=intro.pdf intro.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=intro.html intro.md \
       && pagedjs-cli intro.html \
       --css=../style.css \
       -o intro.pdf