Voici un aperçu rapide de la syntaxe Markdown repris d'une
[[https://guides.github.com/features/mastering-markdown/][présentation de Github]] ainsi que de celles d'[[http://csrgxtu.github.io/2015/03/20/Writing-Mathematic-Fomulars-in-Markdown/][Archer Reilly]].
[[https://guides.github.com/features/mastering-markdown/][présentation de GitHub]] ainsi que de celles d'[[http://csrgxtu.github.io/2015/03/20/Writing-Mathematic-Fomulars-in-Markdown/][Archer Reilly]].
* Table des matières :TOC:
- [[#syntaxe][Syntaxe]]
- [[#headers][Headers]]
...
...
@@ -21,10 +21,10 @@ Voici un aperçu rapide de la syntaxe Markdown repris d'une
- [[#lettres-grecques][Lettres grecques]]
- [[#fonctions-et-opérateurs][Fonctions et opérateurs]]
Tout d'abord, pour aller plus loin avec =markdown= et ses extensions / ramifications :
* Autour de =Markdown=
Tout d'abord, pour aller plus loin avec =Markdown= et ses extensions / ramifications :
- Le didacticiel « [[https://enacit1.epfl.ch/markdown-pandoc/][Élaboration et conversion de documents avec Markdown et Pandoc]] » de Jean-Daniel Bonjour (EPFL), précis, complet, concis, en français ; un vrai bonheur !
- L'article [[https://en.wikipedia.org/wiki/Markdown#Example][Markdown]] de wikipedia en anglais contient un bon pense-bête sur la syntaxe =markdown=.
- Github propose un court et efficace didacticiel (en anglais) : [[https://guides.github.com/features/mastering-markdown/][Mastering Markdown]].
- L'article [[https://en.wikipedia.org/wiki/Markdown#Example][Markdown]] de wikipedia en anglais contient un bon pense-bête sur la syntaxe =Markdown=.
- GitHub propose un court et efficace didacticiel (en anglais) : [[https://guides.github.com/features/mastering-markdown/][Mastering Markdown]].
Comme nous l'illustrons dans la « film d'écran » (/screencast/), l'éditeur de texte des dépôts =github= et =gitlab= permet d'interpréter / transformer à la demande un fichier =mardown= en un fichier =html=. C'est à la fois agréable et pratique, mais ce n'est pas une solution pour une utilisation quotidienne de =markdown=, pour cela, il est plus efficace d'éditer son texte, avec un éditeur de texte, sur son ordinateur, avant de « l'exporter » dans un format comme =html=, =pdf=, =docx=, =epub=, etc. Il existe des éditeurs plus ou moins spécialisés pour =markdown=, certains sont indiqués sur la page [[https://github.com/jgm/pandoc/wiki/Pandoc-Extras#editors][Editors]] du site de =pandoc=, mais nous préconisons clairement l'emploi d'un éditeur de texte « généraliste » capable de reconnaître la syntaxe =markdown=. Nous en avons indiqué en début de séquence et on pourra trouver des informations complémentaires dans la section [[https://enacit1.epfl.ch/markdown-pandoc/#editeurs_markdown][Quelques éditeurs adaptés à l'édition Markdown]] du didacticiel de Jean-Daniel Bonjour.
Comme nous l'illustrons dans le « film d'écran » (/screencast/), l'éditeur de texte des dépôts =GitHub= et =GitLab= permet d'interpréter / transformer à la demande un fichier =Markdown= en un fichier =html=. C'est à la fois agréable et pratique, mais ce n'est pas une solution pour une utilisation quotidienne de =Markdown=, pour cela, il est plus efficace d'éditer son texte, avec un éditeur de texte, sur son ordinateur, avant de « l'exporter » dans un format comme =html=, =pdf=, =docx=, =epub=, etc. Il existe des éditeurs plus ou moins spécialisés pour =Markdown=, certains sont indiqués sur la page [[https://github.com/jgm/pandoc/wiki/Pandoc-Extras#editors][Editors]] du site de =Pandoc=, mais nous préconisons clairement l'emploi d'un éditeur de texte « généraliste » capable de reconnaître la syntaxe =Markdown=. Nous en avons indiqué en début de séquence et on pourra trouver des informations complémentaires dans la section [[https://enacit1.epfl.ch/markdown-pandoc/#editeurs_markdown][Quelques éditeurs adaptés à l'édition Markdown]] du didacticiel de Jean-Daniel Bonjour.
Pour convertir un fichier =markdown= en un format « arbitraire », la solution à ce jour la plus complète est [[http://pandoc.org/][Pandoc]], logiciel développé par John MacFarlane, un philosophe de Berkeley (le site [[https://github.com/jgm/pandoc][github]]). En plus du site de =Pandoc=, le didacticiel de J.-D. Bonjour donne de nombreuses explications sur comment installer et utiliser =pandoc= dans la section [[https://enacit1.epfl.ch/markdown-pandoc/#commande_pandoc][Utilisation du convertisseur Pandoc]]. Comme =pandoc= -- écrit en Haskell -- peut être parfois un peu difficile à installer, nous indiquons maintenant quelques solutions alternatives :
- Des sites comme [[http://www.markdowntopdf.com/]] et [[http://markdown2pdf.com/]] permettent de convertir en ligne un fichier =markdown= en un fichier =pdf=.
- Le projet [[http://commonmark.org/][CommonMark]] propose, en plus d'une spécifications plus rigoureuse de la syntaxe =markdown=, des convertisseurs =markdown= → =html= / =LaTeX= (et plus) écris en =C= et en =JavaScript= ([[https://github.com/CommonMark/CommonMark]]).
- Le site de [[https://daringfireball.net/projects/markdown/][John Gruber]], le créateur de =markdown=, fournit un convertisseur =markdown= → =html= écrit en =perl=.
- [[http://fletcherpenney.net/multimarkdown/][MultiMarkdown]] est une autre extension de =markdown= qui vient avec son convertisseur =markdown= → =html= écrit en =C=.
- [[https://github.com/joeyespo/grip][grip]] est un serveur écrit en =python= qui permet de convertir et visualiser à la volée des fichiers =markdown= avec son navigateur (très utile pour éviter d'avoir à faire des « commits » en grande quantité lorsqu'on écrit de tels fichiers pour un dépôt =github= ou =gitlab=).
Pour convertir un fichier =Markdown= en un format « arbitraire », la solution à ce jour la plus complète est [[http://pandoc.org/][Pandoc]], logiciel développé par John MacFarlane, un philosophe de Berkeley (le site [[https://github.com/jgm/pandoc][GitHub]]). En plus du site de =Pandoc=, le didacticiel de J.-D. Bonjour donne de nombreuses explications sur comment installer et utiliser =Pandoc= dans la section [[https://enacit1.epfl.ch/markdown-pandoc/#commande_pandoc][Utilisation du convertisseur Pandoc]]. Comme =Pandoc= -- écrit en Haskell -- peut être parfois un peu difficile à installer, nous indiquons maintenant quelques solutions alternatives :
- Des sites comme [[http://www.markdowntopdf.com/]] et [[http://markdown2pdf.com/]] permettent de convertir en ligne un fichier =Markdown= en un fichier =pdf=.
- Le projet [[http://commonmark.org/][CommonMark]] propose, en plus d'une spécification plus rigoureuse de la syntaxe =Markdown=, des convertisseurs =Markdown= → =html= / =LaTeX= (et plus) écrits en =C= et en =JavaScript= ([[https://github.com/CommonMark/CommonMark]]).
- Le site de [[https://daringfireball.net/projects/markdown/][John Gruber]], le créateur de =Markdown=, fournit un convertisseur =Markdown= → =html= écrit en =Perl=.
- [[http://fletcherpenney.net/multimarkdown/][MultiMarkdown]] est une autre extension de =Markdown= qui vient avec son convertisseur =Markdown= → =html= écrit en =C=.
- [[https://github.com/joeyespo/grip][grip]] est un serveur écrit en =Python= qui permet de convertir et visualiser à la volée des fichiers =Markdown= avec son navigateur (très utile pour éviter d'avoir à faire des « commits » en grande quantité lorsqu'on écrit de tels fichiers pour un dépôt =GitHub= ou =GitLab=).
La conversion en =pdf= passe toujours par [[https://fr.wikipedia.org/wiki/LaTeX][LaTeX]] ce qui nécessite d'avoir une version complète et à jour de ce logiciel sur sa machine.
Dans la petite démonstration, nous montrons comment générer un fichier =docx= à partir d'un fichier =md= avec =Pandoc= et nous soulignons qu'il est alors possible d'utiliser un traitement de texte comme =LibreOffice= pour modifier le fichier obtenu. Il est clair que si des modifications sont apportées au =docx= elle en seront pas (automatiquement) propagées au =md=. Il faudra utiliser =Pandoc= pour cela et effectuer une conversion de =docx= vers =md= (et seules les éléments du format =docx= qui existent en =md= seront conservés).
Dans la petite démonstration, nous montrons comment générer un fichier =docx= à partir d'un fichier =md= avec =Pandoc= et nous soulignons qu'il est alors possible d'utiliser un traitement de texte comme =LibreOffice= pour modifier le fichier obtenu. Il est clair que si des modifications sont apportées au =docx= elles ne seront pas (automatiquement) propagées au =md=. Il faudra utiliser =Pandoc= pour cela et effectuer une conversion de =docx= vers =md= (et seuls les éléments du format =docx= qui existent en =md= seront conservés).
Une stratégie qui est souvent employée et qui fonctionne bien en pratique consiste à faire le gros du travail de rédaction d'un article ou d'un mémoire en =Markdown=. La rédaction terminée, le fichier est exporté au format =docx= (ou =LaTeX=) et des ajustements de mise en page sont alors effectués avec un logiciel de traitement de texte (ou un éditeur =LaTeX=).
