Les bases de Markdown#

Information

  • Auteurs : Philippe Dessus, Inspé & LaRAC, Univ. Grenoble Alpes.

  • Date de création : Avril 2022.

  • Résumé : Ce document donne les principaux éléments de la syntaxe Markdown, utilisée par l’extension Sphinx MyST (pour Markedly Structured Text).

  • Voir aussi : Le Document :ref: syntaxe_sphinx peut être lu ensuite.

Informations supplémentaires

  • Date de modification : 28 mars 2023.

  • Durée de lecture : 2 minutes.

  • Statut du document : en travaux.

  • Note : Ces ressources constituent l’un des kits de pérennisation du projet ANR-Idéfi ReFlexPro et a bénéficié de son financement. Il concerne plus précisément l’action A20 (WP 1) du projet, pilotée par Philippe Dessus, assisté d’Émilie Besse.

  • Citation : Pour citer ce document : Auteur·s (Date_de_création_ou_de_révision). Titre_du_document. Grenoble : Univ. Grenoble Alpes, Inspé, base de cours en sciences de l’éducation, accédé le date_d_accès, URL_du_document.

  • Licence : Document placé sous licence Creative Commons : BY-NC-SA.

Introduction#

La syntaxe Markdown est maintenant très connue car utilisée dans la plupart des wikis et de nombreux outils de prise de note. Mais il en existe de nombreuses versions (mySt supporte CommonMark Markdown), et le plus simple est de référer au document qui spécifie la syntaxe. Ce tutoriel permet d’en comprendre les principales règles. Nous ne traiterons ici que des principales balises.

Si l’on part d’un ensemble de documents Sphinx écrits en reStructuredText, il existe un utilitaire, rst-to-myst qui convertit automatiquement l’ensemble d’un répertoire reST en markdown. Une fois installé, il suffit d’aller dans le répertoire à convertir et de taper dans le terminal rst2myst convert *.rst pour réaliser la conversion, de très bonne qualité.

Paragraphes#

Un paragraphe est séparé de 2 sauts de paragraphes.

Gras et italiques#

Un passage ou un mot en italiques est encadré par des astérisques simples ; le gras est rendu par des doubles astérisques : un mot en \*italiques\* italiques, en \*\*gras\*\*.

Listes#

  • Les énumérations sont classiquement rendues par des numéros suivis d’un point et d’une espace en début de ligne 1. , suivis d’un seul saut de paragraphe.

  • Les listes sont rendues par des astérisques ou tirets en début de ligne (ces deux lignes sont rendues en liste).

Code#

Des éléments de code insérés dans une ligne sont rendus par des guillemets obliques `code`. Du code écrit dans un bloc de paragraphe est, soit indenté de 4 espaces, soit 3 guillemets obliques encadrent le paragraphe avant et après.

```

Bloc de code ```

Gestion des références bibliographiques#

Contrairement à reST, il devient difficile de gérer, avec Markdown, des fichiers bibliographiques propres à chaque document. L’ensemble des références doit être mis dans un fichier unique par dépôt, référencé dans le conf.py ainsi : bibtex_bibfiles = ['refs.bib']