Format Markdown en entrée

Elium sait importer et exporter des contenus en Markdown. Cette page décrit le Markdown qu’Elium importe sans perte, que le contenu vienne d’un copier-coller depuis un autre outil, d’une migration en masse ou d’une génération automatique (par un modèle d’IA, par exemple).

Le format repose sur CommonMark, enrichi de quelques extensions courantes. Partout où la syntaxe Markdown suffit, Elium l’utilise telle quelle. Pour le reste, deux notations prennent le relais : une directive {% … %}, qui ajoute des attributs à un bloc Markdown ou décrit un bloc sans équivalent Markdown (encadrés, sections repliables), et le HTML canonique, la forme la plus précise, qui couvre tout ce qui reste (fichiers, galeries, contenus intégrés, blocs de contenu lié, tableaux et images enrichis).

Fonctionnement

Markdown pris en charge

Elium reconnaît tous les éléments ci-dessous. Un élément "en ligne" s’insère dans une ligne de texte ; un "bloc" occupe une ou plusieurs lignes à lui seul.

Dans un paragraphe, un simple saut de ligne est conservé et devient un retour à la ligne. Une URL écrite seule ne devient pas un lien : utilisez la forme [libellé](url).

Les trois formes

Tout ce que vous écrivez appartient à l’une de ces trois formes, de la plus simple à la plus précise. Prenez toujours la plus simple qui suffit :

1. Le Markdown pur. Tout ce que CommonMark sait exprimer s’écrit en CommonMark : ## Titre pour un titre, - [x] fait pour une tâche, un bloc de code pour du code. C’est la forme à privilégier.

2. Une directive {% … %}. Elle sert à deux choses, et deux seulement :

   • {% attrs %} complète un bloc Markdown avec des attributs que la syntaxe ne prévoit pas (alignement ou ancre d’un titre, alignement d’un paragraphe). Le bloc lui-même reste écrit en Markdown, à l’intérieur de la directive.

   • Une directive nommée ({% callout %}, {% collapse %}) décrit un bloc sans équivalent Markdown, dont le contenu reste malgré tout du Markdown.

3. Le HTML canonique. La forme la plus précise et la plus complète : un sous-ensemble défini de balises et d’attributs HTML, où chaque construction prise en charge par Elium a exactement une écriture. On y trouve des balises HTML classiques (<table>, <img>, <blockquote>) et des éléments el-* propres à Elium (<el-callout>, <el-asset>, <el-collapse>). Tout peut s’écrire ainsi, et certains blocs riches (fichiers, galeries, blocs de contenu lié, tableaux et images enrichis) n’ont aucune autre écriture.

Une directive s’écrit ainsi :

{% callout type="warning" %}
Le contenu, écrit en Markdown normal.
{% endcallout %}

• Les options se placent sur la balise d’ouverture, sous forme de paires nom="valeur" séparées par des espaces. La valeur peut être entre guillemets (title="A b"), sans guillemets si elle ne contient pas d’espace (type=warning), ou omise pour dire true (isTree). Un booléen absent vaut false.

• Le corps est du Markdown et peut lui-même contenir d’autres blocs.

• L’écriture sur une seule ligne est acceptée : {% callout %}Attention.{% endcallout %}.

La directive {% attrs %} entoure un seul bloc Markdown et lui applique ses options :

{% attrs align="center" id="intro" %}
## Un titre centré avec une ancre
{% endattrs %}

Elium normalise ce que vous écrivez

Elium conserve une seule forme canonique, et c’est elle qu’il produit à l’export Markdown : vous ne retrouvez donc pas votre Markdown à l’identique. Chaque élément est réécrit dans la forme la plus simple capable de l’exprimer :

• un bloc de code garde son langage en premier mot de l’info string, et le nom de fichier éventuel suit sous la forme name="…" ;

