MarkDown Mkdocs-Material pour le contenu#

Introduction#

Rendu MarkDownMarkDownHTMLRendu HTML :

Logo

Markdown est un langage de description à balisage plus léger à coder que des balises HTML.
Son code est plus lisible dans l'éditeur, plus pratique et rapide pour rédiger et publier un document sur le Web.

Cliquer sur les onglets ci-dessus pour comparer les codes MarkDown et HTML qui produisent ce même Rendu

Le principal défaut de MarkDown est son manque d'unification : il existe plusieurs versions de ce langage qui, à partir d'une syntaxe de base commune, possèdent d'autres éléments additionnels souvent très spécifiques...

Cependant il est de plus en plus utilisé :

incontournable sur GitHub,
le site de partage d'informations Reddit,
l'éditeur collaboratif en ligne HedgeDoc,
les forums Discourse, Stack Overflow...

Mais c'est surtout le langage que nous utiliserons pour rédiger du texte enrichi dans nos notebook jupyter et nos pages web rédigées avec le MarkDown de Mkdocs tel que présenté ici.

Remarque :

Vous avez toujours la possibilité de coder en HTML dans les fichiers.md de Mkdocs, comme dans les cellules MarkDown d'un notebook jupyter...

Par exemple, pour écrire des commentaires dans un code en MarkDown on utilise la syntaxe HTML : 

![Logo]{ align=left }

[**Markdown**][1]{target="_blank"} est un langage de description à balisage plus léger à coder que des balises HTML.  
Son code est plus lisible dans l'éditeur,
    plus pratique et rapide pour rédiger et publier un document sur le Web.

> Cliquer sur les onglets ci-dessus pour comparer les codes **MarkDown** et **HTML** qui produisent ce même **Rendu**

Le principal défaut de MarkDown est son manque d'unification :
    il existe plusieurs versions de ce langage qui,
    à partir d'une syntaxe de base commune,
    possèdent d'autres éléments additionnels souvent très spécifiques...  

Cependant il est de plus en plus utilisé :

- incontournable sur [GitHub]{target="_blank"},
- le site de partage d'informations [Reddit]{target="_blank"},
- l'éditeur collaboratif en ligne [HedgeDoc]{target="_blank"},
- les forums [Discourse]{target="_blank"},
    [Stack Overflow]{target="_blank"}...

Mais c'est surtout le langage que nous utiliserons pour rédiger du texte enrichi
    dans nos [notebook jupyter][bn-md]{target="_blank"} 
    et nos pages web rédigées avec le MarkDown de Mkdocs tel que présenté ici.

> **Remarque** :
>
> Vous avez toujours la possibilité de coder en HTML
    dans les `fichiers.md` de Mkdocs,
    comme dans les cellules MarkDown
    d'un [notebook jupyter][bn-html]{target="_blank"}...
>
> Par exemple, pour écrire des commentaires dans un code en MarkDown
on utilise la syntaxe HTML : `<!-- mon commentaire -->`

<!-- Ceci est un commentaire qui ne sera donc pas affiché
Liste des liens pour l'introduction : -->

[1]: https://fr.wikipedia.org/wiki/Markdown "Page Markdown sur Wikipedia" 
[GitHub]: https://guides.github.com/features/mastering-markdown/ "Guide MarkDown de GitHub"
[Reddit]: https://www.reddit.com/wiki/markdown "Guide MarkDown de Reddit"
[HedgeDoc]: https://demo.hedgedoc.org/features?both "Page de demonstration du Markdown de HedgeDoc"
[Discourse]: https://forum.digikey.com/t/an-unofficial-discourse-user-reference-guide/1125/4  "Référence MarkDown pour Discourse"
[Stack Overflow]: https://stackoverflow.com/editing-help "Aide Markdown de Stack Overflow"
[bn-md]: ../MarkDown-Le_BN_pour_rapporter "Notebook d'initiation au Markdown de Jupyter"
[bn-html]: ../HTML-Le_BN_pour_multimedier "Notebook d'initiation au HTML de Jupyter"
[Logo]: https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg "Logo du langage MarkDown"

<img src="https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg" align="left" title="Logo du langage MarkDown" alt="Logo du langage MarkDown">

<p>
    <a href="https://fr.wikipedia.org/wiki/Markdown" target="_blank" title="Page Markdown sur Wikipedia"><strong>Markdown</strong></a>
    est un langage de description à balisage plus léger à coder que des balises HTML.
    <br>
    Son code est plus lisible dans l'éditeur,
    plus pratique et rapide pour rédiger et publier un document sur le Web.
</p>

<blockquote>
    <p>
        Cliquer sur les onglets ci-dessus pour comparer les codes <strong>MarkDown</strong>
        et <strong>HTML</strong> qui produisent ce même <strong>Rendu</strong>
    </p>
</blockquote>
<p>
    Le principal défaut de MarkDown est son manque d'unification : 
    il existe plusieurs versions de ce langage qui,
    à partir d'une syntaxe de base commune,
    possèdent d'autres éléments additionnels souvent très spécifiques...  
</p>
<p>
    Cependant il est de plus en plus utilisé :
    <ul>
        <li>
            incontournable sur <a href="https://guides.github.com/features/mastering-markdown/" target="_blank" title="Guide MarkDown de GitHub">GitHub</a>,
        </li>
        <li>
            le site de partage d'informations <a href="https://www.reddit.com/wiki/markdown" target="_blank" title="Guide MarkDown de Reddit">Reddit</a>,
        </li>
        <li>
            l'éditeur collaboratif en ligne <a href="https://demo.hedgedoc.org/features?both" target="_blank" title="Page de demonstration du Markdown de HedgeDoc">HedgeDoc</a>,
        </li>
        <li>
            les forums <a href="https://forum.digikey.com/t/an-unofficial-discourse-user-reference-guide/1125/4" target="_blank" title="Référence MarkDown pour Discourse">Discourse</a>,
            <a href="https://stackoverflow.com/editing-help" target="_blank" title="Aide Markdown de Stack Overflow">Stack Overflow</a>...
        </li>
    </ul>
    Mais c'est surtout le langage que nous utiliserons pour rédiger du texte enrichi
    dans nos <a href="../MarkDown-Le_BN_pour_rapporter" target="_blank" title="Notebook d'initiation au Markdown de Jupyter">notebook jupyter</a> 
    et nos pages web rédigées avec le MarkDown de Mkdocs tel que présenté ici.
</p>
<blockquote>
    <p>
        <strong>Remarque</strong> :
    </p>
    <p>
        Vous avez toujours la possibilité de coder en HTML
        dans les <code>fichiers.md</code> de Mkdocs,
        comme dans les cellules MarkDown d'un 
        <a href="../HTML-Le_BN_pour_multimedier" target="_blank" title="Notebook d'initiation au HTML de Jupyter">notebook jupyter</a>...
    </p>
    <p>
        Par exemple, pour écrire des commentaires dans un code en MarkDown
        on utilise la syntaxe HTML : <code>&lt;!-- mon commentaire --&gt;</code>
    </p>  
</blockquote>
<!-- Ceci est un commentaire qui ne sera donc pas affiché -->

Logo du langage MarkDown

Markdown est un langage de description à balisage plus léger à coder que des balises HTML.
Son code est plus lisible dans l'éditeur, plus pratique et rapide pour rédiger et publier un document sur le Web.

Cliquer sur les onglets ci-dessus pour comparer les codes MarkDown et HTML qui produisent ce même Rendu

Le principal défaut de MarkDown est son manque d'unification : il existe plusieurs versions de ce langage qui, à partir d'une syntaxe de base commune, possèdent d'autres éléments additionnels souvent très spécifiques...

Cependant il est de plus en plus utilisé :

incontournable sur GitHub,
le site de partage d'informations Reddit,
l'éditeur collaboratif en ligne HedgeDoc,
les forums Discourse, Stack Overflow...

Mais c'est surtout le langage que nous utiliserons pour rédiger du texte enrichi dans nos notebook jupyter et nos pages web rédigées avec le MarkDown de Mkdocs tel que présenté ici.

Remarque :

Vous avez toujours la possibilité de coder en HTML dans les fichiers.md de Mkdocs, comme dans les cellules MarkDown d'un notebook jupyter...

Par exemple, pour écrire des commentaires dans un code en MarkDown on utilise la syntaxe HTML : 

Titres#

MarkDown

# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
##### Titre de niveau 5
###### Titre de niveau 6
####### Il n'y a pas de titre de niveau 7

Autres solutions pour obtenir des titres de niveau 1 et 2 :

MarkDown

Souligner avec des `=` produit un titre de niveau 1
===================================================

Souligner avec des `-` produit un titre de niveau 2
---------------------------------------------------

Remarque :

Un seul = ou - suffirait.
Leur répétition permet de souligner ces titres également dans le code en mode édition.

Titres, titre de page et table des matières automatique : ...

En pratique, un fichier MarkDown source.md du dossier docs ne doit comporter, au plus, qu'un titre de niveau 1 qui peut potentiellement devenir le titre de la page web. De même pour un Notebook Jupyter source.ipynb du dossier docs.
A partir des titres de niveau 2, MkDocs génère automatiquement une table des matières pour naviguer dans la page courante.
La profondeur des sous-titres souhaités est réglable. Une profondeur fixée à la valeur 0 désactive l'affichage de la table des matières.

Pour cela, il faut activer dans le fichier mkdocs.yml l'extension toc (table of contents) en précisant les options souhaitées : plus petit niveau de titre à intégrer, ajout de lien vers les ancres des titres,...

Par exemple pour ce site :

markdown_extensions:
    - toc:                          # Table des matières générée automatiquement à partir des titres du niveau 2
        permalink: "&num;"          # Ajoute un symbole lien hypertexte vers l'ancre du titre #le-titre 
        toc_depth: 4                # Limite de la profondeur d'inclusion des titres dans la table des matières

Corps de texte#

RenduMarkDown

On peut obtenir du texte avec simple emphase rendu en italique, du texte avec forte emphase rendu en Gras, du Texte à la fois en gras et en italique, du code source rendu en caractères monospaces, du ~~texte barré~~ rendu avec une ligne en travers du texte, du texte souligné rendu avec une ligne en dessous du texte. On peut aussi mettre en _indice ou en ^exposant et même surligné.

En regardant le code qui produit cette phrase, vous remarquerez que même si on fait des retours à la ligne dans le code, le texte s'affiche sans rupture dans un seul et même paragraphe et les espaces laissés en trop sont supprimés...

Pour former des paragraphes séparés, il faut laisser une ligne vide entre eux.

Pour forcer le retour à la ligne dans un paragraphe,
il faut ajouter deux espaces à la fin d'une ligne
avant de faire un retour à la ligne...

On peut obtenir du _texte_ avec *simple emphase* rendu en *italique*,
 du __texte__ avec **forte emphase** rendu en **Gras**,
  du **_Texte_** à la fois en **gras** et en *italique*,
   du `code source` rendu en caractères `monospaces`,
    du ~~texte barré~~  rendu avec une ligne en travers du texte,
     du ^^texte souligné^^  rendu avec une ligne en dessous du texte.
      On peut aussi mettre en ~indice~ ou en ^exposant^ et même ==surligné==.

En regardant le code
qui produit cette phrase,
vous remarquerez que
même
si
on
fait 
des
retours
à
la
ligne
dans
le
code,
le texte                s'affiche              sans rupture
dans un seul            et                  même paragraphe
et les espaces      laissés en trop         sont supprimés...

Pour former des paragraphes séparés, il faut laisser une ligne vide entre eux.

Pour forcer le retour à la ligne dans un paragraphe,  
il faut ajouter deux espaces à la fin d'une ligne  
avant de faire un retour à la ligne...

Complément pour ajouter des marquages et commentaires de révision : ...

Rendu TexteRendu CodeMarkDown

Du texte, comme du code, peuvent être révisés¹ : ~~à enlever~~ ou à ajouter ; Ceci peut être fait en ~~deux~~une seule opération.
Et aussi surligné avec un commentaire lié.

Un formatage peut être appliqué à tout un bloc de lignes et paragraphes :

Il faut commencer par un saut de ligne pour commencer un nouveau bloc ;
Puis l'encadrer globalement entre les balises ouvrantes et fermantes souhaitées, disposées chacune sur leur propre ligne ;
Sans oublier de laisser un saut de ligne avant et après le contenu à marquer.

Du texte, comme du code, peuvent être révisés[^critic] :
 à enlever ou à ajouter ; 
  Ceci peut être fait en deuxune seule opération.  
   Et aussi surligné avec un commentaire lié.



Un formatage peut être appliqué à tout un bloc de lignes et paragraphes :





* Il faut commencer par un saut de ligne pour commencer un nouveau bloc ;
* Puis l'encadrer globalement entre les balises ouvrantes et fermantes souhaitées,
 disposées chacune sur leur propre ligne ;
* Sans oublier de laisser un saut de ligne avant et après le contenu à marquer.

Code markDown de marquage de Texte & Code

