Markdown

Markdown est couramment utilisé pour créer des contenus à forte teneur en texte, tels que des articles de blog et de la documentation. Astro inclut une prise en charge intégrée des fichiers Markdown qui peuvent également inclure un frontmatter en YAML (ou TOML) pour définir des propriétés personnalisées telles qu’un titre, une description et des étiquettes.

Dans Astro, vous pouvez créer du contenu en utilisant GitHub Flavored Markdown, puis l’afficher dans des composants .astro. Cela combine un format d’écriture familier conçu pour le contenu avec la flexibilité de la syntaxe et de l’architecture des composants d’Astro.

Organiser les fichiers Markdown

Vos fichiers Markdown locaux peuvent être conservés n’importe où dans votre répertoire src/. Les fichiers Markdown situés dans src/pages/ généreront automatiquement des pages Markdown sur votre site.

Votre contenu Markdown et vos propriétés frontmatter peuvent être utilisés dans les composants via des importations de fichiers locaux ou lorsqu’ils sont interrogés et rendus à partir de données récupérées par une fonction d’assistance de collections de contenu.

Importations de fichiers vs requêtes de collections de contenu

Vos fichiers Markdown locaux peuvent être importés dans les composants .astro en utilisant une instruction import pour un seul fichier et import.meta.glob() de Vite pour interroger plusieurs fichiers à la fois. Les données exportées à partir de ces fichiers Markdown peuvent ensuite être utilisées dans le composant .astro.

Si vous avez des groupes de fichiers Markdown apparentés, envisagez de les définir comme des collections. Cela présente plusieurs avantages, notamment la possibilité de stocker les fichiers Markdown n’importe où sur votre système de fichiers ou à distance.

Les collections utilisent des API optimisées et spécifiques au contenu pour interroger et restituer votre contenu Markdown au lieu d’importer des fichiers. Les collections sont destinées aux ensembles de données qui partagent la même structure, tels que les articles de blog ou les pages de produits. Lorsque vous définissez cette forme dans un schéma, vous bénéficiez en outre de la validation, de la sécurité des types et de l’Intellisense dans votre éditeur.

En savoir plus sur quand utiliser les collections de contenu au lieu des importations de fichiers.

Expressions dynamiques de type JSX

Après avoir importé ou interrogé des fichiers Markdown, vous pouvez écrire des modèles HTML dynamiques dans vos composants .astro qui incluent les données du frontmatter et le contenu du corps du texte.

---
title: 'Le meilleur article de tous les temps'
author: 'Ben'
---

Voici mon _incroyable_ billet !

---
import * as greatPost from "./posts/article-incroyable.md";
const compiled = await greatPost.compiledContent();
const posts = Object.values(import.meta.glob("./posts/*.md", { eager: true }));
---

<p>{greatPost.frontmatter.title}</p>
<p>Écrit par : {greatPost.frontmatter.author}</p>

<Fragment set:html={compiled} />

<p>Archive des articles :</p>
<ul>
  {
    posts.map((post: any) => (
      <li>
        <a href={post.url}>{post.frontmatter.title}</a>
      </li>
    ))
  }
</ul>

Propriétés disponibles

Markdown à partir des requêtes de collections de contenu

Lorsque vous récupérez des données de vos collections avec les fonctions d’aide getCollection() ou getEntry(), les propriétés du frontmatter de votre Markdown sont disponibles dans un objet data (par exemple post.data.title). De plus, body contient le contenu brut, non compilé, sous forme de chaîne de caractères.

La fonction render() renvoie le contenu du corps de votre Markdown, une liste de titres générée, ainsi qu’un objet frontmatter modifié après l’application de tout module d’extension pour processeur Markdown.

En savoir plus sur l’utilisation du contenu renvoyé par une requête de collection.

Importation de Markdown

Les propriétés exportées suivantes sont disponibles dans votre composant .astro lors de l’importation de Markdown en utilisant import ou import.meta.glob() :

