Démarrage en Markdown

Ce texte est principalement inspiré du travail d’Arthur Turrell et de son cours sur Quarto pour les économistes .

Introduction

Markdown est un langage de balisage léger développé par John Gruber et Aaron Swartz1.

1 Aaron Swartz: hacktiviste (1986-2013) qui a également contribué à développer les licences Creative Commons, RSS, Reddit, etc. Pour en savoir plus sur sa vie épique, voir le documentaire de Brian Knappenberger The Internet’s Own Boy: The Story of Aaron Swartz (2014)

Markdown est donc un langage de balisage facile à lire, populaire pour la mise en forme de texte simple, la création de documentation pour des projets logiciels, mais aussi pour l’écriture de jolis e-mails (pour Thunderbird ou tout navigateur, etc.).

L’extension pour un fichier Markdown est .md. Pour rendre un tel fichier dans VSCode ou Codium, et éventuellement exporter un fichier .pdf ou .html, vous devez installer un package pour cela (par exemple, Markdown All in One peut être installé avec Ctrl+Shift+p, et en recherchant le bon nom dans Extensions: Install Extensions).

Gauche : Code Markdown

# Titre de niveau 1

## Titre de niveau 2

# Un autre titre de niveau 1

## Un autre titre de niveau 2

Ceci serait un paragraphe. Vous pouvez utiliser **une police en gras** mais aussi *en italique* ou ~~barrée~~.

D'autres éléments sont listés ci-dessous :

- élément 1
- élément 2
  - sous-élément 1
  - sous-élément 2

Droite : rendu

Titre de niveau 1

Titre de niveau 2

Un autre titre de niveau 1

Un autre titre de niveau 2

Ceci serait un paragraphe. Vous pouvez utiliser une police en gras mais aussi en italique ou barrée.

D’autres éléments sont listés ici :

  • élément 1
  • élément 2
    • sous-élément 1
    • sous-élément 2

Une description complète peut être trouvée ici : https://www.markdownguide.org/basic-syntax/; un aide-mémoire pratique est également disponible ici : https://www.markdownguide.org/cheat-sheet/.

Pourquoi utiliser Markdown ?

Il existe de nombreuses situations où vous souhaiterez utiliser markdown :

  • pour créer des sites web, des rapports, des présentations
  • en tant que format de base que des outils comme Pandoc et Quarto peuvent convertir en d’autres types de documents
  • dans les cellules de texte des Jupyter Notebooks
  • dans des emails.
  • pour écrire … ce cours!

Certains des avantages de markdown sont :

  • Les fichiers markdown s’ouverent avec n’importe quel éditeur de texte brut
  • Markdown est indépendant du système d’exploitation
  • Markdown est très lisible, même lorsqu’il n’est pas rendu
  • De nombreux sites web prennent en charge la syntaxe markdown, par exemple GitHub et Reddit.

La syntaxe Markdown

Titres

