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

Structure du document

Le support de cours est rédigé au format Markdown. Il est constitué de plusieurs fichiers, pour faciliter leur édition :

1. 0-frontmatter.md, qui contient les métadonnées et quelques instructions pour la génération du fichier avec pandoc.
2. 1-objectifs.md, pour la page de titre et les objectifs de la présentation.
3. 2-licence.md, pour la licence du document et l'indication des sources.
4. 3-definitions.md.
5. 4-syntaxe.md.
6. 5-editeurs.md.
7. 6-advanced.md.
8. 7-bibliographie.md, pour la bibligraphie.
9. 100-references.md, contient les URL des liens et les notes en bas de page.

La syntaxe utilise 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.

Prévisualisation dans le navigateur

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 --embed-resources=true --to=html \
       --template=template.html --css=style.css \
       --toc --toc-depth=2 --citeproc \
       --output=document.html \
       0-frontmatter.md 1-objectifs.md 2-licence.md \
       3-definitions.md 4-syntaxe.md 5-editeurs.md \
       6-advanced.md 7-bibliographie.md 100-references.md

• --to=html pour convertir vers du HTML.
• --embed-resources=true 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.
• --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 à 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).

Génération du PDF

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 --embed-resources=true -V noscript=true \
       --citeproc \
       --to=pdf --pdf-engine=pagedjs-cli \
       --template=template.html --css=style.css \
       --toc --toc-depth=2 \
       --output=document.pdf \
       0-frontmatter.md 1-objectifs.md 2-licence.md \
       3-definitions.md 4-syntaxe.md 5-editeurs.md \
       6-advanced.md 7-bibliographie.md 100-references.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.

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

pandoc --to=html -V noscript=true \
       --template=template.html --css=style.css \
       --toc --toc-depth=2 --citeproc \
       --output=document.html \
       0-frontmatter.md 1-objectifs.md 2-licence.md \
       3-definitions.md 4-syntaxe.md 5-editeurs.md \
       6-advanced.md 7-bibliographie.md 100-references.md \
       && pagedjs-cli document.html \
       --style=style.css \
       -o document.pdf

Commandes

Si make est disponible sur votre système, vous pouvez :

• make html : génère le HTML.
• make pdf : génère le PDF.
• make watch_html : génère le HTML et relance la commande si des fichiers sont modifiés (utilise watchexe qui doit aussi être installé).
• make serve : lance le serveur web python.