Markdown Astro avancé : 7 astuces pour un blog 10× plus pro

Vous venez de lancer un blog avec Astro et vous rédigez votre premier article technique. Vous voulez surligner une ligne de code ? Impossible. Un encadré repliable pour avertir le lecteur ? Pas possible. Une formule mathématique dans un tuto d’algorithmes ? Aucune idée par où commencer.

Je suis passé par là. En Markdown pur, j’ai vite senti les limites : sur d’autres blogs, les blocs de code mettent en avant l’essentiel, montrent avant/après, et intègrent des composants interactifs — moi, je ne pouvais que coller du code brut.

Heureusement, Astro propose le MDX, un « Markdown renforcé » : composants et JSX dans l’article, et beaucoup plus de possibilités.

Cet article partage 7 usages avancés de Markdown/MDX dans Astro, de la configuration de base à la coloration, aux composants, aux formules et aux diagrammes — avec code et étapes complètes. À la fin, votre blog passe de « lisible » à professionnel.

Première partie : passer de Markdown à MDX

Pourquoi utiliser le MDX ?

La différence entre Markdown et MDX, c’est un peu vélo vs vélo électrique : les deux roulent, l’expérience n’a rien à voir.

Le Markdown pur ne gère que texte, blocs de code et images. Un encadré d’avertissement ? Il faut du HTML brut. Un composant interactif dans l’article ? Quasi impossible.

Le MDX, c’est Markdown + JSX. Vous pouvez :

• Importer et utiliser des composants : tout composant Astro, React ou Vue dans un .mdx
• Écrire des expressions JSX : {variable}, boucles, conditions
• Personnaliser les éléments : remplacer un <h1> standard par votre composant stylé

Exemple concret — un encadré d’avertissement :

En Markdown pur :

<div class="warning">
  <p>Attention : cette opération supprimera toutes les données !</p>
</div>

En MDX :

import Alert from '@/components/Alert.astro';

<Alert type="warning">
  Attention : cette opération supprimera toutes les données !
</Alert>

Le MDX, c’est assembler des briques, pas écrire du HTML partout.

Configurer MDX en 5 minutes

Trois étapes suffisent.

Étape 1 : installer l’intégration

npx astro add mdx

La CLI installe @astrojs/mdx et met à jour la config. Répondez Yes aux questions.

Étape 2 : vérifier la configuration

Dans astro.config.mjs :

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
});

Sinon, ajoutez-le à la main.

Étape 3 : tester

Créez test.mdx dans src/pages/ ou src/content/ :

---
title: Test MDX
---

# Test MDX

Texte Markdown classique.

export const greeting = "Bonjour";

Variable : {greeting} !

<div style="padding: 1rem; background: #f0f0f0;">
  Élément JSX
</div>

Lancez npm run dev : si variable et JSX s’affichent, MDX fonctionne.

Coexistence .md et .mdx

Après l’intégration MDX, les .md restent valides. Astro choisit selon l’extension :

• .md : Markdown standard
• .mdx : MDX (composants + JSX)

Conseil : .md pour les articles simples, .mdx quand il faut des composants.

Deuxième partie : coloration du code avancée

Thème Shiki

Astro utilise Shiki par défaut — très bien. Le thème par défaut est github-dark ; vous pouvez l’adapter au style du blog.

Shiki ou Prism ?

Je recommande Shiki : intégration native, 100+ langages et thèmes, rendu côté serveur sans JS supplémentaire. Prism est correct mais demande plus de CSS et de config.

Changer le thème

Dans astro.config.mjs :

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'dracula', // github-dark, nord, monokai, dracula, etc.
    },
  },
});

Thèmes courants :

• github-dark / github-light
• dracula
• nord
• one-dark-pro

Prévisualisation : Shiki themes.

Thèmes clair / sombre

markdown: {
  shikiConfig: {
    themes: {
      light: 'github-light',
      dark: 'github-dark',
    },
  },
},

Shiki suit prefers-color-scheme ou votre logique de thème.

Surligner des lignes et annoter le code

Pour les tutos : « regardez cette ligne » ou « voici ce qui a changé ». Les Shiki Transformers s’en chargent.

Surligner des lignes

npm install shiki

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { transformerNotationHighlight } from '@shikijs/transformers';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'github-dark',
      transformers: [transformerNotationHighlight()],
    },
  },
});

Dans le bloc :