Passons en revue les bases de Markdown. Par exemple, un seul dièse (#) désigne le titre d’un document, comme ceci :

# Titre

Le niveau de sous-titre suivant peut être spécifié par deux dièses, comme ceci :

## Sous-titre

Chaque niveau de titre suivant devient successivement plus petit, par exemple :

### Embranchement

#### Classe

##### Ordre

###### Famille

devient

Embranchement

Classe

Ordre
Famille

Syntaxe en ligne

Voici quelques autres fonctionnalités de syntaxe courantes dont vous aurez besoin :

  • pour créer du texte en italique, utilisez *un astérisque de chaque côté du texte*
  • le texte en gras est produit à partir de **deux astérisques**
  • le texte en gras et en italique est ***trois astérisques***
  • les liens sont produits avec des crochets pour le texte et des parenthèses pour le lien hypertexte, comme ceci [texte](lien)
  • le code en ligne est affiché à l’aide d’accents graves, comme ceci `code`
  • ~~barré~~ ressemble à ceci barré
  • ^(exposant) crée ^(exposant)
  • Les mathématiques sont prises en charge en ligne via des signes dollar encadrants, par exemple $\int_{-\infty}^{+\infty} e^{-x^2/2}dx = \sqrt{2\pi}$, qui s’affiche comme \int_{-\infty}^{+\infty} e^{-x^2/2}dx = \sqrt{2\pi}.
  • Unicode est pris en charge, vous pouvez donc écrire des symboles comme ∰, ainsi que des émojis ; la syntaxe comme :tada: crée 🎉 (mais il faut rajouter from: markdown+emoji dans le préambule pour que cela fonctionne).

Syntaxe de bloc de texte

Les citations peuvent être réalisées en ajoutant une flèche, >, à chaque ligne :

Voici une citation !

Les listes non ordonnées peuvent être produites avec soit - soit * sur des lignes séparées, de sorte que

- premier élément
- deuxième élément
- troisième élément

devient

  • premier élément
  • deuxième élément
  • troisième élément

Les listes ordonnées peuvent être créées en écrivant simplement des numéros successifs sur des lignes successives :

1. premier élément
2. deuxième élément
3. troisième élément

devient

  1. premier élément
  2. deuxième élément
  3. troisième élément

Les deux types de listes peuvent être sous-ensembles, de sorte que

- premier élément
  - sous-élément
    - sous-sous-élément
- deuxième élément

devient

  • premier élément
    • sous-élément
      • sous-sous-élément
  • deuxième élément

Tableaux

La syntaxe de base pour créer des tableaux est

| Film                  | Année         | Durée (min) |
|-----------------------|---------------|-------------|
| Dr Strangelove        | 1964          | 94          |
| 2001: A Space Odyssey | 1968          | 139         |
| A Clockwork Orange    | 1971          | 136         |
| Barry Lyndon          | 1975          | 185         |

qui devient

Film Année Durée (min)
Dr Strangelove 1964 94
2001: A Space Odyssey 1968 139
A Clockwork Orange 1971 136
Barry Lyndon 1975 185

Vous ne voudrez (presque) jamais écrire de tels tableaux vous-même ! En pratique, il est plus facile d’exporter un fichier markdown à partir d’un dataframe pandas (sous Python) en utilisant df.to_markdown() ou d’utiliser le site web suivant: générateur de tableaux markdown.

Images

Pour insérer des images, utilisez la structure ![texte alternatif](url ou chemin de fichier), par exemple :

![Image à insérer](https://raw.githubusercontent.com/josephsalmon/Tweets/61c3110a15a9dbcaac1698ffe11521b028c4524a/IslamicArt/svg/Sultan_Uljaytu_Frontispiece_colored.svg){width=60%}

Cela produit alors l’affichage suivant:

Image à insérer

Vous pouvez également produire des listes de tâches, par exemple :

- [x] Faire le TP 1
- [x] Faire le TP 2
- [ ] Créer un premier document markdown :rocket:

produit :

Des notes de bas de page peuvent être créées en utilisant [^1] suivi de [^2], et ainsi de suite, ou en utilisant des notes de bas de page liées au contenu comme [^note]. Voici un exemple2, et un autre3, tandis que le troisième se trouve ici4 et a une étiquette à la place d’un numéro (que vous ne pouvez pas voir lorsqu’elle est rendue). La syntaxe pour remplir leurs informations est :

2 Première note de bas de page.

3 Chaque nouvelle ligne dans une note de bas de page doit être préfixée par 2 espaces. Cela vous permet d’avoir une note de bas de page avec plusieurs lignes.

4 Les notes de bas de page nommées s’afficheront toujours avec des numéros au lieu du texte, mais permettent une identification et une liaison plus faciles.

[^2]: Première note de bas de page.
[^3]: Chaque nouvelle ligne dans une note de bas de page doit être préfixée par 2 espaces.
  Cela vous permet d'avoir une note de bas de page avec plusieurs lignes.
[^note]: Les notes de bas de page nommées s'afficheront toujours avec des numéros au lieu du texte, mais permettent une identification et une liaison plus faciles.

Enfin, pour insérer un saut de ligne, utilisez :

***

Pour produire :

Retour au sommet