YannStatic

Élaboration et conversion de documents avec Markdown

  •   6 mai   2019
Afficher/cacher Sommaire

Introduction

Élaboration et conversion de documents avec Markdown et Pandoc par Jean-Daniel Bonjour, EPFL-ENAC-IT, © Creative Commons BY-SA (rĂ©vision 16.12.2014)

Avant-propos

Cette page web dĂ©crit le langage de balisage lĂ©ger d’écriture de documents Markdown (markup language) ainsi que l’utilisation du convertisseur Pandoc, notamment les trĂšs nombreuses, riches et utiles extensions apportĂ©es Ă  la syntaxe Markdown par ce convertisseur.

Cette page a Ă©tĂ© elle-mĂȘme rĂ©digĂ©e en langage Markdown (vous pouvez examiner son code source) en faisant un large usage des extensions offertes par Pandoc (dont il faut utiliser une version ≄ 1.11.1). Elle a Ă©tĂ© convertie en HTML avec la commande pandoc -s -N --toc --mathjax -c markdown-pandoc.css -o index.html index.md. Son rendu web s’appuie en outre sur une feuille de style CSS spĂ©cifique que nous avons rĂ©alisĂ©e et qui est plutĂŽt orientĂ©e impression.

Vous pouvez aussi tĂ©lĂ©charger la [version e-book](index.epub) (au format ePub) de ce document, Ă  consulter par exemple avec l’excellente liseuse libre Calibre.

Une derniĂšre remarque : ne soyez pas effrayĂ© par le volume de cette documentation ! À l’usage, vous constaterez que les concepts prĂ©sentĂ©s ici sont finalement extrĂȘmement naturels, et que Markdown et Pandoc sont trĂšs faciles Ă  mettre en oeuvre â˜ș

Quelques références

Markdown

Pandoc

Autres langages de balisage légers


Le langage Markdown

Généralités

«A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.» (John Gruber)

Markdown est une syntaxe lĂ©gĂšre d’écriture de documents dĂ©finie en 2004 par John Gruber avec la collaboration de Aaron Swartz. Elle a Ă©tĂ© conçue pour ĂȘtre aussi facile Ă  lire et Ă  Ă©crire que possible. D’importants outils (IPython Notebook
) et de nombreux sites Internet (GitHub, StackExchange, Reddit, Tumblr
) l’utilisent comme syntaxe d’édition. Mais en raison du caractĂšre non formel de la dĂ©finition originale de cette syntaxe par Gruber, de certaines ambiguĂŻtĂ©s et du besoin d’évolution de ce format, un projet de standardisation dĂ©bute en 2014 sous la dĂ©nomination CommonMark.

Bien que cette syntaxe permette la conversion en différents formats de documents, elle est principalement orientée vers la production de documents (X)HTML simples, raison pour laquelle nous indiquerons souvent dans ce document les balises (X)HTML résultant de la conversion Markdown dans ce format.

Syntaxe de base du langage Markdown

Paragraphes, sauts de ligne

Dans la syntaxe Markdown, un paragraphe (<p>...</p> en HTML) est constituĂ© d’une ligne ou de plusieurs lignes consĂ©cutives. Le passage au paragraphe suivant s’effectue en introduisant une ou plusieurs lignes vides.

Pour effectuer un saut de ligne Ă  l’intĂ©rieur d’un paragraphe (<br /> en HTML), il faut introduire 2 ou davantage de caractĂšres espaces Ă  la fin de la ligne (avant le saut Ă  la ligne).

Voici un paragrapheâ†Č
de texte avec⎕⎕â†Č   
un saut de ligne.â†Č  
â†Č  
Puis un autre paragraphe...

Voici un paragraphe de texte avec
un saut de ligne.

Puis un autre paragraphe


Titres

Un titre consiste en un paragraphe dĂ©butant par 1 Ă  6 caractĂšres diĂšses # suivi(s) de l’intitulĂ© proprement dit du titre. Le nombre de # dĂ©butant la ligne spĂ©cifie le niveau du titre : par exemple ### Titre... est un titre de 3e niveau (<h3>Titre...</h3>). On peut facultativement terminer la ligne de titre par des diĂšses # (peu importe leur nombre).