```javascript
function hello() {
  console.log('ligne normale');
  console.log('ligne surlignée'); // [!code highlight]
}
```

Diff avant / après

import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers';

markdown: {
  shikiConfig: {
    theme: 'github-dark',
    transformers: [
      transformerNotationHighlight(),
      transformerNotationDiff(),
    ],
  },
},

```javascript
function calculate(a, b) {
  return a + b; // [!code --]
  return a * b; // [!code ++]
}
```

-- = suppression (rouge), ++ = ajout (vert).

Focus sur une zone

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

import { transformerNotationFocus } from '@shikijs/transformers';

transformers: [
  transformerNotationFocus(),
],

```javascript
function process() {
  console.log('grisé');
  console.log('mis en avant'); // [!code focus]
  console.log('grisé');
}
```

Expressive Code (optionnel)

Besoin de plus que Shiki ? Expressive Code ajoute titres de blocs, copie en un clic, numéros de lignes, style terminal, comparaison côte à côte.

npx astro add astro-expressive-code

La CLI configure tout. Utile surtout pour les blogs très orientés code ; sinon Shiki + transformers suffisent.

Troisième partie : composants personnalisés

Importer et utiliser des composants

C’est la force du MDX : Alert, comparaisons de code, sections repliables, etc.

Composant Alert

src/components/Alert.astro :

---
interface Props {
  type?: 'info' | 'warning' | 'error';
}

const { type = 'info' } = Astro.props;

const styles = {
  info: 'bg-blue-50 border-blue-200 text-blue-800',
  warning: 'bg-yellow-50 border-yellow-200 text-yellow-800',
  error: 'bg-red-50 border-red-200 text-red-800',
};
---

<div class={`border-l-4 p-4 ${styles[type]}`}>
  <slot />
</div>

Dans le .mdx :

---
title: Mon article technique
---

import Alert from '@/components/Alert.astro';

# Titre

Contenu normal.

<Alert type="warning">
  Attention : sauvegardez vos données avant cette commande !
</Alert>

<Alert type="info">
  Astuce : le **Markdown** fonctionne aussi dans le slot du composant.
</Alert>

Composants React / Vue

import Counter from '@/components/Counter.tsx';

<Counter client:load initialCount={0} />

client:load active l’interactivité côté client.

Organisation

src/
├── components/
│   ├── mdx/
│   │   ├── Alert.astro
│   │   ├── CodeCompare.astro
│   │   ├── Callout.astro
│   │   └── Tabs.astro

Mapper la syntaxe Markdown vers des composants

Vous pouvez remplacer h1, a, img, etc. par vos composants — ancres sur les titres, icône ↗ sur les liens externes, sans modifier chaque article à la main.

Titre personnalisé

CustomHeading.astro :

---
interface Props {
  level: 1 | 2 | 3 | 4 | 5 | 6;
  id?: string;
}

const { level, id } = Astro.props;
const Tag = `h${level}` as any;
---

<Tag id={id} class="group relative">
  <slot />
  {id && (
    <a href={`#${id}`} class="ml-2 opacity-0 group-hover:opacity-100 transition-opacity">
      #
    </a>
  )}
</Tag>

Dans le .mdx :

import CustomHeading from '@/components/CustomHeading.astro';

export const components = {
  h2: (props) => <CustomHeading level={2} {...props} />,
  h3: (props) => <CustomHeading level={3} {...props} />,
};

## Titre de niveau 2

Au survol, lien d'ancre #.

### Titre de niveau 3

Liens externes

ExternalLink.astro :

---
interface Props {
  href?: string;
}

const { href } = Astro.props;
const isExternal = href?.startsWith('http');
---

<a href={href} target={isExternal ? '_blank' : undefined} rel={isExternal ? 'noopener noreferrer' : undefined}>
  <slot />
  {isExternal && <span class="ml-1 text-xs">↗</span>}
</a>

import ExternalLink from '@/components/ExternalLink.astro';

export const components = {
  a: ExternalLink,
};

[À propos de BetterLink](https://eastondev.com/blog/fr/about/)
[Lien externe](https://example.com)

Pour un mapping global à tous les MDX, il faut un plugin personnalisé dans astro.config.mjs — souvent le mapping par fichier suffit.

Quatrième partie : formules mathématiques et diagrammes

KaTeX pour les formules

Pour algorithmes, maths ou data science, KaTeX est rapide et compatible rendu serveur (souvent préférable à MathJax).

npm install remark-math rehype-katex katex

• remark-math : parse LaTeX
• rehype-katex : rendu HTML
• katex : bibliothèque

astro.config.mjs :

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});

