igor
/
rdv-info-markdown
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 3 Wiki Activity

support: mets à jour pour la session d'automne 

- Mentionne la licence dans le `README.md`. Fixes #1.
- Remplace le fichier d'introduction par la notion de document, puiqu'il
  n'y a plus, pour l'instant, plusieurs sessions.
- Fragmente la source en sous-fichiers pour améliorer la gestion des
  références (à évaluer).
- Mets à jour les fichiers du template (`v0.2.0`).
- Documente comment installer les fichiers du template.
- Mets à jour le fichier du style de citation et des références,
  désormais au format CSL JSON.
- Affiche toutes les références dans la bibliographie.

Co-Authored-by: iGor milhit <igor@milhit.ch>
iGor milhit 2024-11-12 14:41:32 +01:00
parent 8deda1322a
commit b94d18c570
Signed by: igor
GPG Key ID: 692D97C3D0228A99
19 changed files with 34551 additions and 778 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.gitignore vendored
View File

@ -1,2 +1,3 @@
intro.html document.html
intro.pdf document.pdf
*.zip

77
README.md
View File

@ -1,6 +1,6 @@
--- ---
title: Rendez-vous de l'info scientifique sur markdown title: Rendez-vous de l'info scientifique sur markdown
date: 2023-04-19T10:13:18+02:00 date: 2023-04-19T10:13:18+0200
id: 20230419101340 id: 20230419101340
tags: [rdv-info, documentation, markdown] tags: [rdv-info, documentation, markdown]
--- ---
@ -11,26 +11,47 @@ 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 scientifique sur Markdown][2] proposés par la bibliothèque de l'Université de
Genève. Genève.
Les sources du support de cours sont dans le fichier [`intro/intro.html`][4]. 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 La dernière version du support de cours au format PDF se trouve dans la
dernière [publication de version][3]. 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 ## Pré-requis
- `pandoc`. - `pandoc`.
- `pagedjs-cli` (`npm install -g puppeteer pagedjs pagedjs-cli`). - `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 ## Génération du PDF
Le support de cours est rédigé au format markdown, en utilisant des Le support de cours (`./document.md`) est rédigé au format markdown, en
fonctionnalités propres au `pandoc-markdown`. La génération du PDF s'appuie sur utilisant des fonctionnalités propres à la version [Pandoc de markdown][5]. La
`pagedjs`, un modèle HTML (`template.html`) et des règles de styles génération du PDF s'appuie sur `pagedjs`, un modèle HTML (`template.html`) et
(`styles.css`). Le fichier des règles de style est commenté, ce qui devrait des règles de styles (`styles.css`). Le fichier des règles de style est
permettre de comprendre son fonctionnement. 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 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 (à dans le navigateur, il faut utiliser `pandoc` avec les paramètres suivants (à
@ -38,19 +59,19 @@ adapter au fichier à générer) :
```bash ```bash
pandoc --to=html \ pandoc --to=html \
--template=../template.html --css=../style.css \ --template=template.html --css=style.css \
--toc --toc-depth=2 --citeproc \ --toc --toc-depth=2 --citeproc \
--output=intro.html intro.md --output=document.html document.md
``` ```
- `--to=html` pour convertir vers du HTML. - `--to=html` pour convertir vers du HTML.
- `--template=` et `--css=` indiquent quels modèle et feuille de style - `--template=` et `--css=` indiquent quel modèle et feuille de style
utiliser. utiliser.
- `--toc` et `--toc-depth=2` génèrent la table des matière en n'allant pas plus - `--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. loin que les titres de niveau 2.
- `--citeproc` indique qu'il faut tenir compte des citations et générer la - `--citeproc` indique qu'il faut tenir compte des citations et générer la
bibliographie. bibliographie.
- `--output=` précise où et à quel nom générer le fichier de sortie. - `--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 Une fois le fichier HTML généré, il faut lancer un serveur web depuis la racine
du projet, par exemple avec `python` : du projet, par exemple avec `python` :
@ -59,10 +80,11 @@ du projet, par exemple avec `python` :
python -m http.server python -m http.server
``` ```
Puis, ouvrir le navigateur Chromium (ou Chrome) à l'URL Puis, ouvrir un navigateur web Chromium (ou Chrome) à l'URL
<http://localhost:8000>. En effet, Firefox supporte un peu moins bien <http://localhost:8000>. Pour l'impression, il est conseillé d'utiliser
`pagedjs`, notamment pour l'impression en PDF. Pour éviter la coloration des Chromium (ou Chrome). En effet, Firefox supporte un peu moins bien `pagedjs`,
liens déjà visités, la fonction « navigation privée » est bien utile. 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 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 pour comprendre comment améliorer le rendu, et d'imprimer la page web au format
@ -74,8 +96,9 @@ résultats différents. Soit en utilisant `pagedjs` directement avec `pandoc` 
```bash ```bash
pandoc --citeproc \ pandoc --citeproc \
--to=pdf --pdf-engine=pagedjs-cli \ --to=pdf --pdf-engine=pagedjs-cli \
--css=../style.css --toc --toc-depth=2 \ --template=template.html --css=style.css \
--output=intro.pdf intro.md --toc --toc-depth=2 \
--output=document.pdf document.md
``` ```
Soit en utilisant `pagedjs` pour convertir le fichier HTML obtenu par pandoc Soit en utilisant `pagedjs` pour convertir le fichier HTML obtenu par pandoc
@ -83,17 +106,19 @@ plus haut :
```bash ```bash
pandoc --to=html \ pandoc --to=html \
--template=../template.html --css=../style.css \ --template=template.html --css=style.css \
--toc --toc-depth=2 --citeproc \ --toc --toc-depth=2 --citeproc \
--output=intro.html intro.md \ --output=document.html document.md \
&& pagedjs-cli intro.html \ && pagedjs-cli document.html \
--css=../style.css \ --css=../style.css \
-o intro.pdf -o document.pdf
``` ```
<!-- liens --> <!-- références -->
[1]: ./ [1]: ./
[2]: https://www.unige.ch/biblio/index.php?cID=4127 [2]: https://www.unige.ch/biblio/index.php?cID=4127
[3]: https://git.milhit.ch/igor/rdv-info-markdown/releases/latest [3]: https://git.milhit.ch/igor/rdv-info-markdown/releases/latest
[4]: ./intro/intro.md [4]: ./document.md
[5]: https://pandoc.org/MANUAL.html#pandocs-markdown
[6]: ./LICENSE

17
document/0-frontmatter.md 100644
View File

@ -0,0 +1,17 @@
---
title: Introduction à la prise de note avec markdown
author:
- Igor Milhit^[Uni CMU]
date: Printemps 2024
creation_date: 2023-04-19T11:35:14+02:00
id: 20230419113601
tags: [note, markdown]
logo:
- static/logo-md.svg
lang: fr
bibliography: references.json
citation-style: heg-iso-690.csl
nocite: '@*'
link-citations: true
toc-title: Table des matières
---

14
document/1-objectifs.md 100644
View File

@ -0,0 +1,14 @@
## Objectifs
- Avantages et inconvénients.
- Aperçu de la syntaxe de base.
- Les fonctionnalités minimales d’un éditeur.
- Bref aperçu des possibilités avancées :
- Ensemble de notes.
- Conversion dans d’autres formats.
- Insertion de références bibliographiques.
:::{#licence}
![Logo de la licence CC BY-SA 4.0][1] \
[CC BY-SA 4.0][2] --- [Sources][3]
:::

27
document/100-references.md 100644
View File

@ -0,0 +1,27 @@
<!-- références -->
[1]: ../static/by-sa.svg
[2]: https://creativecommons.org/licenses/by-sa/4.0/deed.fr "Texte de la licence en français"
[3]: https://git.milhit.ch/igor/rdv-info-markdown
[4]: https://www.arthurperret.fr/cours/format-texte.html
[5]: https://hedgedoc.org/
[6]: https://hackmd.io/
[7]: https://fr.wikipedia.org/wiki/Git "Article Wikipedia en français"
[8]: #dedies
[9]: #generalistes
[10]: ../static/ghostwriter.png
[11]: ../static/zettlr.png
[12]: ../static/hackmd.png
[13]: ../static/vscode.png
[14]: ../static/lien-entre-fichiers.png
[15]: ../static/recherche-vscode.png
[16]: https://pandoc.org/MANUAL.html#citations
[^0]: Cette section repose beaucoup sur la page [Format texte][0] d'Arthur
Perret [@perretFormatTexte2022].
[^1]: Markdown n'est pas le seul langage de balisage léger existant, bien que
ce soit le plus répandu. D'autres sont encore plus robustes ou puissants,
comme *RestructuredText* ou *AsciiDoc*.
[^2]: Il semble possible de l'installer sur MacOS, mais n'est pas recommandé.
[^3]: Les sources et la méthode de conversion est disponible sur
<https://git.milhit.ch/igor/rdv-info-markdown>.

104
document/2-definitions.md 100644
View File

@ -0,0 +1,104 @@
## Définition, avantages et inconvénients[^0] {#first-section}
Le plus important est de trouver des méthodes et des outils adaptés à *ses
besoins*. Ci-dessous sont listés quelques arguments en faveur de l'usage de
fichiers au format texte et de la syntaxe markdown, mais aucune méthode ou
outil n'est *la* solution miracle pertinente dans *tous* les contextes.
### Définition
L'information numérique est utile si elle est **structurée**. Par exemple, la
table des matières d'un document numérique devrait être constituée de liens
vers les sections. Cette structure peut s'obtenir par l'usage des styles et des
niveaux de titre dans un traitement de texte (Microsoft Word, Libreoffice
Writer, etc.). La syntaxe markdown est une autre méthode, très efficace.[^1]
Markdown est *un langage de balisage léger*. Concrètement, il s'agit d'une
syntaxe qui permet, **uniquement avec des éléments textuels**, de structurer
(niveau de titres) et de mettre en forme du texte. Cette structure et cette
mise en forme sont compréhensibles par des êtres humains ou par des programmes
informatiques. Aussi, les documents rédigés à l'aide de markdown peuvent soit
être lus tels quels, soit être traités par un programme pour afficher un
« rendu » sous forme de page web, de document PDF ou DOCX.
La syntaxe markdown est relativement simple à apprendre et mémoriser. Aussi, la
rédaction au format markdown repose sur très peu de fonctionnalités du
logiciel. Le bloc note suffit, même si un peu plus de confort est souhaitable.
Cette syntaxe est utilisée par de nombreux logiciels ou services en lignes pour
la rédaction. C'est le cas des notes dans Zotero ou d'éditeurs en ligne adaptés
au travail collaboratif ([HedgeDoc][5], [HackMD][6], etc.).
### Avantages
Les fichiers utilisés ne sont composés que de caractères textuels. Aussi, ils
sont :
- Simples et légers :
- Ne dépendent pas d'un logiciel spécifique, ni d'un système d'exploitation.
- Pourront être ouverts et édités dans n'importe quel contexte, et
probablement dans un avenir éloigné (pérennité).
- Rapides à ouvrir. Avec n'importe quel éditeur de texte (bloc note Windows,
Notepad++, TextEdit, Gedit, VIM, EMACS, etc.)
- Faciles à sauvegarder, copier, synchroniser, partager.
Toujours grâce à leur nature textuelle, il est facile d'avoir des outils pour
rechercher (et remplacer) rapidement du texte au sein non seulement du fichier
ouvert, mais d'un ensemble de fichier dans un répertoire. \
Il est même possible d'écrire des programmes pour modifier ou utiliser
automatiquement ces fichiers. Et il en existe justement beaucoup !
Grâce à ces propriétés, il est possible :
- De prendre des notes au clavier rapidement, de manière structurée, et avec
une recherche rapide.
- De rédiger des documents simples (une note) ou complexes (une thèse).
- De regrouper un ensemble de notes dans un « bloc note » et de naviguer dans
cet ensemble, de rechercher de l'information .
- De manière similaire, de regrouper un ensemble de fichiers pour constituer un
document complexe, comme un livre ou un article scientifique.
- Enfin de convertir à partir des mêmes fichiers le document dans plusieurs
formats pour une diffusion sur le web, la lecture dans un PDF ou un ePub
(compatible avec une liseuse électronique).
Enfin, les fichiers textuels sont particulièrement adaptés au suivi de
l'historique des modification (*versioning*), par exemple avec le logiciel
[Git][7].
### Inconvénients
Pour un usage simple, l'apprentissage n'est pas très difficile. La syntaxe de
base s'acquiert rapidement. Pour parvenir à rédiger des documents relativement
complexes (notes, citations et bibliographies, etc.), cet apprentissage est un
peu plus long. Afin de maîtriser la conversion dans différents formats, tout en
personnalisant la mise en forme des documents obtenus, il devient vite
nécessaire d'apprendre à utiliser d'autres outils, à modifier des modèles dans
les formats désirés (HTML, DOCX, peut-être LaTeX, etc.).
Certains éditeurs intègrent la fonction de conversion, mais elle repose sur
l'installation de logiciels annexes, principalement `pandoc`, mais aussi une
distribution LaTeX pour obtenir une conversion en PDF. Ces outils ne sont pas
si difficiles à installer. Surtout, ils sont libres, gratuits et disponibles
pour Windows, Mac OS ou Linux.
Pour utiliser `pandoc`, qui est l'outil de conversion le plus complet, il est
nécessaire de le faire « en ligne de commande » plutôt que dans une interface
graphique, avec la souris. C'est un élément en plus à apprendre, mais qui ouvre
beaucoup de possibilités.
Le travail collaboratif à plusieurs est toujours possible, mais selon les cas
avec une certaine friction. La situation la plus simple est d'utiliser un
éditeur en ligne qui offre des fonctionnalités d'édition à plusieurs. Souvent
cela est au prix de ne pouvoir disposer de toute la puissance de `pandoc`, du
moins directement.
Toujours dans le cas où toutes les personnes qui collaborent sont capables de
travailler avec les mêmes outils, elles peuvent toujours travailler ensemble en
se mettant d'accord sur un « workflow », par exemple grâce à `git` mentionné
plus haut. Mais c'est un outil de plus à apprendre. Et de nouvelles
possibilités à découvrir.
Enfin, si les personnes avec qui on collabore ne veulent ou ne peuvent pas
utiliser les mêmes méthodes, alors il faudra mettre en place un processus
d'export et d'import un peu complexe, mais en partie automatisable
[@perretMarkdownTraitementTexte2022].

26
document/3-syntaxe.md 100644
View File

@ -0,0 +1,26 @@
## La syntaxe markdown
La syntaxe markdown est très bien documentée sur le web :
- La documentation « officielle » est disponible sur le site personnel d'un des
concepteurs de la syntaxe : <https://daringfireball.net/projects/markdown/>
[@gruberMarkdown2004].
- Le site *flus* propose Une documentation en français et très claire :
<https://flus.fr/carnet/markdown.html> [@fressinaudGuideMarkdown2022].
- Il y a plusieurs variantes (ou extensions) de la syntaxe et un site essaie de
proposer un standard. Il met à disposition un tutoriel interactif :
<https://commonmark.org/help/> [@commonmarkCommonMark].
- Arthur Perret a traduit en français ce même tutoriel, disponible sur sa page
expliquant ce qu'est markdown :
<https://www.arthurperret.fr/cours/markdown.html> [@perretMarkdown2022].
Pour les tableaux, il est fortement conseillé :
- D'utiliser un générateur, par exemple
<https://www.tablesgenerator.com/markdown_tables>.
- Ou de disposer dans son éditeur d'un générateur de tableaux.
Le plus souvent les fichiers contenant du markdown ont pour extension `.md`,
mais c'est une convention. Rien n'interdit d'utiliser d'autres extensions comme
`.mkdn` ou `.markdown`, pour autant que l'éditeur que vous utilisez les
reconnaissent comme du markdown.

85
document/4-editeurs.md 100644
View File

@ -0,0 +1,85 @@
## Éditeurs {.newpage}
Il existe beaucoup d'éditeurs pour rédiger en markdown. On peut les regrouper
en deux grandes catégories :
1. Les éditeurs [dédiés][8].
1. Les éditeurs [généralistes][9].
Dans les deux cas, des fonctionnalités de base qui sont presque
incontournables :
- Une prévisualisation, le plus souvent sous la forme d'un *rendu* HTML. Cette
fonctionnalité a l'avantage de permettre de se faire une idée du résultat
sans devoir générer le fichier final.
- La possibilité de naviguer dans une arborescence de fichiers, en général dans
une barre sur le côté de l'interface.
- Une autocomplétion, pour faciliter l'entrée de syntaxe avec des `[]` ou des
`()`.
D'autres fonctionnalités ne sont pas indispensables, mais deviennent rapidement
utiles :
- La correction orthographique pour les langues dans lesquelles vous rédigez.
- Un formatage automatique des tableaux.
- La possibilité de suivre les liens internes, au sein du même fichier ou entre
les fichiers d'un même répertoire.
### Éditeurs dédiés {#dedies}
Ce sont des logiciels conçu spécifiquement pour éditer des fichiers avec la
syntaxe markdown. Ils peuvent être sous la forme d'un logiciel à installer sur
votre appareil (ordinateur, tablette, téléphone) ou d'un service web.
**Typora** est éditeur qui met l'accent sur son interface épurée. Il est disponible
pour tous les systèmes d'exploitation, payant. <https://typora.io/>
![Interface de GhostWriter][10]
**GhostWriter** est libre et gratuit, pour Windows et Linux
principalement.[^2] <https://ghostwriter.kde.org/fr/>
**Abricotine** est libre et gratuit, pour toutes les plateformes.
<http://abricotine.brrd.fr/>
**iA Writer** est payant, pour MacOS et Windows, mais est très apprécié pour la
rédaction. Il permet de lier des notes entre elles et offre ainsi une
navigation dans un ensemble de fichiers. <https://ia.net/writer>
**Obsidian** est un logiciel propriétaire, pour toutes les plateformes. Il ne
se limite pas à l'édition de fichiers markdown, mais permet de constituer une
base de connaissance basée sur des notes, et cela de manière très complète.
<https://obsidian.md/>
![Interface de Zettlr][11]
**Zettlr** est libre et disponible pour tous les systèmes d'exploitation. Il
est destiné à un usage académique, que ce soit pour construire une base de
connaissance à partir de notes ou pour rédiger un travail de mémoire ou un
article scientifique. Il intègre Zotero pour la gestion des références.
En ligne, on peut mentionner à nouveau le service [HackMD][2] ou le logiciel
[HedgeDoc][1] qui permet non seulement d'éditer des fichiers markdown avec une
prévisualisation, mais également de le faire à plusieurs, de disposer d'un
suivi des modifications et de commenter.
![Interface de l'éditeur HackMD][12]
### Éditeurs généralistes {#generalistes}
*Généralistes* car ces éditeurs ne sont pas limités à l'édition de fichier
markdown. Le plus souvent, ce sont des *éditeurs de texte* utilisés
par des développeurs pour écrire du code informatique. Le plus souvent, ils
disposent d'un écosystème d'extensions afin de s'adapter à des besoins
spécifiques. De ce fait, ils sont très puissants.
Ainsi, il est possible d'adapter à l'édition du markdown les éditeurs de texte
suivant, notamment :
- Notepad++, libre et gratuit, pour Windows.
- Visual Studio Code, gratuit, pour Windows, MacOS, Linux. Un des logiciels les
plus utilisés actuellement.
- VIM ou neovim, libre et gratuit, pour tous les systèmes d'exploitation.
- EMACS, libre et gratuit.
![Interface de Visual Studio Code][13]

90
document/5-advanced.md 100644
View File

@ -0,0 +1,90 @@
## Aperçu des possibilités avancées
### Ensemble de notes
Afin d'organiser ses notes, il est possible de réunir un ensemble de fichiers
dans le même répertoires (y compris avec des sous répertoires) et de faire des
liens entre les fichiers (et même au sein d'un seul fichier).
Certains éditeurs, ou certaines extensions d'éditeurs, proposent des facilités
pour générer ces liens, au prix d'une syntaxe *ad hoc* (« wiki links »). Mais
il est parfaitement possible de le faire avec la syntaxe « normale » du lien.
![Lien depuis le fichier `README.md` vers le fichier `points-a-ameliorer.md`][14]
La figure 5 montre sur la gauche une arborescence de fichiers, avec
des sous-répertoires, et dans le fichier affiché (`README.md`), un lien vers le
fichier `points-a-ameliorer.md`. Dans cet éditeur, en plaçant le curseur sur le
lien et en tapant la touche « entrée », on ouvre le fichier cible.
La figure 6 montre la recherche du terme `rdv-info` lancée sur la même
arborescence de fichiers que la figure 5, au moyen du logiciel Visual Studio
Code. Il y a 13 occurrences du terme dans 7 fichiers. Ce type de recherche est
facilité par le fait que ce sont des fichiers au format texte et se retrouve
dans la plupart des éditeurs généralistes de qualité.
![Recherche dans Visual Studio Code][15]
### Export vers d'autres formats
La conversion d'un document markdown en un autre format, plus simple à partager
devient assez vite utile. Pour les conversions, `pandoc` est l'outil le plus
souvent utilisé. Il est soit utilisé par votre éditeur pour faire les exports
(par exemple avec Zettlr), soit par vous même en ligne de commande. C'est un
logiciel libre et gratuit, développé très activement.
Il est capable de lire et d'écrire dans un grand nombre de formats différents,
parfois à l'aide de logiciels spécifiques. Par exemple, pour produire un
fichier PDF, il peut utiliser plusieurs méthodes, dont LaTeX, ce qui suppose
d'en avoir une version installée.
La commande pour une conversion simple est de la forme suivante :
```bash
pandoc --output fichier.docx fichier.md
```
Le format obtenu correspond à celui qui est indiqué en extension du nom de
fichier de sortie `--output`, ici du DOCX. Mais il est possible de
l'expliciter :
```bash
pandoc --to docx --output fichier.docx fichier.md
```
Le support de cours de cette introduction à markdown a été rédigée en markdown
et est exportée en PDF grâce à `pandoc` et à *Paged.js*.[^3]
### Citations et Bibliographie
Pour insérer des citations et générer une bibliographie, il est nécessaire
d'avoir au moins une collection de références bibliographiques, par exemple
sous la forme d'un fichier `.bib`. Pour obtenir ce fichier, il est possible de
passer par Zotero et d'exporter une collection dans le format BibTex (ou Better
BibTex avec l'extension Zotero du même nom.)
Dans ce fichier (et dans Zotero), on trouve pour chaque référence une « clé de
citation » qui permet de l'identifier de manière unique. C'est cette clé que
l'on va insérer dans notre fichier markdown pour indiquer une citation. Elle
est insérée avec la syntaxe suivante : `[@clé-de-citation]`.
On peut encore ajouter à la fin de notre fichier un titre de deuxième niveau
avec le texte bibliographie, pour que `pandoc` puisse y insérer la
bibliographie.
Pour être en mesure de traiter ces informations, il faut utiliser l'option de
`--citeproc` intégrée dans `pandoc` :
```bash
pandoc --citeproc \
--to=pdf --pdf-engine=xelatex \
--bibliography=references.bib \
--output fichier.pdf fichier.md
```
Dans l'exemple ci-dessus, nous voyons l'option `--citeproc` et l'option
`--bibliography=` qui indique où se trouve le fichier des références
bibliographiques. Par défaut le style est Chicago, de type auteur-date.
Pour aller plus loin, le mieux est de consulter la [documentation
officielle][16] de `pandoc.`

1
document/6-bibliographie.md 100644
View File

@ -0,0 +1 @@
## Bibliographie {#bibliography .newpage}

0
intro/intro-déroulé.md → déroulé.md
View File

692
heg-iso-690.csl 100644
View File

@ -0,0 +1,692 @@
<?xml version="1.0" encoding="utf-8"?>
<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0" demote-non-dropping-particle="never">
<info>
<title>Haute école de gestion de Genève (ISO 690)</title>
<title-short>HEG Genève (ISO 690)</title-short>
<id>http://www.zotero.org/styles/haute-ecole-de-gestion-de-geneve-iso-690</id>
<link href="http://www.zotero.org/styles/haute-ecole-de-gestion-de-geneve-iso-690" rel="self"/>
<link href="http://www.zotero.org/styles/iso690-author-date-en" rel="template"/>
<link href="https://www.hesge.ch/heg/campus/infotheque/citations-et-references-bibliographiques" rel="documentation"/>
<author>
<name>Raphael Grolimund</name>
<email>grolimur@protonmail.ch</email>
</author>
<contributor>
<name>Melissa Paez</name>
<email>paez.melissa@gmail.com</email>
</contributor>
<category citation-format="author-date"/>
<category field="generic-base"/>
<updated>2023-10-24T10:00:00+00:00</updated>
<rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License</rights>
</info>
<locale xml:lang="fr-FR">
<terms>
<term name="no date">[sans date]</term>
<term name="online">en&#160;ligne</term>
<term name="retrieved">disponible</term>
<term name="issue" form="short">
<single>no</single>
<multiple>nos</multiple>
</term>
<term name="page" form="short">
<single>p.</single>
<multiple>pp.</multiple>
</term>
<term name="number-of-pages" form="short">
<single>p.</single>
<multiple>pp.</multiple>
</term>
<!-- the 2 following terms, never used in any citation style published on https://zotero.org/styles, are hijacked to distinguish the diffrents dates (submitted, issued) of a patent -->
<term name="special-issue">déposé le</term>
<term name="special-section">publié le</term>
</terms>
</locale>
<locale xml:lang="fr-CA">
<terms>
<term name="no date">[sans date]</term>
<term name="online">en&#160;ligne</term>
<term name="retrieved">disponible</term>
<term name="issue" form="short">
<single>no</single>
<multiple>nos</multiple>
</term>
<term name="page" form="short">
<single>p.</single>
<multiple>pp.</multiple>
</term>
<term name="number-of-pages" form="short">
<single>p.</single>
<multiple>pp.</multiple>
</term>
<!-- the 2 following terms, never used in any citation style published on https://zotero.org/styles, are hijacked to distinguish the diffrents dates (submitted, issued) of a patent -->
<term name="special-issue">déposé le</term>
<term name="special-section">publié le</term>
</terms>
</locale>
<locale xml:lang="en-US">
<terms>
<term name="issue">no.</term>
<!-- the 2 following terms, never used in any citation style published on https://zotero.org/styles, are hijacked to distinguish the diffrents dates (submitted, issued) of a patent -->
<term name="special-issue">submitted on</term>
<term name="special-section">published on</term>
</terms>
</locale>
<locale xml:lang="en-UK">
<terms>
<term name="issue">no.</term>
<!-- the 2 following terms, never used in any citation style published on https://zotero.org/styles, are hijacked to distinguish the diffrents dates (submitted, issued) of a patent -->
<term name="special-issue">submitted on</term>
<term name="special-section">published on</term>
</terms>
</locale>
<macro name="editor">
<names variable="editor">
<name and="text" name-as-sort-order="all" sort-separator=", " delimiter=", " delimiter-precedes-last="never">
<name-part name="family" text-case="uppercase"/>
</name>
<label prefix=" (" form="short" suffix=".)"/>
</names>
</macro>
<macro name="translator">
<names variable="translator">
<name and="text" name-as-sort-order="all" sort-separator=", " delimiter=", " delimiter-precedes-last="never">
<name-part name="family" text-case="uppercase"/>
</name>
<label prefix=" (" form="short" suffix=".)"/>
</names>
</macro>
<macro name="responsability">
<names variable="author director">
<name and="text" name-as-sort-order="all" sort-separator=", " delimiter=", " delimiter-precedes-last="never">
<name-part name="family" text-case="uppercase"/>
</name>
<substitute>
<text macro="editor"/>
<text macro="translator"/>
<text macro="title"/>
</substitute>
</names>
<choose>
<if variable="author editor translator director" match="any">
<text macro="year-date" prefix=", "/>
</if>
</choose>
</macro>
<macro name="author-citation">
<names variable="author director">
<name form="short"/>
<substitute>
<names variable="editor"/>
<names variable="translator"/>
<text variable="title" font-style="italic"/>
</substitute>
</names>
</macro>
<macro name="container-author">
<names variable="container-author">
<name and="text" name-as-sort-order="all" sort-separator=", " delimiter=", " delimiter-precedes-last="never">
<name-part name="family" text-case="uppercase"/>
</name>
</names>
</macro>
<macro name="container-responsability">
<choose>
<if variable="container-author">
<text macro="container-author"/>
</if>
<else-if variable="editor">
<text macro="editor"/>
</else-if>
<else>
<text macro="translator"/>
</else>
</choose>
</macro>
<macro name="year-date">
<choose>
<if is-uncertain-date="issued">
<group prefix="[" suffix="]">
<choose>
<if variable="issued">
<date variable="issued">
<date-part name="year" form="long" suffix="?"/>
</date>
</if>
<else>
<text term="no date"/>
</else>
</choose>
</group>
</if>
<else>
<choose>
<if variable="issued">
<date variable="issued">
<date-part name="year" form="long"/>
</date>
</if>
</choose>
</else>
</choose>
</macro>
<macro name="title">
<choose>
<if type="book thesis map motion_picture song manuscript speech" match="any">
<choose>
<if variable="author editor translator director" match="any">
<text variable="title" font-style="italic"/>
</if>
<else>
<text variable="title" font-style="italic" suffix=", "/>
<text macro="year-date"/>
</else>
</choose>
</if>
<else-if type="software">
<text variable="title" font-style="italic"/>
<text term="software" prefix=" [" suffix="]"/>
</else-if>
<else-if type="paper-conference chapter article-journal article-magazine article-newspaper entry entry-dictionary entry-encyclopedia post-weblog post webpage broadcast" match="any">
<choose>
<if variable="author editor translator director" match="any">
<text variable="title" suffix=". "/>
</if>
<else>
<text variable="title" suffix=", "/>
<text macro="year-date"/>
</else>
</choose>
<choose>
<if type="chapter paper-conference" match="any">
<text term="in" text-case="capitalize-first" suffix="&#160;: "/>
</if>
</choose>
<choose>
<if variable="container-author editor translator" match="any">
<text macro="container-responsability"/>
<choose>
<if variable="container-title event" match="any">
<text value=", "/>
</if>
</choose>
</if>
</choose>
<choose>
<if variable="container-title">
<text variable="container-title" font-style="italic"/>
<choose>
<if type="chapter paper-conference" match="any">
<group delimiter="&#160;" prefix=", ">
<label variable="page" form="short"/>
<text variable="page"/>
</group>
</if>
</choose>
</if>
<else>
<text variable="event" font-style="italic"/>
</else>
</choose>
</else-if>
<else-if type="report">
<choose>
<if variable="author editor translator director" match="any">
<text variable="title" font-style="italic"/>
</if>
<else>
<text variable="number" suffix="&#160;: "/>
<text variable="title" font-style="italic" suffix=", "/>
<text macro="year-date"/>
</else>
</choose>
</else-if>
<else-if type="patent">
<choose>
<if variable="author editor translator director" match="any">
<text variable="title" font-style="italic"/>
</if>
<else>
<text variable="title" suffix=", "/>
<text macro="year-date"/>
</else>
</choose>
</else-if>
<else>
<choose>
<if variable="author editor translator director" match="any">
<text variable="title" font-style="italic"/>
</if>
<else>
<text variable="title" font-style="italic" suffix=", "/>
<text macro="year-date"/>
</else>
</choose>
</else>
</choose>
<choose>
<if variable="DOI version" match="none">
<choose>
<if variable="URL">
<text term="online" prefix=" [" suffix="]"/>
</if>
<else>
<choose>
<if type="broadcast motion_picture song book chapter article-journal article-magazine article-newspaper patent" match="none">
<text value=". "/>
</if>
</choose>
</else>
</choose>
</if>
</choose>
</macro>
<macro name="number">
<text variable="authority" suffix=" "/>
<text variable="number"/>
</macro>
<macro name="medium">
<text variable="medium" prefix=" [" suffix="]"/>
</macro>
<macro name="legislation-number">
<group delimiter=" ">
<text variable="container-title"/>
<text variable="volume"/>
</group>
</macro>
<macro name="genre">
<choose>
<if type="map">
<choose>
<if variable="genre">
<text variable="genre" prefix="[" suffix="]"/>
</if>
<else>
<text value="map" prefix="[" suffix="]"/>
</else>
</choose>
</if>
<else>
<text variable="genre" suffix=" "/>
<text variable="number"/>
</else>
</choose>
</macro>
<macro name="date">
<choose>
<if type="patent">
<text term="patent" text-case="capitalize-first" suffix=" "/>
<text term="special-issue" suffix=" "/>
<date variable="submitted">
<date-part name="day" suffix="&#160;"/>
<date-part name="month" suffix="&#160;"/>
<date-part name="year"/>
</date>
<text term="and" prefix=" " suffix=" "/>
<text term="special-section" suffix=" "/>
<date variable="issued">
<date-part name="day" suffix="&#160;"/>
<date-part name="month" suffix="&#160;"/>
<date-part name="year"/>
</date>
</if>
</choose>
<choose>
<if is-uncertain-date="issued">
<group prefix="[" suffix="]">
<choose>
<if variable="issued">
<date variable="issued">
<date-part name="year" form="long" suffix="?"/>
</date>
</if>
<else>
<text term="no date"/>
</else>
</choose>
</group>
</if>
<else>
<choose>
<if variable="issued">
<date variable="issued">
<date-part name="day" suffix="&#160;"/>
<date-part name="month" suffix="&#160;"/>
<date-part name="year"/>
</date>
</if>
</choose>
</else>
</choose>
</macro>
<macro name="edition">
<text variable="edition" form="long"/>
</macro>
<macro name="publisher-group">
<choose>
<if type="speech" match="any">
<group delimiter=", ">
<text variable="event"/>
<text variable="publisher-place"/>
</group>
</if>
<else>
<group delimiter="&#160;: ">
<text variable="publisher-place"/>
<text variable="publisher"/>
</group>
</else>
</choose>
</macro>
<macro name="issue">
<group delimiter=", ">
<text variable="volume" prefix="Vol.&#160;"/>
<choose>
<if variable="volume">
<group delimiter="&#160;">
<text term="issue" form="short"/>
<text variable="issue"/>
</group>
<group delimiter="&#160;">
<label variable="page" form="short"/>
<text variable="page"/>
</group>
</if>
<else-if variable="issue">
<group delimiter="&#160;">
<text term="issue" form="short" text-case="capitalize-first"/>
<text variable="issue"/>
</group>
<group delimiter="&#160;">
<label variable="page" form="short"/>
<text variable="page"/>
</group>
</else-if>
<else>
<group delimiter="&#160;">
<label variable="page" form="short"/>
<text variable="page"/>
</group>
</else>
</choose>
</group>
</macro>
<macro name="accessed">
<choose>
<if variable="DOI" match="none">
<choose>
<if variable="URL">
<group prefix=" [" suffix="]">
<text term="accessed"/>
<date variable="accessed">
<date-part name="day" prefix=" "/>
<date-part name="month" prefix="&#160;"/>
<date-part name="year" prefix="&#160;"/>
</date>
</group>
</if>
</choose>
</if>
</choose>
</macro>
<macro name="collection">
<group delimiter=", ">
<text variable="collection-title"/>
<text variable="collection-number"/>
</group>
</macro>
<macro name="page">
<text variable="number-of-pages" suffix="&#160;p"/>
</macro>
<macro name="isbn">
<text variable="ISBN" prefix="ISBN&#160;"/>
</macro>
<macro name="doi">
<text variable="DOI" prefix="DOI&#160;"/>
</macro>
<macro name="url">
<choose>
<if variable="DOI" match="none">
<choose>
<if variable="URL">
<group>
<text term="retrieved" suffix=" " text-case="capitalize-first"/>
<text term="from" suffix="&#160;: "/>
<text variable="URL"/>
</group>
</if>
</choose>
</if>
</choose>
</macro>
<citation et-al-min="4" et-al-use-first="1" disambiguate-add-year-suffix="true" disambiguate-add-names="true" disambiguate-add-givenname="true" collapse="year" year-suffix-delimiter=", " after-collapse-delimiter="; ">
<layout prefix="(" suffix=")" delimiter="; ">
<group delimiter=", ">
<group delimiter=" ">
<text macro="author-citation"/>
<text macro="year-date"/>
</group>
<group>
<label variable="locator" suffix=".&#160;" form="short" strip-periods="true"/>
<text variable="locator"/>
</group>
</group>
</layout>
</citation>
<bibliography et-al-min="4" et-al-use-first="1">
<sort>
<key macro="responsability"/>
<key macro="year-date"/>
</sort>
<layout>
<choose>
<if type="book map" match="any">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="edition" suffix=". "/>
<text macro="publisher-group" suffix=". "/>
<text macro="collection" suffix=". "/>
<text macro="isbn" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</if>
<else-if type="article-journal article-magazine" match="any">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="edition" suffix=". "/>
<text macro="issue" suffix=". "/>
<text macro="doi" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else-if type="article-newspaper">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="edition" suffix=". "/>
<text macro="publisher-group" suffix=", "/>
<text macro="date" suffix=". "/>
<text macro="page" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else-if type="chapter entry entry-dictionary entry-encyclopedia" match="any">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="edition" suffix=". "/>
<text macro="publisher-group" suffix=". "/>
<text macro="collection" suffix=". "/>
<text macro="isbn" suffix=". "/>
<text macro="doi" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else-if type="speech">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="genre" suffix=". "/>
<text macro="publisher-group" suffix=". "/>
<text macro="date" suffix=". "/>
<text macro="page" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else-if type="paper-conference">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="genre" suffix=". "/>
<text macro="publisher-group" suffix=". "/>
<text macro="date" suffix=". "/>
<text macro="page" suffix=". "/>
<text macro="collection" suffix=". "/>
<text macro="isbn" suffix=". "/>
<text macro="doi" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else-if type="thesis">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="genre" suffix=". "/>
<text macro="publisher-group" suffix=". "/>
<text macro="doi" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else-if type="post-weblog post webpage" match="any">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="date" suffix=". "/>
<text macro="doi" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else-if type="broadcast motion_picture song" match="any">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="medium" suffix=". "/>
<text macro="publisher-group" suffix=", "/>
<text macro="date" suffix=". "/>
<text macro="collection" suffix=". "/>
<text macro="isbn" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else-if type="report">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="publisher-group" suffix=". "/>
<text macro="genre" suffix=". "/>
<text macro="collection" suffix=". "/>
<text macro="doi" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else-if type="manuscript">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="genre" suffix=". "/>
<text macro="edition" suffix=". "/>
<text macro="publisher-group" suffix=". "/>
<text macro="collection" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else-if type="patent">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="date" suffix=". "/>
<text macro="publisher-group" suffix=". "/>
<text macro="collection" suffix=". "/>
<text macro="url" suffix=". "/>
<text macro="accessed" suffix=". "/>
<text macro="number" suffix=". "/>
</else-if>
<else-if type="software">
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text variable="version" prefix="Version " suffix=". "/>
<text macro="date" suffix=". "/>
<text macro="publisher-group" suffix=". "/>
<text macro="accessed" suffix=". "/>
<text macro="doi" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else-if>
<else>
<text macro="responsability" suffix=". "/>
<choose>
<if variable="author editor translator director" match="any">
<text macro="title" suffix=". "/>
</if>
</choose>
<text macro="medium" suffix=". "/>
<text macro="genre" suffix=". "/>
<text variable="authority" suffix=". "/>
<text macro="edition" suffix=". "/>
<text macro="publisher-group" suffix=". "/>
<text macro="number" suffix=". "/>
<text macro="legislation-number" suffix=". "/>
<text macro="collection" suffix=". "/>
<text macro="page" suffix=". "/>
<text macro="isbn" suffix=". "/>
<text macro="doi" suffix=". "/>
<text macro="url"/>
<text macro="accessed" suffix=". "/>
</else>
</choose>
<text variable="note"/>
</layout>
</bibliography>
</style>

371
intro/intro.md
View File

@ -1,371 +0,0 @@
---
title: Introduction à la prise de note avec markdown
author:
- Igor Milhit^[Uni CMU]
date: Printemps 2024
creation_date: 2023-04-19T11:35:14+02:00
id: 20230419113601
tags: [note, markdown]
logo:
- ../static/logo-md.svg
lang: fr
bibliography: ../static/references.bib
citation-style: ../static/heg-iso-690.csl
link-citations: true
toc-title: Table des matières
---
## Objectifs
- Avantages et inconvénients.
- Aperçu de la syntaxe de base.
- Les fonctionnalités minimales d’un éditeur.
- Bref aperçu des possibilités avancées :
- Ensemble de notes.
- Conversion dans d’autres formats.
- Insertion de références bibliographiques.
:::{#licence}
![Logo de la licence CC BY-SA 4.0](../static/by-sa.svg) \
[CC BY-SA 4.0][cc-by-sa] --- [Sources][sources]
:::
[cc-by-sa]: https://creativecommons.org/licenses/by-sa/4.0/deed.fr "Texte de la licence en français"
[sources]: https://git.milhit.ch/igor/rdv-info-markdown
## Définition, avantages et inconvénients[^0] {#first-section}
Le plus important est de trouver des méthodes et des outils adaptés à *ses
besoins*. Ci-dessous sont listés quelques arguments en faveur de l'usage de
fichiers au format texte et de la syntaxe markdown, mais aucune méthode ou
outil n'est *la* solution miracle pertinente dans *tous* les contextes.
### Définition
L'information numérique est utile si elle est **structurée**. La table des
matières d'un document numérique devrait être constituée de liens vers les
sections. Cette structure peut s'obtenir par l'usage des styles et des niveaux
de titre dans un traitement de texte (Microsoft Word, Libreoffice Writer,
etc.). La syntaxe markdown est une autre méthode, très efficace.[^1]
Markdown est *un langage de balisage léger*. Concrètement, il s'agit d'une
syntaxe qui permet, **uniquement avec des éléments textuels**, de structurer
(niveau de titres) et de mettre en forme du texte. Cette structure et cette
mise en forme sont compréhensibles par des êtres humains ou par des programmes
informatiques. Aussi, les documents rédigés à l'aide de markdown peuvent soit
être lus tels quels, soit être traités par un programme pour afficher un
« rendu » sous forme de page web, de document PDF ou DOCX.
La syntaxe markdown est relativement simple à apprendre et mémoriser. Aussi, la
rédaction au format markdown repose sur très peu de fonctionnalités du
logiciel. Le bloc note suffit, même si un peu plus de confort est souhaitable.
Cette syntaxe est utilisée par de nombreux logiciels ou services en lignes pour
la rédaction. C'est le cas des notes dans Zotero ou d'éditeurs en ligne adaptés
au travail collaboratif ([HedgeDoc][1], [HackMD][2], etc.).
### Avantages
Les fichiers utilisés ne sont composés que de caractères textuels. Aussi, ils
sont :
- Simples et légers :
- Ne dépendent pas d'un logiciel spécifique, ni d'un système d'exploitation.
- Pourront être ouverts et édités dans n'importe quel contexte, et
probablement dans un avenir éloigné (pérennité).
- Rapides à ouvrir. Avec n'importe quel éditeur de texte (bloc note Windows,
Notepad++, TextEdit, Gedit, VIM, EMACS, etc.)
- Faciles à sauvegarder, copier, synchroniser, partager.
Toujours grâce à leur nature textuelle, il est facile d'avoir des outils pour
rechercher (et remplacer) rapidement du texte au sein non seulement du fichier
ouvert, mais d'un ensemble de fichier dans un répertoire. \
Il est même possible d'écrire des programmes pour modifier ou utiliser
automatiquement ces fichiers. Et il en existe justement beaucoup !
Grâce à ces propriétés, il est possible :
- De prendre des notes au clavier rapidement, de manière structurée, et avec
une recherche interne efficace.
- De rédiger des documents simples (une note) ou complexes (une thèse).
- De regrouper un ensemble de notes dans un « bloc note » numérique et de
naviguer dans cet ensemble, de rechercher de l'information .
- De manière similaire, de regrouper un ensemble de fichiers pour constituer un
document complexe, comme un livre ou un article scientifique.
- Enfin de convertir à partir des mêmes fichiers le document dans plusieurs
formats pour une diffusion sur le web, la lecture dans un PDF ou un ePub
(compatible avec une liseuse électronique).
Enfin, les fichiers textuels sont particulièrement adaptés au suivi de
l'historique des modification (*versioning*), par exemple avec le logiciel
[Git][3].
### Inconvénients
Pour un usage simple, l'apprentissage n'est pas très difficile. La syntaxe de
base s'acquiert rapidement. Pour parvenir à rédiger des documents relativement
complexes (notes, citations et bibliographies, etc.), cet apprentissage est un
peu plus long. Afin de maîtriser la conversion dans différents formats, tout en
personnalisant la mise en forme des documents obtenus, il devient vite
nécessaire d'apprendre à utiliser d'autres outils, à modifier des modèles dans
les formats désirés (HTML, DOCX, peut-être LaTeX, etc.).
Certains éditeurs intègrent la fonction de conversion, mais elle repose sur
l'installation de logiciels annexes, principalement `pandoc`, mais aussi une
distribution LaTeX pour obtenir une conversion en PDF. Ces outils ne sont pas
si difficiles à installer. Surtout, ils sont libres, gratuits et disponibles
pour Windows, Mac OS ou Linux.
Pour utiliser `pandoc`, qui est l'outil de conversion le plus complet, il est
nécessaire de le faire « en ligne de commande » plutôt que dans une interface
graphique, avec la souris. C'est un élément en plus à apprendre, mais qui ouvre
beaucoup de possibilités.
Le travail collaboratif à plusieurs est toujours possible, mais selon les cas
avec une certaine friction. La situation la plus simple est d'utiliser un
éditeur en ligne qui offre des fonctionnalités d'édition à plusieurs. Souvent
cela est au prix de ne pouvoir disposer de toute la puissance de `pandoc`, du
moins directement.
Toujours dans le cas où toutes les personnes qui collaborent sont capables de
travailler avec les mêmes outils, elles peuvent toujours travailler ensemble en
se mettant d'accord sur un « workflow », par exemple grâce à `git` mentionné
plus haut. Mais c'est un outil de plus à apprendre. Et de nouvelles
possibilités à découvrir.
Enfin, si les personnes avec qui on collabore ne veulent ou ne peuvent pas
utiliser les mêmes méthodes, alors il faudra mettre en place un processus
d'export et d'import un peu complexe, mais en partie automatisable
[@perretMarkdownTraitementTexte2022].
## La syntaxe markdown
La syntaxe markdown est très bien documentée sur le web :
- La documentation « officielle » est disponible sur le site personnel d'un des
concepteurs de la syntaxe : <https://daringfireball.net/projects/markdown/>
[@gruberMarkdown2004].
- Le site *flus* propose Une documentation en français et très claire :
<https://flus.fr/carnet/markdown.html> [@fressinaudGuideMarkdown2022].
- Il y a plusieurs variantes (ou extensions) de la syntaxe et un site essaie de
proposer un standard. Il met à disposition un tutoriel interactif :
<https://commonmark.org/help/> [@commonmarkCommonMark].
- Arthur Perret a traduit en français ce même tutoriel, disponible sur sa page
expliquant ce qu'est markdown :
<https://www.arthurperret.fr/cours/markdown.html> [@perretMarkdown2022].
Pour les tableaux, il est fortement conseillé :
- D'utiliser un générateur, par exemple
<https://www.tablesgenerator.com/markdown_tables>.
- Ou de disposer dans son éditeur d'un générateur de tableaux.
Le plus souvent les fichiers contenant du markdown ont pour extension `.md`,
mais c'est une convention. Rien n'interdit d'utiliser d'autres extensions comme
`.mkdn` ou `.markdown`, pour autant que l'éditeur que vous utilisez les
reconnaissent comme du markdown.
## Éditeurs
Il existe beaucoup d'éditeurs pour rédiger en markdown. On peut les regrouper
en deux grandes catégories :
1. Les éditeurs dédiés.
1. Les éditeurs généralistes.
Dans les deux cas, des fonctionnalités de base qui sont presque
incontournables :
- Une prévisualisation, le plus souvent sous la forme d'un *rendu* HTML. Cette
fonctionnalité a l'avantage de permettre de se faire une idée du résultat
sans devoir générer le fichier final.
- La possibilité de naviguer dans une arborescence de fichiers, en général dans
une barre sur le côté de l'interface.
- Une autocomplétion, pour faciliter l'entrée de syntaxe avec des `[]` ou des
`()`.
D'autres fonctionnalités ne sont pas indispensables, mais deviennent rapidement
utiles :
- La correction orthographique pour les langues dans lesquelles vous rédigez.
- Un formatage automatique des tableaux.
- La possibilité de suivre les liens internes, au sein du même fichier ou entre
les fichiers d'un même répertoire.
### Éditeurs dédiés
Ce sont des logiciels conçu spécifiquement pour éditer des fichiers avec la
syntaxe markdown. Ils peuvent être sous la forme d'un logiciel à installer sur
votre appareil (ordinateur, tablette, téléphone) ou d'un service web.
**Typora** est éditeur qui met l'accent sur son interface épurée. Il est disponible
pour tous les systèmes d'exploitation, payant. <https://typora.io/>
![Interface de GhostWriter][6]
**GhostWriter** est libre et gratuit, pour Windows et Linux
principalement.[^2] <https://ghostwriter.kde.org/fr/>
**Abricotine** est libre et gratuit, pour toutes les plateformes.
<http://abricotine.brrd.fr/>
**iA Writer** est payant, pour MacOS et Windows, mais est très apprécié pour la
rédaction. Il permet de lier des notes entre elles et offre ainsi une
navigation dans un ensemble de fichiers. <https://ia.net/writer>
**Obsidian** est un logiciel propriétaire, pour toutes les plateformes. Il ne
se limite pas à l'édition de fichiers markdown, mais permet de constituer une
base de connaissance basée sur des notes, et cela de manière très complète.
<https://obsidian.md/>
![Interface de Zettlr][5]
**Zettlr** est libre et disponible pour tous les systèmes d'exploitation. Il
est destiné à un usage académique, que ce soit pour construire une base de
connaissance à partir de notes ou pour rédiger un travail de mémoire ou un
article scientifique. Il intègre Zotero pour la gestion des références.
En ligne, on peut mentionner à nouveau le service [HackMD][2] ou le logiciel
[HedgeDoc][1] qui permet non seulement d'éditer des fichiers markdown avec une
prévisualisation, mais également de le faire à plusieurs, de disposer d'un
suivi des modifications et de commenter.
![Interface de l'éditeur HackMD][4]
### Éditeurs généralistes
*Généralistes* car ces éditeurs ne sont pas limités à l'édition de fichier
markdown. Le plus souvent, ce sont des *éditeurs de texte* utilisés
par des développeurs pour écrire du code informatique. Le plus souvent, ils
disposent d'un écosystème d'extensions afin de s'adapter à des besoins
spécifiques. De ce fait, ils sont très puissants.
Ainsi, il est possible d'adapter à l'édition du markdown les éditeurs de texte
suivant, notamment :
- Notepad++, libre et gratuit, pour Windows.
- Visual Studio Code, gratuit, pour Windows, MacOS, Linux. Un des logiciels les
plus utilisés actuellement.
- VIM ou neovim, libre et gratuit, pour tous les systèmes d'exploitation.
- EMACS, libre et gratuit.
![Interface de Visual Studio Code][7]
## Aperçu des possibilités avancées
### Ensemble de notes
Afin d'organiser ses notes, il est possible de réunir un ensemble de fichiers
dans le même répertoires (y compris avec des sous répertoires) et de faire des
liens entre les fichiers (et même au sein d'un seul fichier).
Certains éditeurs, ou certaines extensions d'éditeurs, proposent des facilités
pour générer ces liens, au prix d'une syntaxe *ad hoc* (« wiki links »). Mais
il est parfaitement possible de le faire avec la syntaxe « normale » du lien.
![Lien depuis le fichier `README.md` vers le fichier `points-a-ameliorer.md`][8]
La figure 5 montre sur la gauche une arborescence de fichiers, avec
des sous-répertoires, et dans le fichier affiché (`README.md`), un lien vers le
fichier `points-a-ameliorer.md`. Dans cet éditeur, en plaçant le curseur sur le
lien et en tapant la touche « entrée », on ouvre le fichier cible.
La figure 6 montre la recherche du terme `rdv-info` lancée sur la même
arborescence de fichiers que la figure 5, au moyen du logiciel Visual Studio
Code. Il y a 13 occurrences du terme dans 7 fichiers. Ce type de recherche est
facilité par le fait que ce sont des fichiers au format texte et se retrouve
dans la plupart des éditeurs généralistes de qualité.
![Recherche dans Visual Studio Code][9]
### Export vers d'autres formats
La conversion d'un document markdown en un autre format, plus simple à partager
devient assez vite utile. Pour les conversions, `pandoc` est l'outil le plus
souvent utilisé. Il est soit utilisé par votre éditeur pour faire les exports
(par exemple avec Zettlr), soit par vous même en ligne de commande. C'est un
logiciel libre et gratuit, développé très activement.
Il est capable de lire et d'écrire dans un grand nombre de formats différents,
parfois à l'aide de logiciels spécifiques. Par exemple, pour produire un
fichier PDF, il peut utiliser plusieurs méthodes, dont LaTeX, ce qui suppose
d'en avoir une version installée.
La commande pour une conversion simple est de la forme suivante :
```bash
pandoc --output fichier.docx fichier.md
```
Le format obtenu correspond à celui qui est indiqué en extension du nom de
fichier de sortie `--output`, ici du DOCX. Mais il est possible de
l'expliciter :
```bash
pandoc --to docx --output fichier.docx fichier.md
```
Le support de cours de cette introduction à markdown a été rédigée en markdown
et est exportée en PDF grâce à `pandoc` et à *Paged.js*.[^3]
### Citations et Bibliographie
Pour insérer des citations et générer une bibliographie, il est nécessaire
d'avoir au moins une collection de références bibliographiques, par exemple
sous la forme d'un fichier `.bib`. Pour obtenir ce fichier, il est possible de
passer par Zotero et d'exporter une collection dans le format BibTex (ou Better
BibTex avec l'extension Zotero du même nom.)
Dans ce fichier (et dans Zotero), on trouve pour chaque référence une « clé de
citation » qui permet de l'identifier de manière unique. C'est cette clé que
l'on va insérer dans notre fichier markdown pour indiquer une citation. Elle
est insérée avec la syntaxe suivante : `[@clé-de-citation]`.
On peut encore ajouter à la fin de notre fichier un titre de deuxième niveau
avec le texte bibliographie, pour que `pandoc` puisse y insérer la
bibliographie.
Pour être en mesure de traiter ces informations, il faut utiliser l'option de
`--citeproc` intégrée dans `pandoc` :
```bash
pandoc --citeproc \
--to=pdf --pdf-engine=xelatex \
--bibliography=references.bib \
--output fichier.pdf fichier.md
```
Dans l'exemple ci-dessus, nous voyons l'option `--citeproc` et l'option
`--bibliography=` qui indique où se trouve le fichier des références
bibliographiques. Par défaut le style est Chicago, de type auteur-date.
Pour aller plus loin, le mieux est de consulter la [documentation
officielle][10] de `pandoc.`
## Bibliographie {#bibliography}
<!-- liens -->
[0]: https://www.arthurperret.fr/cours/format-texte.html
[1]: https://hedgedoc.org/
[2]: https://hackmd.io/
[3]: https://fr.wikipedia.org/wiki/Git "Article Wikipedia en français"
[4]: ../static/hackmd.png
[5]: ../static/zettlr.png
[6]: ../static/ghostwriter.png
[7]: ../static/vscode.png
[8]: ../static/lien-entre-fichiers.png
[9]: ../static/recherche-vscode.png
[10]: https://pandoc.org/MANUAL.html#citations
<!-- notes -->
[^0]: Cette section repose beaucoup sur la page [Format texte][0] d'Arthur
Perret [@perretFormatTexte2022].
[^1]: Markdown n'est pas le seul langage de balisage léger existant, bien que
ce soit le plus répandu. D'autres sont encore plus robustes ou puissants, comme
*RestructuredText* ou *AsciiDoc*.
[^2]: Il semble possible de l'installer sur MacOS, mais n'est pas recommandé.
[^3]: Les sources et la méthode de conversion est disponible sur
<https://git.milhit.ch/igor/rdv-info-markdown>.

370
intro/references.bib
View File

@ -1,370 +0,0 @@
@article{bunchIndirectReferenceIntervals2022,
title = {Indirect Reference Intervals Using an {{R}} Pipeline.},
author = {Bunch, Dustin R.},
date = {2022-04},
journaltitle = {J Mass Spectrom Adv Clin Lab},
volume = {24},
eprint = {35252947},
eprinttype = {pmid},
pages = {22--30},
location = {Netherlands},
issn = {2667-145X 2667-1468},
doi = {10.1016/j.jmsacl.2022.02.004},
abstract = {BACKGROUND: Indirect reference intervals require robust statistical approaches to separate the pathological and healthy values. This can be achieved with a data pipeline created in R, a freely available statistical programming language. METHODS: A data pipeline was created to ingest, partition, normalize, remove outliers, and identify reference intervals for testosterone (Testo; n ~=~7,207) and aspartate aminotransferase (AST; n ~=~5,882) using data sets from NHANES. RESULTS: The estimates for AST and Testo determined by this pipeline approximated current RIs. Care should be taken when using this pipeline as there are limitations that depend on the pathology of the analyte and the data set being used for RI estimation. CONCLUSIONS: R can be used to create a robust statistical reference interval pipeline.},
langid = {english},
pmcid = {PMC8889237},
keywords = {ANOVA Analysis of variance,AST aspartate aminotransferase,CLSI Clinical Laboratory Standards Institute,cmu,EHR electronic health record,IFCC International Federation of Clinical Chemistry and Laboratory Medicine,LC-MS/MS Liquid chromatography tandem mass spectrometry,LIS Laboratory informatics system,markdown,Mixtools,non lu,pubmed,R markdown,R markdown tutorial,Reference interval,RI reference interval,SDI Standard deviation index,SDR Standard deviation ratio,Testo Testosterone,TukeyHSD Tukey multiple pairwise-comparisons,z5 Critical z-score},
file = {/home/igor/Zotero/storage/YYP9JQTY/Bunch_2022_Indirect reference intervals using an R pipeline.pdf}
}
@article{chapmanExpectedPosterioriScoring2022,
title = {Expected a Posteriori Scoring in {{PROMIS}}(®).},
author = {Chapman, Robert},
date = {2022-06-03},
journaltitle = {J Patient Rep Outcomes},
volume = {6},
number = {1},
eprint = {35657454},
eprinttype = {pmid},
pages = {59},
location = {Germany},
issn = {2509-8020},
doi = {10.1186/s41687-022-00464-9},
abstract = {BACKGROUND: The Patient-Reported Outcome Measurement Information System(®) (PROMIS(®)) was developed to reliably measure health-related quality of life using the patient's voice. To achieve these aims, PROMIS utilized Item Response Theory methods in its development, validation and implementation. PROMIS measures are typically scored using a specific method to calculate scores, called Expected A Posteriori estimation. BODY: Expected A Posteriori scoring methods are flexible, produce accurate scores and can be efficiently calculated by statistical software. This work seeks to make Expected A Posteriori scoring methods transparent and accessible to a larger audience through description, graphical demonstration and examples. Further applications and practical considerations of Expected A Posteriori scoring are presented and discussed. All materials used in this paper are made available through the R Markdown reproducibility framework and are intended to be reviewed and reused. Commented statistical code for the calculation of Expected A Posteriori scores is included. CONCLUSION: This work seeks to provide the reader with a summary and visualization of the operation of Expected A Posteriori scoring, as implemented in PROMIS. As PROMIS is increasingly adopted and implemented, this work will provide a basis for making psychometric methods more accessible to the PROMIS user base.},
langid = {english},
pmcid = {PMC9166925},
keywords = {cmu,markdown,non lu,pubmed,R markdown},
file = {/home/igor/Zotero/storage/7R2KLGBS/Chapman_2022_Expected a posteriori scoring in PROMIS(®).pdf}
}
@online{commonmarkCommonMark,
title = {{{CommonMark}}},
author = {CommonMark},
url = {https://commonmark.org/},
urldate = {2023-04-25},
langid = {english},
organization = {CommonMark},
keywords = {cmu,non lu},
file = {/home/igor/Zotero/storage/ESNTHT9H/commonmark.org.html}
}
@article{considineToolEncourageMinimum2019,
title = {A {{Tool}} to {{Encourage Minimum Reporting Guideline Uptake}} for {{Data Analysis}} in {{Metabolomics}}.},
author = {Considine, Elizabeth C. and Salek, Reza M.},
date = {2019-03-05},
journaltitle = {Metabolites},
volume = {9},
number = {3},
eprint = {30841575},
eprinttype = {pmid},
location = {Switzerland},
issn = {2218-1989},
doi = {10.3390/metabo9030043},
abstract = {Despite the proposal of minimum reporting guidelines for metabolomics over a decade ago, reporting on the data analysis step in metabolomics studies has been shown to be unclear and incomplete. Major omissions and a lack of logical flow render the data analysis' sections in metabolomics studies impossible to follow, and therefore replicate or even imitate. Here, we propose possible reasons why the original reporting guidelines have had poor adherence and present an approach to improve their uptake. We present in this paper an R markdown reporting template file that guides the production of text and generates workflow diagrams based on user input. This R Markdown template contains, as an example in this instance, a set of minimum information requirements specifically for the data pre-treatment and data analysis section of biomarker discovery metabolomics studies, (gleaned directly from the original proposed guidelines by Goodacre at al). These minimum requirements are presented in the format of a questionnaire checklist in an R markdown template file. The R Markdown reporting template proposed here can be presented as a starting point to encourage the data analysis section of a metabolomics manuscript to have a more logical presentation and to contain enough information to be understandable and reusable. The idea is that these guidelines would be open to user feedback, modification and updating by the metabolomics community via GitHub.},
langid = {english},
pmcid = {PMC6468746},
keywords = {cmu,data analysis,markdown,minimum guidelines,non lu,pubmed,R markdown,reporting,reproducibility},
file = {/home/igor/Zotero/storage/RSRUDDYS/Considine_Salek_2019_A Tool to Encourage Minimum Reporting Guideline Uptake for Data Analysis in.pdf}
}
@article{daasDynamicPublicationMedia2022,
title = {Dynamic Publication Media with the {{COPASI R Connector}} ({{CoRC}}).},
author = {Daas, Johanna C. J. and Förster, Jonas D. and Pahle, Jürgen},
date = {2022-06},
journaltitle = {Math Biosci},
volume = {348},
eprint = {35452633},
eprinttype = {pmid},
pages = {108822},
location = {United States},
issn = {1879-3134 0025-5564},
doi = {10.1016/j.mbs.2022.108822},
abstract = {In this article we show how dynamic publication media and the COPASI R Connector (CoRC) can be combined in a natural and synergistic way to communicate (biochemical) models. Dynamic publication media are becoming a popular tool for authors to effectively compose and publish their work. They are built from templates and the final documents are created dynamically. In addition, they can also be interactive. Working with dynamic publication media is made easy with the programming environment R via its integration with tools such as R Markdown, Jupyter and Shiny. Additionally, the COmplex PAthway SImulator COPASI (http://www.copasi.org), a widely used biochemical modelling toolkit, is available in R through the use of the COPASI R Connector (CoRC, https://jpahle.github.io/CoRC). Models are a common tool in the mathematical biosciences, in particular kinetic models of biochemical networks in (computational) systems biology. We focus on three application areas of dynamic publication media and CoRC: Documentation (reproducible workflows), Teaching (creating self-paced lessons) and Science Communication (immersive and engaging presentation). To illustrate these, we created six dynamic document examples in the form of R Markdown and Jupyter notebooks, hosted on the platforms GitHub, shinyapps.io, Google Colaboratory. Having code and output in one place, creating documents in template-form and the option of interactivity make the combination of dynamic documents and CoRC a versatile tool. All our example documents are freely available at https://jpahle.github.io/DynamiCoRC under the Creative Commons BY 4.0 licence.},
langid = {english},
keywords = {*Software,*Systems Biology,cmu,COPASI,CoRC,Dynamic publication media,Jupyter,Kinetics,markdown,non lu,pubmed,R markdown,Systems biology},
file = {/home/igor/Zotero/storage/WJ5FCFZY/Daas et al_2022_Dynamic publication media with the COPASI R Connector (CoRC).pdf}
}
@unpublished{deletrazModeTexteMarkdown2022,
type = {Atelier},
title = {En mode texte\,: Markdown, Stylo, Pandoc, Notebook…},
author = {Deletraz, Gaëlle and Rabaud, Julien},
date = {2022},
url = {https://markdown-somate2022.netlify.app},
urldate = {2023-04-17},
eventtitle = {So-Mate 2022},
langid = {fre},
venue = {Pau},
keywords = {cmu,markdown,non lu,pandoc,Publication scientifique}
}
@online{eyssetteUtiliserMarkdownPour2023,
type = {Mastodon post},
title = {Utiliser le Markdown pour tout faire.Le diaporama (fait en markdown bien sûr !) qui m'a servi de support lors de mon atelier pour la Journée…},
author = {Eyssette, Cédric (@eyssette@scholar.social)},
date = {2023-04-07},
url = {https://scholar.social/@eyssette/110158455766516456},
urldate = {2023-04-17},
abstract = {Utiliser le Markdown pour tout faire.Le diaporama (fait en markdown bien sûr !) qui m'a servi de support lors de mon atelier pour la Journée du Libre Éducatif 2023.https://eyssette.forge.aeif.fr/marp-slides/slides/2022-2023/utiliser-le-markdown-pour-tout-faire\#Markdown\#JDLE\#JDLE2023\#TeamEduc\#MastoProf},
langid = {french},
organization = {Mastodon},
keywords = {cmu,fediverse,markdown,mastodon,non lu},
file = {/home/igor/Zotero/storage/7FYFNED6/110158455766516456.html}
}
@unpublished{eyssetteUtiliserMarkdownPour2023a,
title = {Utiliser le markdown pour tout faire},
author = {Eyssette, Cédric},
date = {2023},
url = {https://eyssette.forge.aeif.fr/marp-slides/slides/2022-2023/utiliser-le-markdown-pour-tout-faire},
urldate = {2023-04-17},
langid = {fre},
keywords = {cmu,non lu},
file = {/home/igor/Zotero/storage/I7CTE3X5/utiliser-le-markdown-pour-tout-faire.html}
}
@online{fressinaudGuideMarkdown2022,
type = {Site d'une application web},
title = {Guide Markdown},
author = {Fressinaud, Marien},
date = {2022-07-11},
url = {https://flus.fr/carnet/markdown.html},
urldate = {2023-04-17},
abstract = {Un guide simple pour apprendre Markdown.},
langid = {fre},
organization = {flus},
keywords = {cmu,documentation,markdown,non lu},
file = {/home/igor/Zotero/storage/96VGWVYV/markdown.html}
}
@article{graysonMarkdownDynamicInterface2022,
title = {R {{Markdown}} as a Dynamic Interface for Teaching: {{Modules}} from Math and Biology Classrooms.},
author = {Grayson, Kristine L. and Hilliker, Angela K. and Wares, Joanna R.},
date = {2022-07},
journaltitle = {Math Biosci},
volume = {349},
eprint = {35623397},
eprinttype = {pmid},
pages = {108844},
location = {United States},
issn = {1879-3134 0025-5564},
doi = {10.1016/j.mbs.2022.108844},
abstract = {Advancing technologies, including interactive tools, are changing classroom pedagogy across academia. Here, we discuss the R Markdown interface, which allows for the creation of partial or complete interactive classroom modules for courses using the R programming language. R Markdown files mix sections of R code with formatted text, including LaTeX, which are rendered together to form complete reports and documents. These features allow instructors to create classroom modules that guide students through concepts, while providing areas for coding and text response by students. Students can also learn to create their own reports for more independent assignments. After presenting the features and uses of R Markdown to enhance teaching and learning, we present examples of materials from two courses. In a Computational Modeling course for math students, we used R Markdown to guide students through exploring mathematical models to understand the principle of herd immunity. In a Data Visualization and Communication course for biology students, we used R Markdown for teaching the fundamentals of R programming and graphing, and for students to learn to create reproducible data investigations. Through these examples, we demonstrate the benefits of R Markdown as a dynamic teaching and learning tool.},
langid = {english},
pmcid = {PMC9487201},
keywords = {*Learning,*Students,Biology/education,cmu,Data visualization,Herd immunity,Humans,markdown,non lu,Pedagogy,pubmed,R markdown,Teaching programming},
file = {/home/igor/Zotero/storage/JQGHBHB5/Grayson et al_2022_R Markdown as a dynamic interface for teaching.pdf}
}
@online{gruberMarkdown2004,
type = {Site personnel},
title = {Markdown},
author = {Gruber, John},
date = {2004-12-17},
url = {https://daringfireball.net/projects/markdown/},
urldate = {2023-04-17},
langid = {english},
organization = {Daring Fireball},
keywords = {cmu,documentation,markdown,non lu},
file = {/home/igor/Zotero/storage/J7WP5B3D/markdown.html}
}
@article{hershbergJBrowseRInterfaceJBrowse2021,
title = {{{JBrowseR}}: An {{R}} Interface to the {{JBrowse}} 2 Genome Browser.},
author = {Hershberg, Elliot A. and Stevens, Garrett and Diesh, Colin and Xie, Peter and De Jesus Martinez, Teresa and Buels, Robert and Stein, Lincoln and Holmes, Ian},
date = {2021-11-05},
journaltitle = {Bioinformatics},
volume = {37},
number = {21},
eprint = {34196689},
eprinttype = {pmid},
pages = {3914--3915},
location = {England},
issn = {1367-4811 1367-4803},
doi = {10.1093/bioinformatics/btab459},
abstract = {MOTIVATION: Genome browsers are an essential tool in genome analysis. Modern genome browsers enable complex and interactive visualization of a wide variety of genomic data modalities. While such browsers are very powerful, they can be challenging to configure and program for bioinformaticians lacking expertise in web development. RESULTS: We have developed an R package that provides an interface to the JBrowse 2 genome browser. The package can be used to configure and customize the browser entirely with R code. The browser can be deployed from the R console, or embedded in Shiny applications or R Markdown documents. AVAILABILITY AND IMPLEMENTATION: JBrowseR is available for download from CRAN, and the source code is openly available from the Github repository at https://github.com/GMOD/JBrowseR/.},
langid = {english},
pmcid = {PMC8570803},
keywords = {*Genome,*Genomics,cmu,markdown,non lu,pubmed,R markdown,Software},
file = {/home/igor/Zotero/storage/LYEIF748/Hershberg et al_2021_JBrowseR.pdf}
}
@article{jaglaSCHNAPPsSingleCell2021,
title = {{{SCHNAPPs}} - {{Single Cell sHiNy APPlication}}(s).},
author = {Jagla, Bernd and Libri, Valentina and Chica, Claudia and Rouilly, Vincent and Mella, Sebastien and Puceat, Michel and Hasan, Milena},
date = {2021-12},
journaltitle = {J Immunol Methods},
volume = {499},
eprint = {34742775},
eprinttype = {pmid},
pages = {113176},
location = {Netherlands},
issn = {1872-7905 0022-1759},
doi = {10.1016/j.jim.2021.113176},
abstract = {Single-cell RNA-sequencing (scRNAseq) experiments are becoming a standard tool for bench-scientists to explore the cellular diversity present in all tissues. Data produced by scRNAseq is technically complex and requires analytical workflows that are an active field of bioinformatics research, whereas a wealth of biological background knowledge is needed to guide the investigation. Thus, there is an increasing need to develop applications geared towards bench-scientists to help them abstract the technical challenges of the analysis so that they can focus on the science at play. It is also expected that such applications should support closer collaboration between bioinformaticians and bench-scientists by providing reproducible science tools. We present SCHNAPPs, a Graphical User Interface (GUI), designed to enable bench-scientists to autonomously explore and interpret scRNAseq data and associated annotations. The R/Shiny-based application allows following different steps of scRNAseq analysis workflows from Seurat or Scran packages: performing quality control on cells and genes, normalizing the expression matrix, integrating different samples, dimension reduction, clustering, and differential gene expression analysis. Visualization tools for exploring each step of the process include violin plots, 2D projections, Box-plots, alluvial plots, and histograms. An R-markdown report can be generated that tracks modifications and selected visualizations. The modular design of the tool allows it to easily integrate new visualizations and analyses by bioinformaticians. We illustrate the main features of the tool by applying it to the characterization of T cells in a scRNAseq and Cellular Indexing of Transcriptomes and Epitopes by Sequencing (CITE-Seq) experiment of two healthy individuals.},
langid = {english},
keywords = {*Sequence Analysis RNA,*Single-Cell Analysis,*Software,CITE-Seq,cmu,Humans,Leukocytes Mononuclear/*cytology/immunology,markdown,multi-omics data analysis,non lu,pubmed,R markdown,scRNA-seq,Shiny application},
file = {/home/igor/Zotero/storage/PEARJ76P/Jagla et al_2021_SCHNAPPs - Single Cell sHiNy APPlication(s).pdf}
}
@article{kariyawasamDashboardstyleInteractivePlots2021,
title = {Dashboard-Style Interactive Plots for {{RNA-seq}} Analysis Are {{R Markdown}} Ready with {{Glimma}} 2.0.},
author = {Kariyawasam, Hasaru and Su, Shian and Voogd, Oliver and Ritchie, Matthew E. and Law, Charity W.},
date = {2021-12},
journaltitle = {NAR Genom Bioinform},
volume = {3},
number = {4},
eprint = {34988439},
eprinttype = {pmid},
pages = {lqab116},
location = {England},
issn = {2631-9268},
doi = {10.1093/nargab/lqab116},
abstract = {Glimma 1.0 introduced intuitive, point-and-click interactive graphics for differential gene expression analysis. Here, we present a major update to Glimma that brings improved interactivity and reproducibility using high-level visualization frameworks for R and JavaScript. Glimma 2.0 plots are now readily embeddable in R Markdown, thus allowing users to create reproducible reports containing interactive graphics. The revamped multidimensional scaling plot features dashboard-style controls allowing the user to dynamically change the colour, shape and size of sample points according to different experimental conditions. Interactivity was enhanced in the MA-style plot for comparing differences to average expression, which now supports selecting multiple genes, export options to PNG, SVG or CSV formats and includes a new volcano plot function. Feature-rich and user-friendly, Glimma makes exploring data for gene expression analysis more accessible and intuitive and is available on Bioconductor and GitHub.},
langid = {english},
pmcid = {PMC8693569},
keywords = {cmu,markdown,non lu,pubmed,R markdown},
file = {/home/igor/Zotero/storage/ZQD2WXNN/Kariyawasam et al_2021_Dashboard-style interactive plots for RNA-seq analysis are R Markdown ready.pdf}
}
@online{masuttiRedigerManipulerDocuments2019,
title = {Rédiger et manipuler des documents avec Markdown},
author = {Masutti, Christophe},
date = {2019-05-08},
url = {https://golb.statium.link/post/20190528rediger-et-manipuler-des-documents-markdown/},
urldate = {2024-03-19},
langid = {fre},
organization = {Statium : blog},
keywords = {cmu,markdown,non lu,pandoc,publication numérique,Publication scientifique}
}
@article{ovadiaMarkdownLibrariansAcademics2014a,
title = {Markdown for {{Librarians}} and {{Academics}}},
author = {Ovadia, Steven},
date = {2014-04-03},
journaltitle = {Behavioral \& Social Sciences Librarian},
volume = {33},
number = {2},
pages = {120--124},
issn = {0163-9269, 1544-4546},
doi = {10.1080/01639269.2014.904696},
url = {http://www.tandfonline.com/doi/abs/10.1080/01639269.2014.904696},
urldate = {2023-05-02},
langid = {english},
keywords = {cmu,markdown,non lu,Publication scientifique},
file = {/home/igor/Zotero/storage/25MP4P3N/Ovadia_2014_Markdown for Librarians and Academics.pdf}
}
@online{paged.jsPagedJs,
title = {About {{Paged}}.Js?},
author = {Paged.js},
url = {https://pagedjs.org/about/},
urldate = {2024-03-08},
langid = {english},
organization = {Paged.js},
keywords = {édition numérique,non lu,publication numérique}
}
@online{pandocWritingThesisThinking2023,
type = {Mastodon post},
title = {Writing a \#thesis? {{Thinking}} about Doing It in \#{{Markdown}}? {{No}} Problem, {{Tom Pollard}} Has You Covered.{{https://github.com/tompollard/phd\_thesis\_ma…}}},
shorttitle = {Writing a \#thesis?},
author = {{pandoc}, (@pandoc@fosstodon.org)},
date = {2023-04-12},
url = {https://fosstodon.org/@pandoc/110184589069297715},
urldate = {2023-04-17},
abstract = {Writing a \#thesis? Thinking about doing it in \#Markdown? No problem, Tom Pollard has you covered.https://github.com/tompollard/phd\_thesis\_markdown},
langid = {english},
organization = {Mastodon},
keywords = {cmu,fediverse,markdown,mastodon,non lu,pandoc,Publication scientifique},
file = {/home/igor/Zotero/storage/T354LYSW/110184589069297715.html}
}
@article{perretFormatTexte2022,
title = {Format texte},
author = {Perret, Arthur},
date = {2022-12-11},
journaltitle = {Arthur Perret},
url = {https://www.arthurperret.fr/cours/format-texte.html},
urldate = {2023-04-18},
abstract = {Cette page explique ce qu’est le format texte et donne des arguments en faveur de son utilisation. Elle ouvre vers d’autres ressources pour explorer l’écosystème du format texte.},
langid = {fre},
keywords = {cmu,markdown,non lu,plain text},
file = {/home/igor/Zotero/storage/3IM8K4DU/format-texte.html}
}
@article{perretMarkdown2022,
title = {Markdown},
author = {Perret, Arthur},
date = {2022-12-11},
journaltitle = {Arthur Perret},
publisher = {arthurperret.fr/},
url = {https://www.arthurperret.fr/cours/markdown.html},
urldate = {2023-04-17},
abstract = {Cette page explique ce qu’est Markdown, le plus populaire des langages de balisage léger, et renvoie vers un tutoriel interactif en français.},
langid = {french},
keywords = {cmu,documentation,markdown,non lu},
file = {/home/igor/Zotero/storage/HZNSDQ7S/markdown.html}
}
@online{perretMarkdownTraitementTexte2022,
title = {Markdown et traitement de texte~: une méthode pour collaborer},
shorttitle = {Markdown et traitement de texte},
author = {Perret, Arthur},
date = {2022-10-25},
url = {https://www.arthurperret.fr/blog/2022-10-25-markdown-traitement-de-texte-methode-pour-collaborer.html},
urldate = {2024-04-23},
langid = {fre},
organization = {arthurperret.fr},
keywords = {non lu},
file = {/home/igor/Zotero/storage/TQEHEIHA/2022-10-25-markdown-traitement-de-texte-methode-pour-collaborer.html}
}
@software{pollardTemplateWritingPhD2023,
title = {Template for Writing a {{PhD}} Thesis in {{Markdown}}},
author = {Pollard, Tom},
date = {2023-04-17T04:40:26Z},
origdate = {2015-02-10T10:32:25Z},
url = {https://github.com/tompollard/phd_thesis_markdown},
urldate = {2023-04-17},
abstract = {Template for writing a PhD thesis in Markdown},
keywords = {cmu,markdown,non lu,pandoc,Publication scientifique,thesis-template}
}
@article{schneiderFacilitatingOpenScience2022,
title = {Facilitating Open Science Practices for Research Syntheses: {{PreregRS}} Guides Preregistration.},
author = {Schneider, Jürgen and Backfisch, Iris and Lachner, Andreas},
date = {2022-03},
journaltitle = {Res Synth Methods},
volume = {13},
number = {2},
eprint = {34921744},
eprinttype = {pmid},
pages = {284--289},
location = {England},
issn = {1759-2887 1759-2879},
doi = {10.1002/jrsm.1540},
abstract = {Researchers increasingly engage in adopting open science practices in the field of research syntheses, such as preregistration. Preregistration is a central open science practice in empirical research to enhance transparency in the research process and it gains steady adoption in the context of conducting research synthesis. From an interdisciplinary perspective, frameworks and particularly templates are lacking which support researchers preparing a preregistration. To this end, we introduce preregRS, a template to guide researchers across disciplines through the process of preregistering research syntheses. We utilized an R Markdown template file to provide a framework that structures the process of preparing a preregistration. Researchers can write up the preregistration using the template file similar to filling out a form, with the template providing additional hints and further information for the decisions along the framework. We integrated the R Markdown template in an R package for easy installation and use, but also provide a browser-based option for users granting low-barrier access. PreregRS constitutes a first step to facilitate and support preregistration with research syntheses for all disciplines. It further adds to establishing open science practices in conducting research syntheses.},
langid = {english},
keywords = {*Surveys and Questionnaires,cmu,Empirical Research,markdown,non lu,open science,preregistration,pubmed,R markdown,R package}
}
@article{yuVeridicalDataScience2020,
title = {Veridical Data Science.},
author = {Yu, Bin and Kumbier, Karl},
date = {2020-02-25},
journaltitle = {Proc Natl Acad Sci U S A},
volume = {117},
number = {8},
eprint = {32054788},
eprinttype = {pmid},
pages = {3920--3929},
location = {United States},
issn = {1091-6490 0027-8424},
doi = {10.1073/pnas.1901326117},
abstract = {Building and expanding on principles of statistics, machine learning, and scientific inquiry, we propose the predictability, computability, and stability (PCS) framework for veridical data science. Our framework, composed of both a workflow and documentation, aims to provide responsible, reliable, reproducible, and transparent results across the data science life cycle. The PCS workflow uses predictability as a reality check and considers the importance of computation in data collection/storage and algorithm design. It augments predictability and computability with an overarching stability principle. Stability expands on statistical uncertainty considerations to assess how human judgment calls impact data results through data and model/algorithm perturbations. As part of the PCS workflow, we develop PCS inference procedures, namely PCS perturbation intervals and PCS hypothesis testing, to investigate the stability of data results relative to problem formulation, data cleaning, modeling decisions, and interpretations. We illustrate PCS inference through neuroscience and genomics projects of our own and others. Moreover, we demonstrate its favorable performance over existing methods in terms of receiver operating characteristic (ROC) curves in high-dimensional, sparse linear model simulations, including a wide range of misspecified models. Finally, we propose PCS documentation based on R Markdown or Jupyter Notebook, with publicly available, reproducible codes and narratives to back up human choices made throughout an analysis. The PCS workflow and documentation are demonstrated in a genomics case study available on Zenodo.},
langid = {english},
pmcid = {PMC7049126},
keywords = {cmu,computation,data science,markdown,non lu,prediction,pubmed,R markdown,stability},
file = {/home/igor/Zotero/storage/GWVCYDA6/Yu_Kumbier_2020_Veridical data science.pdf}
}

33251
paged.polyfill.js 100644
View File

File diff suppressed because it is too large Load Diff

15
references.json 100644
View File

@ -0,0 +1,15 @@
[
{"id":"commonmarkCommonMark","accessed":{"date-parts":[["2023",4,25]]},"author":[{"family":"CommonMark","given":""}],"citation-key":"commonmarkCommonMark","container-title":"CommonMark","language":"eng","title":"CommonMark","type":"webpage","URL":"https://commonmark.org/"},
{"id":"deletrazModeTexteMarkdown2022","accessed":{"date-parts":[["2023",4,17]]},"author":[{"family":"Deletraz","given":"Gaëlle"},{"family":"Rabaud","given":"Julien"}],"citation-key":"deletrazModeTexteMarkdown2022","event-place":"Pau","event-title":"So-Mate 2022","genre":"Atelier","issued":{"date-parts":[["2022"]]},"language":"fre","publisher-place":"Pau","title":"En mode texte : Markdown, Stylo, Pandoc, Notebook…","type":"speech","URL":"https://markdown-somate2022.netlify.app"},
{"id":"eyssetteUtiliserMarkdownPour2023","accessed":{"date-parts":[["2023",4,17]]},"author":[{"family":"Eyssette","given":"Cédric"}],"citation-key":"eyssetteUtiliserMarkdownPour2023","issued":{"date-parts":[["2023"]]},"language":"fre","title":"Utiliser le markdown pour tout faire","type":"speech","URL":"https://eyssette.forge.aeif.fr/marp-slides/slides/2022-2023/utiliser-le-markdown-pour-tout-faire"},
{"id":"fressinaudGuideMarkdown2022","abstract":"Un guide simple pour apprendre Markdown.","accessed":{"date-parts":[["2023",4,17]]},"author":[{"family":"Fressinaud","given":"Marien"}],"citation-key":"fressinaudGuideMarkdown2022","container-title":"flus","genre":"Site d'une application web","issued":{"date-parts":[["2022",7,11]]},"language":"fre","title":"Guide Markdown","type":"webpage","URL":"https://flus.fr/carnet/markdown.html"},
{"id":"gruberMarkdown2004","accessed":{"date-parts":[["2023",4,17]]},"author":[{"family":"Gruber","given":"John"}],"citation-key":"gruberMarkdown2004","container-title":"Daring Fireball","genre":"Site personnel","issued":{"date-parts":[["2004",12,17]]},"language":"eng","title":"Markdown","type":"webpage","URL":"https://daringfireball.net/projects/markdown/"},
{"id":"martinolliManuelPratiqueRecherche2024","abstract":"Ce manuel est principalement conçu pour accompagner le séminaire PLU6058, qui vise à améliorer les compétences informationnelles des étudiant.es des cycles supérieurs de l’Université de Montréal. Cependant, il peut également être utilisé de manière autonome et autodidacte pour la recherche et l’utilisation de la documentation dans le cadre d’un projet de recherche. En outre, il peut être utilisé comme une ressource éducative par les enseignant.es en bibliothèque de recherche.","accessed":{"date-parts":[["2024",11,12]]},"author":[{"family":"Martinolli","given":"Pascal"}],"citation-key":"martinolliManuelPratiqueRecherche2024","issued":{"date-parts":[["2024",11,8]]},"language":"fre","note":"https://github.com/pmartinolli/QMpRD","title":"Manuel pratique de recherche documentaire","type":"document","URL":"https://pmartinolli.github.io/QMpRD/"},
{"id":"masuttiRedigerManipulerDocuments2019","accessed":{"date-parts":[["2024",3,19]]},"author":[{"family":"Masutti","given":"Christophe"}],"citation-key":"masuttiRedigerManipulerDocuments2019","container-title":"Statium : blog","issued":{"date-parts":[["2019",5,8]]},"language":"fre","title":"Rédiger et manipuler des documents avec Markdown","type":"post-weblog","URL":"https://golb.statium.link/post/20190528rediger-et-manipuler-des-documents-markdown/"},
{"id":"ovadiaMarkdownLibrariansAcademics2014a","accessed":{"date-parts":[["2023",5,2]]},"author":[{"family":"Ovadia","given":"Steven"}],"citation-key":"ovadiaMarkdownLibrariansAcademics2014a","container-title":"Behavioral & Social Sciences Librarian","container-title-short":"Behavioral & Social Sciences Librarian","DOI":"10.1080/01639269.2014.904696","ISSN":"0163-9269, 1544-4546","issue":"2","issued":{"date-parts":[["2014",4,3]]},"language":"en","page":"120-124","source":"DOI.org (Crossref)","title":"Markdown for Librarians and Academics","type":"article-journal","URL":"http://www.tandfonline.com/doi/abs/10.1080/01639269.2014.904696","volume":"33"},
{"id":"paged.jsPagedJs","accessed":{"date-parts":[["2024",3,8]]},"author":[{"family":"Paged.js","given":""}],"citation-key":"paged.jsPagedJs","container-title":"Paged.js","language":"eng","title":"About Paged.js?","type":"webpage","URL":"https://pagedjs.org/about/"},
{"id":"perretFormatTexte2022","abstract":"Cette page explique ce qu’est le format texte et donne des arguments en faveur de son utilisation. Elle ouvre vers d’autres ressources pour explorer l’écosystème du format texte.","accessed":{"date-parts":[["2023",4,18]]},"author":[{"family":"Perret","given":"Arthur"}],"citation-key":"perretFormatTexte2022","container-title":"Arthur Perret","issued":{"date-parts":[["2022",12,11]]},"language":"fre","title":"Format texte","type":"article-journal","URL":"https://www.arthurperret.fr/cours/format-texte.html"},
{"id":"perretMarkdown2022","abstract":"Cette page explique ce qu’est Markdown, le plus populaire des langages de balisage léger, et renvoie vers un tutoriel interactif en français.","accessed":{"date-parts":[["2023",4,17]]},"author":[{"family":"Perret","given":"Arthur"}],"citation-key":"perretMarkdown2022","container-title":"Arthur Perret","issued":{"date-parts":[["2022",12,11]]},"language":"fr","publisher":"arthurperret.fr/","title":"Markdown","type":"article-journal","URL":"https://www.arthurperret.fr/cours/markdown.html"},
{"id":"perretMarkdownTraitementTexte2022","accessed":{"date-parts":[["2024",4,23]]},"author":[{"family":"Perret","given":"Arthur"}],"citation-key":"perretMarkdownTraitementTexte2022","container-title":"arthurperret.fr","issued":{"date-parts":[["2022",10,25]]},"language":"fre","title":"Markdown et traitement de texte : une méthode pour collaborer","title-short":"Markdown et traitement de texte","type":"post-weblog","URL":"https://www.arthurperret.fr/blog/2022-10-25-markdown-traitement-de-texte-methode-pour-collaborer.html"},
{"id":"pollardTemplateWritingPhD2023","abstract":"Template for writing a PhD thesis in Markdown","accessed":{"date-parts":[["2023",4,17]]},"author":[{"family":"Pollard","given":"Tom"}],"citation-key":"pollardTemplateWritingPhD2023","genre":"HTML","issued":{"date-parts":[["2023",4,17]]},"license":"MIT","original-date":{"date-parts":[["2015",2,10]]},"source":"GitHub","title":"Template for writing a PhD thesis in Markdown","type":"software","URL":"https://github.com/tompollard/phd_thesis_markdown"}
]

117
reload-in-place.js 100644
View File

@ -0,0 +1,117 @@
// Reload-in-place v2.0
// Nicolas Taffin + Sameh Chafik - 2020
// MIT License https://opensource.org/licenses/MIT
// A simple script to add your pagedjs project. On reload, it will make the web browser scroll to the place it was before reload.
// Useful when styling or proof correcting your book. Multi docs compatible and doesn't wait for complete compilation to go.
console.log("reload in place");
// separate human / machine scroll
var machineScroll = false;
// check pagedJS ended compilation
var pagedjsEnd = false;
class pagedjsEnded extends Paged.Handler {
constructor(chunker, polisher, caller) {
super(chunker, polisher, caller);
}
afterRendered(pages) {
pagedjsEnd = true;
}
}
Paged.registerHandlers(pagedjsEnded);
// set a "unique" filename based on title element, in case several books are opened
var fileTitle = document.getElementsByTagName("title")[0].text;
function getDocHeight() {
var D = document;
return Math.max(
D.body.scrollHeight, D.documentElement.scrollHeight,
D.body.offsetHeight, D.documentElement.offsetHeight,
D.body.clientHeight, D.documentElement.clientHeight
)
}
function saveAmountScrolled(){
var scrollArray = [];
var scrollTop = window.pageYOffset || (document.documentElement || document.body.parentNode || document.body).scrollTop
if (!machineScroll) {
var scrollLeft = window.pageXOffset || (document.documentElement || document.body.parentNode || document.body).scrollLeft
scrollArray.push({ X: Math.round(scrollLeft), Y: Math.round(scrollTop) });
console.log("Saved ", scrollArray);
localStorage[fileTitle] = JSON.stringify(scrollArray);
}
}
// on Load, blur or opacify the page, and try to join ASAP
// last saved position, or at least last compiled page
window.onload = moveFast;
function moveFast() {
machineScroll= true;
var styleEl = document.createElement('style');
document.head.appendChild(styleEl);
var styleSheet = styleEl.sheet;
styleSheet.insertRule('.pagedjs_pages { filter: blur(10px); }', 0);
//styleSheet.insertRule('.pagedjs_pages { opacity: 0.1; }', 0);
var savedData = localStorage.getItem(fileTitle);
if (savedData) {
var scrollArray = JSON.parse(savedData);
var scrollTop = scrollArray[0].Y;
var scrollLeft = scrollArray[0].X;
} else {
var scrollTop = 0;
var scrollLeft = 0;
}
var winheight= window.innerHeight || (document.documentElement || document.body).clientHeight
window.currentInterval = setInterval(function(){
var docheight = getDocHeight();
if ( scrollTop > 0 && scrollTop > docheight - winheight && !pagedjsEnd) {
window.scrollTo(scrollLeft,docheight);
} else {
window.scrollTo(scrollLeft,scrollTop);
clearInterval(window.currentInterval);
setTimeout(function(){
window.scrollTo(scrollLeft,scrollTop);
machineScroll = false;
styleSheet.deleteRule(0);
}, 500); // Delay to start
}
}, 50); // refresh frequency
};
// slow down a bit save position pace
var slowSave = debounce(function() {
if(!machineScroll) {
saveAmountScrolled();
}
}, 100); // save frequency
function debounce(func, wait, immediate) {
var timeout;
return function() {
var context = this, args = arguments;
var later = function() {
timeout = null;
if (!immediate) func.apply(context, args);
};
var callNow = immediate && !timeout;
clearTimeout(timeout);
timeout = setTimeout(later, wait);
if (callNow) func.apply(context, args);
};
};
// Scroll triggers save, but not immediately on load
setTimeout(function(){
window.addEventListener('scroll', slowSave);
}, 1000); // wait a bit before starting position save

57
style.css
View File

@ -28,7 +28,7 @@
* bibliothèque de l'UNIGE. */ * bibliothèque de l'UNIGE. */
@top-right { @top-right {
content: ""; content: "";
background-image: url("./static/bibliotheque-logo.svg"); background-image: url("static/bibliotheque-logo.svg");
background-position: right; background-position: right;
background-repeat: no-repeat; background-repeat: no-repeat;
background-size: 25%; background-size: 25%;
@ -56,9 +56,10 @@
* ************************ */ * ************************ */
body { body {
font-family: "TheSansOsF", "Open Sans", Arial, Helvetica, sans-serif; font-family: "Noto Sans", "Open Sans",
/* Définit les deux variable de compteur nécessaires */ Arial, Helvetica, sans-serif;
counter-reset: figureNumber toc; /* Définit les trois variables de compteur nécessaires */
counter-reset: figureNumber toc tableNumber;
} }
/* Définit que string(date) contient la date indiquée dans le frontmatter /* Définit que string(date) contient la date indiquée dans le frontmatter
* de la source markdown */ * de la source markdown */
@ -127,20 +128,25 @@
* Structure du document * * Structure du document *
* ************************* */ * ************************* */
/* Ajouter ou supprimer les ID de titre pour un saut de page /* Ajouter ou supprimer les ID de titre pour un saut de page.
* Les IDs #first-section et #bibliography peuvent être ajoutés * Les IDs #first-section et #bibliography peuvent être ajoutés
* dans la source markdown. */ * dans la source markdown. */
#first-section, #first-section,
#bibliography, #bibliography,
.newpage,
.footnotes { .footnotes {
break-before: page; break-before: page;
} }
/* *************
* Contenu *
* *********** */
h2 { h2 {
color: #d80669; color: #d80669;
text-decoration: underline; text-decoration: underline;
} }
pre { pre {
background-color: #f2f1f1; background-color: #f2f1f1;
border: 2px solid #d80669; border: 2px solid #d80669;
@ -154,8 +160,9 @@
padding: none; padding: none;
} }
code { code {
font-family:'Courier New', Courier, monospace; font-family: 'Lilex Nerd Font', 'Courier New', Courier, monospace;
font-size: 90%; font-size: 90%;
line-height: 1.4;
background-color: #f2f1f1; background-color: #f2f1f1;
padding: 2px; padding: 2px;
border-radius: 5px; border-radius: 5px;
@ -169,6 +176,12 @@
} }
.footnote-ref { .footnote-ref {
text-decoration: none; text-decoration: none;
padding-left: 2px;
}
.footnote-back {
font-size: small;
text-decoration: none;
padding-left: .5em;
} }
figure { figure {
@ -177,6 +190,7 @@
border: 2px solid #d80669; border: 2px solid #d80669;
border-radius: .5em; border-radius: .5em;
padding: .5em; padding: .5em;
/* Évite que les figures ne soient séparés sur 2 pages */
break-inside: avoid; break-inside: avoid;
} }
figure img { figure img {
@ -193,6 +207,15 @@
content: "Figure " counter(figureNumber) " : "; content: "Figure " counter(figureNumber) " : ";
} }
.exercise {
background-color: #f2f1f1;
width: 90%;
margin: 0 auto;
border: 2px solid #d80669;
border-radius: .5em;
padding: 0 .5em;
}
blockquote { blockquote {
font-style: italic; font-style: italic;
} }
@ -203,4 +226,24 @@
div.csl-entry { div.csl-entry {
padding: .5em; padding: .5em;
} }
table {
width: 90%;
margin: 1em auto;
border-collapse: collapse;
}
th, td {
padding: 5px;
border: 1px solid;
}
table > caption {
counter-increment: tableNumber;
caption-side: bottom;
font-size: small;
padding-top: .5em;
}
table > caption:before {
content: "Table " counter(tableNumber) " : ";
}
} }

10
template.html
View File

@ -26,15 +26,21 @@ $endif$
$for(css)$ $for(css)$
<link rel="stylesheet" href="$css$" /> <link rel="stylesheet" href="$css$" />
$endfor$ $endfor$
<!-- Allow to use -V noscript=true with pandoc
in order to avoid to insert these lines
when they are unnecessary. -->
$if(noscript)$
$else$
<link href="/interface.css" rel="stylesheet" type="text/css" /> <link href="/interface.css" rel="stylesheet" type="text/css" />
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script> <script src="/paged.polyfill.js"></script>
<script src="/reload-in-place.js"></script>
$endif$
$for(header-includes)$ $for(header-includes)$
$header-includes$ $header-includes$
$endfor$ $endfor$
$if(math)$ $if(math)$
$math$ $math$
$endif$ $endif$
</head> </head>
<body> <body>
$for(include-before)$ $for(include-before)$