file - Le chemin absolu du fichier (par exemple /home/utilisateur/projets/.../fichier.md).
url - L’URL de la page (par exemple /fr/guides/markdown-content).
frontmatter - Contient toutes les données spécifiées dans le frontmatter en YAML (ou TOML) du fichier.
<Content /> - Un composant qui renvoie le contenu complet du fichier après rendu.
RawContent() - Une fonction qui renvoie le document Markdown brut sous forme de chaîne de caractères.
compiledContent() - Une fonction asynchrone qui retourne le document Markdown compilé en une chaîne HTML.
getHeadings() - Une fonction asynchrone qui retourne un tableau de tous les titres (<h1> à <h6>) dans le fichier avec le type : { depth: number; slug: string; text: string }[]. Le slug de chaque titre correspond à l’identifiant généré pour un titre donné et peut être utilisé pour les liens d’ancrage.

Un exemple de billet de blog en Markdown peut passer l’objet Astro.props suivant :

Astro.props = {
  file: "/home/user/projects/.../file.md",
  url: "/en/guides/markdown-content/",
  frontmatter: {
    /** Frontmatter pour un article */
    title: "Astro 0.18 Release",
    date: "Tuesday, July 27 2021",
    author: "Matthew Phillips",
    description: "Astro 0.18 is our biggest release since Astro launch.",
  },
  getHeadings: () => [
    {"depth": 1, "text": "Astro 0.18 Release", "slug": "astro-018-release"},
    {"depth": 2, "text": "Responsive partial hydration", "slug": "responsive-partial-hydration"}
    /* ... */
  ],
  rawContent: () => "# Astro 0.18 Release\nA little over a month ago, the first public beta [...]",
  compiledContent: () => "<h1>Astro 0.18 Release</h1>\n<p>A little over a month ago, the first public beta [...]</p>",
}

Le composant `<Content />`

Le composant <Content /> est disponible en important Content à partir d’un fichier Markdown. Ce composant renvoie le contenu complet du fichier, converti en HTML. Vous pouvez éventuellement renommer Content avec le nom de composant de votre choix.

Vous pouvez également afficher le contenu HTML d’une entrée de collection en Markdown en effectuant le rendu d’un composant <Content />.

---
// Déclaration d'importation
import {Content as PromoBanner} from '../components/promoBanner.md';

// Requête sur les collections
import { getEntry, render } from 'astro:content';

const product = await getEntry('products', 'shirt');
const { Content } = await render(product);
---
<h2>Promotion du jour</h2>
<PromoBanner />

<p>Fin de la vente : {product.data.saleEndDate.toDateString()}</p>
<Content />

ID des titres

En écrivant des titres en Markdown, vous obtiendrez automatiquement des liens d’ancrage qui vous permettront d’accéder directement à certaines sections de votre page.

---
title: Ma page de contenu
---
## Introduction