Astuces pour obtenir au clavier les caractères spéciaux comme ~, `, {ou }: ...

Le tilde s'obtient avec la combinaison de touches AltGr＋é ;
L'accent grave s'obtient avec la combinaison de touches AltGr＋è ;
Les accolades (braces) ouvrante et fermante s'obtiennent respectivement avec les combinaisons de touches AltGr＋' et AltGr＋=

Info

Il faut activer dans le fichier mkdocs.yml les extensions :

markdown_extensions:
    - pymdownx.caret
    - pymdownx.mark
    - pymdownx.tilde
    - pymdownx.critic

pymdownx.caret pour ^^souligné^^ ou mettre en ^exposant^;
pymdownx.mark pour ==surligné==;
pymdownx.tilde pour ~~barré~~ ou mettre en ~indice~ ;
pymdownx.critic pour du marquage et des commentaires de révision.

Lien#

MarkDownRendu

Le plus simple pour intégrer un lien hypertexte est de coller son adresse
directement entre deux chevrons `<URL>` comme par exemple : <https://www.mkdocs.org/> ;
De cette façon on peut aussi indiquer une adresse `<mail>` : <prenom.nom@ecmorlaix.fr>.

La syntaxe `[texte](adresse "info-bulle")` lie une adresse à un texte support
avec l'affichage optionnel d'une info-bulle au survol du lien :
par exemple, voici [un lien relatif](./#introduction "Introduction au MarkDown de Mkdocs avec Material")
vers l'introduction de cette page, et
[un lien absolu]( https://ericecmorlaix.github.io/adn-Tutoriel_site_web/MarkDown-Mkdocs_Material/#introduction
"Introduction au MarkDown de Mkdocs avec Material") qui renvoie au même titre.

Le plus simple pour intégrer un lien hypertexte est de coller son adresse directement entre deux chevrons <URL> comme par exemple : https://www.mkdocs.org/ ; De cette façon on peut aussi indiquer une adresse <mail> : prenom.nom@ecmorlaix.fr.

La syntaxe [texte](adresse "info-bulle") lie une adresse à un texte support avec l'affichage optionnel d'une info-bulle au survol du lien : par exemple, voici un lien relatif vers l'introduction de cette page, et un lien absolu qui renvoie au même titre.

Parce que de longues adresses de liens dégradent la lisibilité du texte en mode édition de code, MarkDown permet de définir des liens par référence.
Dans ce cas, on définit tous les liens à un endroit du document, en dehors du texte (généralement rassemblé), avec la syntaxe :

[référence]: adresse "info-bulle"

et au fil du texte on lie cette adresse par sa référence à un texte support avec la syntaxe [texte][référence] ou encore tout simplement [référence].
Cette solution offre aussi l'avantage de pouvoir partager la même adresse par plusieurs liens en ne la définissant qu’une fois dans le document.

Pour exemple :

Le code MarkDown du paragraphe d'introduction comporte de nombreux liens de ce type, tous listés à la fin du texte de cette partie :

![Logo]{ align=left }

[**Markdown**][1]{target="_blank"} est un langage de description à balisage plus léger à coder que des balises HTML.  
Son code est plus lisible dans l'éditeur,
    plus pratique et rapide pour rédiger et publier un document sur le Web.

> Cliquer sur les onglets ci-dessus pour comparer les codes **MarkDown** et **HTML** qui produisent ce même **Rendu**

Le principal défaut de MarkDown est son manque d'unification :
    il existe plusieurs versions de ce langage qui,
    à partir d'une syntaxe de base commune,
    possèdent d'autres éléments additionnels souvent très spécifiques...  

Cependant il est de plus en plus utilisé :

- incontournable sur [GitHub]{target="_blank"},
- le site de partage d'informations [Reddit]{target="_blank"},
- l'éditeur collaboratif en ligne [HedgeDoc]{target="_blank"},
- les forums [Discourse]{target="_blank"},
    [Stack Overflow]{target="_blank"}...

Mais c'est surtout le langage que nous utiliserons pour rédiger du texte enrichi
    dans nos [notebook jupyter][bn-md]{target="_blank"} 
    et nos pages web rédigées avec le MarkDown de Mkdocs tel que présenté ici.

> **Remarque** :
>
> Vous avez toujours la possibilité de coder en HTML
    dans les `fichiers.md` de Mkdocs,
    comme dans les cellules MarkDown
    d'un [notebook jupyter][bn-html]{target="_blank"}...
>
> Par exemple, pour écrire des commentaires dans un code en MarkDown
on utilise la syntaxe HTML : `<!-- mon commentaire -->`

<!-- Ceci est un commentaire qui ne sera donc pas affiché
Liste des liens pour l'introduction : -->

[1]: https://fr.wikipedia.org/wiki/Markdown "Page Markdown sur Wikipedia" 
[GitHub]: https://guides.github.com/features/mastering-markdown/ "Guide MarkDown de GitHub"
[Reddit]: https://www.reddit.com/wiki/markdown "Guide MarkDown de Reddit"
[HedgeDoc]: https://demo.hedgedoc.org/features?both "Page de demonstration du Markdown de HedgeDoc"
[Discourse]: https://forum.digikey.com/t/an-unofficial-discourse-user-reference-guide/1125/4  "Référence MarkDown pour Discourse"
[Stack Overflow]: https://stackoverflow.com/editing-help "Aide Markdown de Stack Overflow"
[bn-md]: ../MarkDown-Le_BN_pour_rapporter "Notebook d'initiation au Markdown de Jupyter"
[bn-html]: ../HTML-Le_BN_pour_multimedier "Notebook d'initiation au HTML de Jupyter"
[Logo]: https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg "Logo du langage MarkDown"

Astuce pour faire ouvrir la page liée dans un nouvel onglet :

Par défaut, et contrairement à jupyter notebook, MkDocs ouvre la page web liée dans le même onglet que le document consulté.
L'extension attr_list activée dans le fichier mkdocs.yml permet de préciser des valeurs personnalisées aux attributs HTML et CSS.
Ainsi la syntaxe {target="_blank"} après le code d'un lien MarkDown modifie la valeur par défaut de l'attribut target afin d'ouvrir la page liée dans un nouvel onglet.

En résumé, la syntaxe complète en markdown d'un lien avec ce comportement est donc :

en ligne dans le texte :

[mon texte support](https://monlien.com "mon info-bulle"){target="_blank"}

par référence :

dans le texte :
```
[référence]{target="_blank"}
```

hors du texte

[référence]: https://monlien.com "mon info-bulle"

Image#

La syntaxe pour les images est la même que pour les liens hypertextes, mais avec un ! devant :

![texte alternatif](adresse "info-bulle")

L'info-bulle optionnelle s'affichera au survol de l'image.

Il est important de bien choisir le texte alternatif qui s'affichera lorsque l'image n'est pas disponible, car il permet aussi l'accessibilité pour les non-voyants et apporte de la sémantique pour les moteurs de recherche...

L'adresse est l'URL relative ou absolue qui permet d'atteindre le fichier lié en cheminant dans l'arborescence du site web, sachant que le dossier docs du projet MkDocs (cf. branche main du dépot GitHub) devient la racine du site une fois déployé (cf. branche gh-pagesdu dépot GitHub) :

Exemple :

chemin relatif à la pagechemin absolupar référence

![Illustration d'une photo instantané](../images/undraw_Polaroid.svg "image via URL relative")

![Illustration d'une photo instantané](https://ericecmorlaix.github.io/adn-Tutoriel_site_web/images/undraw_Polaroid.svg "image via URL absolue")

Ce qui permet d'ajouter facilement un [lien pour ouvrir cette image][polaroïd]{ target="_blank"} dans un nouvel onglet...

![polaroïd]

<!-- Une seule et même référence pour le lien et l'image, une référence plusieurs fois réutilisable dans ce document... -->
[polaroïd]: https://ericecmorlaix.github.io/adn-Tutoriel_site_web/images/undraw_Polaroid.svg "Illustration d'une photo instantané"

Ce qui permet d'ajouter facilement un lien pour ouvrir cette image dans un nouvel onglet...

polaroïd

Ici le fichier de l'image est placé dans un dossier nommé images lui même situé dans le dossier docs :

├── docs/
│   └── images/
│   │   └── undraw_Polaroid.svg
│   └── MarkDown-Mkdocs_Material.md
│   └── index.md
└─ mkdocs.yml

Une fois déployé ce dossier images sera à la racine du site :

└── site/
    ├── images/
    │   └── undraw_Polaroid.svg
    ├── MarkDown-Mkdocs_Material/
    │   ├── MarkDown-Mkdocs_Material.md
    │   ├── index.html
    ├── index.md
    ├── index.html
    ├── 404.html

Alors, le chemin relatif vers cette image depuis la page web index.html située dans le dossier MarkDown-Mkdocs_Material et générée à partir du fichier MarkDown-Mkdocs_Material.md sera ../images/undraw_Polaroid.svg car il faut sortir du dossier MarkDown-Mkdocs_Material pour pouvoir rentrer dans le dossier images.

Remarque 1 :

Un chemin relatif vers cette même image depuis la page web index.html située à la racine du site et générée à partir du fichier index.md serait ./images/undraw_Polaroid.svg.

Pour gérer l'alignement et la taille d'une image :

L'extension attr_list qui permet de préciser des valeurs personnalisées aux attributs HTML et CSS doit être activée dans le fichier mkdocs.yml :

    markdown_extensions:
        - attr_list

RenduMarkDown

polaroïd
Ainsi le code MarkDown suivant :

![polaroïd]{width=20% align=right}

placé au début du texte de ce paragraphe, produit l'affichage de l'image tel que ci-contre.

![polaroïd]{width=20% align=right}  
Ainsi le code MarkDown suivant :
```markdown
![polaroïd](../images/undraw_Polaroid.svg){width=20% align=right}
```
placé au début du texte de ce paragraphe, produit l'affichage de l'image tel que ci-contre.

Une explication en vidéo par Fred LELEU :

Les vidéos de Fred LELEU

Une image cliquable, support d'un lien :

Il suffit de remplacer le texte support d'un lien hypertexte par le code MarDown d'une image tel que :

[![texte alternatif](adresse)](adresse "info-bulle")

RenduMarkDown

[![polaroïd]{width=20%}](https://undraw.co/illustrations "Vers le site de unDraw"){target="_blank"}

Des solutions pour centrer une image :

Solution 1 : un code HTML...

CodeRendu

<figure>
    <img src="../images/undraw_Polaroid.svg"  alt="Illustration d'une photo instantané" width="300" >
    <figcaption>
        Un Polaroïd selon <a href="https://undraw.co/illustrations">unDraw</a>
    </figcaption>
</figure>

Pour une largeur en %, l'image est décalée par rapport à sa légende...

CodeRendu

<figure>
    <img src="../images/undraw_Polaroid.svg" alt ="Illustration d'une photo instantané" width="50%" >
    <figcaption>
        Un Polaroïd selon <a href="https://undraw.co/illustrations">unDraw</a>
    </figcaption>
</figure>

Ce décalage n'apparait pas pour une largeur indiquée en px ou en em.

Une explication en vidéo par Fred LELEU :

Les vidéos de Fred LELEU

Solution 2 : un code MarkDown...

L'extension attr_list qui permet de préciser des valeurs personnalisées aux attributs HTML et CSS doit être activée dans le fichier mkdocs.yml :

markdown_extensions:
    - attr_list

Il faut ajouter la spécification CSS supplémentaire dans le fichier docs/stylesheet/extra.css (Merci à Gilles) :

.center {
    display: block;
    margin: 0 auto;
}

L’insertion d’une image peut se faire maintenant avec la syntaxe :

![texte alternatif](adresse "info-bulle"){ .center }

RenduCode

polaroïd

![polaroïd]{ width="30%" .center }

Même avec une largeur en %, l'image est centrée mais il n'y a pas de légende centrée possible.

Solution 3 : un code hybride...

En plus de l'extension attr_list qui permet de préciser des valeurs personnalisées aux attributs HTML et CSS, il faut également activer dans le fichier mkdocs.yml l'extension md_in_html qui permet d'écrire du code MarkDown à l'intérieur de balises HTML :

markdown_extensions:
    - attr_list
    - md_in_html

Comme pour la solution précédente, il faut ajouter la spécification CSS supplémentaire dans le fichier docs/stylesheet/extra.css (Merci à Gilles) :

.center {
    display: block;
    margin: 0 auto;
}

Pour notre exemple, une syntaxe possible serait, sans oublier d'inscrire markdown dans les balises HTML qui contiendront du MarkDown :

CodeRendu

<figure markdown>
    ![polaroïd]{ width="50%" .center }
    <figcaption markdown>
        Un Polaroïd selon [unDraw](https://undraw.co/illustrations){target="_blank"}
    </figcaption>
</figure>

Quel format d'image pour le web ?

JPEG (Joint Photographic Expert Group): Parfait pour les photos et visuels colorés, c’est le format compressé le plus utilisé sur le web.
PNG (Portable Network Graphics): Idéal pour les images à fond transparent, graphique et logo.
SVG (Graphics Interchange Format): Format adapté aux images vectorielles, permet de les déformer sans altérer la qualité.
GIF (Graphics Interchange Format): Images animées idéale pour illustrer vos propos, fortement utilisé sur les réseaux sociaux.

Trait horizontal#

RenduMarkDown

Une série d'au moins trois *,

ou trois _,

ou trois - après un saut de ligne,

trace une ligne de séparation.

Une série d'au moins trois `*`,
***
ou trois `_`,
___
ou trois `-` après un saut de ligne,

---
trace une ligne de séparation.

Listes#

Liste à puces#

On commence par sauter une ligne, puis on place devant chaque item un caractère -, + ou *, suivi d'au moins d'une espace :

MarkDownRendu

* Un élement de ma liste ;
Une précision concernant cet élément...
- Un autre élément de ma liste ;
    * Un élément de ma sous-liste ;
    * Un autre élément de ma sous-liste ;
+ Encore un autre élément de ma liste.

Un élement de ma liste ;
Une précision concernant cet élément...
Un autre élément de ma liste ;
- Un élément de ma sous-liste ;
- Un autre élément de ma sous-liste ;
Encore un autre élément de ma liste.

Liste ordonnées#

On procède de même, mais en précédant chaque item d'un nombre suivi d'un ., la numérotation se fait alors automatiquement indépendamment du nombre indiqué :

MarkDownRendu

1. Le premier élement de ma liste ;  
Une précision concernant cet élément...
1. Le second élément de ma liste ;
    1. Le premier élément de ma sous-liste ;
    72. Le second élément de ma sous-liste ;
1024. Le troisième élément de ma liste.

Le premier élement de ma liste ;
Une précision concernant cet élément...
Le second élément de ma liste ;
1. Le premier élément de ma sous-liste ;
2. Le second élément de ma sous-liste ;
Le troisième élément de ma liste.

Liste de taches#

On insère [ ] ou [x] devant chaque item d'une liste non ordonnée pour ajouter des cases à cocher :

MarkDownRendu

- [ ] Une tâche de ma todo liste ;
- [x] Une autre tâche de ma todo liste ;
    - [x] une sous tâche de ma todo liste ;
    - [ ] une autre sous tâche de ma todo liste ;
- [ ] Encore une autre tâche de ma todo liste.

Une tâche de ma todo liste ;
Une autre tâche de ma todo liste ;
- une sous tâche de ma todo liste ;
- une autre sous tâche de ma todo liste ;
Encore une autre tâche de ma todo liste.

Info

Il faut activer dans le fichier mkdocs.yml l'extension pymdownx.tasklist pour générer des listes de tâches avec des cases à cocher.

markdown_extensions:
    - pymdownx.tasklist

Liste de description#

Sous la ligne d'un terme, on précède sa définition par un : suivi d'au moins une espace :

MarkDownRendu

**Premier terme** :
: Voici la définition du premier terme...

**Second terme** :
: Voici une définition pour le second terme...
: Voici une autre définition pour le second terme...

Premier terme :: Voici la définition du premier terme...
Second terme :: Voici une définition pour le second terme...; Voici une autre définition pour le second terme...

Info

Il faut activer dans le fichier mkdocs.yml l'extension def_list pour générer des listes de définitions.

markdown_extensions:
    - def_list

Citation#

Pour créer un bloc de citation, il suffit d'ajouter un > devant un paragraphe.

Les blocs de citation peuvent s'imbriqués tels que par exemple :

MarkDownRendu

> Cette première ligne est incluse dans un bloc de citation.
>
> Cette seconde ligne l'est également.
>> Celle ci se situe dans un bloc de citation imbriqué...

Cette première ligne est incluse dans un bloc de citation.

Cette seconde ligne l'est également.

Celle ci se situe dans un bloc de citation imbriqué...

On peut utiliser les blocs de citation pour souligner un point, comme par exemple :

RenduMarkDown

ATTENTION !

Toto est dans la place...

Ceci est une mise en garde, vous voilà prévenu !!

> :warning: &nbsp; **ATTENTION !**
>
> **Toto** est dans la place...
>
> *Ceci est une mise en garde, 
vous voilà prévenu !!*

Mais pour cela, MkDocs-Material offre bien mieux...

Admonition#

ATTENTION !

Toto est dans la place...

Ceci est une mise en garde, vous voilà prévenu !!

Une caractéristique remarquable de MkDocs avec Material sont ces admonitions : ce sont des boites colorées d'avertissements, pour des alertes, mises en garde et autres appartés, qui viennent compléter le flux normal de l'information sur une page web de documentation pour illustrer ou souligner un point particulier, une difficulté...

De base, il existe 12 styles de boites différentes définies par des noms de types. Si aucun de ces mots clés types n'est précisé, ou si le mot clé n'est pas reconnu, c'est le type note qui sera utilisé par défaut.

noteabstractinfotipsuccessquestionattentionfailuredangerbugexamplequote

RenduMardown

Note

Un avertissement de type note.

!!! note
    Un avertissement de type `note`.

RenduMardown

Abstract

Un avertissement de type abstract (résumé), summary (sommaire) ou tdlr (too long ; didn't read).

!!! abstract
    Un avertissement de type `abstract` (résumé), `summary` (sommaire) ou `tdlr` (too long ; didn't read).

RenduMardown

Info

Un avertissement de type info ou todo (à faire).

!!! info
    Un avertissement de type `info` ou `todo` (à faire).

RenduMardown

Tip

Un avertissement de type tip (astuce), hint (indice), important.

!!! tip
    Un avertissement de type `tip` (astuce), `hint` (indice), `important`.

RenduMardown

Success

Un avertissement de type success, check (vérifié) ou done (terminé).

!!! success
    Un avertissement de type `success`, `check` (vérifié) ou `done` (terminé).

RenduMardown

Question

Un avertissement de type question, help (aide) ou faq (Frequently Asked Questions)

!!! question
    Un avertissement de type `question`, `help` (aide) ou `faq` (Frequently Asked Questions)

RenduMardown

Attention

Un avertissement de type attention, warning, caution (avertir).

!!! attention
    Un avertissement de type `attention`, `warning`, `caution` (avertir).

RenduMardown

Failure

Un avertissement de type failure (échec), missing (manquant), fail (échouer).

!!! failure
    Un avertissement de type `failure` (échec), `missing` (manquant), `fail` (échouer).

RenduMardown

Danger

Un avertissement de type danger ou error.

!!! danger
    Un avertissement de type `danger` ou `error`.

RenduMardown

Bug

Un avertissement de type bug.

!!! bug
    Un avertissement de type `bug`.

RenduMardown

Example

Un avertissement de type example.

!!! example
    Un avertissement de type `example`.

RenduMardown

Quote

Un avertissement de type quote (citation) ou cite (citer).

!!! quote
    Un avertissement de type `quote` (citation) ou `cite` (citer).

Pour la syntaxe, on commmence par trois points d'exclamation !!! suivi d'une espace et du mot clé type de l'admonition qui s'affichera en titre par défaut.

Puis, après un retour à la ligne et une indentation de 4 espaces, on peut écrire en MarkDown le code du contenu de la boite d'avertissement.

Des titres personnalisés : ...

Après le type, il est possible d'ajouter un titre personnalisé entre guillemets ce qui va nous permettre au moins de franciser les titres de nos boites :

RenduMardown

Exemple :

Un exemple de boite avec un titre personnalisé.

!!! example "Exemple :"
    Un exemple de boite
     avec un titre
      personnalisé.

Un titre personalisé vide "" permet de produire une boite d'avertissement sans barre de titre :

MardownRendu

!!! example ""
    Un exemple de boite sans titre.

Un exemple de boite sans titre.

Des boites déroulantes : ...

En remplaçant les trois points d'exclamation !!! par trois points d'interrogation ??? on obtient une boite déroulante enroulée par défaut.

RenduMardown

Exemple NF : ...

Un exemple de boite déroulante enroulée par défaut.

??? example "Exemple NF : ..."
    Un exemple de boite déroulante
     enroulée par défaut.

Pour qu'elle soit déroulée par défaut, il suffit d'ajouter un + après les trois points d'interrogation ???.

MardownRendu

???+ example "Exemple NO : ..."
    Un exemple de boite déroulante
     déroulée par défaut.

Exemple NO : ...

Un exemple de boite déroulante déroulée par défaut.

Une boite d'avertissement déroulante possède toujours une barre de titre même avec un titre personnalisé vide !

RenduMardown

Un exemple de boite déroulante sans titre mais avec une barre.

???+ example ""
    Un exemple de boite déroulante
    sans titre mais avec une barre.

Des boites "inline" : ...

Rendu à gaucheMardown à gaucheRendu à droiteMardown à droite

Exemple :

Un exemple de boite s'alignant à gauche.

En indiquant inline entre le mot clé du type et le titre personnalisé, cela modifie le comportement d'affichage de la boite d'avertissement.

Elle s'aligne à gauche en parallèle du bloc de paragraphes qu'elle précède.

!!! example inline "Exemple :"
    Un exemple de boite
    s'alignant à gauche.
En indiquant `inline` entre
 le mot clé du type et le titre personnalisé,
  cela modifie le comportement d'affichage de la boite
   d'avertissement.

Elle s'aligne à **gauche** en parallèle
    du bloc de paragraphes qu'elle précède.

Exemple :

Un exemple de boite s'alignant à droite.

En indiquant inline end entre le mot clé du type et le titre personnalisé, cela modifie le comportement d'affichage de la boite d'avertissement.

Elle s'aligne à droite en parallèle du bloc de paragraphes qu'elle précède.

!!! example inline end "Exemple :"
    Un exemple de boite
    s'alignant à droite.
En indiquant `inline end` entre
 le mot clé du type et le titre personnalisé,
  cela modifie le comportement d'affichage de la boite
   d'avertissement.

Elle s'aligne à **droite** en parallèle
    du bloc de paragraphes qu'elle précède.

Des boites très personnalisées : ...

En attendant qu'il soit possible de choisir des icones personnalisés pour chaque type de boite d'avertissement, on peut déjà customiser ses propres types de boites d'avertissement, cf. la recette pour "Créer ses propres admonitions" de Franck CHAMBON, comme par exemple :

RenduMardowndocs/stylesheets/extra.cssmkdocs.yml

Adn

La boite très spéciale pour l'Atelier du numérique.

!!! adn
    La boite très spéciale pour l'Atelier du numérique.

/*Ajout pour admonition spéciale adn */
:root {
    --md-admonition-icon--adn: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="m290.2,256c51.2-33.4 164.8-119.4 164.8-224.6 0-11.3-9.1-20.4-20.4-20.4-11.3,0-20.4,9.1-20.4,20.4 0,93.3-122.2,175.6-158.2,197.9-36.1-22.2-158.2-104.4-158.2-197.9-1.42109e-14-11.3-9.1-20.4-20.4-20.4-11.3,0-20.4,9.1-20.4,20.4 0,105.2 113.6,191.2 164.8,224.6-51.3,33.4-164.9,119.4-164.9,224.6-7.10543e-15,11.3 9.1,20.4 20.4,20.4 11.3,0 20.4-9.1 20.4-20.4 0-93.3 122.2-175.6 158.2-197.9 36.1,22.2 158.2,104.4 158.2,197.9 0,11.3 9.1,20.4 20.4,20.4 11.3,0 20.4-9.1 20.4-20.4 0.2-105.2-113.4-191.2-164.7-224.6z"/><path d="m177,51.8h158c11.3,0 20.4-9.1 20.4-20.4 0-11.3-9.1-20.4-20.4-20.4h-158c-11.3,0-20.4,9.1-20.4,20.4 0,11.3 9.1,20.4 20.4,20.4z"/><path d="m211.7,113.3c-11.3,0-20.4,9.1-20.4,20.4 0,11.3 9.1,20.4 20.4,20.4h88.6c11.3,0 20.4-9.1 20.4-20.4 0-11.3-9.1-20.4-20.4-20.4h-88.6v1.42109e-14z"/><path d="m335,460.2h-158c-11.3,0-20.4,9.1-20.4,20.4 0,11.3 9.1,20.4 20.4,20.4h158c11.3,0 20.4-9.1 20.4-20.4 0-11.3-9.1-20.4-20.4-20.4z"/><path d="m300.3,398.7c11.3,0 20.4-9.1 20.4-20.4 0-11.3-9.1-20.4-20.4-20.4h-88.6c-11.3,0-20.4,9.1-20.4,20.4 0,11.3 9.1,20.4 20.4,20.4h88.6z"/></svg>')
}
.md-typeset .admonition.adn,
.md-typeset details.adn {
    border-color: rgb(233, 32, 99);
}
.md-typeset .adn > .admonition-title,
.md-typeset .adn > summary {
    background-color: rgba(233, 32, 99, 0.1);
    border-color: rgb(233, 32, 99);
}
.md-typeset .adn > .admonition-title::before,
.md-typeset .adn > summary::before {
    background-color: rgb(233, 32, 99);
    -webkit-mask-image: var(--md-admonition-icon--adn);
            mask-image: var(--md-admonition-icon--adn);
}

extra_css:
  - stylesheets/extra.css

Info

Pour permettre les fonctionnalités des boites d'avertissement décrites ci-dessus, il faut activer dans le fichier mkdocs.yml les extensions :

markdown_extensions:
  - admonition              
  - pymdownx.details        
  - pymdownx.superfences

Une explication en vidéo par Fred LELEU :

Les vidéos de Fred LELEU

Onglet#

La syntaxe pour créer des onglets coulissants commence par trois signes d'égalité === suivi d'une espace et d'un titre écrit entre guillemets.

Puis, après un retour à la ligne et une indentation de 4 espaces, on peut écrire en MarkDown le code du contenu de cet onglet.

On quitte l'onglet en revenant à l'indentation de base. On peut alors en commencer un autre et ainsi de suite autant de fois que nécessaire.

On peut aussi imbriquer des onglets les uns dans les autres...

Exemple : ...

Rendu :Markdown :

Justifier :Indice :Réponse :

$1+1=10$

Calculer en base 2 !

===  "Justifier :"
    $1+1=10$
===  "Indice :"
    <img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2ZXJzaW9uPSIxLjEiIHdpZHRoPSIxMDc2cHgiIGhlaWdodD0iNDE3cHgiIHZpZXdCb3g9Ii0wLjUgLTAuNSAxMDc2IDQxNyI+PGRlZnMvPjxnPjxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDIwMC41LDEzMi41KSI+PHN3aXRjaD48Zm9yZWlnbk9iamVjdCBzdHlsZT0ib3ZlcmZsb3c6dmlzaWJsZTsiIHBvaW50ZXItZXZlbnRzPSJhbGwiIHdpZHRoPSI3MDUiIGhlaWdodD0iMTc4IiByZXF1aXJlZEZlYXR1cmVzPSJodHRwOi8vd3d3LnczLm9yZy9UUi9TVkcxMS9mZWF0dXJlI0V4dGVuc2liaWxpdHkiPjxkaXYgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGh0bWwiIHN0eWxlPSJkaXNwbGF5OiBpbmxpbmUtYmxvY2s7IGZvbnQtc2l6ZTogMTJweDsgZm9udC1mYW1pbHk6IEhlbHZldGljYTsgY29sb3I6IHJnYigwLCAwLCAwKTsgbGluZS1oZWlnaHQ6IDEuMjsgdmVydGljYWwtYWxpZ246IHRvcDsgd2lkdGg6IDcwN3B4OyB3aGl0ZS1zcGFjZTogbm93cmFwOyBvdmVyZmxvdy13cmFwOiBub3JtYWw7IHRleHQtYWxpZ246IGNlbnRlcjsiPjxkaXYgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGh0bWwiIHN0eWxlPSJkaXNwbGF5OmlubGluZS1ibG9jazt0ZXh0LWFsaWduOmluaGVyaXQ7dGV4dC1kZWNvcmF0aW9uOmluaGVyaXQ7d2hpdGUtc3BhY2U6bm9ybWFsOyI+PHNwYW4gc3R5bGU9ImZvbnQtc2l6ZTogNDhweCI+PGZvbnQgZmFjZT0iQ29taWMgU2FucyBNUyIgc3R5bGU9ImZvbnQtc2l6ZTogNDhweCIgY29sb3I9IiMwMDAwOTkiPklsIHkgYSAxMCBjYXTDqWdvcmllcyBkJ2luZGl2aWR1cyw8YnIgLz5jZXV4IHF1aSBjb21wcmVubmVudCBsZSBiaW5haXJlPGJyIC8+ZXQgbGVzIGF1dHJlcy4uLjwvZm9udD48YnIgLz48L3NwYW4+PC9kaXY+PC9kaXY+PC9mb3JlaWduT2JqZWN0Pjx0ZXh0IHg9IjM1MyIgeT0iOTUiIGZpbGw9IiMwMDAwMDAiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZvbnQtc2l6ZT0iMTJweCIgZm9udC1mYW1pbHk9IkhlbHZldGljYSI+Jmx0O3NwYW4gc3R5bGU9ImZvbnQtc2l6ZTogNDhweCImZ3Q7Jmx0O2ZvbnQgZmFjZT0iQ29taWMgU2FucyBNUyIgc3R5bGU9ImZvbnQtc2l6ZTogNDhweCIgY29sb3I9IiMwMDAwOTkiJmd0O0lsIHkgYSAxMCBjYXTDqWdvcmllcyBkJ2luZGl2aWR1cywmbHQ7YnImZ3Q7Y2V1eCBxdWkgY29tcHJlbm5lbnQgbGUgYmluYWlyZSZsdDticiZndDtldCBsZXMgYXV0cmVzLi4uJmx0Oy9mb250Jmd0OyZsdDticiZndDsmbHQ7L3NwYW4mZ3Q7PC90ZXh0Pjwvc3dpdGNoPjwvZz48cGF0aCBkPSJNIDI2OS41IDEwNC41IEMgNTUuNSAxMDQuNSAyIDIwNyAxNzMuMiAyMjcuNSBDIDIgMjcyLjYgMTk0LjYgMzcxIDMzMy43IDMzMCBDIDQzMCA0MTIgNzUxIDQxMiA4NTggMzMwIEMgMTA3MiAzMzAgMTA3MiAyNDggOTM4LjI1IDIwNyBDIDEwNzIgMTI1IDg1OCA0MyA2NzAuNzUgODQgQyA1MzcgMjIuNSAzMjMgMjIuNSAyNjkuNSAxMDQuNSBaIiBmaWxsPSJub25lIiBzdHJva2U9IiMwMDAwMDAiIHN0cm9rZS13aWR0aD0iNCIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyLDMpIiBvcGFjaXR5PSIwLjI1Ii8+PHBhdGggZD0iTSAyNjkuNSAxMDQuNSBDIDU1LjUgMTA0LjUgMiAyMDcgMTczLjIgMjI3LjUgQyAyIDI3Mi42IDE5NC42IDM3MSAzMzMuNyAzMzAgQyA0MzAgNDEyIDc1MSA0MTIgODU4IDMzMCBDIDEwNzIgMzMwIDEwNzIgMjQ4IDkzOC4yNSAyMDcgQyAxMDcyIDEyNSA4NTggNDMgNjcwLjc1IDg0IEMgNTM3IDIyLjUgMzIzIDIyLjUgMjY5LjUgMTA0LjUgWiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjN2YwMGZmIiBzdHJva2Utd2lkdGg9IjQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgcG9pbnRlci1ldmVudHM9Im5vbmUiLz48L2c+PC9zdmc+" width=50% />
=== "Réponse :"
    _**Calculer en base 2 !**_ &nbsp; :wink:

Code MarkDown de cet exemple : ...

=== "Rendu :"
    ===  "Justifier :"
        $1+1=10$
    ===  "Indice :"
        <img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2ZXJzaW9uPSIxLjEiIHdpZHRoPSIxMDc2cHgiIGhlaWdodD0iNDE3cHgiIHZpZXdCb3g9Ii0wLjUgLTAuNSAxMDc2IDQxNyI+PGRlZnMvPjxnPjxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDIwMC41LDEzMi41KSI+PHN3aXRjaD48Zm9yZWlnbk9iamVjdCBzdHlsZT0ib3ZlcmZsb3c6dmlzaWJsZTsiIHBvaW50ZXItZXZlbnRzPSJhbGwiIHdpZHRoPSI3MDUiIGhlaWdodD0iMTc4IiByZXF1aXJlZEZlYXR1cmVzPSJodHRwOi8vd3d3LnczLm9yZy9UUi9TVkcxMS9mZWF0dXJlI0V4dGVuc2liaWxpdHkiPjxkaXYgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGh0bWwiIHN0eWxlPSJkaXNwbGF5OiBpbmxpbmUtYmxvY2s7IGZvbnQtc2l6ZTogMTJweDsgZm9udC1mYW1pbHk6IEhlbHZldGljYTsgY29sb3I6IHJnYigwLCAwLCAwKTsgbGluZS1oZWlnaHQ6IDEuMjsgdmVydGljYWwtYWxpZ246IHRvcDsgd2lkdGg6IDcwN3B4OyB3aGl0ZS1zcGFjZTogbm93cmFwOyBvdmVyZmxvdy13cmFwOiBub3JtYWw7IHRleHQtYWxpZ246IGNlbnRlcjsiPjxkaXYgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGh0bWwiIHN0eWxlPSJkaXNwbGF5OmlubGluZS1ibG9jazt0ZXh0LWFsaWduOmluaGVyaXQ7dGV4dC1kZWNvcmF0aW9uOmluaGVyaXQ7d2hpdGUtc3BhY2U6bm9ybWFsOyI+PHNwYW4gc3R5bGU9ImZvbnQtc2l6ZTogNDhweCI+PGZvbnQgZmFjZT0iQ29taWMgU2FucyBNUyIgc3R5bGU9ImZvbnQtc2l6ZTogNDhweCIgY29sb3I9IiMwMDAwOTkiPklsIHkgYSAxMCBjYXTDqWdvcmllcyBkJ2luZGl2aWR1cyw8YnIgLz5jZXV4IHF1aSBjb21wcmVubmVudCBsZSBiaW5haXJlPGJyIC8+ZXQgbGVzIGF1dHJlcy4uLjwvZm9udD48YnIgLz48L3NwYW4+PC9kaXY+PC9kaXY+PC9mb3JlaWduT2JqZWN0Pjx0ZXh0IHg9IjM1MyIgeT0iOTUiIGZpbGw9IiMwMDAwMDAiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZvbnQtc2l6ZT0iMTJweCIgZm9udC1mYW1pbHk9IkhlbHZldGljYSI+Jmx0O3NwYW4gc3R5bGU9ImZvbnQtc2l6ZTogNDhweCImZ3Q7Jmx0O2ZvbnQgZmFjZT0iQ29taWMgU2FucyBNUyIgc3R5bGU9ImZvbnQtc2l6ZTogNDhweCIgY29sb3I9IiMwMDAwOTkiJmd0O0lsIHkgYSAxMCBjYXTDqWdvcmllcyBkJ2luZGl2aWR1cywmbHQ7YnImZ3Q7Y2V1eCBxdWkgY29tcHJlbm5lbnQgbGUgYmluYWlyZSZsdDticiZndDtldCBsZXMgYXV0cmVzLi4uJmx0Oy9mb250Jmd0OyZsdDticiZndDsmbHQ7L3NwYW4mZ3Q7PC90ZXh0Pjwvc3dpdGNoPjwvZz48cGF0aCBkPSJNIDI2OS41IDEwNC41IEMgNTUuNSAxMDQuNSAyIDIwNyAxNzMuMiAyMjcuNSBDIDIgMjcyLjYgMTk0LjYgMzcxIDMzMy43IDMzMCBDIDQzMCA0MTIgNzUxIDQxMiA4NTggMzMwIEMgMTA3MiAzMzAgMTA3MiAyNDggOTM4LjI1IDIwNyBDIDEwNzIgMTI1IDg1OCA0MyA2NzAuNzUgODQgQyA1MzcgMjIuNSAzMjMgMjIuNSAyNjkuNSAxMDQuNSBaIiBmaWxsPSJub25lIiBzdHJva2U9IiMwMDAwMDAiIHN0cm9rZS13aWR0aD0iNCIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyLDMpIiBvcGFjaXR5PSIwLjI1Ii8+PHBhdGggZD0iTSAyNjkuNSAxMDQuNSBDIDU1LjUgMTA0LjUgMiAyMDcgMTczLjIgMjI3LjUgQyAyIDI3Mi42IDE5NC42IDM3MSAzMzMuNyAzMzAgQyA0MzAgNDEyIDc1MSA0MTIgODU4IDMzMCBDIDEwNzIgMzMwIDEwNzIgMjQ4IDkzOC4yNSAyMDcgQyAxMDcyIDEyNSA4NTggNDMgNjcwLjc1IDg0IEMgNTM3IDIyLjUgMzIzIDIyLjUgMjY5LjUgMTA0LjUgWiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjN2YwMGZmIiBzdHJva2Utd2lkdGg9IjQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgcG9pbnRlci1ldmVudHM9Im5vbmUiLz48L2c+PC9zdmc+" width=50% />
    === "Réponse :"
        _**Calculer en base 2 !**_ &nbsp; :wink:
=== "Markdown :"
    ```md
    ===  "Justifier :"
        $1+1=10$
    ===  "Indice :"
        <img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2ZXJzaW9uPSIxLjEiIHdpZHRoPSIxMDc2cHgiIGhlaWdodD0iNDE3cHgiIHZpZXdCb3g9Ii0wLjUgLTAuNSAxMDc2IDQxNyI+PGRlZnMvPjxnPjxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDIwMC41LDEzMi41KSI+PHN3aXRjaD48Zm9yZWlnbk9iamVjdCBzdHlsZT0ib3ZlcmZsb3c6dmlzaWJsZTsiIHBvaW50ZXItZXZlbnRzPSJhbGwiIHdpZHRoPSI3MDUiIGhlaWdodD0iMTc4IiByZXF1aXJlZEZlYXR1cmVzPSJodHRwOi8vd3d3LnczLm9yZy9UUi9TVkcxMS9mZWF0dXJlI0V4dGVuc2liaWxpdHkiPjxkaXYgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGh0bWwiIHN0eWxlPSJkaXNwbGF5OiBpbmxpbmUtYmxvY2s7IGZvbnQtc2l6ZTogMTJweDsgZm9udC1mYW1pbHk6IEhlbHZldGljYTsgY29sb3I6IHJnYigwLCAwLCAwKTsgbGluZS1oZWlnaHQ6IDEuMjsgdmVydGljYWwtYWxpZ246IHRvcDsgd2lkdGg6IDcwN3B4OyB3aGl0ZS1zcGFjZTogbm93cmFwOyBvdmVyZmxvdy13cmFwOiBub3JtYWw7IHRleHQtYWxpZ246IGNlbnRlcjsiPjxkaXYgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGh0bWwiIHN0eWxlPSJkaXNwbGF5OmlubGluZS1ibG9jazt0ZXh0LWFsaWduOmluaGVyaXQ7dGV4dC1kZWNvcmF0aW9uOmluaGVyaXQ7d2hpdGUtc3BhY2U6bm9ybWFsOyI+PHNwYW4gc3R5bGU9ImZvbnQtc2l6ZTogNDhweCI+PGZvbnQgZmFjZT0iQ29taWMgU2FucyBNUyIgc3R5bGU9ImZvbnQtc2l6ZTogNDhweCIgY29sb3I9IiMwMDAwOTkiPklsIHkgYSAxMCBjYXTDqWdvcmllcyBkJ2luZGl2aWR1cyw8YnIgLz5jZXV4IHF1aSBjb21wcmVubmVudCBsZSBiaW5haXJlPGJyIC8+ZXQgbGVzIGF1dHJlcy4uLjwvZm9udD48YnIgLz48L3NwYW4+PC9kaXY+PC9kaXY+PC9mb3JlaWduT2JqZWN0Pjx0ZXh0IHg9IjM1MyIgeT0iOTUiIGZpbGw9IiMwMDAwMDAiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZvbnQtc2l6ZT0iMTJweCIgZm9udC1mYW1pbHk9IkhlbHZldGljYSI+Jmx0O3NwYW4gc3R5bGU9ImZvbnQtc2l6ZTogNDhweCImZ3Q7Jmx0O2ZvbnQgZmFjZT0iQ29taWMgU2FucyBNUyIgc3R5bGU9ImZvbnQtc2l6ZTogNDhweCIgY29sb3I9IiMwMDAwOTkiJmd0O0lsIHkgYSAxMCBjYXTDqWdvcmllcyBkJ2luZGl2aWR1cywmbHQ7YnImZ3Q7Y2V1eCBxdWkgY29tcHJlbm5lbnQgbGUgYmluYWlyZSZsdDticiZndDtldCBsZXMgYXV0cmVzLi4uJmx0Oy9mb250Jmd0OyZsdDticiZndDsmbHQ7L3NwYW4mZ3Q7PC90ZXh0Pjwvc3dpdGNoPjwvZz48cGF0aCBkPSJNIDI2OS41IDEwNC41IEMgNTUuNSAxMDQuNSAyIDIwNyAxNzMuMiAyMjcuNSBDIDIgMjcyLjYgMTk0LjYgMzcxIDMzMy43IDMzMCBDIDQzMCA0MTIgNzUxIDQxMiA4NTggMzMwIEMgMTA3MiAzMzAgMTA3MiAyNDggOTM4LjI1IDIwNyBDIDEwNzIgMTI1IDg1OCA0MyA2NzAuNzUgODQgQyA1MzcgMjIuNSAzMjMgMjIuNSAyNjkuNSAxMDQuNSBaIiBmaWxsPSJub25lIiBzdHJva2U9IiMwMDAwMDAiIHN0cm9rZS13aWR0aD0iNCIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyLDMpIiBvcGFjaXR5PSIwLjI1Ii8+PHBhdGggZD0iTSAyNjkuNSAxMDQuNSBDIDU1LjUgMTA0LjUgMiAyMDcgMTczLjIgMjI3LjUgQyAyIDI3Mi42IDE5NC42IDM3MSAzMzMuNyAzMzAgQyA0MzAgNDEyIDc1MSA0MTIgODU4IDMzMCBDIDEwNzIgMzMwIDEwNzIgMjQ4IDkzOC4yNSAyMDcgQyAxMDcyIDEyNSA4NTggNDMgNjcwLjc1IDg0IEMgNTM3IDIyLjUgMzIzIDIyLjUgMjY5LjUgMTA0LjUgWiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjN2YwMGZmIiBzdHJva2Utd2lkdGg9IjQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgcG9pbnRlci1ldmVudHM9Im5vbmUiLz48L2c+PC9zdmc+" width=50% />
    === "Réponse :"
        _**Calculer en base 2 !**_ &nbsp; :wink:
    ```

Une explication en vidéo par Fred LELEU :

Les vidéos de Fred LELEU

Codes#

Code inline#

Comme vu dans le Corps de texte, on peut afficher dans le flux d'un paragraphe, du code en caractères monospaces en l'encadrant entre deux ` que l'on peut obtenir par la combinaison de touches AltGr＋è.