• un tableau simple et rectangulaire reste un tableau à barres verticales ; dès qu’il comporte des cellules fusionnées, des couleurs, des largeurs ou une colonne d’en-tête, il ressort en <table> HTML ;

• un titre aligné ou doté d’une ancre, un paragraphe ou une tâche alignés, ressortent entourés de {% attrs %} ;

• une image avec un style, un lien ou une taille explicite ressort en <img> HTML (une image en ligne sans option reste ![alt](url)).

Écrivez dans la forme qui vous arrange ; c’est la forme canonique qui vous revient.

Les éléments non reconnus

Les éléments non reconnus suivent des règles simples :

• Une directive au nom inconnu ({% foo %}) reste du texte. Seules les directives décrites sur cette page sont reconnues.

• Du HTML en ligne qui sort de l’ensemble reconnu (voir Texte et mise en forme en ligne) reste du texte, tel quel.

• Une balise {% … %} indentée de quatre espaces ou plus, ou placée dans un élément de liste, est lue comme du texte ou du code, pas comme une directive.

• Le frontmatter n’est lu que s’il ouvre le document et forme un dictionnaire YAML valide ; ses clés inconnues sont ignorées.

Vue d’ensemble

Exemple rapide

---
showHeadingNumbers: true
---

# Nouveautés

Nous avons livré quelques améliorations cette semaine.

