Importer du Markdown

Vous avez une pile d'écrits venant d'un autre outil : fichiers .md simples (un export de site statique, un CMS précédent, ou un dossier de notes) ? L'écran Import Markdown les transforme en pages ou posts brouillons en un seul lot : téléversez, passez en revue, publiez. Rien n'est publié automatiquement : chaque fichier importé atterrit comme un brouillon ordinaire, exactement comme si vous l'aviez tapé.

Démarrer un import

Dans l'admin, dirigez-vous vers une liste Pages ou Posts, puis ouvrez Import Markdown (pages et posts ont chacun leur route ; type fixe la cible).
Définissez la langue par défaut du lot.
Sélectionnez jusqu'à 100 fichiers .md/.markdown d'un coup (lot entier jusqu'à 40 MiB).
Téléversez.

Si les modules de conversion optionnels ne sont pas installés sur votre serveur, le formulaire vous le dit avant que vous ne choisissiez un seul fichier, et l'import échoue avec « ask an admin to install them » (demandez à un admin de les installer) : il n'échoue jamais silencieusement au milieu du lot.

Front matter

Chaque fichier peut commencer par un bloc d'en-tête YAML --- facultatif :

---
title: My First Post
slug: my-first-post
language: en
category: News
tags: [announcements, tips]
date: 2024-03-14
meta_title: My First Post | Example Site
meta_description: A short searchable summary…
---

Des règles de repli rendent le front matter facultatif :

Titre : title de front matter → le premier # titre du document (retiré du corps pour ne pas apparaître deux fois) → le nom du fichier.
Slug : slug de front matter → une version propre du titre → le nom de fichier nettoyé, avec suffixes automatiques pour doublons (-2, -3…) si deux fichiers aboutiraient à la même adresse.
Tags : une chaîne à virgules ou une liste YAML conviennent toutes deux.

Règles qui s'appliquent quand vous incluez effectivement un en-tête :

Gardez-le plat : uniquement les clés ci-dessus. Une liste imbriquée sous title: est rejetée avec le champ nommé.
language: doit être une langue réellement configurée sur votre site, et une langue où votre compte a le droit d'écrire ; vérifié fichier par fichier.
Une valeur date:/published_at: est acceptée en YYYY-MM-DD simple ou avec une heure ; une vraie vérification de calendrier rejette le mois 13, le jour 45, etc. Une date absurde ne fait pas échouer le fichier : elle est simplement ignorée.
Pas de planification : les dates de front matter sont enregistrées uniquement comme métadonnées de l'élément ; la publication reste une décision manuelle/de revue. C'est explicite dans le code (« auto-scheduling ruled out »), donc rien ne passe en ligne inopinément.

Ce que vous obtenez

Tous les fichiers deviennent des brouillons : un import ne publie jamais rien, jamais.
Le Markdown du corps est converti en le même HTML qu'écrit votre éditeur, y compris la conversion d'un # titre résiduel un niveau plus bas en un H2, puisque la structure de titres de l'éditeur commence à H2.
Une reconstruction du site se produit automatiquement si au moins un brouillon a été créé (ces brouillons existent dans le CMS immédiatement ; seule leur publication attend votre intervention).
L'écran de résultats est par fichier : chaque brouillon créé avec son lien d'édition et le fichier dont il provient, et chaque échec avec son erreur précise.

Quels échecs vous pourriez voir

Chaque problème est signalé par nom de fichier, en langage clair :

Message	Cause
« not a .md/.markdown file »	Le fichier n'avait pas la bonne extension
« file is empty »	Téléversement de longueur nulle
« invalid YAML front matter (…) »	L'en-tête `---` existe mais ne s'analyse pas
« front matter must be a YAML mapping… »	L'en-tête n'est pas des paires clé/valeur
« front matter field '<x>' must be plain text, not a nested list/mapping »	YAML imbriqué là où une chaîne simple est attendue
« could not determine a title (empty file/filename) »	Tout ce que la chaîne de repli pouvait tenter était vide
« title exceeds 500 characters »	Titre trop long
« could not derive a slug from the title or filename »	Les deux sources aboutissaient à rien d'utilisable
« markdown conversion failed (…) »	Le document ne s'analysait pas comme Markdown
« language '…' is not configured » / « not authorised for language '…' »	Le `language:` du fichier (ou la valeur par défaut du lot) n'est pas une langue où vous pouvez écrire
« database error: check the server log »	L'écriture elle-même a échoué : réessayez le fichier

Les échecs par fichier ne font jamais tomber le lot : les fichiers valides continuent d'être importés pendant que les invalides signalent leur erreur.

Bonnes pratiques

Amenez vos images séparément : les URL d'images dans le corps sont importées telles quelles ; le geste pratique est de téléverser d'abord les images dans la médiathèque et de les référencer depuis le Markdown, pour que les brouillons pointent déjà vers des URL fonctionnelles avant la mise en ligne.
Laissez les titres faire les slugs : si deux fichiers du lot entraient en collision, l'importeur ajoute le suffixe pour vous ; remplacer des slugs se fait avec le slug: de front matter seulement là où cela compte.
Format sans douleur : n'acceptez le titre en repli H1 qu'en dernier recours ; écrire title: dans le front matter garde les pages de départ propres.
Vérifiez les colonnes et les brouillons un par un : l'écran de résultats relie chaque brouillon immédiatement après l'import pour un passage de revue.

La version courte

Un dossier de Markdown devient un dossier de brouillons en une seule requête : un YAML facultatif définit titre, slug, catégorie/tags, langue et métadonnées ; tout le reste est déduit ; rien n'est publié automatiquement ; l'écran de résultats par fichier est votre liste de contrôle de ce qui mérite un coup d'œil avant la mise en ligne.