Une autre syntaxe peut ĂȘtre utilisĂ©e pour les titres de premier et second niveau. Pour le 1er niveau (<h1>), on peut saisir le texte du Titre directement suivi d’une ligne composĂ©e d’un ou plusieurs caractĂšres Ă©gal = puis d’une ligne vide. Pour le 2Ăšme niveau (<h2>), le titre sera suivi d’une ligne composĂ©e d’un ou plusieurs tirets -

Notez finalement que l’on peut faire usage de styles et liens (techniques prĂ©sentĂ©es plus bas) Ă  l’intĂ©rieur des titres.


	# Titre de niveau 1
	
	Autre syntaxe pour niveau 1
	===========================
	
	## Titre de niveau 2
	
	Syntaxe ⎯alternative⎯ pour niveau 2
	-----------------------------------
	
	### Titre de niveau 3 incluant [un lien](#)
	
	#### Titre de niveau 4

Titre de niveau 3 incluant un lien

Traits horizontaux

Un trait horizontal (<hr />) est dĂ©fini par un nouveau paragraphe (donc prĂ©cĂ©dĂ© et suivi d’1 ligne vide au moins) comportant au minimum 3 caractĂšres de type tiret -, soulignĂ© _ ou Ă©toile *, optionnellement sĂ©parĂ©s par des espaces.

	------------
	
	Paragraphe...
	
	*********
	
	Paragraphe...
	
	* * *

Paragraphe


Paragraphe


Styles et blocs

Les styles de base sont définis par la syntaxe suivante :

  • une portion de texte en italique (<em>) sera bordĂ©e Ă  gauche et Ă  droite par le caractĂšre _ ou *
  • le texte en gras (<strong>) sera bordĂ© Ă  gauche et Ă  droite par 2 caractĂšres ** ou __