Je peux créer un lien interne vers [ma conclusion](#conclusion) sur la même page lorsque j'écris en Markdown.

## Conclusion

Je peux visiter `https://example.com/page-1/#introduction` dans un navigateur pour naviguer directement vers mon Introduction.

Astro génère des id de titres à l’aide github-slugger. Vous pouvez trouver plus d’exemples dans la documentation de github-slugger.

ID de titres et modules d’extension

Astro injecte un attribut id dans tous les éléments de titre (<h1> à <h6>) dans les fichiers Markdown et MDX. Vous pouvez récupérer ces données à partir de l’utilitaire getHeadings() disponible en tant que propriété exportée Markdown à partir d’un fichier importé, ou à partir de la fonction render() lorsque vous utilisez du Markdown renvoyé à partir d’une requête de collections de contenu.

Vous pouvez personnaliser ces ID avec un module d’extension pour processeur Markdown qui injecte les attributs id (par exemple rehype-slug). Vos ID personnalisés, au lieu des valeurs par défaut d’Astro, seront reflétés dans la sortie HTML et les éléments retournés par getHeadings().

Astro injecte les attributs id après l’exécution de vos modules d’extension personnalisés, de sorte que tout ID défini par un module d’extension est préservé. Si l’un de vos modules d’extension personnalisés a besoin d’accéder aux ID injectés par Astro, vous pouvez importer le module d’extension rehypeHeadingIds d’Astro et le placer avant les modules d’extension qui en dépendent :

Sätteri
Unified

import { defineConfig } from 'astro/config';
import { satteri, satteriHeadingIdsPlugin } from '@astrojs/markdown-satteri';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

export default defineConfig({
  markdown: {
    processor: satteri({
      hastPlugins: [
        satteriHeadingIdsPlugin(),
        otherPluginThatReliesOnHeadingIDs,
      ],
    }),
  },
});

import { defineConfig } from 'astro/config';
import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

export default defineConfig({
  markdown: {
    processor: unified({
      rehypePlugins: [
        rehypeHeadingIds,
        otherPluginThatReliesOnHeadingIDs,
      ],
    }),
  },
});

Processeurs Markdown

Ajouté à la version : astro@6.4.0

Un processeur Markdown analyse la syntaxe Markdown et la convertit en HTML. Il peut proposer des fonctionnalités intégrées ou accepter des modules d’extension pour étendre les capacités du Markdown.

Astro fournit deux processeurs officiels, Sätteri et Unified. Vous pouvez configurer un processeur pour l’ensemble de votre projet ou choisir un processeur différent pour les fichiers Markdown et MDX.

Depuis Astro v7, Sätteri est le processeur Markdown par défaut. Vous pouvez l’utiliser pour effectuer le rendu des fichiers Markdown et MDX sans installation ni configuration, en fonction des besoins de votre projet.

Choisir un processeur Markdown

Chaque processeur offre les mêmes fonctionnalités intégrées, mais diffère légèrement en termes d’architecture et d’avantages.

Quand utiliser Sätteri

Sätteri est le processeur Markdown par défaut depuis Astro v7. Utilisez-le lorsque :

Vous souhaitez bénéficier d’un compilateur Markdown et MDX rapide s’appuyant sur Rust.
Votre projet ne nécessite aucun module d’extension, ou vous êtes à l’aise pour écrire vos propres modules d’extension.

Quand utiliser Unified

Unified est le processeur utilisé par les anciennes versions d’Astro. Utilisez-le lorsque :

Vous souhaitez tirer parti de son vaste écosystème de modules d’extension remark ou rehype, ou si vous avez besoin de modules d’extension recma dans vos fichiers MDX.
Vous n’êtes pas prêt à porter vos modules d’extension Unified existants vers Sätteri.

Configurer un processeur Markdown

Astro fournit des options de configuration pour Markdown qui vous permettent de contrôler la coloration syntaxique et le processeur Markdown. De plus, chaque processeur Markdown propose des fonctionnalités configurables et permet d’ajouter des modules d’extension pour personnaliser le rendu Markdown.

Sätteri
Unified

Sätteri fonctionne sans installation ni configuration par défaut. Installez-le explicitement pour configurer ses fonctionnalités ou ajouter des modules d’extension :

Installez le paquet @astrojs/markdown-satteri :

npm install @astrojs/markdown-satteri

pnpm add @astrojs/markdown-satteri

yarn add @astrojs/markdown-satteri

Importez satteri depuis @astrojs/markdown-satteri et transmettez-le à l’option markdown.processor dans votre configuration d’Astro :

import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";

export default defineConfig({
  markdown: {
    processor: satteri(),
  },
});

Unified n’est pas inclus avec Astro. Installez-le pour l’utiliser en tant que processeur Markdown :

Installez le paquet @astrojs/markdown-remark :

npm install @astrojs/markdown-remark

pnpm add @astrojs/markdown-remark

yarn add @astrojs/markdown-remark

Importez unified depuis @astrojs/markdown-remark et transmettez-le à l’option markdown.processor dans votre configuration d’Astro :

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";

export default defineConfig({
  markdown: {
    processor: unified(),
  },
});

Fonctionnalités intégrées

Les deux processeurs Markdown officiels offrent les mêmes fonctionnalités par défaut, y compris la prise en charge de GitHub-Flavored Markdown et de la ponctuation intelligente. Vous pouvez les désactiver, les personnaliser ou ajouter des modules d’extension pour introduire de nouvelles fonctionnalités.

GitHub-Flavored Markdown

Les processeurs Markdown dans Astro prennent en charge GitHub-Flavored Markdown (GFM) par défaut. Il s’agit d’un sur-ensemble de la spécification Markdown originale qui ajoute des fonctionnalités telles que les tableaux, le texte barré, les listes de tâches et les notes de bas de page.

Si vous souhaitez désactiver GFM, vous pouvez définir gfm sur false dans les options du processeur :

Sätteri
Unified

import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";

export default defineConfig({
  markdown: {
    processor: satteri({
      features: { gfm: false },
    }),
  },
});

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";

export default defineConfig({
  markdown: {
    processor: unified({ gfm: false }),
  },
});

Pour configurer les notes de bas de page, transmettez un objet de configuration à gfm.footnotes pour Sätteri ou à remarkRehype pour Unified :

Sätteri
Unified

import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";

export default defineConfig({
  markdown: {
    processor: satteri({
      features: {
        gfm: {
          // Configuration par défaut des notes de bas de page
          footnotes: {
            backContent: "↩",
            backLabel: "Back to reference {reference}",
            label: "Footnotes",
          },
        },
      },
    }),
  },
});

En savoir plus sur la configuration des notes de bas de page dans Sätteri.

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";

export default defineConfig({
  markdown: {
    processor: unified({
      // Configuration par défaut des notes de bas de page
      remarkRehype: {
        footnoteBackContent: "↩",
        footnoteBackLabel: (referenceIndex, rereferenceIndex) =>
          `Back to reference ${referenceIndex + 1}${rereferenceIndex > 1 ? '-' + rereferenceIndex : ''}`,
        footnoteLabel: "Footnotes",
      },
    }),
  },
});

En savoir plus sur la configuration des notes de bas de page avec remark-rehype.

Ponctuation intelligente

Les processeurs Markdown dans Astro prennent en charge la ponctuation intelligente à l’aide de Smartypants par défaut. Cette fonctionnalité convertit automatiquement les guillemets droits en guillemets typographiques, les doubles tirets en tirets cadratins et les trois points en points de suspension.

Si vous ne souhaitez pas utiliser la conversion automatique, vous pouvez désactiver la ponctuation intelligente dans les options du processeur :

Sätteri
Unified

import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";

export default defineConfig({
  markdown: {
    processor: satteri({
      features: { smartPunctuation: false },
    }),
  },
});

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";

export default defineConfig({
  markdown: {
    processor: unified({ smartypants: false }),
  },
});

Pour un contrôle plus précis de la typographie, vous pouvez plutôt spécifier un objet de configuration dans les options du processeur :

Sätteri
Unified

import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";

export default defineConfig({
  markdown: {
    processor: satteri({
      features: {
        smartPunctuation: {
          quotes: true,
          dashes: false,
          ellipses: false,
        },
      },
    }),
  },
});

En savoir plus sur la configuration de la ponctuation intelligente dans Sätteri.

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";

export default defineConfig({
  markdown: {
    processor: unified({
      smartypants: {
        quotes: true,
        dashes: false,
        ellipses: false,
      },
    }),
  },
});

En savoir plus sur les propriétés prises en charge par retext-smartypants.

Modules d’extension pour les processeurs Markdown

Les modules d’extension pour les processeurs Markdown vous permettent d’étendre votre Markdown avec de nouvelles fonctionnalités, comme la génération automatique d’une table des matières, l’application d’étiquettes accessibles pour les émojis, et la mise en forme de votre Markdown. Ces modules d’extension peuvent modifier l’arbre syntaxique à différentes étapes du pipeline de traitement.

Deux types de modules d’extension sont pris en charge :

Les modules d’extension mdast agissent sur l’arbre syntaxique Markdown (mdast) avant sa transformation en HTML. Unified désigne ces derniers en tant que modules d’extension remark.
Les modules d’extension hast agissent sur l’arbre syntaxique HTML (hast) après la conversion du Markdown en HTML. Unified désigne ces derniers en tant que modules d’extension rehype.

Sätteri
Unified

Lorsque les modules d’extension mdast ou hast acceptent des options pour configurer leur comportement, vous pouvez les transmettre sous la forme d’un objet d’options à la fonction du module d’extension.

L’exemple suivant applique satteri-imgattr et satteri-callouts aux fichiers Markdown :

import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";
import imgAttr from "satteri-imgattr";
import satteriCallouts from "satteri-callouts";

export default defineConfig({
  markdown: {
    processor: satteri({
      mdastPlugins: [
        imgAttr({
          defaults: { loading: "lazy", decoding: "async" },
        }),
      ],
      hastPlugins: [satteriCallouts()],
    }),
  },
});

Lorsque les modules d’extension remark ou rehype acceptent des options pour configurer leur comportement, vous pouvez les transmettre sous la forme d’un tableau imbriqué. Le premier élément est le module d’extension, et le deuxième élément est un objet d’options.

L’exemple suivant applique remark-imgattr et rehype-github-alerts aux fichiers Markdown :

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import remarkImgAttr from "remark-imgattr";
import rehypeGithubAlerts from "rehype-github-alerts";

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [
        [remarkImgAttr, { defaults: { width: 700, format: "avif" } }],
      ],
      rehypePlugins: [rehypeGithubAlerts],
    }),
  },
});