Dans le layout (MarkdownLayout.astro), dans <head> :

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
  crossorigin="anonymous"
/>

Usage

Formule en ligne ($...$) :

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Équation masse-énergie : $E = mc^2$

Racines du trinôme : $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

Bloc ($$...$$) :

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

Dépannage

1. CSS KaTeX chargé (onglet Network)
2. Version compatible de rehype-katex (essayer 6.x si besoin)
3. Syntaxe supportée : KaTeX supported

Mermaid pour flux et schémas

Je recommande rehype-mermaid (SVG statique, SEO).

npm install rehype-mermaid

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import rehypeMermaid from 'rehype-mermaid';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    rehypePlugins: [
      [rehypeMermaid, { strategy: 'img-svg' }]
    ],
  },
});

Exemples

```mermaid
graph TD
    A[Début] --> B{MDX installé ?}
    B -->|Oui| C[Configurer la coloration]
    B -->|Non| D[Installer MDX]
    D --> C
    C --> E[Terminé]
```

```mermaid
sequenceDiagram
    Utilisateur->>Navigateur: Visite la page
    Navigateur->>Serveur: Requête HTML
    Serveur->>Navigateur: Page rendue
    Navigateur->>Utilisateur: Affichage
```

Au npm run build, les diagrammes deviennent des SVG statiques — rapides, sans JS client.

Si erreur Puppeteer : npm install -D playwright, ou essayez astro-diagram.

Cinquième partie : astuces avancées et bonnes pratiques

Content Collections et MDX

Avec Content Collections (src/content/), le frontmatter est validé et l’API typée.

src/content/config.ts :

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()).optional(),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

Dans le MDX :

---
title: Tutoriel MDX Astro avancé
description: Usages avancés du MDX
pubDate: 2025-12-02
tags: [Astro, MDX, Tutoriel]
---

import Alert from '@/components/Alert.astro';

# {frontmatter.title}

<Alert type="info">
  Date de publication : {frontmatter.pubDate.toLocaleDateString()}
</Alert>

Table des matières avec getHeadings() :

---
import { getEntry } from 'astro:content';

const entry = await getEntry('blog', 'my-mdx-article');
const { Content, headings } = await entry.render();
---

<aside>
  <h2>Sommaire</h2>
  <ul>
    {headings.map(h => (
      <li style={`margin-left: ${(h.depth - 1) * 1}rem`}>
        <a href={`#${h.slug}`}>{h.text}</a>
      </li>
    ))}
  </ul>
</aside>

<article>
  <Content />
</article>

Performance et pièges

• Évitez trop de client:load ; préférez Astro pour le statique, client:visible ou client:idle pour l’interactif.
• Images : composant Image d’Astro plutôt que <img> brut.

import { Image } from 'astro:assets';
import cover from './cover.jpg';

<Image src={cover} alt="Image de couverture" width={800} height={600} />

• Beaucoup de MDX : mdx({ optimize: true }) accélère le build (testez le HTML généré).

Conclusion

Les 7 astuces en bref :

1. MDX — une commande, 5 minutes
2. Thème Shiki — style de code sur mesure
3. Transformers — lignes clés et diffs
4. Composants — Alert, démos interactives
5. Mapping — titres, liens, styles globaux
6. KaTeX — formules pro
7. Mermaid — diagrammes en code, rendu serveur

Parcours suggéré : MDX + un composant → coloration si besoin → KaTeX/Mermaid pour algo/architecture → mapping avancé ensuite.

Checklist :

• MDX rendu correctement
• Coloration des blocs de code
• Composants personnalisés visibles
• Formules (si configuré)
• Diagrammes Mermaid (si configuré)
• Temps de build acceptable

Pour aller plus loin : Astro Integrations, bibliothèques MDX communautaires, View Transitions pour des transitions fluides.

Choisissez une fonctionnalité et testez-la sur votre blog. En cas de blocage, la doc officielle et la communauté Astro aident en général vite.

Au fond, le contenu compte le plus : ces outils clarifient votre expression ; ce qui fidélise les lecteurs, ce sont vos idées et votre expérience. Bonne continuation avec votre blog Astro !