Pour insĂ©rer du code inline (<code>...</code> ⇒ texte en chasse fixe), on placera celui-ci entre ` ` (accents graves,AltGr 7), et ceux-ci seront doublĂ©s si ce code contient lui-mĂȘme un ou plusieurs accents graves. Dans ce code inline, les directives de formatage Markdown _ * ainsi que les balises HTML ne sont pas interprĂ©tĂ©es mais restituĂ©es telles quelles.

	Mots en ⎯italique **gras**⎯ ou en **gras ⎯italique⎯**,
	du `code contenant des
	*balises* HTML, p.ex. <u> <span>` ...
	
	Mais _ ceci _ ou ** cela ** ne va pas (en raison d'espaces) !

Mots en italique gras ou en gras italique, du code contenant des *balises*, p.ex. <u> <span> 

Mais _ ceci _ ou ** cela ** ne va pas (en raison d’espaces) !

Pour définir un bloc de code (structure <pre>...</pre> en HTML), on fera précéder chaque ligne de 1 ou plusieurs tab ou de 4 espaces ou plus.
Notez que dùs le 2ùme tab ou le 5ùme espace, ces caractùres participent à l’indentation du code !
Dans un tel bloc, les directives de formatage Markdown _ *, les balises HTML ainsi que les caractÚres HTML (p.ex. &eacute;, &amp;) ne sont pas non plus interprétées (les caractÚres < > & étant affichés tels quels).

	 ⟌ Sur le pont d'Avignon
	 ⟌ ⎕⎕L'on y danse, l'on y danse,
	 ⟌ Sur le pont d'Avignon
	 ⟌ ⎕⎕L'on y danse tous en rond.

Sur le pont d'Avignon
  L'on y danse, l'on y danse,
Sur le pont d'Avignon
  L'on y danse tous en rond.

Pour dĂ©caler Ă  droite un paragraphe (on appelle ça un bloc de “citation”, hĂ©ritĂ© de l’email), on fera prĂ©cĂ©der la premiĂšre ligne du paragraphe (facultativement les suivantes) par le caractĂšre >. En HTML cela gĂ©nĂ©rera un bloc <blockquote>. On peut faire des citations/dĂ©calages de 2Ăšme niveau avec >> ou > >, de 3Ăšme niveau avec >>> ou > > >, et ainsi de suite.

Rien n’interdit de faire usage de toute autre possibilitĂ© Markdown dans les citations (styles Markdown, titres, listes, blocs de code, ainsi que balises HTML
).


	Paragraphe normal

	> DĂ©but du bloc de citation
	>
	> * élément de liste
	> * second élément
	>
	>> DĂ©calage de 2Ăšme niveau, usage de _styles_
	Markdown, <u>balises</u> HTML
	>
	> ⟌ Bloc de code dans la citation

	Retour Ă  l'alignement normal

Paragraphe normal

DĂ©but du bloc de citation

  • Ă©lĂ©ment de liste
  • second Ă©lĂ©ment

DĂ©calage de 2Ăšme niveau, usage de styles Markdown, balises HTML

  Bloc de code dans la citation

Retour à l’alignement normal

Liens

Markdown propose deux techniques de définition de liens.

A) Pour dĂ©finir un lien inline (technique HTML classique du lien “au fil du texte”) :

  • si l’URL est ancrĂ©e Ă  un texte, on utilise la syntaxe : [texte](URL "titre optionnel")
    ‱ notez bien l’usage respectif des crochets et parenthùses, ainsi que l’absence d’espace entre ] et (
    ‱ le titre optionnel est le texte qui s’affichera lorsque le curseur survole le lien
    ‱ le texte d’ancrage peut bien entendu faire l’objet d’un formatage Markdown (p.ex. gras, italique
)

  • si l’on veut insĂ©rer au fil du paragraphe une URL (non ancrĂ©e Ă  un texte, mais prĂ©sentĂ©e telle quelle et cliquable), on utilise simplement la syntaxe : <URL> (donc entre signes < et >)
    ‱ pour dĂ©finir des adresses emails cliquables, il n’est pas nĂ©cessaire de les prĂ©fixer par mailto:

	Lien externe : l' [EPFL](http://www.epfl.ch "École polytechnique fĂ©dĂ©rale de Lausanne") se trouve...  
	Web: <http://www.epfl.ch>, Email: <accueil@epfl.ch>
	
	Lien interne : vers le [haut de la page](#)

Lien externe : l’ EPFL se trouve

Web : http://www.epfl.ch, Email: accueil@epfl.ch

Lien interne : vers le haut de la page

Remarque : si vous examinez le code HTML, vous constaterez que les liens de type <adresse_email> sont automatiquement encodĂ©s (et mĂȘme associĂ©s par Pandoc Ă  du JavaScript) et sont de ce fait relativement rĂ©sistant aux robots de spam !

B) Markdown offre en outre la possibilité trÚs intéressante de définir des liens par référence, explicite ou implicite. On réalise cela en deux étapes (ci-dessous la référenciation explicite) :

  1. d’une part on dĂ©finit, n’importe oĂč dans le fichier, l’URL et un label urlId permettant de s’y rĂ©fĂ©rer selon la syntaxe : [urlId]: URL "titre optionnel"
    ‱ notez bien le double point : suivant directement le crochet ]
    ‱ l’URL peut optionnellement ĂȘtre Ă©crite entre < >
    ‱ sachez aussi que le label urlId n’est pas case-sensitive et peut contenir des espaces !
    ‱ ces 3 champs peuvent optionnellement ĂȘtre dĂ©finis sur 2-3 lignes (mais sans intercaler de ligne vide)

  2. au fil du texte (inline), on ancre simplement par référence cette URL à un texte avec : [texte][urlId]
    ‱ notez bien que l’on n’utilise ici que des crochets, ainsi que l’absence d’espace entre ] et [

	La [faculté **ENAC**][webEnac] forme des ing. et architectes...  
	L'[ENAC][webEnac] est constituée de...

	[webEnac]: http://enac.epfl.ch "Environnement naturel..."

La faculté ENAC forme des ing. et architectes

L’ENAC est constituĂ©e de


Le grand intĂ©rĂȘt de cette seconde technique de “liens par rĂ©fĂ©rence” est de pouvoir dĂ©porter les URLs en dehors du texte proprement dit (allĂ©geant la composition et la lecture de celui-ci), d’éventuellement regrouper toutes les URLs au mĂȘme endroit dans le fichier, et surtout de pouvoir partager la mĂȘme URL par plusieurs liens en ne la dĂ©finissant qu’une fois dans le document !

Images inlines

Syntaxiquement, un lien Markdown prĂ©cĂ©dĂ© du caractĂšre point d’exclamation ! est considĂ©rĂ© comme une image. De la mĂȘme façon que pour les liens, il existe deux syntaxes d’insertion d’images au fil du texte.

A) L’insertion d’image par rĂ©fĂ©rence inline s’effectue selon la syntaxe : ![texte alternatif](URL_IMAGE "titre optionnel")
Notez donc bien le point d’exclamation dĂ©butant cette expression. Le titre optionnel est le texte s’affichant lorsque le curseur survole le lien. Quant au texte alternatif, c’est celui qui apparaĂźt lorsque le navigateur ne prend pas en charge l’affichage des images.