Nous vous encourageons à parcourir awesome-remark et awesome-rehype pour découvrir des modules d’extension populaires ! Consultez le README de chaque module d’extension pour les instructions d’installation spécifiques.

Modification programmatique du frontmatter

Vous pouvez ajouter des propriétés au frontmatter de vos fichiers Markdown et MDX en utilisant des modules d’extension pour le processeur.

Ajoutez vos propriétés personnalisées à l’objet data.astro.frontmatter.

data.astro.frontmatter contient déjà toutes les propriétés du frontmatter du document Markdown ou MDX. Cela vous permet de modifier les propriétés existantes dans le frontmatter ou d’en calculer de nouvelles à partir de celles-ci.

Sätteri
Unified

import { defineMdastPlugin } from "satteri";

export const exampleMdastPlugin = defineMdastPlugin({
  name: "exemple-module-extension-mdast",
  text(node, ctx) {
    if (ctx.data.astro !== undefined) {
      ctx.data.astro.frontmatter.newProperty = "Nouvelle propriété";
      // En supposant que `title` est une propriété requise du frontmatter
      ctx.data.astro.frontmatter.computedProperty = `${ctx.data.astro.frontmatter.title} | Mon site`;
    }
  },
});

export function exampleRemarkPlugin() {
  return function (tree, file) {
    file.data.astro.frontmatter.newProperty = "Nouvelle propriété";
    // En supposant que `title` est une propriété requise du frontmatter
    file.data.astro.frontmatter.computedProperty = `${file.data.astro.frontmatter.title} | Mon site`;
  };
}

