{"id":240,"date":"2023-04-08T18:02:29","date_gmt":"2023-04-08T16:02:29","guid":{"rendered":"https:\/\/e-publish.uliege.be\/md\/?post_type=chapter&p=240"},"modified":"2025-06-15T08:47:44","modified_gmt":"2025-06-15T06:47:44","slug":"markdown","status":"publish","type":"chapter","link":"https:\/\/e-publish.uliege.be\/md\/chapter\/markdown\/","title":{"raw":"Markdown","rendered":"Markdown"},"content":{"raw":"

Historique<\/h1>\r\nMarkdown<\/em> est donc un langage de balisage l\u00e9ger. Il a \u00e9t\u00e9 co-cr\u00e9\u00e9 par Aaron Swartz et John Gruber en 2004[footnote]http:\/\/www.aaronsw.com\/weblog\/001189<\/a>[\/footnote]\u00a0afin de g\u00e9n\u00e9rer facilement du code HTML pour le web. Markdown<\/em> est pr\u00e9vu pour \u00eatre facile \u00e0 lire et facile \u00e0 \u00e9crire (Mpondo-Dicka, 2020<\/a>). Comme les commandes Markdown<\/em> sont assez simples, on peut les ma\u00eetriser en dix minutes (Ball, 2018<\/a>).\r\n\r\nDepuis sa cr\u00e9ation, il a \u00e9t\u00e9 \u00e9tendu pour \u00eatre utilis\u00e9 pour produire d\u2019autres types de documents dont le pdf<\/em> qui n\u2019est pas vraiment un format ouvert mais qui est le plus utilis\u00e9 actuellement. L\u2019utilisation de Pandoc<\/em>[footnote]https:\/\/github.com\/jgm\/pandoc\/wiki\/Pandoc-User's-Manual-in-French<\/a>[\/footnote] qui fait appel \u00e0 LaTeX<\/em>[footnote]https:\/\/fr.wikibooks.org\/wiki\/LaTeX<\/a>[\/footnote] permet maintenant de produire des documents avec une qualit\u00e9 identique \u00e0 celle des documents produits directement avec LaTeX<\/em> (Pierre, 2017<\/a>).\r\n\r\nUtiliser Markdown<\/em> ne doit pas \u00eatre consid\u00e9r\u00e9 comme une complication suppl\u00e9mentaire mais fait au contraire partie d\u2019un mouvement Low-Tech<\/em>. Ce manuel (sous la forme d\u2019un site Web mais \u00e9galement export\u00e9 au format pdf<\/em> et epub<\/em>) a \u00e9t\u00e9 r\u00e9dig\u00e9 avec un simple \u00e9diteur de texte (Gedit<\/em>[footnote]https:\/\/fr.wikipedia.org\/wiki\/Gedit<\/a>[\/footnote]). Il permet de se concentrer sur la r\u00e9daction du texte sans se pr\u00e9occuper de sa forme finale (Dehut, 2018<\/a>). Il rassemble les fonctions de base pr\u00e9sentes dans tous les bons manuels (Mailund, 2019<\/a>) ou des fonctions plus \u201cpratiques\u201d glan\u00e9es au fil de lectures.\r\n\r\nMarkdown<\/em> fait partie de ces solutions Single Source publishing<\/em> \u00e9voqu\u00e9es en introduction, c\u2019est \u00e0 dire qu\u2019avec un (ou plusieurs) m\u00eame(s) fichier(s) source(s) on peut produire des documents dans diff\u00e9rents formats (essentiellement HTML<\/em>, ePub<\/em> et pdf<\/em>).\r\n\r\nToutes les fonctions pr\u00e9sent\u00e9es dans ce chapitre illustrent l\u2019utilisation de la variante \u201cPandoc<\/em>\u201d de Markdown<\/em> (il existe d\u2019autres d\u00e9clinaisons de Markdown<\/em>[footnote]https:\/\/www.iana.org\/assignments\/markdown-variants\/markdown-variants.xhtml<\/a>[\/footnote] comme MultiMarkdown<\/em> et GitHub Flavored Markdown<\/em> qui ne sont pas d\u00e9crites ici) pour la cr\u00e9ation de documents pdf<\/em>.\r\n
\r\n

Principe<\/h1>\r\nAvec Markdown<\/em>, il y a de nombreuses fonctions propos\u00e9es par les traitements de texte impossibles \u00e0 reproduire. Le fait qu\u2019elles existent n\u2019en fait d\u2019ailleurs pas des fonctions indispensables. L\u2019objectif est bien de proposer une m\u00e9thode simple, ouverte et durable pour r\u00e9diger et produire de beaux documents num\u00e9riques (Audet et al., 2018<\/a>).\r\n\r\nLe principe de base est de s\u00e9parer le fond de la forme. Le fond, c\u2019est le texte, une suite de caract\u00e8res, qui se lit en dehors de toute mise en forme. La forme, c\u2019est la traduction graphique, enrichie, du texte. Elle peut \u00eatre diff\u00e9rente d\u2019un support \u00e0 l\u2019autre.\r\n\r\nPratiquement, il faut cr\u00e9er un fichier texte avec n\u2019importe quel \u00e9diteur (voir les outils<\/a>) et l\u2019enregistrer avec l\u2019extension \u201c.md\u201d. Vous trouverez le lien pour t\u00e9l\u00e9charger un mod\u00e8le de document dans le chapitre \u201cT\u00e9l\u00e9charger\u201d<\/a>.\r\n\r\nAutour du fond et du texte, nous avons cinq \u00e9l\u00e9ments \u00e0 prendre en compte :\r\n
    \r\n \t
  1. la structure du document (parties, chapitres, titres et paragraphes)<\/li>\r\n \t
  2. la mise en forme du texte<\/li>\r\n \t
  3. les compl\u00e9ments du texte (notes, liens, figures, tableaux et citations)<\/li>\r\n \t
  4. les \u00e9l\u00e9ments de mise en forme du document<\/li>\r\n \t
  5. la description du document (les m\u00e9tadonn\u00e9es).<\/li>\r\n<\/ol>\r\nLes \u00e9l\u00e9ments de mise en forme du document (langue du document, taille du papier, taille des caract\u00e8res, pr\u00e9sence ou non d\u2019une table des mati\u00e8res\u2026) et la description du document, ses m\u00e9tadonn\u00e9es, sont int\u00e9gr\u00e9es dans l\u2019en-t\u00eate du document dans une partie appel\u00e9e YAML<\/em><\/a>.\r\n\r\n<\/div>\r\n
    \r\n

    <\/a>La structure du document<\/h1>\r\n
    \r\n

    Les titres<\/h2>\r\nPour \u00eatre correctement structur\u00e9, un texte doit \u00eatre divis\u00e9 en parties, chapitres, sous-chapitres, etc. Le niveau des titres va d\u00e9terminer cette structure. Avec Mardown<\/em>, ces niveaux sont simplement indiqu\u00e9s avec les balises \u201c#\u201d dont le nombre d\u00e9termine la profondeur du titre :\r\n
    # Titre de niveau 1\r\n## Titre de niveau 2\r\n### Titre de niveau 3\r\n#### Titre de niveau 4\r\n##### Titre de niveau 5\r\n###### Titre de niveau 6<\/div>\r\nPour un document de type article<\/em>, le niveau 1 repr\u00e9sente les chapitres. Pour un document de type book<\/em> ou reports<\/em>, le niveau 1 repr\u00e9sente les parties et chaque titre de partie est pr\u00e9c\u00e9d\u00e9 par un saut de page.\r\n\r\nLes titres peuvent \u00eatre num\u00e9rot\u00e9s automatiquement via une instruction pr\u00e9sente dans l\u2019en-t\u00eate YAML<\/em> : numbersections:<\/em> true<\/em>. Pour emp\u00eacher la num\u00e9rotation d\u2019un titre en particulier, il faut ajouter \u201c{-}<\/strong>\u201d \u00e0 la suite du titre, sur la m\u00eame ligne.\r\n\r\n<\/div>\r\n
    \r\n

    Les paragraphes<\/h2>\r\nDans le texte, la s\u00e9paration en paragraphes est r\u00e9alis\u00e9e par un double saut de ligne.\r\n\r\nIl est cependant possible, en ajoutant \u201c\\\u201d<\/strong>\u00a0\u00e0 la fin de la ligne, de provoquer un saut de ligne sans cr\u00e9er un nouveau paragraphe.\r\n\r\n<\/div>\r\n
    \r\n

    Les listes<\/h2>\r\nMarkdown<\/em> permet de cr\u00e9er des listes simples et des listes num\u00e9rot\u00e9es.\r\n\r\nPour les listes simples, il faut utiliser le tiret (ou le +<\/strong>) suivi d\u2019une espace.\r\n\r\nCeci :<\/strong>\r\n<\/code>\r\n
    - item 1\r\n- item 2\r\n+ item 3<\/div>\r\n \r\n\r\nDonnera :<\/strong>\r\n\r\n\u2014\u00a0item 1\r\n\u2014\u00a0item 2\r\n\u2014\u00a0item 2\r\n\r\nNotez au passage que les bullets sont ici remplac\u00e9s par des tirets longs (quadratins)[footnote]Sp\u00e9cifique pour les documents d\u00e9clar\u00e9s en fran\u00e7ais (voir le chapitre YAML<\/a>).[\/footnote].\r\n\r\nPour les listes num\u00e9rot\u00e9es, il faut mettre un chiffre (peu importe le chiffre mais le premier indique le d\u00e9but de la num\u00e9rotation), suivi d\u2019un point et d\u2019une espace.\r\n\r\nCeci : <\/strong>\r\n<\/code>\r\n
    1. item 1\r\n1. item 2\r\n1. item 3<\/div>\r\nDonnera :<\/strong>\r\n
      \r\n \t
    1. item 1<\/li>\r\n \t
    2. item 2<\/li>\r\n \t
    3. item 3<\/li>\r\n<\/ol>\r\nLes listes doivent \u00eatre pr\u00e9c\u00e9d\u00e9es d\u2019un saut de ligne. Il est possible de combiner les deux types de listes.\r\n\r\nPeut-\u00eatre moins utile, il est aussi possible de cr\u00e9er des cases \u00e0 cocher.\r\n\r\nCeci :<\/strong>\r\n
      - [x] item 1, coch\u00e9\r\n- [ ] item 2, non-coch\u00e9\r\n- [x] item 2.1, coch\u00e9\r\n- [ ] item 2.2, non-coch\u00e9\r\n- [ ] item 3, non-coch\u00e9\r\n- [X] item 4, coch\u00e9<\/div>\r\nDonnera :<\/strong>\r\n\r\n\"image\"<\/a>\r\n\r\n<\/div>\r\n<\/div>\r\n
      \r\n

      La mise en forme du texte<\/h1>\r\n
      \r\n

      Les styles<\/h2>\r\nLes fonctions de base sont l\u2019italique<\/em> et le gras<\/strong>. Il est aussi possible de barrer<\/del> un texte.\r\n\r\nCe passage :<\/strong>\r\n
      *Ceci est un texte italique*, **Ceci est un texte gras** et ~~Ceci est un texte barr\u00e9~~<\/div>\r\nDonnera :<\/strong>\r\n\r\nCeci est un texte italique<\/em>, Ceci est un texte gras<\/strong> et Ceci est un texte barr\u00e9<\/del>\r\n\r\n(il est possible de les combiner).\r\n\r\nLes indices et les exposants sont r\u00e9alis\u00e9s avec ~ et ^ donc : H~2O<\/strong> et X^2<\/strong> pour : H2<\/sub>O et X2<\/sup>\r\n\r\nLes tirets longs (cadratin) et demi-longs (demi-cadratin) sont cr\u00e9\u00e9s avec trois et deux tirets (le signe moins) : \u2014 et \u2013\r\n

      Les mises en \u00e9vidence<\/span><\/h2>\r\nPour citer et mettre en \u00e9vidence un passage de texte, il faut utiliser le caract\u00e8re \u201c>\u201d en d\u00e9but de paragraphe.<\/span>\r\n\r\n \r\n\r\n<\/div>\r\n
      \r\n\r\nCe passage :<\/strong>\r\n
      > \"But here\u2019s the most important bit, saved for last: none of this matters if you want to write a book. Quite a few people have told me that they want to write a book, but they\u2019re not sure about which tools to use. My advice: all you need to write a book is a program that allows you to write text into a file [@ball2018].\"<\/div>\r\nDonnera :<\/strong>\r\n
      \u201cBut here\u2019s the most important bit, saved for last: none of this matters if you want to write a book. Quite a few people have told me that they want to write a book, but they\u2019re not sure about which tools to use. My advice: all you need to write a book is a program that allows you to write text into a file (Ball, 2018).\u201d<\/blockquote>\r\nLe texte est centr\u00e9 dans la page avec une justification gauche et droite (comme le reste du texte).\r\n\r\nNotez au passage l\u2019ajout de la citation \u00e0 l\u2019auteur du texte qui va reproduire le renvoi \u00e0 la bibliographie suivant la norme s\u00e9lectionn\u00e9e dans l\u2019en-t\u00eate YAML<\/em> et ajouter la r\u00e9f\u00e9rence dans la bibliographie en fin de document (voir plus loin pour plus d\u2019explications \u00e0 propos des possibilit\u00e9s en mati\u00e8re de bibliographie).\r\n\r\n<\/div>\r\n
      \r\n

      Les codes et textes non format\u00e9s<\/h2>\r\nPour afficher du code sans formatage (comme fait \u00e0 plusieurs reprises plus haut), il faut :\r\n