Matériel pour le « rendez-vous de l'info scientifique » sur Markdown proposés par la bibliothèque de l'Université de Genève. https://www.unige.ch/biblio/index.php?cID=4127
 
 
 
Go to file
iGor milhit 8696a63df7
projet: mise à jour pour le printemps 2025
- Mets à jour la date du document.
- Réordonne les fichiers du document.
- Améliore la formulation de la section « définitions ».
- Mets à jour le déroulé.
- Crée un fichier d'exemple de la syntaxe markdown.
- Mets à jour la base de donnée des références bibliographiques.
- Corrige le Makefile selon le nouvel ordre des fichiers du documents.
- Améliore la documentation dans le README, avec des commandes pandoc
  et/ou pagedjs-cli plus robustes, ainsi que la mention des commandes du
  Makefile.

Co-Authored-by: iGor milhit <igor@milhit.ch>
2025-04-29 16:17:05 +02:00
static support: mets à jour pour la session d'automne 2024-11-19 16:21:13 +01:00
.gitignore projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
0-frontmatter.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
1-objectifs.md support: mets à jour pour la session d'automne 2024-11-19 16:21:13 +01:00
2-licence.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
3-definitions.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
4-syntaxe.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
5-editeurs.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
6-advanced.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
7-bibliographie.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
100-references.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
LICENSE Initial commit 2023-04-19 10:06:41 +02:00
Makefile projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
README.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
déroulé.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
exemple.md projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
heg-iso-690.csl support: mets à jour pour la session d'automne 2024-11-19 16:21:13 +01:00
interface.css template: ajoute les fichiers pour export pagedjs 2023-04-24 20:31:19 +02:00
paged.polyfill.js support: mets à jour pour la session d'automne 2024-11-19 16:21:13 +01:00
references.json projet: mise à jour pour le printemps 2025 2025-04-29 16:17:05 +02:00
reload-in-place.js support: mets à jour pour la session d'automne 2024-11-19 16:21:13 +01:00
style.css support: mets à jour pour la session d'automne 2024-11-19 16:21:13 +01:00
template.html support: mets à jour pour la session d'automne 2024-11-19 16:21:13 +01:00

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.