Aller au contenu

Extensions Markdown

Enrichir vos pages avec des admonitions, onglets, coloration de code, emojis et grilles de cartes.

Configuration

Les extensions s'ajoutent dans properdocs.yml :

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - attr_list
  - md_in_html
  - toc:
      permalink: true

Admonitions

Blocs d'information mis en avant : notes, astuces, avertissements.

!!! note "Titre"
    Contenu de la note.

!!! tip "Astuce"
    Contenu de l'astuce.

!!! warning "Attention"
    Contenu de l'avertissement.

!!! danger "Danger"
    Contenu de danger.

Résultat :

Titre

Contenu de la note.

Astuce

Contenu de l'astuce.

Attention

Contenu de l'avertissement.

Admonitions dépliables

??? note "Cliquer pour ouvrir"
    Contenu caché par défaut.

???+ warning "Ouvert par défaut"
    Contenu visible par défaut.
Cliquer pour ouvrir

Contenu caché par défaut.

Ouvert par défaut

Contenu visible par défaut.

Onglets de code

Comparer plusieurs langages côte à côte :

=== "Python"

    ```python
    print("Hello World")
    ```

=== "JavaScript"

    ```javascript
    console.log("Hello World")
    ```

Résultat :

print("Hello World")

console.log("Hello World")

Coloration de code

Avec numéros de ligne et surbrillance :

```python title="example.py" linenums="1" hl_lines="2 3"
def hello(name):
    """Saluer un utilisateur."""
    print(f"Bonjour {name}!")
    return True
```
example.py
1
2
3
4
def hello(name):
    """Saluer un utilisateur."""
    print(f"Bonjour {name}!")
    return True

Emojis & Icônes Material

Utilisez les icônes Material Design inline :

:material-home: :material-github: :fontawesome-brands-python:
:octicons-star-16: :material-check:

Grid Cards

Grille de cartes cliquables avec attr_list + md_in_html :

<div class="grid cards" markdown>

-   :materialrocket-launch:{ .lg .middle } __Titre__

    ---

    Description de la carte.

    [:octicons-arrow-right-24: Lien](page.md)

</div>

Résultat :

  • Exemple

    Une carte de démonstration avec un lien.

    Voir

Liens boutons

[:material-download: Télécharger](fichier.zip){ .md-button .md-button--primary }
[:fontawesome-brands-github: GitHub](https://github.com){ .md-button }

Télécharger GitHub

Listes de définition

Terme
:   Définition du terme

Autre terme
:   Une autre définition

Footnotes

Ceci est un texte avec une note[^1].

[^1]: Voici le contenu de la note.

Table des matières

markdown_extensions:
  - toc:
      permalink: true    # Lien d'ancrage sur chaque titre

Titres et numérotation

Habillage des titres

Chaque titre porte la classe de son niveau, définie dans docs/css/custom.css :

# <span class="h1">Titre de la page</span>

## <span class="h2">Section</span>

### <span class="h3">Sous-section</span>

Numérotation des étapes

Convention

Les étapes d'un tutoriel pas-à-pas se numérotent en chiffres arabes : un h2 pour l'étape, un h3 pour la sous-étape.

## <span class="h2">1. Créer le compte</span>

### <span class="h3">1.1 Installer l'extension</span>

Une fois les étapes numérotées, tout renvoi dans le texte cite le numéro — « retourne à l'étape 3 » — jamais la lettre. Les pages de concepts (cours, notes, fiches projets) ne numérotent pas leurs titres : l'habillage h2/h3 suffit à les repérer.

C'est la forme prévue par la norme ISO 2145 — chiffres arabes, point entre les niveaux, rien après le dernier numéro.