Markdown enrichi

Lisible prend en charge Markdown standard, GFM et plusieurs extensions adaptées aux articles techniques. Chaque exemple ci-dessous présente d’abord le code à écrire, puis son rendu réel. Le comportement reste identique dans les six variantes, même si leur style change. Pour ajouter de vraies interactions, poursuivez avec Composants MDX.

Titres et paragraphes

Utilisez un seul titre de niveau 1 dans le frontmatter avec title. Dans le corps de l’article, commencez à ## pour les grandes sections, puis descendez sans sauter de niveau. Les titres de niveaux 2 à 4 reçoivent automatiquement une ancre copiable.

Code

1
#### Un titre d’exemple
2

3
Un paragraphe reste une suite de lignes sans ligne vide.
4
Une ligne vide commence un nouveau paragraphe.

Rendu

Un titre d’exemple

Un paragraphe reste une suite de lignes sans ligne vide. Une ligne vide commence un nouveau paragraphe.

Mise en forme inline

L’emphase sert à structurer une phrase, pas à remplacer les titres. GFM ajoute le texte barré. Le code inline convient aux commandes courtes, noms de fichiers et identifiants. Les balises HTML mark et kbd sont acceptées dans MDX pour un surlignage ou une touche de clavier.

Code

1
Un texte peut être **important**, *nuancé*, ~~obsolète~~ ou contenir `const value = 1`.
2

3
Appuyez sur <kbd>Ctrl</kbd> + <kbd>K</kbd> pour ouvrir la <mark>recherche</mark>.

Rendu

Un texte peut être important, nuancé, obsolète ou contenir const value = 1.

Appuyez sur Ctrl + K pour ouvrir la recherche.

Liens

Le texte du lien doit décrire sa destination. Utilisez une route commençant par / pour une page interne et une URL absolue pour un site externe. Un titre facultatif peut compléter le lien au survol sans remplacer son libellé.

Code

