Aller au contenu

Les bases de rédaction en Markdown

Ressources

Compte-tenu de la popularité du Markdown, inutile de réinventer la roue, autant pointer vers les bonnes ressources déjà disponibles en ligne :

La syntaxe

Le markdown est une syntaxe extensible et son rendu dépend de l'outil utilisé pour l'implémenter. Il existe donc des différences entre le rendu :

  • dans l'onglet Preview de [GitHub],
  • celui dans un éditeur [Visual Studio Code]
  • celui de l'outil utilisé pour le rendu final MkDocs / Material.

C'est ce dernier qui fait foi.

Tip

Pour comprendre comment fonctionne le rendu des contenus, consulter l'article dédié.

Bien démarrer

Aller plus loin

Editeurs

N'importe quel éditeur de texte "plat" suffit pour rédiger en Markdown.

Bureautique

En ligne

Tip

Le choix du Markdown pour Geotribu a été détaillé dans l'article Du HTML au Markdown (et vice-versa). Il contient quelques éléments de compréhension sur la syntaxe et un petit TP pour s'exercer.

Prochaine étape : respecter et valider la syntaxe


Spécimen

En plus des ressources, à suivre quelques exemples de base.

Titres et paragraphes

1
2
3
4
5
6
7
# Titre de niveau 1

Le titre de niveau 1 est le titre principal. Il doit être unique.

## De l'importance des sauts de ligne

En Markdown, les sauts de ligne font foi. Avant d'entamer le paragraphe, il faut sauter une ligne. De même entre deux paragraphes, il faut laisser une ligne vide.

Titre de niveau 1

Le titre de niveau 1 est le titre principal. Il doit être unique.

De l'importance des sauts de ligne

En Markdown, les sauts de ligne font foi. Avant d'entamer le paragraphe, il faut sauter une ligne. De même entre deux paragraphes, il faut laisser une ligne vide.

Format

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Pour mettre en forme le texte, c'est facile. Il s'agit surtout de se souvenir que les retours à ligne et les retraits font loi dans la syntaxe.

Mettre un texte en italique avec une *astérisque*
ou un _underscores (autrement appelés tiret du 8)_ de chaque côté.

Mettre un texte en gras avec deux **astérisques**
ou deux __underscores (autrement appelés tiret du 8)__ de chaque côté.

Barrer un texte avec deux ~~tildes~~ de chaque côté.

Combiner les différents styles est possible. Ainsi on peut obtenir un texte en italique, un texte en italique et gras, un texte en italique et barré avec : un _underscore, **deux astérisques** et ~~deux tildes~~_.

Pour mettre en forme le texte, c'est facile. Il s'agit surtout de se souvenir que les retours à ligne et les retraits font loi dans la syntaxe.

Mettre un texte en italique avec une astérisque ou un underscores (autrement appelés tiret du 8) de chaque côté.

Mettre un texte en gras avec deux astérisques ou deux underscores (autrement appelés tiret du 8) de chaque côté.

Barrer un texte avec deux tildes de chaque côté.

Combiner les différents styles est possible. Ainsi on peut obtenir un texte en italique, un texte en italique et gras, un texte en italique et barré avec : un underscore, deux astérisques et deux tildes.

Listes à puces

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
Liste numérotée à plusieurs niveaux :

1. premier élément de la liste
2. deuxième élément de la liste
    1. indenter avec 4 espaces avant le chiffre permet de faire des sous-listes imbriquées
    2. deuxième élément de second niveau
3. troisième élément de la liste de 1er niveau qui contient une sous-liste non ordonnée :
    * hip,
    * hop,

Ou sans numéros :

* on peut créer des puces avec différents caractères :
    * astérisque,
    - tiret
    + signe plus (\+)
* mais, pour éviter les effets de bord (espacement de paragraphe, mauvais niveau de retrait...) et selon les règles établies, il est préférable de rester cohérent dans le caractère utilisé, au moins dans un même document
* en général, on utilise l'astérisque ou alors le tiret.

Liste numérotée à plusieurs niveaux :

  1. premier élément de la liste
  2. deuxième élément de la liste
    1. indenter avec 4 espaces avant le chiffre permet de faire des sous-listes imbriquées
    2. deuxième élément de second niveau
  3. troisième élément de la liste de 1er niveau qui contient une sous-liste non ordonnée :
    • hip,
    • hop,

Ou sans numéros :

  • on peut créer des puces avec différents caractères :
    • astérisque,
    • tiret
    • signe plus (+)
  • mais, pour éviter les effets de bord (espacement de paragraphe, mauvais niveau de retrait...) et selon les règles établies, il est préférable de rester cohérent dans le caractère utilisé, au moins dans un même document
  • en général, on utilise l'astérisque ou alors le tiret.

Prochaine étape : respecter et valider la syntaxe


Dernière mise à jour: 14 septembre 2020
Contributions à cette page : Julien Moura

Commentaires