125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
---
|
||
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
|