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 dossier sources.

La mise en forme s'appuie sur le modèle pagedjs pour la BUNIGE (Bibliothèque de l'Université de Genève). Les fichiers correspondant sont dans le dossier static.

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

Une proposition de déroulé pour une présentation orale se trouve dans le dossier présentation.

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

Requis

• pandoc (obligatoire).
• pagedjs-cli (obligatoire, voir la documentation pour l'installation).
• GNU Make et watchexe pour utiliser les commandes.

Utilisation

Structure du document

Le support de cours est rédigé au format Markdown. Il est constitué de plusieurs fichiers dans le dossier sources, 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 le bloc de 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 la bibliothèque pagedjs, un modèle HTML (static/template.html) et des règles de styles (static/styles.css). Le fichier des règles de style est commenté, ce qui devrait permettre de comprendre son fonctionnement.

Prévisualiser

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 --standalone --to=html \
       --template=static/template.html --css=static/style.css \
       --toc --toc-depth=2 \
       --citeproc \
       --bibliography=static/references.json --csl=static=heg-iso-690.csl \
       -V static="./static" \
       --output=document.html \
       sources/0-frontmatter.md sources/1-objectifs.md sources/2-licence.md \
       sources/3-definitions.md sources/4-syntaxe.md sources/5-editeurs.md \
       sources/6-advanced.md sources/7-bibliographie.md \
       sources/100-references.md

• --to=html pour convertir vers du HTML.
• --standalone 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.
• --bibliography="" définit le chemin vers la base de données des références bibliographique et --csl="" donne le chemin vers le style de citation utilisé.
• -V static="" permet de définir le chemin relatif (du point de vue du fichier HTML fournit par le serveur web local).
• --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/document.html.

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, il faut lancer la commande pandoc suivante :

pandoc --embed-resources=true -V noscript=true \
       -V static="./static"
       --citeproc \
       --bibliography=static/references.json \
       --csl=static/heg-iso-690.csl
       --to=pdf --pdf-engine=pagedjs-cli \
       --template=static/template.html --css=static/style.css \
       --toc --toc-depth=2 \
       --output=document.pdf \
       sources/0-frontmatter.md sources/1-objectifs.md sources/2-licence.md \
       sources/3-definitions.md sources/4-syntaxe.md sources/5-editeurs.md \
       sources/6-advanced.md sources/7-bibliographie.md \
       sources/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.
• --pdf-engine="pagedjs-cli" indique à pandoc quel outil utiliser pour la construction du PDF.

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 (GNU Make) est installé sur votre système, les commandes suivantes sont disponibles :

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