rdv-info-markdown/README.md

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

## [Introduction à la prise de notes avec Markdown][1]

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

Les sources du support de cours sont dans le fichier [`document.html`][4].

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

## Licence et réutilisation

La [licence][6] 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][5]. 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) :

```bash
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` :

```bash
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` :

```bash
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 :

```bash
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
```

<!-- références -->

[1]: ./
[2]: https://www.unige.ch/biblio/index.php?cID=4127
[3]: https://git.milhit.ch/igor/rdv-info-markdown/releases/latest
[4]: ./document.md
[5]: https://pandoc.org/MANUAL.html#pandocs-markdown
[6]: ./LICENSE