Les Bases de Markdown

Introduction

Ce guide propose une introduction complète aux bases de Markdown dans Quarto, incluant une gamme d’options de formatage et de fonctionnalités avancées pour améliorer vos projets de documentation.

Voici ce que vous apprendrez:

  • Formatage du texte : Apprenez à appliquer des styles de texte essentiels comme le gras, l’italique et les en-têtes pour structurer efficacement votre document.
  • Créer des listes : Comprendre comment organiser clairement les informations à l’aide de listes ordonnées et non ordonnées.
  • Construire des tableaux : Acquérir le savoir-faire nécessaire pour assembler des tableaux lisibles qui améliorent la présentation des données.
  • Incorporer des médias : Découvrez comment intégrer des images, des diagrammes et des vidéos pour rendre votre contenu plus attrayant.
  • Améliorer la navigation : Utilisez des références croisées pour relier les différentes parties de vos documents de manière transparente, améliorant ainsi l’expérience de navigation du lecteur.

Ce guide vous permet de disposer de tous les outils nécessaires pour améliorer votre documentation, la rendre accessible et la mettre en forme de manière professionnelle. Que vous compiliez un rapport technique, du matériel pédagogique ou toute autre documentation importante, la maîtrise de ces bases de Markdown améliorera significativement votre capacité à présenter des informations de manière claire et interactive.



Titres

Markdown supporte six niveaux de titres, # représentant le niveau le plus élevé (Titre 1) et ###### le niveau le plus bas (Titre 6).

Syntaxe:

# En-tête 1
## En-tête 2
### En-tête 3
#### En-tête 4
##### En-tête 5
###### En-tête 6

Sortie:

En-tête 1

En-tête 2

En-tête 3

En-tête 4

En-tête 5
En-tête 6

Formatage du texte

Syntaxe:

- *italics*, **bold**, ***bold italics***
- superscript^2^ / subscript~2~
- ~~strikethrough~~
- `verbatim code`

Sortie:

  • italics, bold, bold italics
  • superscript2 / subscript2
  • strikethrough
  • verbatim code

Listes

Syntaxe:

* liste non ordonnée
    + sous-élément 1
    + sous-élément 2
        - sous-sous-élément 1

Sortie:

  • liste non ordonnée
    • sous-élément 1
    • sous-élément 2
      • sous-sous-élément 1

Syntaxe:

*   élément 2
        
    Suite (retrait de 4 espaces)

Sortie:

  • élément 2

    Suite (retrait de 4 espaces)

Syntaxe:

1. liste ordonnée
2. élément 2
    i) sous-élément 1
         A.  sous-sous-élément 1

Sortie:

  1. liste ordonnée
  2. élément 2
    1. sous-élément 1
      1. sous-sous-élément 1

Syntaxe:

(@)  Une liste dont la numérotation
                   
continue après
                 
(@)  une interruption

Sortie:

  1. Une liste dont la numérotation

continue après

  1. une interruption

Syntaxe:

::: {}
1. Liste A
:::
::: {}
1. Suivi d'une autre liste
:::

Sortie:

  1. Liste A
  1. Suivi d’une autre liste

Syntaxe:

terme
: définition

Sortie:

terme
définition

Notez que contrairement à d’autres moteurs de rendu Markdown (notamment Jupyter et GitHub), les listes dans Quarto nécessitent une ligne blanche entière au-dessus de la liste. Dans le cas contraire, la liste ne sera pas affichée sous forme de liste, mais apparaîtra comme du texte normal sur une seule ligne.

Tableaux

Code Markdown

| droite | Gauche | Défaut | Centre |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Sortie

droite Gauche Défaut Centre
12 12 12 12
123 123 123 123
1 1 1 1

Diagrammes

Dans Quarto, les diagrammes Mermaid et Graphviz sont pris en charge en mode natif.

Éditeurs en direct pour améliorer votre productivité lors de la création de diagrammes:

  1. Le [Mermaid Live Editor] (https://mermaid.live/) est un outil en ligne qui permet d’éditer et de prévisualiser les diagrammes Mermaid en temps réel.
  2. [Graphviz Online] (https://dreampuf.github.io/GraphvizOnline/) fournit un outil similaire pour éditer les diagrammes Graphviz.

Créer un organigramme avec Mermaid:

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

Un simple graphe non orienté créé à l’aide de graphviz:

```{dot}
graph G {
  layout=neato
  run -- intr;
  intr -- runbl;
  runbl -- run;
  run -- kernel;
  kernel -- zombie;
  kernel -- sleep;
  kernel -- runmem;
  sleep -- swap;
  swap -- runswap;
  runswap -- new;
  runswap -- runmem;
  new -- runmem;
  sleep -- runmem;
}
```

G run run intr intr run--intr kernel kernel run--kernel runbl runbl intr--runbl runbl--run zombie zombie kernel--zombie sleep sleep kernel--sleep runmem runmem kernel--runmem sleep--runmem swap swap sleep--swap runswap runswap swap--runswap runswap--runmem new new runswap--new new--runmem

En savoir plus sur diagrammes dans Quarto.

Vidéos

Inclure une vidéo de YouTube:

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

Exemples supplémentaires démontrant l’utilisation de diverses sources et options vidéo:

{{< video local-video.mp4 >}}

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

{{< video https://youtu.be/wo9vZccmqwc width="400" height="300" >}}

{{< video https://www.youtube.com/embed/wo9vZccmqwc
    title="What is the CERN?"
    start="116"
    aspect-ratio="21x9" 
>}}

En savoir plus sur videos dans Quarto.

Sauts de page

Insérer un saut de page avec le shortcode pagebreak:

page 1

{{< pagebreak >}}

page 2

Les sauts de page natifs sont pris en charge pour HTML, LaTeX, Context, MS Word, Open Document et ePub.

Blocs de notices

Code Markdown

:::{.callout-note}
Notez qu'il existe cinq types de notices, incluant: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Sortie

Note

Notez qu’il existe cinq types de notices, incluant note, tip, warning, caution, and important.

Astuce

Ceci est un conseil.

Avertissement

Ceci est un avertissement.

Mise en garde

Ceci est une mise en garde.

Important

Ceci est important.

Annotations du code

Les annotations des cellules de code impliquent:

  1. Terminer chaque ligne annotée par un commentaire et un numéro d’annotation entre crochets (comme # <2>). Utiliser le même nombre pour étendre une annotation sur plusieurs lignes.
  2. Ajout d’une liste ordonnée juste après la cellule de code, où chaque élément correspond à un numéro d’annotation dans le code.

Syntaxe:

```r
x <- 1:10  # <1>
y <- x^2   # <2>
z <- x^3   # <2>
```
1. Créer un vecteur `x`, puis,
2. calculer `y` and `z`

Sortie:

1x <- 1:10
2y <- x^2
z <- x^3
1
Créer un vecteur x, puis,
2
calculer y and z

Les positions d’annotation possibles pour la sortie HTML sont les suivantes:

  • below (par défaut) : Les annotations apparaissent par défaut sous la cellule de code.
  • hover: Les annotations s’affichent au passage de la souris sur un marqueur de ligne.
  • select: Les annotations apparaissent lorsqu’on clique sur un marqueur et peuvent être supprimées en cliquant à nouveau.

Pour changer la position par défaut des annotations, utilisez le champ de métadonnées code-annotations dans l’en-tête du document:

---
code-annotations: hover
---

Références

Les bases du Markdown dans Quarto