Mettre du code dans du code : ...

Si le codage renferme déjà une apostrophe inversée ( backtick, accent grave), on peut précéder et terminer la zone de code de deux fois ce caractère.
Dans ce cas, MarkDown n’interprétera pas cette apostrophe inversée comme une balise.

MarkDownRendu

Exemple : ``Ceci est du `code`.``

Exemple : Ceci est du `code`.

Activer la coloration syntaxique : ...

La coloration syntaxique s'applique aussi sur du code en ligne, par exemple, for lettre in "Bonjour" :, s'obtient en écrivant en markdown `#!python3 for lettre in "Bonjour" :` dans le flux du texte.

Après le premier `, on place un shebang #! (ou :::) suivi d'un nom court désignant le langage utilisé. Aussi, ici on aurait pu se contenter du nom court py qui correspont à python3 par défaut, ainsi le code `:::py for lettre in "Bonjour" :` produit le même résultat : for lettre in "Bonjour" :.

Info

Pour la coloration syntaxique du code en ligne, il faut activer dans le fichier mkdocs.yml les extensions :

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.inlinehilite

Bloc de texte brut#

MarkDownRendu

Pour produire un bloc de texte brut,
 il suffit de faire
  un **saut de ligne**
   et de précéder le code
    d'une tabulation équivalente
     à au moins **quatre espaces** :

    Ceci est un bloc de texte brut ;

    A l'intérieur de ce dernier,
    tous les retours à la ligne,


    sont considérés ;

    Tous les  espaces   laissés    vides     sont      conservés ;
        L'indentation est donc respectée ;

    De plus :
        - aucun caractère de balisage **MarkDown**, <HTML> ou $LaTeX$ n'est interprété ;
        + ![image](url "info"){ heigt=300 align=left} ...
        # tout le texte s'affiche en caractère monospace ;
   On sort simplement de ce bloc de texte brut en revenant à une indentation inférieure à 4 espaces.

Pour produire un bloc de texte brut, il suffit de faire un saut de ligne et de précéder le code d'une tabulation équivalente à au moins quatre espaces :

Ceci est un bloc de texte brut ;

A l'intérieur de ce dernier,
tous les retours à la ligne,

sont considérés ;

Tous les  espaces   laissés    vides     sont      conservés ;
    L'indentation est donc respectée ;

De plus :
    - aucun caractère de balisage **MarkDown**, <HTML> ou $LaTeX$ n'est interprété ;
    + ![image](url "info"){ heigt=300 align=left} ...
    # tout le texte s'affiche en caractère monospace ;

On sort simplement de ce bloc de texte brut en revenant à une indentation inférieure à 4 espaces.

Une indentation ⩾ à 4 espaces après une ligne vide ⇒ génère du texte brut !

Bloc de code#

Coloré#

Une autre pratique pour produire des blocs de texte brut consiste à encadrer les lignes de code entre deux triplets d'apostrophes inversées ``` (backtick, accent grave) ;