{% callout type="info" %}
Consultez le [journal des modifications](https://example.com/log) pour la liste complète.
{% endcallout %}

## Points forts

- [x] Import plus rapide
- [ ] Mode sombre

```bash name="upgrade.sh"
npm install elium@latest
```

Frontmatter du document

Un document peut s’ouvrir sur un bloc de frontmatter YAML, qui contient des métadonnées de l’article et du document. Ce bloc doit être le tout premier et former un dictionnaire YAML valide ; les clés inconnues sont ignorées.

---
showHeadingNumbers: true
summarized: false
---

# Premier titre

Clés prises en charge : showHeadingNumbers, summarized, toc, truncationResult.

Texte et mise en forme en ligne

Le socle commun à tous les blocs qui contiennent du texte.

CommonMark couvre l’essentiel : **gras**, *italique*, ~~barré~~, `code`, [lien](url) et ![alt](url). Elium ajoute :

• L’indice H~2~O et l’exposant x^2^.

• Les notes de bas de page : un appel [^label] dans le texte et sa définition [^label]: …, regroupée avec les autres en fin de contenu :

Elium importe CommonMark[^cm] et quelques extensions.

[^cm]: La spécification Markdown de référence.

Quand CommonMark ne suffit pas à décrire un élément en ligne, Elium accepte un ensemble restreint de HTML en ligne :

Une mention renvoie, dans le texte, à une personne, un espace, une équipe ou un article. L’élément est vide : data-type vaut user, space, team ou story, data-id donne l’identifiant et data-name le nom affiché. Tout balisage hors de cet ensemble reste du texte.

Blocs

Tous les blocs pris en charge par Elium, avec leur écriture en Markdown pur (quand elle existe) et le passage aux formes plus riches. La Vue d’ensemble en donne l’index.

Titre

Les titres de section, du niveau 1 au niveau 3.

Syntaxe

• Markdown pur : ## Titre de section (le nombre de # fixe le niveau).

• {% attrs %} autour du titre Markdown, quand il faut un alignement ou une ancre :

  {% attrs align="center" id="intro" %}
  ## Titre centré
  {% endattrs %}
  

Attributs (sur {% attrs %})

Contenu Markdown en ligne.

Paragraphe

Du texte courant. {% attrs %} ne sert ici qu’à l’aligner.

Syntaxe

• Markdown pur : du texte, séparé du reste par une ligne vide.

• {% attrs %} pour aligner le paragraphe :

  {% attrs align="right" %}
  Ce paragraphe est aligné à droite.
  {% endattrs %}
  

Attributs (sur {% attrs %})

Contenu Markdown en ligne.

Liste et liste de tâches

Listes à puces, numérotées ou à cocher.

Syntaxe

- puce
- avec un
  - élément imbriqué

1. premier
2. deuxième

- [ ] à faire
- [x] fait

Une liste qui mélange tâches et éléments ordinaires est scindée en plusieurs listes à l’import. Pour aligner une tâche isolée, entourez son - [x] de {% attrs %} :

{% attrs align="center" %}
- [x] Une tâche centrée
{% endattrs %}

Contenu Chaque élément accepte du Markdown en ligne et des listes imbriquées. Un titre ou un tableau placé dans un élément de liste est ramené à du texte simple.

Citation

Du texte cité.

Syntaxe

> Une ligne citée.
> Une deuxième ligne.

Contenu Markdown en ligne ; chaque ligne du bloc devient un retour à la ligne.

Tableau

Une grille de cellules. Un tableau simple et rectangulaire s’écrit avec des barres verticales ; tout ce qui va au-delà passe en HTML canonique.

Syntaxe

• Markdown pur : un tableau CommonMark à barres verticales (dans une cellule, une barre verticale littérale s’écrit \|).

• HTML canonique, dès qu’il faut des largeurs de colonnes, des cellules fusionnées, un alignement ou des couleurs par cellule, une colonne d’en-tête ou un bloc dans une cellule : une balise <table>.

Options (forme HTML)

Contenu Chaque cellule contient du Markdown.

Exemple

| Nom             | Caractère |
| --------------- | --------- |
| Accent grave    | `         |
| Barre verticale | \|        |

<table data-column-widths="120,-">
<tr>
<td>

Simple

</td>
<td align="center">

**Centré**

</td>
</tr>
</table>

Code

Un bloc de code, avec en option un titre ou un nom de fichier.

Syntaxe

• Markdown pur : un bloc de code classique. Le premier mot de l’info string (le texte qui suit les trois accents graves d’ouverture) donne le langage ; un attribut name="…" à sa suite donne le titre ou le nom de fichier.

Options de l’info string

En règle générale, le langage est ce premier mot. L’attribut language="…" n’est utile (et n’est produit) que si le nom du langage ne peut pas s’écrire tel quel dans l’info string.

Contenu Littéral. Le corps est conservé tel quel, jamais relu comme du Markdown.

Exemple

```python
import re

def word_count(html: str) -> int:
    return max(len(re.sub(r"<[^>]+>", " ", html).split()), 1)
```

```python name="word_count.py"
import re

def word_count(html: str) -> int:
    return max(len(re.sub(r"<[^>]+>", " ", html).split()), 1)
```

Encadré (callout)

Un encadré qui attire l’attention sur une note ou un avertissement. HTML canonique : <el-callout>.

Syntaxe

{% callout type="warning" %}
Attention : cette action est irréversible.
{% endcallout %}

Options

Contenu Markdown en ligne.

Section repliable (collapse)

Une section repliable, composée de sous-directives : un titre, des liens de navigation facultatifs et un corps. HTML canonique : <el-collapse>.

Syntaxe

{% collapse id="faq" %}
{% collapse-title %}
## Questions fréquentes
{% endcollapse-title %}

{% collapsable %}
Le corps est du Markdown normal et peut contenir n’importe quel autre bloc.
{% endcollapsable %}
{% endcollapse %}

Options (sur {% collapse %})

Sous-directives

• {% collapse-title %} : le titre, sous la forme d’un titre Markdown ou d’un paragraphe unique. Le niveau vient du nombre de # (un paragraphe donne un titre sans niveau).

• {% collapsable %} : le corps, avec ses blocs.

• {% collapse-navigation to="…" label="…" %}{% endcollapse-navigation %} : un lien facultatif vers une autre section (to donne l’identifiant cible, label le texte du lien). L’élément est vide et se place directement dans {% collapse %} :

  {% collapse id="q1" %}
  {% collapse-title %}
  ## Question 1
  {% endcollapse-title %}
  
  {% collapse-navigation to="q2" label="Question suivante" %}{% endcollapse-navigation %}
  
  {% collapsable %}
  La réponse vient ici.
  {% endcollapsable %}
  {% endcollapse %}
  

Image

Le Markdown pur suffit pour une image en ligne sans option ; le HTML canonique prend en charge la mise en page, le lien et la taille.

Syntaxe

• Markdown pur : ![alt](url) (une image en ligne sans option).

• HTML canonique, pour un style, un lien, une taille ou une image en bloc (sur sa propre ligne) : un élément <img>.

Options (forme HTML)

Exemple

<img src="https://example.com/photo.png" alt="Coucher de soleil" data-style="full-width" width="1200" height="630">

Fichier

Un renvoi vers une ressource stockée dans Elium, affiché en carte ou en aperçu. HTML canonique uniquement : <el-asset>.

Syntaxe

<el-asset data-asset="2f1c8e44-…" data-type="file" data-display-mode="card">
</el-asset>

Options

Galerie

Un ensemble de ressources présenté en grille ou en liste. HTML canonique uniquement : un <el-gallery> qui contient des éléments <el-gallery-asset>.

Syntaxe

<el-gallery title="Vacances" data-layout="gallery">
<el-gallery-asset data-asset="2f1c8e44-…" title="Itinéraire"></el-gallery-asset>
<el-gallery-asset data-asset="7c41ab90-…"></el-gallery-asset>
</el-gallery>

Options

Chaque <el-gallery-asset> porte un data-asset (l’UUID) et, en option, un title (la légende).

Contenu intégré (embed)

Un contenu externe (lecteur vidéo, widget) intégré sous forme de HTML. Il s’écrit dans un bloc de code dont l’info string est html type="embed".

Syntaxe

```html type="embed" height="420" scrolling="no"
<iframe src="https://example.com/player"></iframe>
```

Options de l’info string

Contenu Du HTML littéral, conservé tel quel.

Contenu lié

Des blocs qui renvoient vers un élément d’Elium. HTML canonique uniquement. (Pour renvoyer vers une personne, un espace ou un article dans le texte, utilisez plutôt une mention.)

Syntaxe

<el-space-box data-id="9b2e-…"></el-space-box>
<el-story-box data-id="7c41-…"></el-story-box>
<el-user-box data-id="42"></el-user-box>
<el-drive-folder data-folder-id="1AbCdEf…"></el-drive-folder>

Options

HTML brut

La solution de dernier recours : du HTML libre pour tout ce qu’aucun bloc Elium ci-dessus ne couvre. Il s’écrit dans un bloc de code dont l’info string est html type="html".

Syntaxe

```html type="html"
<section class="hero">Contenu HTML brut</section>
```

Contenu Du HTML littéral, conservé tel quel.

Tester un contenu dans le playground

Le playground, accessible à l’adresse /_debug/rich/playground, montre exactement comment Elium interprète un contenu, avant de l’importer.

Vous lui donnez :

• un format d’entrée : Markdown (CommonMark standard), Elium Markdown (CommonMark plus les directives {% … %} et le frontmatter décrits sur cette page), Canonical Elium HTML ou Slate ;

• une cible : Story, Comment, Template ou Smart feed. Chaque cible limite les blocs autorisés (un commentaire refuse les galeries, un article refuse les champs de modèle), et le même contenu peut donc donner un résultat différent d’une cible à l’autre.

Il affiche ensuite les erreurs et avertissements rencontrés (blocs supprimés, options ramenées à leur valeur par défaut, contenu normalisé), puis le résultat sous trois angles : le HTML rendu, le HTML canonique brut correspondant, et le Markdown produit en retour. Comparer ce Markdown à votre texte de départ est le moyen le plus rapide de voir ce que la normalisation a changé.