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 :

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 suffit pour rédiger en Markdown. Ci-dessous, voici une liste très loin d'être exhaustive d'outils permettant de 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#

# 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.

Mise en forme#

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#

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

  1. étape où un contributeur propose d'intégrer ses modifications dans le socle principal du projet. Voir la documentation de GitHub. ↩

Commentaires