171 lines
6.4 KiB
Markdown
171 lines
6.4 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
|
||
|
||
### 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`.
|
||
1. `1-objectifs.md`, pour la page de titre et les objectifs de la présentation.
|
||
1. `2-licence.md`, pour la licence du document et l'indication des sources.
|
||
1. `3-definitions.md`.
|
||
1. `4-syntaxe.md`.
|
||
1. `5-editeurs.md`.
|
||
1. `6-advanced.md`.
|
||
1. `7-bibliographie.md`, pour la bibligraphie.
|
||
1. `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][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.
|
||
|
||
### 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) :
|
||
|
||
```bash
|
||
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` :
|
||
|
||
```bash
|
||
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` :
|
||
|
||
```bash
|
||
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 :
|
||
|
||
```bash
|
||
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.
|
||
|
||
<!-- 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
|