Aussi, si on précise après le premier triplet le nom court du langage informatique correspondant au contenu des lignes de code, une coloration syntaxique idoine s'applique :

Exemple : ...

MarkDown sans langageRendu texte brutMarkDown avec langageRendu avec coloration

```
def ma_fonction(paramètres):
    ''' docstring '''
    # bloc d'instructions (optionnel)            
    return valeur
```

def ma_fonction(paramètres):
    ''' docstring '''
    # bloc d'instructions (optionnel)            
    return valeur

``` python
def ma_fonction(paramètres):
    ''' docstring '''
    # bloc d'instructions (optionnel)            
    return valeur
```

def ma_fonction(paramètres):
    ''' docstring '''
    # bloc d'instructions (optionnel)            
    return valeur

La liste des langages supportés est plutôt exhaustive. Aussi il est pratique d'utiliser la barre de recherche pour trouver un nom court correspondant au langage souhaité...

Numéroté, surligné#

Franck CHAMBON présente parfaitement les différentes options pour faire cela. Il s'appuie sur l'exemple de code utilisé dans la référence mkdocs-material à ce sujet :

Numérotation des lignes et marquage : ...

Il suffit d'ajouter linenums="1" (ou un autre nombre) pour faire débuter la numérotation.
Pour marquer des lignes en particulier, on utilise hl_lines="<tranches et numéros>"

Exemples : ...

Sans numérotationNumérotation classiqueNumérotation décaléeMarquage d'une ligneMarquage d'une ligne, avec numérotationMarquage de lignes éparsesMarquage d'une trancheMarquage lignes et tranches

Entrée

```python
def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Rendu

def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Entrée

```python linenums="1"
def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Rendu

def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Entrée

```python linenums="42"
def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Rendu

def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Entrée

```python hl_lines="2"
def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Rendu

def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Entrée

```python linenums="1" hl_lines="2"
def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Rendu

def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Entrée

```python linenums="1" hl_lines="2 5"
def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Rendu

def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Entrée

```python linenums="1" hl_lines="2-4"
def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Rendu

def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Entrée

```python linenums="1" hl_lines="1 2 3-3 5-5"
def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Rendu

def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Annoté ? ...

Cette fonctionnalité est pour l'instant exclusivement réservée aux insiders...

Info

Pour permettre les fonctionnalités des lignes et blocs de code décrites ci-dessus, il faut activer dans le fichier mkdocs.yml les extensions :

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.superfences
  - pymdownx.snippets

Intégré#

Ne pas copier/coller...

... le code ci-contre sans enlever l'espace laissé volontairement après le nom du fichier.

C'est un caractère d'échappement qui évite l'intégration effective du code contenu dans le fichier mkdocs.yml ici .

Pour afficher dans un bloc de code le contenu du fichier mkdocs.yml qui est situé à la racine du dépôt on écrirait :

```yaml
--8<-- "mkdocs.yml" 
```

├── docs/
│   └── images/
│   │   └── undraw_Polaroid.svg
│   └── MarkDown-Mkdocs_Material.md
│   └── index.md
├── includes/
│   └── py/
│       └── exemple.py
└─ mkdocs.yml

Exemple 1 : un fichier MarkDown ...

Pour le fichier index.md du dossier docs/ situé à la racine du dépôt :

MarkDownRendu

```md
--8<-- "docs/index.md" 
```

---
hide:
  - navigation
  - toc
---
Ceci est un tutoriel pour déployer un site web depuis un dépôt git
 avec le framework material pour mkdocs en incluant, ou pas, des notebook jupyter...