B) Par ailleurs, et comme pour les liens, on peut également insérer une image par référence en deux étapes avec :

  1. d’une part la dĂ©finition de l’URL_IMAGE, n’importe oĂč dans le document, par : [imgId]: URL_IMAGE "titre optionnel"
    (optionnellement définis sur 2-3 lignes, mais sans intercaler de ligne vide)
  2. d’autre part l’insertion proprement dite, au fil du texte, de l’image rĂ©fĂ©rencĂ©e avec : ![texte alternatif][imgId]
	Le logo Markdown ![logo Markdown](markdown-logo.png "Markdown")
	apparaĂźt parfois Ă©galement ainsi ![autre variante][imgMD]

	[imgMD]: /images/markdown-logo.png "Markdown"

Le logo Markdown logo Markdown apparaĂźt parfois Ă©galement ainsi autre variante

Le grand intĂ©rĂȘt de cette seconde technique rĂ©side notamment dans la possibilitĂ© d’insĂ©rer de façon trĂšs concise la mĂȘme image (icĂŽne, logo
) Ă  plusieurs endroits dans le document !

DĂ©finition de liens ou d’images par rĂ©fĂ©rence implicite

Lorsque l’on insĂšre par rĂ©fĂ©rence, dans un paragraphe, un lien ou une image dĂ©finis ailleurs dans le document, il est possible d’omettre le second champ [urlId] ou [imgId] ! On parle dans ce cas de rĂ©fĂ©rence implicite, car cela revient Ă  Ă©tablir un lien vers une rĂ©fĂ©rence de nom identique Ă  ce qui est dĂ©fini dans le premier champ : ainsi [du texte] renverrait vers la rĂ©fĂ©rence [du texte]: url. Cette syntaxe apporte une concision extrĂȘme dans l’utilisation de liens et d’images !

	La [faculté ENAC] forme des ing. et architectes...
	
	La syntaxe ![image] est super légÚre et concise !

	[faculté enac]: <http://enac.epfl.ch> "Environnement naturel..."
	[image]: /images/markdown-logo.png 'Markdown'

La faculté ENAC forme des ing. et architectes


La syntaxe image est super légÚre et concise !

Rappelons encore (ce qui est illustrĂ© dans l’exemple ci-dessus) que :

  • les labels (urlId, imgId) ne sont pas case-sensitive et peuvent contenir des espaces
  • dans les dĂ©finition de rĂ©fĂ©rences, l’URL peut optionnellement ĂȘtre dĂ©finie entre < >
  • le titre optionnel des liens et des images peut ĂȘtre dĂ©fini entre guillemets, apostrophes ou parenthĂšses

!!!ATTENTION , référence implicite problÚme avec les images pour des éditeurs avec aperçu (retext)

Listes

Pour dĂ©finir une liste numĂ©rotĂ©e (<ol>), il suffit de saisir, au dĂ©but de chaque Ă©lĂ©ment de la liste, un nombre quelconque suivi d’un point et de 1 ou plusieurs espaces ou tab. Si un paragraphe doit commencer par un nombre, il faut prĂ©fixer le point du nombre par \ afin qu’il ne soit pas considĂ©rĂ© comme un dĂ©but de liste numĂ©rotĂ©e.

Pour dĂ©finir une liste Ă  puce (<ul>), il suffit de dĂ©buter chaque item par l’un des caractĂšres *, + ou - suivi d’1 ou plusieurs espaces ou tab.