1
Consultez [le modèle de contenu](/docs/authoring/content/) ou la [documentation Astro](https://docs.astro.build/ "Documentation officielle Astro").

Rendu

Consultez le modèle de contenu ou la documentation Astro.

Images

Placez les fichiers partagés dans public/images, puis référencez-les depuis la racine. Le texte alternatif décrit l’information portée par l’image ; laissez-le vide uniquement pour une image strictement décorative. Le titre entre guillemets est facultatif.

Les dimensions ne sont pas à votre charge : au build, Lisible lit la taille intrinsèque de toute image locale (SVG, PNG, JPEG, GIF) et pose width, height, loading="lazy" et decoding="async" sur la balise produite. La place est donc réservée avant le chargement et l’image ne décale jamais la mise en page.

Code

1
![Pipeline en îlots Astro](/images/demo-ilots.svg "Pipeline de rendu")

Rendu

Listes

Markdown gère les listes à puces, numérotées et imbriquées. GFM ajoute les tâches avec - [ ] et - [x] ; les cases rendues sont informatives et ne modifient pas le fichier source.

Code

1
- Écrire le brouillon
2
  - Ajouter les exemples
3
- Relire le contenu
4

5
1. Construire le site
6
2. Vérifier les liens
7

8
- [x] Documentation rédigée
9
- [ ] Relecture terminée

Rendu

• Écrire le brouillon
  • Ajouter les exemples
• Relire le contenu

1. Construire le site
2. Vérifier les liens

• Documentation rédigée
• Relecture terminée

Citations

Préfixez chaque paragraphe cité avec >. Une seconde citation imbriquée utilise >>. Ajoutez la source dans le texte ou dans un lien : Markdown ne l’invente pas.

Code

1
> La performance est une fonctionnalité éditoriale.
2
>
3
> Équipe Lisible

Rendu

La performance est une fonctionnalité éditoriale.

Équipe Lisible

Tableaux

La deuxième ligne définit l’alignement de chaque colonne : :--- à gauche, :---: au centre et ---: à droite. Les tableaux larges deviennent défilables horizontalement sur petit écran.

Code

1
| Variante | Usage | Articles |
2
| :--- | :---: | ---: |
3
| Organique | Éditorial | 12 |
4
| Terminal | Technique | 8 |

Rendu

Notes de bas de page

Une référence [^id] pointe vers une définition portant le même identifiant. Les définitions peuvent être placées près du paragraphe source ; le moteur les rassemble automatiquement en fin de page et ajoute les liens de retour.

Code

1
Les îlots réduisent le JavaScript envoyé au navigateur.[^islands]
2

3
[^islands]: Astro hydrate uniquement les composants marqués par une directive client.

Rendu

Les îlots réduisent le JavaScript envoyé au navigateur.¹

Détails repliables

La balise HTML native details masque un complément non essentiel. Le summary doit annoncer clairement ce qui sera révélé. Ajoutez open pour afficher le contenu dès le chargement.

Code

1
<details>
2
  <summary>Afficher la commande complète</summary>
3

4
  Exécutez `bun run check:all` avant le déploiement.
5
</details>

Rendu

Séparateur horizontal

Trois tirets seuls sur une ligne créent une séparation thématique. Réservez-la aux changements de sujet importants ; les titres suffisent dans la plupart des sections.

Code

1
Fin de la première partie.
2

3
---
4

5
Début de la partie suivante.

Rendu

Fin de la première partie.

Début de la partie suivante.

Callouts

Un callout met en avant une information qui mérite un niveau d’attention particulier. Les variantes disponibles sont note, tip, important, warning et caution. Le texte entre crochets remplace le titre traduit par défaut.

Code

1
:::note[Contexte]
2
Les brouillons restent visibles en développement.
3
:::
4

5
:::tip[Gain de temps]
6
Lancez les contrôles avant de pousser.
7
:::
8

9
:::important[Configuration requise]
10
Définissez l’URL publique avant le build.
11
:::
12

13
:::warning[Avant de déployer]
14
Vérifiez les liens internes.
15
:::
16

17
:::caution[Action destructive]
18
Sauvegardez les données avant une migration.
19
:::

Rendu

Callout repliable

Ajoutez l’attribut {collapse} après le titre pour transformer le callout en zone repliable native. Le contenu reste présent dans la page et ne doit donc jamais contenir un secret.

Code

1
:::note[Détails facultatifs]{collapse}
2
Cette explication peut être ouverte à la demande.
3
:::

Rendu

Blocs Expressive Code

Expressive Code fournit ici la coloration Shiki, le bouton de copie, un badge de langage, les cadres de fichier ou de terminal, les numéros de lignes, le retour à la ligne, les marqueurs de texte et de lignes ainsi que les sections de code repliables. Indiquez toujours le langage juste après les trois accents graves.

Lignes, plages et libellés

Un même bloc peut combiner surlignage neutre, ajouts et suppressions. Les sélecteurs acceptent une ligne, plusieurs lignes séparées par des virgules et des plages inclusives. Un texte placé avant : ajoute un libellé visible.

Code

1
```ts title="src/users.ts" {2,8-9} ins={"Ajout":4-5} del={"Suppression":7}
2
interface User {
3
  id: string;
4
  name: string;
5
  plan: "free" | "pro";
6
  lastLogin: Date;
7
}
8
const legacyUser = loadLegacyUser();
9
export function displayName(user: User) {
10
  return user.name.trim();
11
}
12
```

Rendu

1
interface User {
2
  id: string;
3
  name: string;
4
  plan: "free" | "pro";
5
  lastLogin: Date;
6
}
7
const legacyUser = loadLegacyUser();
8
export function displayName(user: User) {
9
  return user.name.trim();
10
}

Marqueurs dans une ligne

Une chaîne entre guillemets surligne toutes ses occurrences. Préfixez-la avec ins= ou del= pour lui donner le sens d’un ajout ou d’une suppression. Une expression entre /.../ accepte les expressions régulières ; avec un groupe capturant, seule la partie capturée est marquée.

Code

1
```ts "user.name" ins="cache.get" del="legacyToken" /user(Id|Name)/
2
const userId = request.params.id;
3
const legacyToken = request.headers.token;
4
const cached = cache.get(userId);
5
return user.name ?? cached;
6
```

Rendu

1
const userId = request.params.id;
2
const legacyToken = request.headers.token;
3
const cached = cache.get(userId);
4
return user.name ?? cached;

Diff avec coloration du langage

Le langage diff interprète + et - comme des ajouts et suppressions. Ajoutez lang="ts" pour conserver la coloration TypeScript ; l’espace d’alignement placé devant les lignes inchangées disparaît au rendu.

Code

1
```diff lang="ts" title="src/config.ts"
2
  export const config = {
3
-   locale: "fr",
4
+   locale: "en",
5
    trailingSlash: true,
6
  };
7
```

Rendu

1
export const config = {
2
  locale: "fr",
3
  locale: "en",
4
  trailingSlash: true,
5
};

Sections de code repliables

collapse accepte plusieurs plages. Le projet utilise collapseStyle=collapsible-auto par défaut : le résumé reste disponible après ouverture et se place du côté le plus logique de la plage. Les autres valeurs sont github (ouverture définitive), collapsible-start (résumé au début) et collapsible-end (résumé à la fin). Ajoutez collapsePreserveIndent=false pour aligner le résumé à gauche.

Code

1
```ts title="src/server.ts" collapse={1-4,8-10} collapseStyle=collapsible-auto
2
import { logger } from "./logger";
3
import { metrics } from "./metrics";
4
const app = createApp();
5
app.use(logger, metrics);
6
app.get("/health", () => {
7
  return new Response("ok");
8
});
9
app.listen(4321);
10
console.log("ready");
11
process.on("SIGTERM", shutdown);
12
```

Rendu

4 lignes masquées
1
import { logger } from "./logger";
2
import { metrics } from "./metrics";
3
const app = createApp();
4
app.use(logger, metrics);
5
app.get("/health", () => {
6
  return new Response("ok");
7
});
3 lignes masquées
8
app.listen(4321);
9
console.log("ready");
10
process.on("SIGTERM", shutdown);

Cadres, numéros et retour à la ligne

title crée automatiquement un cadre d’éditeur pour un fichier. Les langages shell utilisent un terminal ; frame="none" convient aux commandes isolées. startLineNumber change seulement les numéros affichés : les marqueurs continuent de compter depuis la première ligne source.

Code

1
```ts title="src/config.ts" startLineNumber=40 wrap=true preserveIndent=true hangingIndent=2 {2}
2
export const description =
3
  "Une ligne volontairement longue qui conserve son indentation lorsqu’elle revient à la ligne dans une colonne étroite.";
4
```
5

6
```bash frame="none" showLineNumbers=false
7
bun run check:all
8
```

Rendu

40
export const description =
41
  "Une ligne volontairement longue qui conserve son indentation lorsqu’elle revient à la ligne dans une colonne étroite.";

bun run check:all

Références : marqueurs de texte et de lignes, cadres, numéros de lignes, retour à la ligne et sections repliables.

Mathématiques

KaTeX rend les expressions LaTeX. Une formule entre deux $ reste dans la ligne ; un bloc entouré de $$ est centré et séparé du paragraphe. Utilisez des commandes LaTeX prises en charge par KaTeX.

Code

1
La relation $E = mc^2$ est affichée dans la phrase.
2

3
$$
4
L = -\sum_{i=1}^{n} y_i \log(\hat{y}_i)
5
$$

Rendu

La relation $E = mc^2$ est affichée dans la phrase.

Mermaid

Une fence mermaid est transformée en diagramme interactif. La barre d’outils permet le zoom, le déplacement, la réinitialisation, la copie de la source et le plein écran ; les couleurs se synchronisent avec le thème clair ou sombre. Le plein écran utilise l’API du navigateur lorsqu’elle existe, sinon un overlay occupant la viewport. Quittez-le avec le bouton de la barre ou Échap. La syntaxe interne reste celle de Mermaid.

Code

1
```mermaid
2
flowchart TD
3
  MD[Markdown] --> R[remark]
4
  R --> H[rehype]
5
  H --> HTML[HTML statique]
6
  HTML --> M[Mermaid interactif]
7
```

Rendu

Diagramme
100%
Rendu du diagramme...
Molette pour zoomer, glisser pour deplacer