projet: mise à jour pour le printemps 2025
- Mets à jour la date du document. - Réordonne les fichiers du document. - Améliore la formulation de la section « définitions ». - Mets à jour le déroulé. - Crée un fichier d'exemple de la syntaxe markdown. - Mets à jour la base de donnée des références bibliographiques. - Corrige le Makefile selon le nouvel ordre des fichiers du documents. - Améliore la documentation dans le README, avec des commandes pandoc et/ou pagedjs-cli plus robustes, ainsi que la mention des commandes du Makefile. Co-Authored-by: iGor milhit <igor@milhit.ch>main v0.4.0
parent
f066f2c1d0
commit
8696a63df7
GPG Key ID:
692D97C3D0228A99
|
|
@ -1,3 +1,4 @@
|
|||
document.html
|
||||
document.pdf
|
||||
test.html
|
||||
*.pdf
|
||||
*.zip
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
title: Introduction à la prise de note avec markdown
|
||||
author:
|
||||
- Igor Milhit^[Uni CMU]
|
||||
date: Printemps 2024
|
||||
date: Printemps 2025
|
||||
creation_date: 2023-04-19T11:35:14+02:00
|
||||
id: 20230419113601
|
||||
tags: [note, markdown]
|
||||
|
|
|
|||
|
|
@ -20,6 +20,7 @@
|
|||
[18]: https://joplinapp.org/
|
||||
[19]: https://www.notion.so/
|
||||
[20]: https://obsidian.md/
|
||||
[21]: https://www.tablesgenerator.com/markdown_tables
|
||||
|
||||
[^0]: Cette section repose beaucoup sur la page [Format texte][4] d'Arthur
|
||||
Perret [@perretFormatTexte2022].
|
||||
|
|
|
|||
110
2-definitions.md
110
2-definitions.md
|
|
@ -1,110 +0,0 @@
|
|||
## Définition, avantages et inconvénients[^0] {#first-section}
|
||||
|
||||
:::{.exercise}
|
||||
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*. C'est ce qui
|
||||
permet, par exemple, que la table des matières d'un document numérique soit
|
||||
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.), ou grâce à un langage de balisage
|
||||
comme HTML ou XML. Markdown est une autre méthode, très efficace.[^1]
|
||||
|
||||
Markdown est *un langage de balisage léger*. Il s'agit d'une syntaxe qui
|
||||
permet, *uniquement avec des éléments textuels*, d'indiquer la structure
|
||||
(sections, titres) et la fonction d'éléments textuels (emphase, liste, liens).
|
||||
Cette structure et ces fonctions sont lisibles, compréhensibles par des êtres
|
||||
humains[^4] 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 de
|
||||
l'éditeur de texte. 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][17], de solution de prise de
|
||||
note comme [Joplin][18], [Notion][19] ou [Obsidian][20], ou encore 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].
|
||||
|
|
@ -0,0 +1,105 @@
|
|||
## Définition, avantages et inconvénients[^0] {#first-section}
|
||||
|
||||
:::{.exercise}
|
||||
Le plus important est de trouver des méthodes et des outils
|
||||
adaptés à *vos besoins*. Cette section liste des arguments pour 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*. C'est elle qui
|
||||
permet, par exemple, de cliquer sur les titres d'une table des matières dans un
|
||||
PDF. Cette structure peut s'obtenir grâce aux styles et aux niveaux de titre
|
||||
dans un traitement de texte (Microsoft Word, Libreoffice Writer, etc.), ou
|
||||
grâce à un langage de balisage comme HTML ou XML. Markdown est une autre
|
||||
méthode, très efficace.[^1]
|
||||
|
||||
Markdown est *un langage de balisage léger*. Il s'agit d'une syntaxe qui,
|
||||
*uniquement avec des éléments textuels*, détermine la structure
|
||||
(sections, titres) et la fonction d'éléments textuels (emphase, liste, liens).
|
||||
Cette structure et ces fonctions sont compréhensibles par des êtres
|
||||
humains[^4] 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 simple à apprendre et mémoriser. La rédaction au format
|
||||
markdown repose sur très peu de fonctionnalités de l'éditeur de texte. 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][17], de solution de prise de
|
||||
note comme [Joplin][18], [Notion][19] ou [Obsidian][20], ou encore 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, etc.)
|
||||
- Faciles à sauvegarder, copier, synchroniser, partager.
|
||||
|
||||
Toujours grâce au format texte, il est facile de 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 !
|
||||
|
||||
Ces propriétés permettent :
|
||||
|
||||
- De prendre des notes structurées rapidement.
|
||||
- De disposer d'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 générer un 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 à la gestion de
|
||||
versions (*versioning*), par exemple avec le logiciel
|
||||
[Git][7].
|
||||
|
||||
### Inconvénients
|
||||
|
||||
Pour un usage simple, l'apprentissage n'est pas difficile. La syntaxe de
|
||||
base s'acquiert rapidement. Pour parvenir à rédiger des documents complexes
|
||||
(avec des notes de bas de page, des citations et bibliographies, etc.), cet
|
||||
apprentissage est 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` et une
|
||||
distribution LaTeX pour obtenir une conversion en PDF. Ces outils ne sont pas à
|
||||
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.
|
||||
|
||||
Il est possible d'organiser le travail collaboratir 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].
|
||||
|
|
@ -16,8 +16,7 @@ La syntaxe markdown est très bien documentée sur le web :
|
|||
|
||||
Pour les tableaux, il est fortement conseillé :
|
||||
|
||||
- D'utiliser un générateur, par exemple
|
||||
<https://www.tablesgenerator.com/markdown_tables>.
|
||||
- D'utiliser un générateur comme [Tables Generator][21].
|
||||
- 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`,
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
## Éditeurs {.newpage}
|
||||
## Éditeurs
|
||||
|
||||
Il existe beaucoup d'éditeurs pour rédiger en markdown. On peut les regrouper
|
||||
en deux grandes catégories :
|
||||
|
|
@ -75,6 +75,8 @@ 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.
|
||||
|
||||
![Interface de Visual Studio Code][13]
|
||||
|
||||
Ainsi, il est possible d'adapter à l'édition du markdown les éditeurs de texte
|
||||
suivant, notamment :
|
||||
|
||||
|
|
@ -83,5 +85,3 @@ suivant, notamment :
|
|||
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]
|
||||
|
|
@ -55,7 +55,7 @@ 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
|
||||
### Citations et Bibliographie {.newpage}
|
||||
|
||||
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
|
||||
|
|
@ -1 +0,0 @@
|
|||
## Bibliographie {#bibliography .newpage}
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
## Bibliographie {#bibliography .newpage}
|
||||
|
||||
La bibliographie suivante est constituée à la fois de sources sur lesquelles
|
||||
s'appuie le présent document et de ressources utiles pour aller plus loin avec
|
||||
Markdown ou la génération de document « en mode texte ».
|
||||
12
Makefile
12
Makefile
|
|
@ -1,11 +1,11 @@
|
|||
input_files := \
|
||||
0-frontmatter.md \
|
||||
1.1-licence.md \
|
||||
2-definitions.md \
|
||||
3-syntaxe.md \
|
||||
4-editeurs.md \
|
||||
5-advanced.md \
|
||||
6-bibliographie.md \
|
||||
2-licence.md \
|
||||
3-definitions.md \
|
||||
4-syntaxe.md \
|
||||
5-editeurs.md \
|
||||
6-advanced.md \
|
||||
7-bibliographie.md \
|
||||
100-references.md \
|
||||
|
||||
pandoc := \
|
||||
|
|
|
|||
82
README.md
82
README.md
|
|
@ -47,24 +47,47 @@ les fichiers suivants :
|
|||
|
||||
## Génération du PDF
|
||||
|
||||
Le support de cours (`./document.md`) est rédigé au format markdown, en
|
||||
utilisant des fonctionnalités propres à la version [Pandoc de markdown][5]. La
|
||||
génération du PDF s'appuie sur `pagedjs`, un modèle HTML (`template.html`) et
|
||||
des règles de styles (`styles.css`). Le fichier des règles de style est
|
||||
commenté, ce qui devrait permettre de comprendre son fonctionnement.
|
||||
### Structure du document
|
||||
|
||||
Le support de cours est rédigé au format Markdown. Il est constitué de
|
||||
plusieurs fichiers, pour faciliter leur édition :
|
||||
|
||||
1. `0-frontmatter.md`, qui contient les métadonnées et quelques instructions
|
||||
pour la génération du fichier avec `pandoc`.
|
||||
1. `1-objectifs.md`, pour la page de titre et les objectifs de la présentation.
|
||||
1. `2-licence.md`, pour la licence du document et l'indication des sources.
|
||||
1. `3-definitions.md`.
|
||||
1. `4-syntaxe.md`.
|
||||
1. `5-editeurs.md`.
|
||||
1. `6-advanced.md`.
|
||||
1. `7-bibliographie.md`, pour la bibligraphie.
|
||||
1. `100-references.md`, contient les URL des liens et les notes en bas de page.
|
||||
|
||||
La syntaxe utilise des fonctionnalités propres à la version [Pandoc de
|
||||
markdown][5]. La génération du PDF s'appuie sur `pagedjs`, un modèle HTML
|
||||
(`template.html`) et des règles de styles (`styles.css`). Le fichier des règles
|
||||
de style est commenté, ce qui devrait permettre de comprendre son
|
||||
fonctionnement.
|
||||
|
||||
### Prévisualisation dans le navigateur
|
||||
|
||||
Pour générer le fichier HTML à servir par un serveur web pour le visualiser
|
||||
dans le navigateur, il faut utiliser `pandoc` avec les paramètres suivants (à
|
||||
adapter au fichier à générer) :
|
||||
|
||||
```bash
|
||||
pandoc --to=html \
|
||||
pandoc --embed-resources=true --to=html \
|
||||
--template=template.html --css=style.css \
|
||||
--toc --toc-depth=2 --citeproc \
|
||||
--output=document.html document.md
|
||||
--output=document.html \
|
||||
0-frontmatter.md 1-objectifs.md 2-licence.md \
|
||||
3-definitions.md 4-syntaxe.md 5-editeurs.md \
|
||||
6-advanced.md 7-bibliographie.md 100-references.md
|
||||
```
|
||||
|
||||
- `--to=html` pour convertir vers du HTML.
|
||||
- `--embed-resources=true` assure que toutes les dépendances externes sont bien
|
||||
intégrées dans le fichier généré.
|
||||
- `--template=` et `--css=` indiquent quel modèle et feuille de style
|
||||
utiliser.
|
||||
- `--toc` et `--toc-depth=2` génèrent la table des matière en n'allant pas plus
|
||||
|
|
@ -80,40 +103,63 @@ du projet, par exemple avec `python` :
|
|||
python -m http.server
|
||||
```
|
||||
|
||||
Puis, ouvrir un navigateur web Chromium (ou Chrome) à l'URL
|
||||
<http://localhost:8000>. Pour l'impression, il est conseillé d'utiliser
|
||||
Chromium (ou Chrome). En effet, Firefox supporte un peu moins bien `pagedjs`,
|
||||
notamment pour l'impression en PDF. Pour éviter la coloration des liens déjà
|
||||
visités, la fonction « navigation privée » est bien utile.
|
||||
Puis, ouvrir un navigateur web à l'URL <http://localhost:8000>. Pour
|
||||
l'impression, il est conseillé d'utiliser Chromium (ou Chrome). En effet,
|
||||
Firefox supporte un peu moins bien `pagedjs`, notamment pour l'impression en
|
||||
PDF. Pour éviter la coloration des liens déjà visités, la fonction « navigation
|
||||
privée » est bien utile.
|
||||
|
||||
Cet affichage permet d'inspecter les règles CSS et de les modifier à la volée
|
||||
pour comprendre comment améliorer le rendu, et d'imprimer la page web au format
|
||||
PDF (`ctrl+p`).
|
||||
|
||||
### Génération du PDF
|
||||
|
||||
Pour générer directement le PDF, deux possibilités s'ouvrent à vous, avec des
|
||||
résultats différents. Soit en utilisant `pagedjs` directement avec `pandoc` :
|
||||
|
||||
```bash
|
||||
pandoc --citeproc \
|
||||
pandoc --embed-resources=true -V noscript=true \
|
||||
--citeproc \
|
||||
--to=pdf --pdf-engine=pagedjs-cli \
|
||||
--template=template.html --css=style.css \
|
||||
--toc --toc-depth=2 \
|
||||
--output=document.pdf document.md
|
||||
--output=document.pdf \
|
||||
0-frontmatter.md 1-objectifs.md 2-licence.md \
|
||||
3-definitions.md 4-syntaxe.md 5-editeurs.md \
|
||||
6-advanced.md 7-bibliographie.md 100-references.md
|
||||
```
|
||||
|
||||
Soit en utilisant `pagedjs` pour convertir le fichier HTML obtenu par pandoc
|
||||
- `-V noscript=true`. `-V` permet d'ajouter des variables. La variable
|
||||
`noscript` vient du `template.html` et permet d'éviter d'ajouter les scripts
|
||||
utilisé pour la prévisualisation dans le navigateur.
|
||||
|
||||
Soit en utilisant `pagedjs` pour convertir le fichier HTML obtenu par `pandoc`
|
||||
plus haut :
|
||||
|
||||
```bash
|
||||
pandoc --to=html \
|
||||
pandoc --to=html -V noscript=true \
|
||||
--template=template.html --css=style.css \
|
||||
--toc --toc-depth=2 --citeproc \
|
||||
--output=document.html document.md \
|
||||
--output=document.html \
|
||||
0-frontmatter.md 1-objectifs.md 2-licence.md \
|
||||
3-definitions.md 4-syntaxe.md 5-editeurs.md \
|
||||
6-advanced.md 7-bibliographie.md 100-references.md \
|
||||
&& pagedjs-cli document.html \
|
||||
--css=../style.css \
|
||||
--style=style.css \
|
||||
-o document.pdf
|
||||
```
|
||||
|
||||
## Commandes
|
||||
|
||||
Si `make` est disponible sur votre système, vous pouvez :
|
||||
|
||||
- `make html` : génère le HTML.
|
||||
- `make pdf` : génère le PDF.
|
||||
- `make watch_html` : génère le HTML et relance la commande si des fichiers
|
||||
sont modifiés (utilise `watchexe` qui doit aussi être installé).
|
||||
- `make serve` : lance le serveur web python.
|
||||
|
||||
<!-- références -->
|
||||
|
||||
[1]: ./
|
||||
|
|
|
|||
16
déroulé.md
16
déroulé.md
|
|
@ -8,8 +8,6 @@ tags: [rdv-info, déroulé, markdown]
|
|||
## Checklist
|
||||
|
||||
- [ ] Polycopié généré et prêt au partage et ouvert pour s'y référer.
|
||||
- [ ] URL du formulaire de feedback prête à être copiée-collée. \
|
||||
<https://formulaire.unige.ch/outils/limesurvey3/index.php/926275?lang=fr>
|
||||
- [ ] Éditeur ouvert avec un exemple de fichier markdown.
|
||||
- [ ] Navigateur de fichier ouvert sur l'ensemble de notes et dans le dossier
|
||||
`~/tmp/intro-md/`.
|
||||
|
|
@ -33,6 +31,8 @@ tags: [rdv-info, déroulé, markdown]
|
|||
|
||||
## Présentation
|
||||
|
||||
### Introduction
|
||||
|
||||
- Ouvrir l'éditeur avec le fichier d'exemple.
|
||||
- Montrer que ce n'est que du texte = format texte.
|
||||
- Montrer le rendu et la structure.
|
||||
|
|
@ -56,6 +56,9 @@ tags: [rdv-info, déroulé, markdown]
|
|||
- Notes structurées, recherche textuelle efficace.
|
||||
- Adapté pour documents simples (notes) ET pour documents complexes (thèse).
|
||||
- Constitution d'une base de connaissance.
|
||||
|
||||
### Syntaxe
|
||||
|
||||
- Détail de la syntaxe depuis l'éditeur.
|
||||
- Documentation en lien dans le support de cours (page 4).
|
||||
- Générateur de tableau en ligne.
|
||||
|
|
@ -65,6 +68,9 @@ tags: [rdv-info, déroulé, markdown]
|
|||
- Italiques et gras.
|
||||
- Liens. Sans et avec référence.
|
||||
- Image.
|
||||
|
||||
### Éditeurs
|
||||
|
||||
- Fonctionnalités utiles :
|
||||
- Prévisualisation.
|
||||
- Autocomplétion de la syntaxe.
|
||||
|
|
@ -74,6 +80,9 @@ tags: [rdv-info, déroulé, markdown]
|
|||
- Formatage automatique des tableaux.
|
||||
- Suivi des liens internes, entre fichiers.
|
||||
- Raccourcis pour accéder à la syntaxe.
|
||||
|
||||
### Usages avancés
|
||||
|
||||
- Usages avancés :
|
||||
- Démo avec Visual Code. Ouvrir le dossier `~/bc/`.
|
||||
- Ouvrir README, suivre un lien.
|
||||
|
|
@ -94,7 +103,4 @@ tags: [rdv-info, déroulé, markdown]
|
|||
|
||||
## Après la présentation
|
||||
|
||||
- Partager le lien pour le formulaire de feedback : \
|
||||
<https://formulaire.unige.ch/outils/limesurvey3/index.php/664325?&lang=fr>.
|
||||
- Mentionner la possibilité d'ateliers pour aller plus loin.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,115 @@
|
|||
# Exemple de note
|
||||
|
||||
Pour écrire un paragraphe, il faut séparer deux blocs de texte par une ligne vide. Un simple retour à la ligne
|
||||
ne change rien.
|
||||
|
||||
Ici commence le paragraphe suivant. Dans celui-ci, on peut insérer *un texte en italique*, soit en entourant la partie en *italique* par des astérisques (`*`), soit au moyen _d'underscore_ (`_`).
|
||||
|
||||
Pour le gras, **on utilise un double astérisque**, ou __un double underscore__.
|
||||
|
||||
## Les listes
|
||||
|
||||
Pour générer une liste, on commence chaque ligne de la liste avec un tiret :
|
||||
|
||||
```markdown
|
||||
- Une liste
|
||||
- Simple et
|
||||
- Non ordonnée.
|
||||
```
|
||||
|
||||
- Une liste
|
||||
- Simple et
|
||||
- Non ordonnée.
|
||||
|
||||
Pour une liste ordonnée, on commence chaque ligne par un chiffre suivit d'un point :
|
||||
|
||||
```markdown
|
||||
1. Une liste
|
||||
3. Simple mais
|
||||
9. Ordonnée.
|
||||
```
|
||||
|
||||
1. Une liste
|
||||
3. Simple mais
|
||||
9. Ordonnée.
|
||||
|
||||
L'ordre de la numérotation n'importe pas. Pour ne pas s'ennuyer à réordonner une liste qui peut évoluer, il y a une solution simple :
|
||||
|
||||
```markdown
|
||||
1. Pomme.
|
||||
1. Poire.
|
||||
1. Cerise.
|
||||
```
|
||||
|
||||
1. Pomme.
|
||||
1. Poire.
|
||||
1. Cerise.
|
||||
|
||||
Des listes imbriquées plus complexes peuvent être réalisées en ajoutant des espaces devant les lignes des sections inférieures :
|
||||
|
||||
```markdown
|
||||
1. Une liste
|
||||
1. Ordonnée et
|
||||
- Plus
|
||||
- Complexe
|
||||
1. Voilà.
|
||||
```
|
||||
|
||||
1. Une liste
|
||||
1. Ordonnée et
|
||||
- Plus
|
||||
- Complexe
|
||||
1. Voilà.
|
||||
|
||||
## Les liens
|
||||
|
||||
### La méthode simple
|
||||
|
||||
Il y a plusieurs méthodes pour insérer un lien. La plus simple est de mettre le texte du lien entre crochets, suivi de la cible entre parenthèses :
|
||||
|
||||
```markdown
|
||||
[site de l'UNIGE](https://unige.ch)
|
||||
```
|
||||
|
||||
Ce qui donne le lien suivant : [site de l'UNIGE](https://unige.ch).
|
||||
|
||||
On peut vouloir ajouter un titre à ce lien, qui s'affiche lorsque le curseur survol le lien :
|
||||
|
||||
```markdown
|
||||
[site de l'UNIGE](https://unige.ch "site officiel d'UNIGE")
|
||||
```
|
||||
|
||||
Ce qui donne le lien suivant :
|
||||
[site de l'UNIGE](https://unige.ch "site officiel d'UNIGE").
|
||||
|
||||
### Avec les références
|
||||
|
||||
Une autre méthode existe qui a les avantages suivants :
|
||||
|
||||
- Une même référence (cible du lien) peut être réutilisée plusieurs fois dans le même texte.
|
||||
- La lisibilité du texte est améliorée.
|
||||
|
||||
Le texte du lien est toujours entre crochet, mais à la place de la cible entre parenthèse, on ajoute une référence entre crochet. Cette référence, qui peut être un chiffre, une lettre ou un texte, correspond à la cible, définie n'importe où dans le fichier.
|
||||
|
||||
```markdown
|
||||
[site de l'UNIGE][1]
|
||||
|
||||
[1]: https://unige.ch "site officiel de l'UNIGE"
|
||||
```
|
||||
|
||||
Ce qui donne le lien suivant : [site de l'UNIGE][1].
|
||||
|
||||
## Images (fichiers)
|
||||
|
||||
Pour l'insertion d'une image, on reprend la même syntaxe que pour le lien, en ajoutant un point d'exclamation au début de la ligne :
|
||||
|
||||
|
||||
|
||||
Le lien pour l'image peut être une URL ou un chemin vers un fichier local. Et la syntaxe avec la référence est possible aussi :
|
||||
|
||||
![Légende de l'image][2]
|
||||
|
||||
|
||||
|
||||
[1]: https://unige.ch "site officiel de l'UNIGE"
|
||||
[2]: ./static/logo-md.svg
|
||||
|
|
@ -6,7 +6,7 @@
|
|||
{"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":"ovadiaMarkdownLibrariansAcademics2014","accessed":{"date-parts":[["2023",5,2]]},"author":[{"family":"Ovadia","given":"Steven"}],"citation-key":"ovadiaMarkdownLibrariansAcademics2014","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"]]},"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"},
|
||||
|
|
|
|||
Loading…
Reference in New Issue