02-Markdown.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"color:#FFF; background:#07D; padding:12px; font-size:20px; font-style:italic; text-align:center\">\n",
    "<span style=\"width:49%; display:inline-block; text-align:left\">Christophe Schlick</span>\n",
    "<span style=\"width:49%; display:inline-block; text-align:right\">schlick[at]u-bordeaux.fr</span>\n",
    "<span style=\"font-size:48px; font-style:normal\"><b>MARKDOWN</b></span><br>\n",
    "<span style=\"width:49%; display:inline-block; text-align:left\">Version 2022-06</span>\n",
    "<span style=\"width:49%; display:inline-block; text-align:right\">Licence CC-BY-NC-ND</span></p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Comme indiqué dans le chapitre d'introduction, les **cellules de texte** présentes dans un notebook Jupyter, vont être écrites et formatées en utilisant la syntaxe du langage **Markdown**. La documentation complète du langage Markdown se trouve le site [**markdownguide.org**](https://www.markdownguide.org/), mais une copie locale est directement accessible dans le menu **`Help`** de JupyterLab, sous le titre ***Markdown Reference***.\n",
    "\n",
    "En pratique, il s'avère que ce langage est tellement simple que la lecture d'un simple exemple commenté (comme celui présenté dans ce notebook) permet de comprendre la quasi-totalité de ses fonctionnalités. Pour étudier le contenu du notebook et comprendre les commandes **Markdown** mises en oeuvre, l'idéal est de sélectionner chaque cellule à tour de rôle (clic sur la marge gauche) puis d'alterner entre le mode ***edit*** (appui sur **<kbd>ENTER</kbd>** ) pour voir la syntaxe du document Markdown, et le mode ***view*** (appui sur **<kbd>CTRL</kbd>** + **<kbd>ENTER</kbd>** ) pour voir le résultat visuel.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Ceci est un titre de niveau 1\n",
    "`= ligne préfixée par #`\n",
    "## Ceci est un titre de niveau 2\n",
    "`= ligne préfixée par ##`\n",
    "### Ceci est un titre de niveau 3\n",
    "`= ligne préfixée par ###`\n",
    "#### Ceci est un titre de niveau 4\n",
    "`= ligne préfixée par ####`\n",
    "##### Ceci est un titre de niveau 5\n",
    "`= ligne préfixée par #####`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "---\n",
    "Ceci est un paragraphe standard aligné à gauche et libre à droite.\n",
    "Toutes les lignes attenantes sont insérées dans le même paragraphe.\n",
    "Seul un saut de ligne permet de créer un nouveau paragraphe.\n",
    "Ceci est un paragraphe standard aligné à gauche et libre à droite.\n",
    "Toutes les lignes attenantes sont insérées dans le même paragraphe.\n",
    "Seul un saut de ligne permet de créer un nouveau paragraphe.\n",
    "Ceci est un paragraphe standard aligné à gauche et libre à droite.\n",
    "\n",
    "Ceci est un nouveau paragraphe qui sert d'entête à une **citation** :<br>\n",
    "`= ligne préfixée par >`\n",
    "\n",
    "> *Ceci est une citation qui va être indentée à gauche et à droite.\n",
    "Toutes les lignes attenantes sont insérées dans la même citation.\n",
    "Seul un saut de ligne permet de créer un nouveau paragraphe ou une nouvelle citation*\n",
    "\n",
    "> Ceci est une nouvelle citation qui sert d'entête à une citation secondaire :\n",
    ">> *Ceci est une citation secondaire qui va donc être doublement indentée à gauche et à droite\n",
    "Toutes les lignes attenantes sont insérées dans la même citation.\n",
    "Seul un saut de ligne permet de créer un nouveau paragraphe ou une nouvelle citation*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "---\n",
    "Ceci est un nouveau paragraphe qui sert d'entête à une **énumération** :<br>\n",
    "`= suite de lignes préfixées par 1.`\n",
    "\n",
    "1. Mon premier est une boisson\n",
    "1. Mon second est une boisson\n",
    "1. Mon troisième est une boisson\n",
    "1. Mon tout est une boisson\n",
    "\n",
    "Ceci est un nouveau paragraphe qui sert d'entête à une **liste** :<br>\n",
    "`= suite de lignes préfixées par * ou -`\n",
    "\n",
    "* Elément contenant du *texte en italique*<br>\n",
    "  `= texte encadré par * ... * ou _ ... _`\n",
    "* Elément contenant du **texte en gras**<br>\n",
    "  `= texte encadré par ** ... ** ou __ ... __`\n",
    "* Elément contenant du ***texte en italique gras***<br>\n",
    "  `= texte encadré par *** ... *** ou ___ ... ___`\n",
    "* Elément contenant du ~~texte barré~~<br>\n",
    "  `= texte encadré par ~ ... ~ ou ~~ ... ~~`\n",
    "* [X] Elément contenant une case cochée<br>\n",
    "  `= texte préfixé par un [X]`\n",
    "* [ ] Elément contenant une case non cochée<br>\n",
    "  `= texte préfixé par un [ ]`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "---\n",
    "Ceci est un nouveau paragraphe qui sert d'entête à une autre **liste** :<br>\n",
    "`= suite de lignes préfixées par * ou -`\n",
    "\n",
    "* Elément contenant des caractères Unicode quelconques : 🙂👍🌞⛔<br>\n",
    "  `= faire un copier-coller depuis un document contenant le caractère souhaité`\n",
    "* Elément contenant des caractères Unicode quelconques : &#9824; &#9827; &#9829; &#9830;<br>\n",
    "  `= code décimal du caractère encadré par &# ... ; (syntaxe HTML)`\n",
    "* Elément contenant une équation mathématique : $e^{\\,i\\pi} + 1 = 0$<br>\n",
    "  `= texte encadré par $ ... $ (syntaxe LaTeX)`\n",
    "* Elément contenant un extrait de code source : `x, y = minmax(x, y)`<br>\n",
    "  ``  = texte encadré par ` ...` ou`` ` `` ... `` `\n",
    "* Elément contenant un lien hypertexte local : [Jupyter Logo](IMG/jupyter.png)<br>\n",
    "  `= texte encadré par [ ... ] et adresse encadrée par ( ... )`\n",
    "* Elément contenant un lien hypertexte distant : [Jupyter Website](https://www.jupyter.org)<br>\n",
    "  `= adresse préfixée par 'http://' ou autre protocole standard`\n",
    "* Elément contenant lui-même une liste :<br>\n",
    "  `= suite de lignes indentées, préfixées par * ou -`\n",
    "  - aaa\n",
    "  - bbb\n",
    "  - ccc\n",
    "* Element contenant lui-même une énumération :<br>\n",
    "  `= suite de lignes indentées, préfixées par 1.`\n",
    "  1. aaa\n",
    "  2. bbb\n",
    "  3. ccc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "---\n",
    "Ceci est un nouveau paragraphe qui sert d'entête à un **bloc d'équations** :<br>\n",
    "`= bloc encadré par $$ ... $$`\n",
    "\n",
    "$$\\left\\{\\begin{align}\n",
    "e^{\\,i\\pi} + 1 &= 0 &&\\textrm{(identité d'Euler)}\\\\\n",
    "F(\\omega) &= \\int_{-\\infty}^{+\\infty} f(t)\\,e^{-2\\pi i\\, \\omega t}\\, dt &&\\textrm{(transformée de Fourier continue)}\\\\\n",
    "S_m &= \\sum_{n\\,=\\,0}^{N-1} s_n\\, e^{-2\\pi i\\frac{m\\,n}{N}} &&\\textrm{(transformée de Fourier discrète)}\n",
    "\\end{align}\\right.$$\n",
    "\n",
    "Ceci est un nouveau paragraphe qui sert d'entête à un **bloc de code** :<br>\n",
    "`= bloc encadré par ``` ... ``` ou ~~~ ... ~~~` \n",
    "\n",
    "```python\n",
    "def fibo(n):\n",
    "  a, b = 0, 1\n",
    "  for loop in range(n):\n",
    "    a, b = b, a + b\n",
    "  return a\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "---\n",
    "Ceci est un nouveau paragraphe qui sert d'entête à une **image** :<br>\n",
    "`= lien hypertexte préfixé par !`\n",
    "\n",
    "Avec la syntaxe Mardown, les **images matricielles** (formats ***PNG***, ***JPG***, ***GIF***...) sont insérées avec une taille par défaut correspondant à leur résolution en pixels, et sont systématiquement alignées sur la marge gauche du notebook :\n",
    "\n",
    "![](IMG/smiley.png 'Ceci est une image de smiley (format PNG)')\n",
    "![](IMG/smiley.png 'Ceci est une image de smiley (format PNG)')\n",
    "![](IMG/smiley.png 'Ceci est une image de smiley (format PNG)')\n",
    "\n",
    "Pour changer la taille ou l'alignement des images, il faut passer par la syntaxe HTML :\n",
    "\n",
    "<center> <!-- solution simple pour centrer horizontalement -->\n",
    "  <img src=IMG/smiley.png  width=100 title='Ceci est une image de smiley (format PNG)'>\n",
    "  <img src=IMG/smiley.png  width=200 title='Ceci est une image de smiley (format PNG)'>\n",
    "  <img src=IMG/smiley.png  width=400 title='Ceci est une image de smiley (format PNG)'>\n",
    "</center>\n",
    "\n",
    "Avec la syntaxe Mardown, les **images vectorielles** (formats ***SVG***, ***VL***, ***EPS***...) sont insérées avec une taille par défaut correspondant à la largeur de page du notebook (il ne peut donc y avoir qu'une image sur une même ligne) :\n",
    "\n",
    "![](IMG/smiley.svg 'Ceci est une image de smiley (format SVG)')\n",
    "\n",
    "Pour afficher plusieurs images vectorielles sur une même ligne, changer leur taille ou leur alignement, il faut passer par la syntaxe HTML :\n",
    "\n",
    "<center> <!-- solution simple pour centrer horizontalement et verticalement -->\n",
    " <img src=IMG/smiley.svg  width=100 align=middle title='Ceci est une image de smiley (format SVG)'>\n",
    " <img src=IMG/smiley.svg  width=200 align=middle title='Ceci est une image de smiley (format SVG)'>\n",
    " <img src=IMG/smiley.svg  width=400 align=middle title='Ceci est une image de smiley (format SVG)'>\n",
    "</center>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "---\n",
    "Ceci est un nouveau paragraphe qui sert d'entête à une **table** :<br>\n",
    "`= cellules encadrées par | ... |`\n",
    "\n",
    "| Titre A | Titre B | Titre C |\n",
    "| :--- | :---: | ---: |\n",
    "| aa | aa | aa |\n",
    "| bbbb | bbbb | bbbb | \n",
    "| cccccc | cccccc | cccccc |\n",
    "| dddddddd | dddddddd | dddddddd |\n",
    "| texte aligné à gauche | texte centré | texte aligné à droite |\n",
    "\n",
    "On peut mélanger arbitrairement du texte, du code, des équations, des images et des liens hypertextes dans une table :\n",
    "\n",
    "| Jupyter | Python | Numpy | Scipy | Sympy | Pandas | Matplotlib | \n",
    "| :---: | :---: | :---: | :---: | :---: | :---: | :---: |\n",
    "| [![](IMG/jupyter.png)](https://www.jupyter.org) | [![](IMG/python.png)](https://www.python.org) | [![](IMG/numpy.png)](https://www.numpy.org) | [![](IMG/scipy.png)](https://www.scipy.org) | [![](IMG/sympy.png)](https://www.sympy.org)| [![](IMG/pandas.png)](https://pandas.pydata.org/) | [![](IMG/matplotlib.png)](https://www.matplotlib.org) |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "---\n",
    "Si on souhaite créer des tables avec une mise en page plus complexe, il faut à nouveau passer par la syntaxe HTML :\n",
    "\n",
    "<table style=\"border:3px solid black\">\n",
    "<tr style=\"background:white\">\n",
    "  <th style=\"border:2px solid black\"></th>\n",
    "  <th style=\"border:2px solid black\">Colonne A</th>\n",
    "  <th style=\"border:2px solid black\">Colonne B</th>\n",
    "  <th style=\"border:2px solid black\">Colonne C</th>\n",
    "  <th style=\"border:2px solid black\">Colonne D</th>\n",
    "</tr><tr style=\"background:white\">\n",
    "  <th style=\"border:2px solid black\">Ligne 1</th>\n",
    "  <td style=\"border:1px solid black; text-align:left\">aa</td>\n",
    "  <td style=\"border:1px solid black; text-align:center; font-size:32px; color:#000\"\n",
    "      rowspan=3>&#9824;<br>&#9827;</td>\n",
    "  <td style=\"border:1px solid black; text-align:center; font-size:32px; color:#F00\"\n",
    "      rowspan=3>&#9829;<br>&#9830;</td>\n",
    "  <td style=\"border:1px solid black; text-align:right\">aa</td>\n",
    "</tr><tr style=\"background:white\">\n",
    "  <th style=\"border:2px solid black;\">Ligne 2</th>\n",
    "  <td style=\"border:1px solid black; text-align:left\">bbbb</td>\n",
    "  <td style=\"border:1px solid black; text-align:right\">bbbb</td>\n",
    "</tr><tr style=\"background:white\">\n",
    "  <th style=\"border:2px solid black;\">Ligne 3</th>\n",
    "  <td style=\"border:1px solid black; text-align:left\">cccccc</td>\n",
    "  <td style=\"border:1px solid black; text-align:right\">cccccc</td>\n",
    "</tr><tr style=\"background:white\">\n",
    "  <th style=\"border:2px solid black;\">Ligne 4</th>\n",
    "  <td style=\"border:1px solid black; text-align:left\">dddddddd</td>\n",
    "  <td style=\"border:1px solid black; text-align:center; font-size:16px\" colspan=2>$e^{\\,i\\pi} + 1 = 0$</td>\n",
    "  <td style=\"border:1px solid black; text-align:right\">dddddddd</td>\n",
    "</tr><tr style=\"background:white\">\n",
    "  <th style=\"border:2px solid black;\">Ligne 5</th>\n",
    "  <td style=\"border:1px solid black; text-align:right\" colspan=2> <img src=IMG/smiley.svg width=60></td>\n",
    "  <td style=\"border:1px solid black; text-align:left\"  colspan=2> <img src=IMG/smiley.svg width=60></td>\n",
    "</tr>\n",
    "  <caption><h4 style=\"text-align:center\">Ceci est le titre d'une table créée en HTML</h4></caption>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "---\n",
    "Comme on l'a vu ci-dessus pour le cas des images et des tables, l'inclusion de code HTML dans une cellule de texte écrite en Markdown permet d'obtenir un contrôle beaucoup plus précis de la mise en page, ce qui peut s'avérer utile de temps en temps. Néanmoins, pour ne pas alourdir la structure des cellules de texte, il faut veiller à ce que le recours au code HTML reste assez rare dans les notebooks. Habituellement, on considère que l'inclusion de code HTML n'est judicieux que pour les quatre situations suivantes :\n",
    "\n",
    "- mettre en forme les titres des chapitres et des sections d'un notebook\n",
    "- inclure des images dont on souhaite modifier la taille et/ou la position\n",
    "- inclure des éléments audio ou vidéo\n",
    "- créer des tables avec une composition complexe (les tables qui ne sont pas de simples matrices)\n",
    "\n",
    "La plupart du temps, les balises HTML incluses dans les cellules de texte vont utiliser la propriété **`style=...`** qui donne accès aux différents paramètres standards fournis par le langage [**CSS**](https://fr.wikipedia.org/wiki/Feuilles_de_style_en_cascade) (Cascading Style Sheets). Par exemple, on peut intégrer directement une ligne ou un paragraphe formaté par des paramètres CSS, comme dans cet exemple déjà rencontré à la fin du chapitre 1 :\n",
    "\n",
    "<p style=\"background:#07D; color:#FFF; font-size:40px; font-weight:700; text-align:center\"> ABCDEFGHIJKLMNOPQRSTUVWXYZ </p>\n",
    "\n",
    "Les balises **`<audio>`** et **`<video>`** sont également utilisables, mais (à cause d'un bug dans l'interpréteur Markdown) ces balises doivent impérativement être la dernière instruction de la cellule de texte."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "Inclusion d'un fichier audio dans une cellule de texte (via la balise **`<audio>`**) :\n",
    "\n",
    "<center> <audio controls loop src='IMG/beep.ogg'/> </center>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "Inclusion d'un fichier vidéo dans une cellule de texte (via la balise **`<video>`**) :\n",
    "\n",
    "<center> <video controls loop src=\"IMG/noise.mp4\" /> </center>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "Par contre, la balise **`<style>`** ne peut être directement utilisée dans une cellule de texte, ce qui signifie qu'il sera impossible de créer et nommer un style pour le réutiliser à plusieurs endroits. De même, la balise **`<iframe>`** est également interdite dans les cellules de texte, ce qui empêche d'y intégrer directement des vidéos en streaming ou des extraits d'un site web existant. Pour ces cas de figure, la mise en oeuvre d'une cellule de code contenant la commande magique **`%%html`** (comme on l'a vu au chapitre 1) ou utilisant le module **`display`** (comme nous le verrons au chapitre 3) restent les seules options fonctionnelles.\n",
    "\n",
    "---"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}