Ajoutez ce module d’extension à votre configuration Markdown :

Sätteri
Unified

import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";
import { exampleMdastPlugin } from "./exemple-module-extension-mdast";

export default defineConfig({
  markdown: {
    processor: satteri({ mdastPlugins: [exampleMdastPlugin()] }),
  },
});

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import { exampleRemarkPlugin } from "./exemple-module-extension-remark.mjs";

export default defineConfig({
  markdown: {
    processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
  },
});

Désormais, chaque fichier Markdown ou MDX aura newProperty et computedProperty dans son frontmatter, les rendant disponibles via un fichier Markdown importé, la propriété Astro.props.frontmatter lors de l’utilisation de mises en page, ou remarkPluginFrontmatter lors du rendu des collections de contenu.

Méthode associée : Ajout du temps de lecture

Pages Markdown individuelles

Astro traite tout fichier pris en charge dans le répertoire /src/pages/ comme une page, y compris .md et d’autres types de fichiers Markdown.

Placer un fichier dans ce répertoire, ou n’importe quel sous-répertoire, génèrera automatiquement une route de page en utilisant le nom de chemin du fichier et affichera le contenu Markdown converti en HTML. Astro ajoutera automatiquement une balise <meta charset="utf-8"> à votre page pour permettre une création plus facile de contenu non ASCII.

