rdv-info-markdown/README.md

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

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

## 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) :

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

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

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

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

<!-- liens -->

[1]: ./
[2]: https://www.unige.ch/biblio/index.php?cID=4127
[3]: https://git.milhit.ch/igor/rdv-info-markdown/releases/latest
[4]: ./intro/intro.md