[![building_websites](https://ericecmorlaix.github.io/adn-Tutoriel_site_web/images/undraw_building_websites_i78t.svg){: align=right width=53%}](https://undraw.co/illustrations "Illustration par unDraw"){target="_blank"}


???+ adncogs "Créer, déployer puis maintenir son site :"

    1. [Premiers pas depuis un navigateur web](./PremiersPas) ;

    2. [Puis sur PC avec Visual Studio Code](./PCW10-VSC) ;

    3. [Et même sur un iPad en ligne de commande](./iPad.md) ;

![Bienvenue](https://ericecmorlaix.github.io/adn-Tutoriel_site_web/images/undraw_handcrafts_welcome.svg "Degemer Mat !"){width=20% .center }

???+ adncode "Coder pour générer ses pages web  :"

    1. [MarkDown Mkdocs-Material pour le contenu](./MarkDown-Mkdocs_Material.md) ;

    2. [YAML pour la configuration](./Yaml.md) ;

    3. [$\LaTeX$ pour les sciences](./LaTeX.md) ;

    4. [Python pour les macros](./Python.md) ;

Exemple 2 : un fichier Python ...

Pour le fichier exemple.py du dossier py/ situé dans le dossier includes qui est aussi, comme le dossier docs/, à la racine du dépôt :

MarkDownRendu

```py
--8<-- "includes/py/exemple.py" 
```

def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Exemple 3 : un fichier SVG ...

Pour le fichier undraw_Polaroid.svg du dossier images situé le dossier docs/ :

MarkDownRendu

```svg
--8<-- "docs/images/undraw_Polaroid.svg" 
```

<svg id="b05a8b24-0cfe-4b22-93a9-3846e5c8b4da" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" width="541" height="606" viewBox="0 0 541 606"><path d="M847.04975,752.74227H352.02241a23.01224,23.01224,0,0,1-22.98633-22.98633V169.7286a23.01224,23.01224,0,0,1,22.98633-22.98633H847.04975a23.01223,23.01223,0,0,1,22.98633,22.98633V729.75594A23.01224,23.01224,0,0,1,847.04975,752.74227Z" transform="translate(-329.03608 -146.74227)" fill="#f2f2f2"/><path d="M822.15608,185.74227h-445.24a15.64143,15.64143,0,0,0-15.62,15.62v410.42a15.64143,15.64143,0,0,0,15.62,15.62h445.24a15.64142,15.64142,0,0,0,15.62-15.62v-410.42A15.64142,15.64142,0,0,0,822.15608,185.74227Z" transform="translate(-329.03608 -146.74227)" fill="#e92063"/><path d="M608.57468,374.35144c-4.32513-7.1534-9.45023-14.7911-17.47656-17.12689-9.295-2.705-18.84337,2.66857-26.94255,7.97116a785.1068,785.1068,0,0,0-69.86968,51.47911l.02443.27768q26.06891-1.79775,52.13774-3.59549c12.55653-.86592,25.54444-1.85127,36.64094-7.7913,4.21074-2.254,8.3153-5.26492,13.08677-5.47473,5.9281-.26064,11.097,3.87955,15.15908,8.20508,24.0284,25.587,30.98174,64.71558,57.93919,87.19565A855.50925,855.50925,0,0,0,608.57468,374.35144Z" transform="translate(-329.03608 -146.74227)" fill="#fff"/><path d="M756.27371,591.37542c-2.65715-3.35527-3.74288-4.14107-6.36393-7.52739q-32.01228-41.40317-60.17793-85.6033-19.13118-30.01909-36.365-61.19105-8.2047-14.81953-15.95956-29.87171-6.0176-11.67106-11.76659-23.48172c-1.09608-2.24892-2.16111-4.50817-3.22084-6.77259-2.49711-5.325-4.94777-10.67584-7.57917-15.92849-2.99845-5.98673-6.64843-12.263-12.15458-16.28521a16.58291,16.58291,0,0,0-8.6389-3.32424c-4.48227-.28952-8.61819,1.56132-12.506,3.58274a402.57534,402.57534,0,0,0-79.16143,54.58907,412.12253,412.12253,0,0,0-64.31385,71.39123c-.56849.81168-1.91271.0362-1.33892-.78063q3.389-4.79254,6.91222-9.48162A414.39962,414.39962,0,0,1,549.436,362.00731q10.29109-6.66917,20.96917-12.71282c3.58789-2.03177,7.19143-4.03769,10.85681-5.91951,3.59319-1.84566,7.40852-3.50522,11.51339-3.56725,13.9691-.21713,21.20193,15.60277,26.17014,26.24763q2.342,5.02513,4.74076,10.01928,9.06538,18.9606,18.82876,37.57489,6.02554,11.4927,12.31489,22.851,19.57307,35.36991,41.6074,69.30778c19.4596,29.96994,38.764,56.445,60.93246,84.4711C757.97993,591.05488,756.88915,592.16125,756.27371,591.37542Z" transform="translate(-329.03608 -146.74227)" fill="#e4e4e4"/><path d="M500.99918,391.7498c-.81159-.90473-1.61813-1.80946-2.435-2.7142-6.44169-7.12414-13.35366-14.16556-22.19955-18.2498a32.20737,32.20737,0,0,0-13.49351-3.12778,38.50755,38.50755,0,0,0-14.01025,3.05543c-2.10936.8427-4.17228,1.79912-6.20389,2.81757-2.32141,1.16841-4.60142,2.41437-6.87083,3.67066q-6.39018,3.5362-12.61452,7.38261-12.38468,7.654-23.99362,16.47649-6.018,4.57539-11.78754,9.45061-5.36631,4.52882-10.51551,9.30066c-.73409.67725-1.83017-.41876-1.09609-1.096.90474-.8427,1.81982-1.68022,2.73491-2.50739q3.87743-3.50522,7.87906-6.876,7.29706-6.15735,14.972-11.83907,11.93484-8.84055,24.69136-16.48166,6.37466-3.81539,12.92476-7.31026c1.31848-.7031,2.65236-1.39071,4.00163-2.04212a63.792,63.792,0,0,1,9.51258-3.87226,33.84064,33.84064,0,0,1,14.3672-1.41137,37.405,37.405,0,0,1,13.25571,4.58571c8.68534,4.85455,15.42162,12.36123,21.97716,19.687C502.75715,391.39308,501.66611,392.49427,500.99918,391.7498Z" transform="translate(-329.03608 -146.74227)" fill="#e4e4e4"/><path d="M678.9595,465.57479l20.81236-7.61222,10.3334-3.77949a105.67624,105.67624,0,0,1,10.20179-3.51362,16.09445,16.09445,0,0,1,9.23387.11765,21.28211,21.28211,0,0,1,7.20219,4.46461,58.449,58.449,0,0,1,5.90731,6.30858c2.24977,2.70372,4.46631,5.43579,6.6928,8.1587q13.78369,16.857,27.38714,33.86031,13.60313,17.003,27.02437,34.15055,13.45406,17.18943,26.723,34.52261,1.62548,2.12337,3.24817,4.24888c.59767.78282,1.94533.01107,1.33922-.7828q-13.36689-17.50749-26.92011-34.87165-13.58655-17.40566-27.36086-34.66367-13.774-17.25766-27.73423-34.36566-3.4779-4.26211-6.96729-8.51485c-1.96228-2.39156-3.90244-4.8089-6.05473-7.03486-3.95068-4.08591-8.88656-7.69676-14.79487-7.79473-3.47378-.0576-6.83564,1.04471-10.06315,2.21231-3.47938,1.25872-6.95042,2.541-10.42536,3.812l-20.9579,7.66544-5.23947,1.91637c-.92981.34008-.52815,1.83954.41231,1.49557Z" transform="translate(-329.03608 -146.74227)" fill="#e4e4e4"/><path d="M473.62576,379.75015a33.60017,33.60017,0,0,0-33.83986,2.42A482.65361,482.65361,0,0,1,494.698,394.98639C487.20731,390.59664,481.34778,383.7189,473.62576,379.75015Z" transform="translate(-329.03608 -146.74227)" fill="#fff"/><path d="M439.68181,382.15146l-2.0361,1.655c.68871-.57924,1.40469-1.12233,2.14019-1.63626C439.75116,382.16417,439.71655,382.15745,439.68181,382.15146Z" transform="translate(-329.03608 -146.74227)" fill="#f2f2f2"/><path d="M735.95944,465.65083c-2.04871-2.49382-4.26372-5.105-7.32808-6.11793l-2.861.11283a324.5172,324.5172,0,0,0,86.43508,98.81564Q774.08247,512.05611,735.95944,465.65083Z" transform="translate(-329.03608 -146.74227)" fill="#fff"/><g opacity="0.17"><path d="M791.79345,323.39222c5.76935-2.51553-5.93086-3.9799-19.20533-4.46137s-29.33268-.45483-37.8158-1.82429c-8.2044-1.32446-7.5999-3.67944-8.29-5.81314s-3.84423-4.32149-16.64635-4.79579c-15.95307-.591-42.26067,1.684-54.30349.31817-11.23819-1.2746-4.558-5.27276-20.94516-5.42579-9.3576-.08738-21.41277,1.23075-31.825,1.54885a116.01452,116.01452,0,0,1-22.08215-1.15126c-5.075-.83149-8.60986-1.88563-14.32157-2.62006-14.99567-1.92821-44.33435-1.28008-70.5202,1.19119s-48.63194,6.52118-61.29082,10.53243-16.15629,7.96063-13.20756,11.3097c1.88293,2.13857,6.70129,4.13827,18.38945,4.99762,21.86194,1.60736,60.78519-1.15935,83.37576.303,12.5907.81506,18.17647,2.83584,29.22349,3.94158,11.86819,1.18794,29.24216,1.25091,46.31211,1.22273,35.54177-.05869,71.99263-.42383,109.16139-1.09351,15.52474-.27972,31.79162-.64338,48.31132-1.97637s33.36908-3.90493,36.85433-6.316" transform="translate(-329.03608 -146.74227)" fill="#fff"/></g><circle cx="217.0152" cy="124.42378" r="2.99187" fill="#fff"/><circle cx="290.23466" cy="91.99777" r="1.79512" fill="#fff"/><circle cx="191.23466" cy="202.99777" r="1.79512" fill="#fff"/><circle cx="397.23154" cy="119.40752" r="1.79512" fill="#fff"/><circle cx="278.23154" cy="170.40752" r="1.79512" fill="#fff"/><circle cx="327.23154" cy="138.40752" r="1.79512" fill="#fff"/><circle cx="417.93247" cy="234.36521" r="1.79512" fill="#fff"/><circle cx="73.93247" cy="219.36521" r="1.79512" fill="#fff"/><path d="M837.77607,576.85225v34.93a15.64142,15.64142,0,0,1-15.62,15.62h-445.24a15.64143,15.64143,0,0,1-15.62-15.62v-43.64a264.22453,264.22453,0,0,1,70.01-7.48c56.9,1.24,112.47,16.43,168.84,24.29a659.89327,659.89327,0,0,0,199.88-2.75C812.48609,580.11226,825.1761,577.67226,837.77607,576.85225Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><path d="M686.761,417.85547c-2.27357-4.20958-2.591-9.7268.20064-13.61217a22.04318,22.04318,0,0,0,8.78119,12.32609c1.65858,1.12925,3.62091,2.21254,4.1883,4.13717a4.92756,4.92756,0,0,1-.51378,3.61684,14.63438,14.63438,0,0,1-2.27087,2.96491l-.08038.30113C692.95023,425.15035,689.03457,422.06505,686.761,417.85547Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><path d="M540.761,529.85547c-2.27357-4.20958-2.591-9.7268.20064-13.61217a22.04318,22.04318,0,0,0,8.78119,12.32609c1.65858,1.12925,3.62091,2.21254,4.1883,4.13717a4.92756,4.92756,0,0,1-.51378,3.61684,14.63438,14.63438,0,0,1-2.27087,2.96491l-.08038.30113C546.95023,537.15035,543.03457,534.06505,540.761,529.85547Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><path d="M720.761,506.85547c-2.27357-4.20958-2.591-9.7268.20064-13.61217a22.04318,22.04318,0,0,0,8.78119,12.32609c1.65858,1.12925,3.62091,2.21254,4.1883,4.13717a4.92756,4.92756,0,0,1-.51378,3.61684,14.63438,14.63438,0,0,1-2.27087,2.96491l-.08038.30113C726.95023,514.15035,723.03457,511.06505,720.761,506.85547Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><path d="M452.16255,264.0201A31.01709,31.01709,0,1,1,483.17964,233.003,31.052,31.052,0,0,1,452.16255,264.0201Z" transform="translate(-329.03608 -146.74227)" fill="#fff"/><path d="M545.59839,231.41249c-8.0763-8.47227-17.45607-16.20121-28.56-20.28545a45.90466,45.90466,0,0,0-9.56581-2.40387c-.02626-.00362-.05113.00171-.07725-.0004a1.40837,1.40837,0,0,0-.16135-.03167,36.82309,36.82309,0,0,0-13.66765.82514,37.76206,37.76206,0,0,0-6.36383,2.21691,55.65007,55.65007,0,0,0-5.97143,3.38416A38.83959,38.83959,0,0,1,468.03554,220.04a44.3928,44.3928,0,0,1-7.08718.69559,17.11875,17.11875,0,0,0-5.96219.85823,14.31053,14.31053,0,0,0-8.71529,9.43667.92793.92793,0,0,0,.41248,1.01363c.52865.37862,1.044.80819,1.59944,1.1455a4.98957,4.98957,0,0,0,1.56233.4261q1.32459.27951,2.65255.54268,4.8922.96933,9.82507,1.71609,9.98148,1.511,20.07078,2.12875a223.4829,223.4829,0,0,0,40.3964-1.21409,224.25471,224.25471,0,0,0,22.41238-3.87651A.90587.90587,0,0,0,545.59839,231.41249Z" transform="translate(-329.03608 -146.74227)" fill="#f0f0f0"/><path d="M453.61072,251.81649a45.90466,45.90466,0,0,0-9.56581-2.40387c-.02626-.00361-.05113.00172-.07725-.0004a1.40835,1.40835,0,0,0-.16135-.03166,36.82309,36.82309,0,0,0-13.66765.82514,37.76118,37.76118,0,0,0-6.36383,2.21691,55.65281,55.65281,0,0,0-5.97144,3.38415,38.83947,38.83947,0,0,1-13.19553,4.92271,44.39166,44.39166,0,0,1-7.08718.6956,17.11851,17.11851,0,0,0-5.96219.85823A14.31052,14.31052,0,0,0,382.8432,271.72a.92793.92793,0,0,0,.41248,1.01363c.52865.37862,1.044.80819,1.59944,1.14551a4.9901,4.9901,0,0,0,1.56233.4261q1.32459.27949,2.65255.54268,4.89221.96933,9.82507,1.71609,9.98148,1.511,20.07078,2.12875a223.482,223.482,0,0,0,40.3964-1.2141,224.25181,224.25181,0,0,0,22.41238-3.8765.90588.90588,0,0,0,.39608-1.50018C474.09441,263.62967,464.71464,255.90073,453.61072,251.81649Z" transform="translate(-329.03608 -146.74227)" fill="#f0f0f0"/><path d="M592.03608,681.74227h-225a6,6,0,0,1,0-12h225a6,6,0,1,1,0,12Z" transform="translate(-329.03608 -146.74227)" fill="#ccc"/><path d="M479.03608,715.24227h-112a6,6,0,0,1,0-12h112a6,6,0,1,1,0,12Z" transform="translate(-329.03608 -146.74227)" fill="#ccc"/><polygon points="107.375 384.038 124.578 370.977 132.963 379.362 104.938 398.541 107.375 384.038" fill="#2f2e41"/><path d="M420.36583,566.74387H361.51722l2.064-6.68758h0c12.79222-4.63087,5.60682-14.58464,17.77517-20.66882,29.7631-14.88155,41.28561-59.28965,36.92732-76.84429l19.50438-.82469S464.72374,538.21174,420.36583,566.74387Z" transform="translate(-329.03608 -146.74227)" fill="#2f2e41"/><path d="M470.60568,535.3075a9.89147,9.89147,0,0,1-12.78172.23913l-.03826-.03142-.00131-.04919a9.47684,9.47684,0,0,0-.37995-2.4188,6.77026,6.77026,0,0,1-.24584,1.67423l-.04929.1836-.13219-.13647c-.11417-.11773-.22466-.23731-.32842-.35529a9.97468,9.97468,0,0,1-1.51926-2.30058,29.07888,29.07888,0,0,0-8.06828-10.05664,14.118,14.118,0,0,1-1.69263-1.62867,13.95425,13.95425,0,0,1,17.52315-21.25934l.08719.051-.04528.09025a7.26871,7.26871,0,0,1-1.29692,1.87076,9.47928,9.47928,0,0,0,1.9974-1.44308l.06337-.05975.0718.04951a14.01337,14.01337,0,0,1,2.55182,2.27146l.08134.09326a6.2294,6.2294,0,0,0,4.6128,2.12867,9.88837,9.88837,0,0,1,9.57517,11.58491l-.0112.06532-.06355.01925a8.48535,8.48535,0,0,1-3.45588.43121,9.64019,9.64019,0,0,0,3.07823.771l.13713.01088-.04353.13058a9.8818,9.8818,0,0,1-2.852,4.30008l-.03754.03285-.03986.03489a9.7103,9.7103,0,0,0-3.35461,6.74A9.964,9.964,0,0,1,470.60568,535.3075Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><path d="M472.40585,532.12862a9.86349,9.86349,0,0,1-.11121,1.06328,9.99679,9.99679,0,0,0,1.60714-4.95271c.01311-.27.04146-.539.07947-.80679A9.38181,9.38181,0,0,0,472.40585,532.12862Z" transform="translate(-329.03608 -146.74227)" opacity="0.15"/><path d="M475.51806,520.10833a9.62507,9.62507,0,0,0,2.45985.6955,9.89773,9.89773,0,0,0,.90133-1.0997A8.38739,8.38739,0,0,1,475.51806,520.10833Z" transform="translate(-329.03608 -146.74227)" opacity="0.15"/><path d="M479.14311,516.86068a9.949,9.949,0,0,1-.07038,2.5661,9.83448,9.83448,0,0,0,1.11307-2.29544l.04354-.13058-.13714-.01088A9.55592,9.55592,0,0,1,479.14311,516.86068Z" transform="translate(-329.03608 -146.74227)" opacity="0.15"/><path d="M478.228,507.47444a9.91161,9.91161,0,0,0-7.25857-3.35623,6.22938,6.22938,0,0,1-4.61281-2.12868l-.08134-.09325a14.01337,14.01337,0,0,0-2.55182-2.27146l-.0718-.04951-.06336.05975a9.47874,9.47874,0,0,1-1.99742,1.44307,7.269,7.269,0,0,0,1.297-1.87076l.04525-.09024-.08718-.051a13.94385,13.94385,0,0,0-20.659,9.02719,13.94642,13.94642,0,0,1,19.163-5.13776l.08718.051-.04525.09024a7.26926,7.26926,0,0,1-1.297,1.87076,9.47868,9.47868,0,0,0,1.99741-1.44307l.06337-.05975.0718.04951a14.01337,14.01337,0,0,1,2.55182,2.27146l.08133.09326a6.22944,6.22944,0,0,0,4.61282,2.12867,9.89007,9.89007,0,0,1,9.565,8.12834,11.98677,11.98677,0,0,0,1.43129-.34829l.06355-.01925.01125-.06532A9.85036,9.85036,0,0,0,478.228,507.47444Z" transform="translate(-329.03608 -146.74227)" opacity="0.15"/><path d="M499.04886,466.75383a31.84958,31.84958,0,0,1-26.603,31.41149l-.15732.02566-.12171-.10142a30.51655,30.51655,0,0,0-6.656-4.22513,21.8005,21.8005,0,0,1,3.52508,4.15475l.339.50961-.611.0294c-.52742.02566-1.05152.0385-1.55741.0385a32.118,32.118,0,0,1-8.793-1.21919,93.63086,93.63086,0,0,0-41.47214-1.87907,45.458,45.458,0,0,1-7.53721.62884,44.93133,44.93133,0,0,1-14.1355-87.57594l.30883-.10225.12192.30138a23.40468,23.40468,0,0,1,1.765,7.11391,30.52291,30.52291,0,0,0,.75863-7.898l-.00973-.28026.2724-.06831a45.12252,45.12252,0,0,1,10.91843-1.33924l.39846.00165a20.05806,20.05806,0,0,0,14.956-6.62582,31.83962,31.83962,0,0,1,48.3716,1.48579l.13413.166-.08859.19457a27.32206,27.32206,0,0,1-6.30664,9.27243,31.04045,31.04045,0,0,0,8.4101-5.80282l.31794-.30842.22313.38293a31.8183,31.8183,0,0,1,4.33152,16.03983l-.00041.16063c-.00042.05672-.00042.11385-.00042.17056a31.26636,31.26636,0,0,0,9.1619,22.44376A32.08311,32.08311,0,0,1,499.04886,466.75383Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><g opacity="0.15"><path d="M460.11959,391.50282a22.49407,22.49407,0,0,1-4.012,4.92175,30.96211,30.96211,0,0,0,6.26856-3.91791Q461.26814,391.96086,460.11959,391.50282Z" transform="translate(-329.03608 -146.74227)"/><path d="M478.55133,429.51105A31.97,31.97,0,0,1,483.13,435.089a32.54708,32.54708,0,0,1-2.97907-13.6731c0-.05672,0-.11385.0004-.17055l.00041-.16063a31.81856,31.81856,0,0,0-4.3315-16.03983l-.22314-.38294-.318.30841a31.112,31.112,0,0,1-5.80764,4.42232A31.01389,31.01389,0,0,0,478.55133,429.51105Z" transform="translate(-329.03608 -146.74227)"/><path d="M469.39025,406.7361l-.0004.16063c-.00041.05671-.00041.11384-.00041.17056,0,.31256.00566.62434.01439.93563a33.16272,33.16272,0,0,0,3.77185-6.50215l.08857-.19458-.13411-.166a32.10042,32.10042,0,0,0-5.76052-5.57135A31.89066,31.89066,0,0,1,469.39025,406.7361Z" transform="translate(-329.03608 -146.74227)"/><path d="M489.31279,443.85966a28.78932,28.78932,0,0,1-4.05843-4.93763,31.8105,31.8105,0,0,1-23.57,44.89467l-.15732.02568-.1217-.10143a30.5172,30.5172,0,0,0-6.65606-4.22512,21.79991,21.79991,0,0,1,3.52506,4.15473l.33907.50963-.611.02938c-.52745.02568-1.05154.03851-1.55741.03851a32.11821,32.11821,0,0,1-8.793-1.21919,93.631,93.631,0,0,0-41.47214-1.87907,45.45764,45.45764,0,0,1-7.53719.62883,44.7262,44.7262,0,0,1-29.84116-11.37979,44.97143,44.97143,0,0,0,40.60261,25.72841,45.45767,45.45767,0,0,0,7.5372-.62884,93.631,93.631,0,0,1,41.47214,1.87907,32.11819,32.11819,0,0,0,8.793,1.21919c.50588,0,1.03-.01283,1.55742-.03851l.611-.02938-.33907-.50962a21.79968,21.79968,0,0,0-3.52506-4.15474,30.5169,30.5169,0,0,1,6.656,4.22512l.12171.10143.15731-.02568a31.82584,31.82584,0,0,0,16.867-54.30565Z" transform="translate(-329.03608 -146.74227)"/></g></svg>

Info

Pour permettre cette fonctionnalité d'intégration de contenu externe décrite ci-dessus, il faut activer dans le fichier mkdocs.yml l'extension :

markdown_extensions:
  - pymdownx.snippets

Inclusion#

Quid : si on intègre le contenu d'un fichier en dehors d'un bloc de code ?

MarkDownRendu

--8<-- "docs/index.md"

hide: - navigation - toc

Ceci est un tutoriel pour déployer un site web depuis un dépôt git avec le framework material pour mkdocs en incluant, ou pas, des notebook jupyter...

Créer, déployer puis maintenir son site :

Bienvenue

Coder pour générer ses pages web :

MarkDownRendu

--8<-- "includes/py/exemple.py"

def tri_bulles(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] > items[j + 1]: items[j], items[j + 1] = items[j + 1], items[j]

MarkDownRendu

--8<-- "docs/images/undraw_Polaroid.svg"

Fichier `.md`#

On observe que le code MarkDown contenu dans le fichier index.md s'affiche bien, hormis son en tête de métadonnées...

On a là une solution pour inclure du contenu externe codé en MarkDown pour développer une longue page web en la décomposant en sous-parties.

Exemple avec le début du code qui génère cette page : ...

# MarkDown Mkdocs-Material pour le contenu
## Introduction :
=== "Rendu MarkDown"
    --8<-- "includes/md/introductionM.md" 
=== "MarkDown"
    ```md
    --8<-- "includes/md/introductionM.md" 
    ```
=== "HTML"
    ```html
    --8<-- "includes/md/introductionH.md" 
    ```
=== "Rendu HTML :"
    --8<-- "includes/md/introductionH.md" 

***
## Titres :
--8<-- "includes/md/titres.md" 

***
## Corps de texte :
--8<-- "includes/md/texte.md" 

***
## Lien :
--8<-- "includes/md/lien.md" 

***

Il est alors simple de répéter plusieurs fois un même bout de code dans une ou plusieurs pages différentes à partir d'une seule et même source.

C'est le cas ici du contenu du fichier introductionM.md qui est appelé deux fois dans la partie ## Introduction :, et également dans le fichier lien.md, qui est lui même intégré plus loin dans la partie ## Lien :.

Au total, on retrouve trois fois le contenu du paragraphe d'introduction MarkDown dans cette page et s'il faut y apporter une modification, il suffira d'agir dans son unique fichier source pour la répercuter partout...

Ce mécanisme d'inclusion d'extraits de code MarkDown est permis par l'extension Snippets. La syntaxe --8<-- représente une paire de ciseaux en art ASCII. Il est aussi possible d'inclure plusieurs fichiers d'affilée en ajoutant selon le besoin des sauts de lignes et des indentations, un point virgule suivi d'une espace pour ignorer un fichier...

Comme par exemple ainsi : ...

MarkDown avec inclusionsCode MarkDown généréRendu

--8<-- 
includes/md/loremIpsum.md
includes/md/totoAlerte.md

        includes/md/loremIpsum.md

includes/md/loremIpsum.md
; includes/md/loremIpsum.md
includes/md/loremIpsum.md

    includes/md/loremIpsum.md

includes/md/loremIpsum.md
--8<--

Sed quid est quod in hac
causa maxime homines
admirentur et repredant
meum consilium, cum ego
idem antea multa derim,
que magis ad hominis
dignitatem quam ad rei
publicae necessitatem
pertinerent ?
???+ warning inline end "<a id='toto'></a>ATTENTION !"

    **Toto** est dans la place...


    *Ceci est une mise en garde,
     vous voilà prévenu !!*

        Sed quid est quod in hac
        causa maxime homines
        admirentur et repredant
        meum consilium, cum ego
        idem antea multa derim,
        que magis ad hominis
        dignitatem quam ad rei
        publicae necessitatem
        pertinerent ?

Sed quid est quod in hac
causa maxime homines
admirentur et repredant
meum consilium, cum ego
idem antea multa derim,
que magis ad hominis
dignitatem quam ad rei
publicae necessitatem
pertinerent ?
Sed quid est quod in hac
causa maxime homines
admirentur et repredant
meum consilium, cum ego
idem antea multa derim,
que magis ad hominis
dignitatem quam ad rei
publicae necessitatem
pertinerent ?

    Sed quid est quod in hac
    causa maxime homines
    admirentur et repredant
    meum consilium, cum ego
    idem antea multa derim,
    que magis ad hominis
    dignitatem quam ad rei
    publicae necessitatem
    pertinerent ?

Sed quid est quod in hac
causa maxime homines
admirentur et repredant
meum consilium, cum ego
idem antea multa derim,
que magis ad hominis
dignitatem quam ad rei
publicae necessitatem
pertinerent ?

Sed quid est quod in hac causa maxime homines admirentur et repredant meum consilium, cum ego idem antea multa derim, que magis ad hominis dignitatem quam ad rei publicae necessitatem pertinerent ?

ATTENTION !

Toto est dans la place...

Ceci est une mise en garde, vous voilà prévenu !!

Sed quid est quod in hac
causa maxime homines
admirentur et repredant
meum consilium, cum ego
idem antea multa derim,
que magis ad hominis
dignitatem quam ad rei
publicae necessitatem
pertinerent ?

Sed quid est quod in hac causa maxime homines admirentur et repredant meum consilium, cum ego idem antea multa derim, que magis ad hominis dignitatem quam ad rei publicae necessitatem pertinerent ? Sed quid est quod in hac causa maxime homines admirentur et repredant meum consilium, cum ego idem antea multa derim, que magis ad hominis dignitatem quam ad rei publicae necessitatem pertinerent ?

Sed quid est quod in hac
causa maxime homines
admirentur et repredant
meum consilium, cum ego
idem antea multa derim,
que magis ad hominis
dignitatem quam ad rei
publicae necessitatem
pertinerent ?

Sed quid est quod in hac causa maxime homines admirentur et repredant meum consilium, cum ego idem antea multa derim, que magis ad hominis dignitatem quam ad rei publicae necessitatem pertinerent ?

Remarque :

Snippets concatène (agrège) tout le code contenu dans les fichiers à inclure, il peut donc être nécessaire d'insérer des sauts de lignes et/ou des indentations entre les extraits inclus.

Le fonctionnement de Snippets est-il récursif ?

Si comme moi vous êtes joueur, vous brulez d'envie de l'expérimenter pour le vérifier par vous même... , sinon :

divulgachage n°1 :divulgachage n°2 :divulgachage n°3 :

La réponse se trouve là…

Oui, c'est récursif au sens ou un fichier_a.md peut inclure un fichier_b.md qui lui même inclut un autre fichier_c.md et ainsi de suite...

Non, ce n'est pas vraiment récursif car le fichier_b.md ne peut pas s'inclure lui même, ni être inclus dans le fichier_c qu'il inclut déjà.
Dès que Snippets rencontre une nouvelle fois un même fichier dans la pile d'appels, le processus d'inclusion s'arrête par sécurité pour éviter une boucle infinie...

Un fichier unique de références hypertextes et d'abréviations : ...

L'extension Snippets permet ainsi de créer facilement un fichier commun de références pour regrouper toutes les adresses de liens des différentes pages d'un site.

De plus, en l'associant avec l'extension md abbr qui sert à définir des abréviations et qu'il faut rajouter dans le fichier mkdocs.yml :

markdown_extensions:
- abbr
- pymdownx.snippets

Il est possible de créer un glossaire d'acronymes :

Fichier : includes/md/abr_ref-exemple.mdMarkDownRendu

<!-- Liste d'abréviations -->
*[HTML]: Hyper Text Markup Language

<!-- Liste d'URL référencées pour liens hypertextes -->
[W3C]: https://www.w3.org/Consortium/ "World Wide Web Consortium"

La spécification HTML est maintenue par le [W3C]{target=_blank}.

--8<-- "includes/md/abr_ref-exemple.md"

La spécification HTML est maintenue par le W3C.

Autres fichiers#

On observe que le contenu du fichier .py n'est pas bien interprété car son indentation n'est pas respecté.

Ce genre de contenu ne sera correctement affiché que dans un bloc de code encadré entre des ``` et en précisant le langage si on souhaite la coloration syntaxique.

Pour un affichage plus basique en texte brut, il suffit d'indenter de 4 espaces à gauche avant les ciseaux --8<-- :

MarkDown avec inclusionCode MarkDown généréRendu

    --8<-- "includes/py/exemple.py"

    def tri_bulles(items):
        for i in range(len(items)):
            for j in range(len(items) - 1 - i):
                if items[j] > items[j + 1]:
                    items[j], items[j + 1] = items[j + 1], items[j]

def tri_bulles(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

En revanche le code du fichier .svg est bien interprété.

Voici donc une autre façon d'intégrer une image SVG mais sans la gestion ici de la taille d'affichage :

MarkDown avec inclusionCode MarkDown généréRendu

<figure markdown>
    --8<-- "docs/images/undraw_Polaroid.svg" 
<figcaption markdown>
        Un Polaroïd selon [unDraw]{target="_blank"}
    </figcaption>
</figure>

<figure markdown>
    <svg id="b05a8b24-0cfe-4b22-93a9-3846e5c8b4da" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" width="541" height="606" viewBox="0 0 541 606"><path d="M847.04975,752.74227H352.02241a23.01224,23.01224,0,0,1-22.98633-22.98633V169.7286a23.01224,23.01224,0,0,1,22.98633-22.98633H847.04975a23.01223,23.01223,0,0,1,22.98633,22.98633V729.75594A23.01224,23.01224,0,0,1,847.04975,752.74227Z" transform="translate(-329.03608 -146.74227)" fill="#f2f2f2"/><path d="M822.15608,185.74227h-445.24a15.64143,15.64143,0,0,0-15.62,15.62v410.42a15.64143,15.64143,0,0,0,15.62,15.62h445.24a15.64142,15.64142,0,0,0,15.62-15.62v-410.42A15.64142,15.64142,0,0,0,822.15608,185.74227Z" transform="translate(-329.03608 -146.74227)" fill="#e92063"/><path d="M608.57468,374.35144c-4.32513-7.1534-9.45023-14.7911-17.47656-17.12689-9.295-2.705-18.84337,2.66857-26.94255,7.97116a785.1068,785.1068,0,0,0-69.86968,51.47911l.02443.27768q26.06891-1.79775,52.13774-3.59549c12.55653-.86592,25.54444-1.85127,36.64094-7.7913,4.21074-2.254,8.3153-5.26492,13.08677-5.47473,5.9281-.26064,11.097,3.87955,15.15908,8.20508,24.0284,25.587,30.98174,64.71558,57.93919,87.19565A855.50925,855.50925,0,0,0,608.57468,374.35144Z" transform="translate(-329.03608 -146.74227)" fill="#fff"/><path d="M756.27371,591.37542c-2.65715-3.35527-3.74288-4.14107-6.36393-7.52739q-32.01228-41.40317-60.17793-85.6033-19.13118-30.01909-36.365-61.19105-8.2047-14.81953-15.95956-29.87171-6.0176-11.67106-11.76659-23.48172c-1.09608-2.24892-2.16111-4.50817-3.22084-6.77259-2.49711-5.325-4.94777-10.67584-7.57917-15.92849-2.99845-5.98673-6.64843-12.263-12.15458-16.28521a16.58291,16.58291,0,0,0-8.6389-3.32424c-4.48227-.28952-8.61819,1.56132-12.506,3.58274a402.57534,402.57534,0,0,0-79.16143,54.58907,412.12253,412.12253,0,0,0-64.31385,71.39123c-.56849.81168-1.91271.0362-1.33892-.78063q3.389-4.79254,6.91222-9.48162A414.39962,414.39962,0,0,1,549.436,362.00731q10.29109-6.66917,20.96917-12.71282c3.58789-2.03177,7.19143-4.03769,10.85681-5.91951,3.59319-1.84566,7.40852-3.50522,11.51339-3.56725,13.9691-.21713,21.20193,15.60277,26.17014,26.24763q2.342,5.02513,4.74076,10.01928,9.06538,18.9606,18.82876,37.57489,6.02554,11.4927,12.31489,22.851,19.57307,35.36991,41.6074,69.30778c19.4596,29.96994,38.764,56.445,60.93246,84.4711C757.97993,591.05488,756.88915,592.16125,756.27371,591.37542Z" transform="translate(-329.03608 -146.74227)" fill="#e4e4e4"/><path d="M500.99918,391.7498c-.81159-.90473-1.61813-1.80946-2.435-2.7142-6.44169-7.12414-13.35366-14.16556-22.19955-18.2498a32.20737,32.20737,0,0,0-13.49351-3.12778,38.50755,38.50755,0,0,0-14.01025,3.05543c-2.10936.8427-4.17228,1.79912-6.20389,2.81757-2.32141,1.16841-4.60142,2.41437-6.87083,3.67066q-6.39018,3.5362-12.61452,7.38261-12.38468,7.654-23.99362,16.47649-6.018,4.57539-11.78754,9.45061-5.36631,4.52882-10.51551,9.30066c-.73409.67725-1.83017-.41876-1.09609-1.096.90474-.8427,1.81982-1.68022,2.73491-2.50739q3.87743-3.50522,7.87906-6.876,7.29706-6.15735,14.972-11.83907,11.93484-8.84055,24.69136-16.48166,6.37466-3.81539,12.92476-7.31026c1.31848-.7031,2.65236-1.39071,4.00163-2.04212a63.792,63.792,0,0,1,9.51258-3.87226,33.84064,33.84064,0,0,1,14.3672-1.41137,37.405,37.405,0,0,1,13.25571,4.58571c8.68534,4.85455,15.42162,12.36123,21.97716,19.687C502.75715,391.39308,501.66611,392.49427,500.99918,391.7498Z" transform="translate(-329.03608 -146.74227)" fill="#e4e4e4"/><path d="M678.9595,465.57479l20.81236-7.61222,10.3334-3.77949a105.67624,105.67624,0,0,1,10.20179-3.51362,16.09445,16.09445,0,0,1,9.23387.11765,21.28211,21.28211,0,0,1,7.20219,4.46461,58.449,58.449,0,0,1,5.90731,6.30858c2.24977,2.70372,4.46631,5.43579,6.6928,8.1587q13.78369,16.857,27.38714,33.86031,13.60313,17.003,27.02437,34.15055,13.45406,17.18943,26.723,34.52261,1.62548,2.12337,3.24817,4.24888c.59767.78282,1.94533.01107,1.33922-.7828q-13.36689-17.50749-26.92011-34.87165-13.58655-17.40566-27.36086-34.66367-13.774-17.25766-27.73423-34.36566-3.4779-4.26211-6.96729-8.51485c-1.96228-2.39156-3.90244-4.8089-6.05473-7.03486-3.95068-4.08591-8.88656-7.69676-14.79487-7.79473-3.47378-.0576-6.83564,1.04471-10.06315,2.21231-3.47938,1.25872-6.95042,2.541-10.42536,3.812l-20.9579,7.66544-5.23947,1.91637c-.92981.34008-.52815,1.83954.41231,1.49557Z" transform="translate(-329.03608 -146.74227)" fill="#e4e4e4"/><path d="M473.62576,379.75015a33.60017,33.60017,0,0,0-33.83986,2.42A482.65361,482.65361,0,0,1,494.698,394.98639C487.20731,390.59664,481.34778,383.7189,473.62576,379.75015Z" transform="translate(-329.03608 -146.74227)" fill="#fff"/><path d="M439.68181,382.15146l-2.0361,1.655c.68871-.57924,1.40469-1.12233,2.14019-1.63626C439.75116,382.16417,439.71655,382.15745,439.68181,382.15146Z" transform="translate(-329.03608 -146.74227)" fill="#f2f2f2"/><path d="M735.95944,465.65083c-2.04871-2.49382-4.26372-5.105-7.32808-6.11793l-2.861.11283a324.5172,324.5172,0,0,0,86.43508,98.81564Q774.08247,512.05611,735.95944,465.65083Z" transform="translate(-329.03608 -146.74227)" fill="#fff"/><g opacity="0.17"><path d="M791.79345,323.39222c5.76935-2.51553-5.93086-3.9799-19.20533-4.46137s-29.33268-.45483-37.8158-1.82429c-8.2044-1.32446-7.5999-3.67944-8.29-5.81314s-3.84423-4.32149-16.64635-4.79579c-15.95307-.591-42.26067,1.684-54.30349.31817-11.23819-1.2746-4.558-5.27276-20.94516-5.42579-9.3576-.08738-21.41277,1.23075-31.825,1.54885a116.01452,116.01452,0,0,1-22.08215-1.15126c-5.075-.83149-8.60986-1.88563-14.32157-2.62006-14.99567-1.92821-44.33435-1.28008-70.5202,1.19119s-48.63194,6.52118-61.29082,10.53243-16.15629,7.96063-13.20756,11.3097c1.88293,2.13857,6.70129,4.13827,18.38945,4.99762,21.86194,1.60736,60.78519-1.15935,83.37576.303,12.5907.81506,18.17647,2.83584,29.22349,3.94158,11.86819,1.18794,29.24216,1.25091,46.31211,1.22273,35.54177-.05869,71.99263-.42383,109.16139-1.09351,15.52474-.27972,31.79162-.64338,48.31132-1.97637s33.36908-3.90493,36.85433-6.316" transform="translate(-329.03608 -146.74227)" fill="#fff"/></g><circle cx="217.0152" cy="124.42378" r="2.99187" fill="#fff"/><circle cx="290.23466" cy="91.99777" r="1.79512" fill="#fff"/><circle cx="191.23466" cy="202.99777" r="1.79512" fill="#fff"/><circle cx="397.23154" cy="119.40752" r="1.79512" fill="#fff"/><circle cx="278.23154" cy="170.40752" r="1.79512" fill="#fff"/><circle cx="327.23154" cy="138.40752" r="1.79512" fill="#fff"/><circle cx="417.93247" cy="234.36521" r="1.79512" fill="#fff"/><circle cx="73.93247" cy="219.36521" r="1.79512" fill="#fff"/><path d="M837.77607,576.85225v34.93a15.64142,15.64142,0,0,1-15.62,15.62h-445.24a15.64143,15.64143,0,0,1-15.62-15.62v-43.64a264.22453,264.22453,0,0,1,70.01-7.48c56.9,1.24,112.47,16.43,168.84,24.29a659.89327,659.89327,0,0,0,199.88-2.75C812.48609,580.11226,825.1761,577.67226,837.77607,576.85225Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><path d="M686.761,417.85547c-2.27357-4.20958-2.591-9.7268.20064-13.61217a22.04318,22.04318,0,0,0,8.78119,12.32609c1.65858,1.12925,3.62091,2.21254,4.1883,4.13717a4.92756,4.92756,0,0,1-.51378,3.61684,14.63438,14.63438,0,0,1-2.27087,2.96491l-.08038.30113C692.95023,425.15035,689.03457,422.06505,686.761,417.85547Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><path d="M540.761,529.85547c-2.27357-4.20958-2.591-9.7268.20064-13.61217a22.04318,22.04318,0,0,0,8.78119,12.32609c1.65858,1.12925,3.62091,2.21254,4.1883,4.13717a4.92756,4.92756,0,0,1-.51378,3.61684,14.63438,14.63438,0,0,1-2.27087,2.96491l-.08038.30113C546.95023,537.15035,543.03457,534.06505,540.761,529.85547Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><path d="M720.761,506.85547c-2.27357-4.20958-2.591-9.7268.20064-13.61217a22.04318,22.04318,0,0,0,8.78119,12.32609c1.65858,1.12925,3.62091,2.21254,4.1883,4.13717a4.92756,4.92756,0,0,1-.51378,3.61684,14.63438,14.63438,0,0,1-2.27087,2.96491l-.08038.30113C726.95023,514.15035,723.03457,511.06505,720.761,506.85547Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><path d="M452.16255,264.0201A31.01709,31.01709,0,1,1,483.17964,233.003,31.052,31.052,0,0,1,452.16255,264.0201Z" transform="translate(-329.03608 -146.74227)" fill="#fff"/><path d="M545.59839,231.41249c-8.0763-8.47227-17.45607-16.20121-28.56-20.28545a45.90466,45.90466,0,0,0-9.56581-2.40387c-.02626-.00362-.05113.00171-.07725-.0004a1.40837,1.40837,0,0,0-.16135-.03167,36.82309,36.82309,0,0,0-13.66765.82514,37.76206,37.76206,0,0,0-6.36383,2.21691,55.65007,55.65007,0,0,0-5.97143,3.38416A38.83959,38.83959,0,0,1,468.03554,220.04a44.3928,44.3928,0,0,1-7.08718.69559,17.11875,17.11875,0,0,0-5.96219.85823,14.31053,14.31053,0,0,0-8.71529,9.43667.92793.92793,0,0,0,.41248,1.01363c.52865.37862,1.044.80819,1.59944,1.1455a4.98957,4.98957,0,0,0,1.56233.4261q1.32459.27951,2.65255.54268,4.8922.96933,9.82507,1.71609,9.98148,1.511,20.07078,2.12875a223.4829,223.4829,0,0,0,40.3964-1.21409,224.25471,224.25471,0,0,0,22.41238-3.87651A.90587.90587,0,0,0,545.59839,231.41249Z" transform="translate(-329.03608 -146.74227)" fill="#f0f0f0"/><path d="M453.61072,251.81649a45.90466,45.90466,0,0,0-9.56581-2.40387c-.02626-.00361-.05113.00172-.07725-.0004a1.40835,1.40835,0,0,0-.16135-.03166,36.82309,36.82309,0,0,0-13.66765.82514,37.76118,37.76118,0,0,0-6.36383,2.21691,55.65281,55.65281,0,0,0-5.97144,3.38415,38.83947,38.83947,0,0,1-13.19553,4.92271,44.39166,44.39166,0,0,1-7.08718.6956,17.11851,17.11851,0,0,0-5.96219.85823A14.31052,14.31052,0,0,0,382.8432,271.72a.92793.92793,0,0,0,.41248,1.01363c.52865.37862,1.044.80819,1.59944,1.14551a4.9901,4.9901,0,0,0,1.56233.4261q1.32459.27949,2.65255.54268,4.89221.96933,9.82507,1.71609,9.98148,1.511,20.07078,2.12875a223.482,223.482,0,0,0,40.3964-1.2141,224.25181,224.25181,0,0,0,22.41238-3.8765.90588.90588,0,0,0,.39608-1.50018C474.09441,263.62967,464.71464,255.90073,453.61072,251.81649Z" transform="translate(-329.03608 -146.74227)" fill="#f0f0f0"/><path d="M592.03608,681.74227h-225a6,6,0,0,1,0-12h225a6,6,0,1,1,0,12Z" transform="translate(-329.03608 -146.74227)" fill="#ccc"/><path d="M479.03608,715.24227h-112a6,6,0,0,1,0-12h112a6,6,0,1,1,0,12Z" transform="translate(-329.03608 -146.74227)" fill="#ccc"/><polygon points="107.375 384.038 124.578 370.977 132.963 379.362 104.938 398.541 107.375 384.038" fill="#2f2e41"/><path d="M420.36583,566.74387H361.51722l2.064-6.68758h0c12.79222-4.63087,5.60682-14.58464,17.77517-20.66882,29.7631-14.88155,41.28561-59.28965,36.92732-76.84429l19.50438-.82469S464.72374,538.21174,420.36583,566.74387Z" transform="translate(-329.03608 -146.74227)" fill="#2f2e41"/><path d="M470.60568,535.3075a9.89147,9.89147,0,0,1-12.78172.23913l-.03826-.03142-.00131-.04919a9.47684,9.47684,0,0,0-.37995-2.4188,6.77026,6.77026,0,0,1-.24584,1.67423l-.04929.1836-.13219-.13647c-.11417-.11773-.22466-.23731-.32842-.35529a9.97468,9.97468,0,0,1-1.51926-2.30058,29.07888,29.07888,0,0,0-8.06828-10.05664,14.118,14.118,0,0,1-1.69263-1.62867,13.95425,13.95425,0,0,1,17.52315-21.25934l.08719.051-.04528.09025a7.26871,7.26871,0,0,1-1.29692,1.87076,9.47928,9.47928,0,0,0,1.9974-1.44308l.06337-.05975.0718.04951a14.01337,14.01337,0,0,1,2.55182,2.27146l.08134.09326a6.2294,6.2294,0,0,0,4.6128,2.12867,9.88837,9.88837,0,0,1,9.57517,11.58491l-.0112.06532-.06355.01925a8.48535,8.48535,0,0,1-3.45588.43121,9.64019,9.64019,0,0,0,3.07823.771l.13713.01088-.04353.13058a9.8818,9.8818,0,0,1-2.852,4.30008l-.03754.03285-.03986.03489a9.7103,9.7103,0,0,0-3.35461,6.74A9.964,9.964,0,0,1,470.60568,535.3075Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><path d="M472.40585,532.12862a9.86349,9.86349,0,0,1-.11121,1.06328,9.99679,9.99679,0,0,0,1.60714-4.95271c.01311-.27.04146-.539.07947-.80679A9.38181,9.38181,0,0,0,472.40585,532.12862Z" transform="translate(-329.03608 -146.74227)" opacity="0.15"/><path d="M475.51806,520.10833a9.62507,9.62507,0,0,0,2.45985.6955,9.89773,9.89773,0,0,0,.90133-1.0997A8.38739,8.38739,0,0,1,475.51806,520.10833Z" transform="translate(-329.03608 -146.74227)" opacity="0.15"/><path d="M479.14311,516.86068a9.949,9.949,0,0,1-.07038,2.5661,9.83448,9.83448,0,0,0,1.11307-2.29544l.04354-.13058-.13714-.01088A9.55592,9.55592,0,0,1,479.14311,516.86068Z" transform="translate(-329.03608 -146.74227)" opacity="0.15"/><path d="M478.228,507.47444a9.91161,9.91161,0,0,0-7.25857-3.35623,6.22938,6.22938,0,0,1-4.61281-2.12868l-.08134-.09325a14.01337,14.01337,0,0,0-2.55182-2.27146l-.0718-.04951-.06336.05975a9.47874,9.47874,0,0,1-1.99742,1.44307,7.269,7.269,0,0,0,1.297-1.87076l.04525-.09024-.08718-.051a13.94385,13.94385,0,0,0-20.659,9.02719,13.94642,13.94642,0,0,1,19.163-5.13776l.08718.051-.04525.09024a7.26926,7.26926,0,0,1-1.297,1.87076,9.47868,9.47868,0,0,0,1.99741-1.44307l.06337-.05975.0718.04951a14.01337,14.01337,0,0,1,2.55182,2.27146l.08133.09326a6.22944,6.22944,0,0,0,4.61282,2.12867,9.89007,9.89007,0,0,1,9.565,8.12834,11.98677,11.98677,0,0,0,1.43129-.34829l.06355-.01925.01125-.06532A9.85036,9.85036,0,0,0,478.228,507.47444Z" transform="translate(-329.03608 -146.74227)" opacity="0.15"/><path d="M499.04886,466.75383a31.84958,31.84958,0,0,1-26.603,31.41149l-.15732.02566-.12171-.10142a30.51655,30.51655,0,0,0-6.656-4.22513,21.8005,21.8005,0,0,1,3.52508,4.15475l.339.50961-.611.0294c-.52742.02566-1.05152.0385-1.55741.0385a32.118,32.118,0,0,1-8.793-1.21919,93.63086,93.63086,0,0,0-41.47214-1.87907,45.458,45.458,0,0,1-7.53721.62884,44.93133,44.93133,0,0,1-14.1355-87.57594l.30883-.10225.12192.30138a23.40468,23.40468,0,0,1,1.765,7.11391,30.52291,30.52291,0,0,0,.75863-7.898l-.00973-.28026.2724-.06831a45.12252,45.12252,0,0,1,10.91843-1.33924l.39846.00165a20.05806,20.05806,0,0,0,14.956-6.62582,31.83962,31.83962,0,0,1,48.3716,1.48579l.13413.166-.08859.19457a27.32206,27.32206,0,0,1-6.30664,9.27243,31.04045,31.04045,0,0,0,8.4101-5.80282l.31794-.30842.22313.38293a31.8183,31.8183,0,0,1,4.33152,16.03983l-.00041.16063c-.00042.05672-.00042.11385-.00042.17056a31.26636,31.26636,0,0,0,9.1619,22.44376A32.08311,32.08311,0,0,1,499.04886,466.75383Z" transform="translate(-329.03608 -146.74227)" fill="#3f3d56"/><g opacity="0.15"><path d="M460.11959,391.50282a22.49407,22.49407,0,0,1-4.012,4.92175,30.96211,30.96211,0,0,0,6.26856-3.91791Q461.26814,391.96086,460.11959,391.50282Z" transform="translate(-329.03608 -146.74227)"/><path d="M478.55133,429.51105A31.97,31.97,0,0,1,483.13,435.089a32.54708,32.54708,0,0,1-2.97907-13.6731c0-.05672,0-.11385.0004-.17055l.00041-.16063a31.81856,31.81856,0,0,0-4.3315-16.03983l-.22314-.38294-.318.30841a31.112,31.112,0,0,1-5.80764,4.42232A31.01389,31.01389,0,0,0,478.55133,429.51105Z" transform="translate(-329.03608 -146.74227)"/><path d="M469.39025,406.7361l-.0004.16063c-.00041.05671-.00041.11384-.00041.17056,0,.31256.00566.62434.01439.93563a33.16272,33.16272,0,0,0,3.77185-6.50215l.08857-.19458-.13411-.166a32.10042,32.10042,0,0,0-5.76052-5.57135A31.89066,31.89066,0,0,1,469.39025,406.7361Z" transform="translate(-329.03608 -146.74227)"/><path d="M489.31279,443.85966a28.78932,28.78932,0,0,1-4.05843-4.93763,31.8105,31.8105,0,0,1-23.57,44.89467l-.15732.02568-.1217-.10143a30.5172,30.5172,0,0,0-6.65606-4.22512,21.79991,21.79991,0,0,1,3.52506,4.15473l.33907.50963-.611.02938c-.52745.02568-1.05154.03851-1.55741.03851a32.11821,32.11821,0,0,1-8.793-1.21919,93.631,93.631,0,0,0-41.47214-1.87907,45.45764,45.45764,0,0,1-7.53719.62883,44.7262,44.7262,0,0,1-29.84116-11.37979,44.97143,44.97143,0,0,0,40.60261,25.72841,45.45767,45.45767,0,0,0,7.5372-.62884,93.631,93.631,0,0,1,41.47214,1.87907,32.11819,32.11819,0,0,0,8.793,1.21919c.50588,0,1.03-.01283,1.55742-.03851l.611-.02938-.33907-.50962a21.79968,21.79968,0,0,0-3.52506-4.15474,30.5169,30.5169,0,0,1,6.656,4.22512l.12171.10143.15731-.02568a31.82584,31.82584,0,0,0,16.867-54.30565Z" transform="translate(-329.03608 -146.74227)"/></g></svg>
<figcaption markdown>
        Un Polaroïd selon [unDraw]{target="_blank"}
    </figcaption>
</figure>

Un Polaroïd selon unDraw

En conclusion, quelque soit l'extension du fichier inclu, MkDocs-Material avec l'extension Snippets va parser (analyser, chercher à interpréter) le code contenu comme s'il s'agissait d'un fichier .md.

S'il rencontre des caractères de balisage assimilable à MarkDown, HTML ou $\LaTeX$, il va les convertir pour générer le code HTML final destiné au navigateur.

Lors de la construction du site, MkDocs convertit chacun des fichiers truc.md qui se trouve dans le dossier docs en créant un dossier nommé truc contenant une copie du fichier truc.md et un fichier index.html généré à partir du code MarkDown de truc.md pour permettre son bon affichage dans un navigateur.
De même avec l'extension mkdocs-jupyter pour les fichiers en .py et .ipynb.
En conséquence, il est préférable de placer tous les fichiers d'extraits à inclure à l'extérieur du dossier docs par exemple dans un dossier nommé includes.

Note

Une autre solution consiste à modifier l'extension du fichier truc.md à inclure en truc.txt, par exemple, et ainsi le conserver dans le dossier docs sans qu'il soit automatiquement converti.

Tableau#

Exemple version basique : ...

MarkDownRendu

Aligné à gauche | Aligné à droite | Texte centré | Défaut
:---|---:|:---:|---
abcdef | 1234 | xyz | etc
ghi jkl mno pqr | 567890 | ........ | etc

Aligné à gauche	Aligné à droite	Texte centré	Défaut
abcdef	1234	xyz	etc
ghi jkl mno pqr	567890	........	etc

La syntaxe de ce type de tableau est très naturelle et légère.

Le type d’alignement dans chaque colonne (à gauche, à droite, centré) est défini dans la seconde ligne par la position du caractère double point : relativement aux tirets -.

Afin d'améliorer la lecture d'un tableau en mode éditon de code, on peut débuter et terminer chaque ligne par une barre verticale |, mais ce n’est pas obligatoire, et aussi ajouter des tirets et des espaces supplémentaires.
Le nombre de tirets dans la seconde ligne n’est pas significatif.

Exemple version plus esthétique : ...

MarkDownRendu

| Aligné à gauche | Aligné à droite | Texte centré | Défaut |
|:----------------|----------------:|:------------:|--------|
| abcdef          |            1234 |      xyz     | etc    |
| ghi jkl mno pqr |          567890 |   ........   | etc    |

Aligné à gauche	Aligné à droite	Texte centré	Défaut
abcdef	1234	xyz	etc
ghi jkl mno pqr	567890	........	etc

Astuces pour obtenir au clavier le caractère spécial | : ...

La barre verticale, également nommée tube ou pipe de l'Anglais, s'obtient avec la combinaison de touches AltGr＋6 ;

Solution pour centrer un tableau et lui ajouter une légende : ...

MarkDownRendu

<figure markdown>

  Aligné à gauche | Aligné à droite | Texte centré | Défaut
  :---|---:|:---:|---
  abcdef | 1234 | xyz | etc
  ghi jkl mno pqr | 567890 | ........ | etc

  <figcaption markdown>
    _Légende du **tableau**_
  </figcaption>
</figure>

Aligné à gauche	Aligné à droite	Texte centré	Défaut
abcdef	1234	xyz	etc
ghi jkl mno pqr	567890	........	etc

Légende du tableau

Générer le code MarkDown d'un tableau : ...

On peut avantageusement utiliser :

un générateur de tableau en ligne ;
Ou un script Python personnel... ;

Exemple :

from IPython.display import Markdown
chaine = "| d | b | h |" + "\n"
chaine += "|:-:" * 3 + "|" + "\n"
for i in range(16) :
    chaine += f"| {i} | {bin(i)} | {hex(i)} |" + "\n"
Markdown(chaine)

A tester : ...

Tri de tableau

Note de bas de page#

Sur son site, Franck CHAMBON présente très complètement les notes de bas de page ;

Il y a également la référence officielle footnotes ;

Exemple : ...

MarkDownRendu

Note pour le marquage de révision[^critic]

[^critic]:
    Le [marquage de révision](https://github.com/CriticMarkup/CriticMarkup-toolkit){target=_blank}
    s'applique aussi bien au rendu HTML qu'aux blocs de code et de texte brut.  
    Ceci est [une note de bas de page](#note-de-bas-de-page).

Note pour le marquage de révision¹

Info

Il faut activer dans le fichier mkdocs.yml l'extension footnotes pour autoriser les notes de bas de page.

markdown_extensions:
    - footnotes

Ancre#

Pour qu'un lien hypertexte pointe vers un endroit précis de la page courante, ou d'une autre page afin de positionner correctement le navigateur, il est nécessaire de définir une ancre :

Ancre sur les titres : ...

A partir des titres, MkDocs crée automatiquement des ancres vers lesquelles pointent les liens de la table des matières.
Pour le nommage de ces ancres, par défaut, les masjuscules sont transformées en minuscules, les espaces sont remplacés par des - et les caractères accentués deviennent des caractères de la table ASCII.

MarkDownRendu

[Lien vers le titre "Caratères spéciaux"](#caracteres-speciaux)

Lien vers le titre "Caratères spéciaux"

Ancre sur les notes de bas page : ...

Une note de bas de page qui aurait bar pour référence d'identification, génère deux ancres :

l'une pour aller au contenu de la note de bas de page, #fn:bar ;
et l'autre pour revenir dans le texte à une référence liée à cette note, #reffn:bar.

MarkDownRenduMarkDownRenduMarkDownRendu

[Lien vers la note de bas de page "critic"](#fn:critic)

Lien vers la note de bas de page "critic"

[Lien de retour vers une référence à la note de bas de page "critic"](#fnref:critic)

Lien de retour vers une référence à la note de bas de page "critic"

[Lien de retour vers une autre référence à la note de bas de page "critic"](#fnref2:critic)

Lien de retour vers une autre référence à la note de bas de page "critic"

Ancre à un endroit quelconque : ...

Pour créer une ancre à un endroit quelconque au beau milieu du MarkDown on peut y placer une balise HTML invisible en lui attribuant un identifiant : <a id="foo"></a>.
Et puis, pour pointer vers cet endroit, on lui associe un lien débutant par le caractère dièse #, suivi du nom de cet identifiant : [lien vers l'ancre identifiée "foo"](#foo)

MarkDownRendu

[Lien vers l'ancre "toto"](#toto)

Lien vers l'ancre "toto"

Bouton#

Sur son site, Franck CHAMBON présente très complètement l'ajout de boutons ;

Il y a également la référence officielle buttons ;

Exemple : ...

RenduMarkDownMarkDown bouton pleinRendu bouton plein

Poser une question à l'auteur...

[![envelope]{align=left width=40%} <br>Poser une question à l'auteur...
 :fontawesome-solid-paper-plane: ](mailto:eric.madec@ecmorlaix.fr
 ?subject=Le MarkDown de Mkdocs-Material&body=Votre question : ...
 ){ .md-button }

[![envelope]{align=left width=40%} <br>Poser une question à l'auteur...
 :fontawesome-solid-paper-plane: ](mailto:eric.madec@ecmorlaix.fr
 ?subject=Le MarkDown de Mkdocs-Material&body=Votre question : ...
 ){ .md-button .md-button--primary }

Poser une question à l'auteur...

Toujours en construction...#

Illustration par unDrawn de la construction d'un mur

Caractères spéciaux#

Entités HTML#

Puisque MarkDown interprète quatre espaces laissés au début d'une ligne de texte comme une intention de généré l'affichage d'un bloc de code et supprime automatiquement les espaces supplémentaires laissés vide, une solution pour en introduire malgré tout est d'utiliser l'entité HTML   correspondante à une espace insécable (&NonBreakingSpace;).

MarkDownRendu

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Une indentation de plus de quatre espaces,
et un vide &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;laissé au milieu de cette ligne de texte.

<!-- un vrai commentaire qui ne s'affichera pas-->
&emsp;&emsp;&emsp;&lt;&excl;&hyphen;&hyphen; ceci est&mldr;
&ensp;&ensp;&ensp;&ensp;&ensp;&ensp;&mldr;un faux commentaire &hyphen;&hyphen;&gt;

Une indentation de plus de quatre espaces, et un vide laissé au milieu de cette ligne de texte.

<!‐‐ ceci est… …un faux commentaire ‐‐>

De la même façon tout autre symbole ou entité HTML peut être introduit ainsi dans du code MarkDown.

Icônes - Emojis#

Il y a la référence officielle icons-emojis ;

Sur son site, Franck CHAMBON présente l'ajout d'émojis et de caractères unicodes ;

Touches#

Sur son site, Franck CHAMBON présente des exemples d'ajout de touches ;

Il y a également la documentation et la référence officielles

Echappement#

En dehors des structures de type code inline ou bloc de texte brut, il peut être nécessaire de mettre un caractère backslash \ devant des caractères qui sinon sont interprétés en Markdown, HTML ou Latex.

Par exemple : ...

avec \sans \

Code :

\##### Usage de l'antislash \\ :

1\. \`code`  
5\. <@\>  
3\. !\[image](url "info"){ heigt=30 align=left}  

\> \~\~barré~~, 
\^\^souligné^^,
\==surligné==, ...

\- \__MarkDown__ ;  
\+ <em\>HTML<em\> ;  
\* \$\LaTeX$ ;

Rendu :

##### Usage de l'antislash \ :

1. `code`
5. <@>
3. ![image](url "info"){ heigt=30 align=left}

> ~~barré~~, ^^souligné^^, ==surligné==, ...

- __MarkDown__ ;
+ <em>HTML<em> ;
* $\LaTeX$ ;

Code :

##### Usage de l'antislash \ :

1. `code`  
5. <@>  
3. ![image](url "info"){ heigt=30 align=left}

> ~~barré~~,
^^souligné^^,
==surligné==, ...

- __MarkDown__  
+ <em>HTML<em>  
* $\LaTeX$

Rendu :

Usage de l'antislash :#

code
<@>

~~barré~~, souligné, surligné, ...

MarkDown
HTML

$\LaTeX$

Ressources#

https://www.jdbonjour.ch/cours/markdown-pandoc/

http://pageperso.lif.univ-mrs.fr/~edouard.thiel/mkdocs-et/

https://agea.github.io/tutorial.md/

https://learninglab.gitlabpages.inria.fr/mooc-rr/mooc-rr-ressources/module1/ressources/introduction_to_markdown_fr.html

https://learninglab.gitlabpages.inria.fr/mooc-impacts-num/mooc-impacts-num-ressources/Exemples.html

https://www.markdownguide.org/

https://www.markdowntutorial.com/

https://www.ionos.fr/digitalguide/sites-internet/developpement-web/markdown/

https://docs.microsoft.com/en-us/contribute/markdown-reference

https://jupyterbook.org/content/myst.html Markedly Structured Text

Le marquage de révision s'applique aussi bien au rendu HTML qu'aux blocs de code et de texte brut.
Ceci est une note de bas de page. ↩↩

MarkDown Mkdocs-Material pour le contenu#

Introduction#

Titres#

Corps de texte#

Lien#

Image#

Trait horizontal#

Listes#

Liste à puces#

Liste ordonnées#

Liste de taches#

Liste de description#

Citation#

Admonition#

Onglet#

Codes#

Code inline#

Bloc de texte brut#

Bloc de code#

Coloré#

Numéroté, surligné#

Intégré#

Inclusion#

Fichier .md#

Autres fichiers#

Tableau#

Note de bas de page#

Ancre#

Bouton#

Toujours en construction...#

Caractères spéciaux#

Entités HTML#

Icônes - Emojis#

Touches#

Echappement#

Usage de l'antislash :#

Ressources#

Fichier `.md`#