---
titre: Bonjour, le monde
---

# Bonjour !

Ce fichier Markdown crée une page à `votre-domaine.com/page-1/`

Elle n'est probablement pas très élégante, mais Markdown prend en charge :
- le **gras** et l'_italique_.
- les listes
- les [liens](https://astro.build)
- <p>les éléments HTML</p>
- et bien d'autres choses encore !

Propriété `layout` du frontmatter

Pour aider avec les fonctionnalités limitées des pages Markdown individuelles, Astro fournit une propriété de frontmatter spéciale nommée layout qui est un chemin relatif vers un composant Astro de mise en page Markdown. layout n’est pas une propriété spéciale lors de l’utilisation de collections de contenu pour interroger et restituer votre contenu Markdown, et il n’est pas garanti qu’elle soit prise en charge en dehors de son cas d’utilisation prévu.

Si votre fichier Markdown est situé dans src/pages/, créez un composant de mise en page et ajoutez-le dans cette propriété de mise en page pour fournir une enveloppe de page autour de votre contenu Markdown.

---
layout: ../../layouts/BlogPostLayout.astro
title: Astro en bref
author: Himanshu
description: Découvrez ce qui rend Astro génial !
---
Il s'agit d'un article rédigé en Markdown.

Ce composant de mise en page est un composant Astro normal avec des propriétés spécifiques automatiquement disponibles à travers Astro.props pour votre modèle Astro. Par exemple, vous pouvez accéder aux propriétés du frontmatter de votre fichier Markdown via Astro.props.frontmatter :

---
const {frontmatter} = Astro.props;
---
<html>
  <head>
    <!-- ... -->
    <meta charset="utf-8"> // n'est plus ajouté par défaut
  </head>
  <!-- ... -->
  <h1>{frontmatter.title}</h1>
  <h2>Auteur de l'article : {frontmatter.author}</h2>
  <p>{frontmatter.description}</p>
  <slot /> <!-- Le contenu Markdown est injecté ici -->
  <!-- ... -->
</html>

Lorsque vous utilisez la propriété frontmatter layout, vous devez inclure la balise <meta charset="utf-8"> dans votre mise en page car Astro ne l’ajoutera plus automatiquement. Vous pouvez désormais également mettre en forme votre Markdown dans votre composant de mise en page.

En savoir plus sur les mises en page Markdown.

Récupérer du Markdown à distance

Le processeur Markdown interne d’Astro n’est pas disponible pour le traitement du Markdown distant.

Pour récupérer du Markdown distant à utiliser dans des collections de contenu, vous pouvez créer un chargeur personnalisé qui a accès à une fonction renderMarkdown().

Pour récupérer directement du Markdown distant et le restituer au format HTML, vous devrez installer et configurer votre propre interpréteur de Markdown à partir de NPM. Celui-ci n’héritera pas des paramètres Markdown intégrés d’Astro que vous avez configurés.

Assurez-vous de bien comprendre ces limitations avant d’implémenter ceci dans votre projet, et envisagez de récupérer votre Markdown distant en utilisant un chargeur de collections de contenu à la place.

---
// Exemple : Récupération du contenu Markdown depuis une API distante
// et le restituer au format HTML, au moment de l'exécution.
// En utilisant "marked" (https://github.com/markedjs/marked)
import { marked } from 'marked';
const response = await fetch('https://raw.githubusercontent.com/wiki/adam-p/markdown-here/Markdown-Cheatsheet.md');
const markdown = await response.text();
const content = marked.parse(markdown);
---
<article set:html={content} />

Contribuer Communauté Parrainer