Le dĂ©but et la fin de la liste doivent ĂȘtre respectivement prĂ©cĂ©dĂ© et suivi d’1 ligne vide au moins.

Il est possible de faire des listes imbriquĂ©es : pour cela la sous-liste devra ĂȘtre indentĂ©e Ă  droite d’1 tab ou de 4 espaces par rapport Ă  l’élĂ©ment supĂ©rieur. Les sous-listes n’ont pas besoin d’ĂȘtre prĂ©cĂ©dĂ©es et suivies d’une ligne vide.

	1. raisin
	0. pomme
	 ⟌ * golden
	 ⟌ - granny smith
	 ⟌ + boskoop
	0. abricot
	
	1291\. Signature du pacte fédéral Suisse
  1. raisin
  2. pomme
    • golden
    • granny smith
    • boskoop
  3. abricot

1291. Signature du pacte fédéral Suisse

Si l’on dĂ©sire un espacement de paragraphe entre les Ă©lĂ©ments de la liste, on dĂ©finira ceux-ci comme des paragraphes c’est-Ă -dire en intercalant des lignes vides.

	* les éléments
	* sont ici
	* serrés

    ---

	1. mais ici espacés
	â†Č
	0. comme plusieurs
	â†Č
	0. paragraphes consécutifs
  • les Ă©lĂ©ments
  • sont ici
  • serrĂ©s

  1. mais ici espacés

  2. comme plusieurs

  3. paragraphes consécutifs

Inclusion de code HTML dans un fichier Markdown

La plupart des balises HTML (y compris <span>) peuvent ĂȘtre utilisĂ©es dans des paragraphes Markdown.

Les structures HTML de type bloc (<div>, <table>, <pre>
) doivent cependant ĂȘtre prĂ©cĂ©dĂ©es et suivies d’1 ligne vide au moins, et les balises de dĂ©but et fin du bloc ne doivent pas ĂȘtre indentĂ©es (donc non prĂ©cĂ©dĂ©es d’espaces ou tab). Mais attention : sachez qu’avec la syntaxe stricte Markdown (cette restriction ne s’applique pas Ă  Pandoc) le formatage Markdown n’est pas appliquĂ© Ă  l’intĂ©rieur de tels blocs HTML !

	Utilisation de balises HTML : <u>souligné</u>,
	  <span style="color: #f00;">couleur</span> ...

	<table border="1" cellspacing="0" cellpadding="4" align="center">
	   <tr> <td>Tableau</td> <td>par balises HTML</td> </tr> 
	</table>
	
	Paragraphe _normal_...

Utilisation de balises HTML : souligné, couleur 


Tableau par balises HTML

Paragraphe normal


Échappement de certains caractùres

A l’extĂ©rieur des structures de type code inline ou bloc de code, si l’on veut afficher les caractĂšres ci-dessous (qui ont sinon une signification Markdown ou Pandoc) il peut ĂȘtre nĂ©cessaire de les â€œĂ©chapper” en les prĂ©fixant par le caractĂšre backslash \


		\       backslash
		`       accent grave
		*       étoile/astérisque
		⎯       soulignĂ©
		+       plus
		-       tiret/moins
		(  )    parenthĂšses
		[  ]    parenthÚses carrées
		{  }    accolades
		<  >    crochets pointus (de balises)
		#       diĂšse
		@       arobase
		~       tilde
		.       point
		!       point d'exclamation

Installation et utilisation du convertisseur Markdown original

Nous vous recommandons plutĂŽt d’utiliser le convertisseur Pandoc qui offre bien plus de possibilitĂ©s. Si vous tenez cependant Ă  tester le convertisseur Markdown original, sachez qu’il s’agit d’un simple script Perl sous license BSD tĂ©lĂ©chargeable via un lien au haut de la home-page du site Markdown. Il est donc nĂ©cessaire de disposer d’un interprĂ©teur Perl sur votre machine (ce qui est par dĂ©faut le cas sous Linux et Mac OS X, mais pas sous Windows oĂč vous pouvez utiliser le Strawberry Perl ou l’ActivePerl). La conversion d’un fichier Markdown en HTML s’effectue alors avec la commande : perl Markdown.pl fichier.md > fichier.html

Recherche