Le langage d’écriture de texte Markdown

3. Le langage d’écriture de texte Markdown#

Markdown est un langage de balisage léger créé en 2004 par John Gruber, qui a pour objectif d’offrir une syntaxe facile à lire et à écrire. Un document balisé par Markdown peut être lu en l’état sans donner l’impression d’avoir été balisé ou formaté par des instructions particulières.

L’approche utilisée privilégie le WYSIWYM portable (what you see is what you mean), signifiant «Ce que vous voyez est ce que vous voulez dire», par opposition au WYSIWYG (what you see is « only » what you get) (« Ce que vous voyez est « uniquement » ce que vous obtenez ») qui est utilisé par les traitements de texte de type Word. On représente les informations de façon portable en fonction de leur sens, avec une meilleure séparation du fond et de la forme lors de la création de documents, ce qui permet ensuite d’avoir plusieurs types de représentation du même document (format HTML pour le web, format PDF pour l’impression, …)

Un document balisé par Markdown est portable et peut être converti en HTML, en PDF ou en d’autres formats et est aussi très utilisé sur le Web dans les blogs ou les sites de partage github ou gitlab. Il permet en outre d’écrire des formules mathématiques en utilisant la syntaxe LaTeX qui est un standard pour l’écriture de formules mathématiques dans les revues scientifiques.

4. Un premier exemple#

Le texte suivant écrit en markdown

      # Equation du 2nd degré 
      - Racines réelles d'une équations du second degré 

        les **racines réelles**  d'une équation du second degré $a x^2 + b x + c$ sont données par la formule suivante

     $$ x_1, x_2 = \frac{ -b \pm \sqrt{b^2 - 4ac}}{2a} $$

      - Dans le cas de racines imaginaires, il faut que:

     $$ b^2 - 4 ac \lt 0  \mbox{ et }  
        x_1, x_2 = \frac{-b}{2a} \pm\mathrm{i} \frac{\sqrt{-\Delta}}{2a} $$

peut être compris tel quel et est rendu sous la forme ci-dessous:

4.1. Equation du 2nd degré#

  • Racines réelles d’une équations du second degré

les racines réelles d’une équation du second degré \(a x^2 + b x + c\) sont données par la formule suivante

\[ x_1, x_2 = \frac{ -b \pm \sqrt{b^2 - 4ac}}{2a} \]

  • Dans le cas de racines imaginaires

\[ b^2 - 4 ac \lt 0 \mbox{ et } x_1, x_2 = \frac{-b}{2a} \pm\mathrm{i} \frac{\sqrt{-\Delta}}{2a} \]

5. Formatage en markdown#

attention on écrit le texte au kilomètre sans se soucier de la mise en page

  • Mais il faut bien séparer les paragraphes avec une ligne vide (aérer le texte !)

5.1. Titres et sections#

       # titre
       ## section niveau 2
       ### sous section niveau 3

5.2. Formatage de texte#

       **mots en gras**
       *idem en italique*

5.3. Listes#

liste non ordonnée

       - liste 1
       - liste 2

ou liste ordonnée

       1. premier
       2. second

5.4. Images#

pour inclure une image au format png, pdf ou jpeg:

          ![texte sous l'image}(nom du fichier)

par exemple:

          ![Figure 1: analyse de la fonction poly3](mafigure.png)

permet l’inclusion de la figure suivante:

Figure 1: analyse de la fonction poly3

5.5. Formules mathématiques#

on utilise la syntaxe LaTeX qui décrit une formule et ne la dessine pas !

  • pour une formule en ligne on utilise $ formule $

par exemple:

l'expression suivante $ x^2+2x+1 = 0$  est une équation du second degré

devient:

l’expression suivante \(x^2+2x+1 = 0\) est une équation du second degré

  • pour une équation hors ligne on utilise $$ equation $$

par exemple:

La forme factorisée de l'équation s'écrit:

$$ x^2 + 2x + 1 = (x+1)^2 $$

devient:

La forme factorisée de l’équation s’écrit:

\[ x^2 + 2x + 1 = (x+1)^2 \]

5.6. Liens#

on peut inserer un lien vers une page web en utilisant une syntaxe similaire à celle des images

    [titre du lien](url du lien)

par exemple

    [compte rendu en markdown](markdown.html)

renvoie vers cette page web si on clique dessus: compte rendu en markdown

6. Ecriture de compte rendu en markdown#

Pour chacun des TP, on vous demandera d’écrire un compte rendu utilisant la notation markdown dans le fichier CompteRendu.md

Le format Markdown permet de rapidement et très simplement rédiger du texte structuré. Ce cours est par exemple complètement rédigé en Markdown :-)

6.1. Méthodologie#

  1. Utiliser le menu Fichier pour éditer le fichier de compte rendu au format markdown: CompteRendu.md dans un onglet du navigateur

  2. Modifier ce fichier en indiquant le nom du TP, votre nom et prenom et en remplissant les paragraphes.

    • Attention laisser bien des lignes vides pour indiquer des fins de paragraphes

    • inclusion de figure dans le compte rendu avec la ligne suivante séparée par 2 lignes blanches:

           ![figure xx: titre de la figure](mafigure.png)

    • attention à bien sauter une ligne avec et après cette commande et penser à commenter chaque figure !

  3. Utiliser ensuite la commande ci-dessous pour générer une version en html avec mise en page du compte-rendu.

         !genereTPhtml CompteRendu

  1. Visualisation du Compte Rendu au format html

    • Cliquez sur le fichier CompteRendu.html pour l’ouvrir dans un onglet du navigateur

6.2. Exemple de compte rendu de TP écrit en markdown#

Quinze pendules simples non couplés de longueurs monotones croissantes dansent ensemble pour produire des ondes visuelles progressives, des ondes stationnaires, des battements et (apparemment) des mouvements aléatoires. L’objectif de l’étude est de construire un modèle explicatif du mouvement de pendules dansants (swinging pendulum) en utilisant un notebook Python et ses possibilités de visualisation.

Le compte rendu suivant sur cette analyse de la danse des pendules « swinging pendulum » est écrit en markdown et convertit en html et pdf avec la commande suivante:

genereTPhtml CompteRendu

7. Bibliographie#

Nous vous conseillons d’explorer les possibilités du Markdown en consultant le site suivant:

pour aller plus loin:

Contenu