- 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> |
||
---|---|---|
static | ||
.gitignore | ||
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 | ||
LICENSE | ||
Makefile | ||
README.md | ||
déroulé.md | ||
exemple.md | ||
heg-iso-690.csl | ||
interface.css | ||
paged.polyfill.js | ||
references.json | ||
reload-in-place.js | ||
style.css | ||
template.html |
README.md
title | date | id | tags | |||
---|---|---|---|---|---|---|
Rendez-vous de l'info scientifique sur markdown | 2023-04-19T10:13:18+0200 | 20230419101340 |
|
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é parpandoc
oupagedjs-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 depagedjs
../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 :
0-frontmatter.md
, qui contient les métadonnées et quelques instructions pour la génération du fichier avecpandoc
.1-objectifs.md
, pour la page de titre et les objectifs de la présentation.2-licence.md
, pour la licence du document et l'indication des sources.3-definitions.md
.4-syntaxe.md
.5-editeurs.md
.6-advanced.md
.7-bibliographie.md
, pour la bibligraphie.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 variablenoscript
vient dutemplate.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 (utilisewatchexe
qui doit aussi être installé).make serve
: lance le serveur web python.