Aller au contenu

Markdown

Le 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 standard qui peuvent également inclure un frontmatter YAML pour définir des propriétés personnalisées telles qu’un titre, une description et des balises.

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

Titre de la section Organiser les fichiers Markdown

Vos fichiers Markdown locaux peuvent être conservés n’importe où dans votre répertoire src/. Ils 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.

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 vous permettent également d’utiliser une API optimisée et spécifique au contenu pour interroger et afficher votre contenu. 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.

Expressions dynamiques de type JSX

Titre de la section Expressions dynamiques de type JSX

Après avoir importé ou analysé 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.

/src/posts/great-post.md
---
title: 'Le meilleur article de tous les temps'
author: 'Ben'
---


Voici mon _incroyable_ billet !
src/pages/my-posts.astro
---
import * as greatPost from '../posts/great-post.md';
const posts = Object.values(await import.meta.glob('../posts/*.md', { eager: true }));
---


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


<p>Archives d'articles :</p>
<ul>
  {posts.map(post => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}
</ul>

Propriétés disponibles

Titre de la section Propriétés disponibles

Interroger les collections

Titre de la section Interroger les collections

Lorsque vous récupérez des données de vos collections via des fonctions d’aide, les propriétés de votre document 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.

Voir le Type des entrées de collection complet.

Importation de Markdown

Titre de la section 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/user/projects/.../file.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 YAML du fichier.
  • <Content /> - Un composant qui renvoie le contenu complet et affiché du fichier.
  • RawContent() - Une fonction qui renvoie le document Markdown brut sous forme de chaîne de caractères.
  • compiledContent() - Une fonction 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 />

Titre de la section Le composant &lt;Content /&gt;

Le composant <Content /> est disponible en important Content à partir d’un fichier Markdown. Ce composant renvoie le contenu complet du fichier, affiché en HTML. Vous pouvez optionnellement renommer Content en n’importe quel nom de composant que vous préférez.

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

src/pages/content.astro
---
// 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();
---
<h2>Promotion du jour</h2>
<PromoBanner />


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

ID des titres

Titre de la section 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.

src/pages/page-1.md
---
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 ids d’en-tête basés sur github-slugger. Vous pouvez trouver plus d’exemples dans la documentation de github-slugger.

ID des titres et plugins

Titre de la section ID des titres et plugins

Astro injecte un attribut id dans tous les éléments d’en-tête (<h1> à <h6>) dans les fichiers Markdown et MDX et fournit un utilitaire getHeadings() pour récupérer ces ID dans les propriétés exportées Markdown.

Vous pouvez personnaliser ces ID en ajoutant un plugin rehype 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().

Par défaut, Astro injecte les attributs id après l’exécution de vos plugins rehype. Si l’un de vos plugins rehype personnalisés a besoin d’accéder aux ID injectés par Astro, vous pouvez importer et utiliser directement le plugin rehypeHeadingIds d’Astro. Assurez-vous d’ajouter rehypeHeadingIds avant tous les plugins qui en dépendent :

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


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

Plugins Markdown

Titre de la section Plugins Markdown

La prise en charge de Markdown dans Astro est assurée par remark, un puissant outil d’analyse et de traitement doté d’un écosystème actif. D’autres analyseurs Markdown comme Pandoc et markdown-it ne sont pas supportés actuellement.

Astro applique par défaut les plugins GitHub-flavored Markdown et SmartyPants. Cela permet de générer des liens cliquables à partir du texte et de formater les citations et les tirets cadratins.

Vous pouvez personnaliser la façon dont remark analyse votre Markdown dans astro.config.mjs. Voir la liste complète des options de configuration Markdown.

Ajouter des plugins remark et rehype

Titre de la section Ajouter des plugins remark et rehype

Astro prend en charge l’ajout de plugins tiers remark et rehype pour Markdown. Ces plugins vous permettent d’étendre votre Markdown avec de nouvelles fonctionnalités, comme générer automatiquement une table des matières, appliquer des étiquettes accessibles aux émojis et styliser votre Markdown.

Nous vous encourageons à consulter awesome-remark et awesome-rehype parmi les plugins populaires ! Consultez le fichier README de chaque plugin pour obtenir des instructions d’installation spécifiques.

Cet exemple applique remark-toc et rehype-accessible-emojis aux fichiers Markdown :

astro.config.mjs
import { defineConfig } from 'astro/config';
import remarkToc from 'remark-toc';
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';


export default defineConfig({
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: 'toc', maxDepth: 3 } ] ],
    rehypePlugins: [rehypeAccessibleEmojis],
  },
});

Personnaliser un plugin

Titre de la section Personnaliser un plugin

Pour personnaliser un plugin, il faut lui ajouter un objet d’options dans un tableau imbriqué.

L’exemple ci-dessous ajoute l’option heading au plugin remarkToc pour modifier l’emplacement de la table des matières, et l’option behavior au plugin rehype-autolink-headings afin d’ajouter la balise d’ancrage après le texte du titre.

astro.config.mjs
import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';


export default {
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: "contents"} ] ],
    rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
  },
}

Modification programmatique du frontmatter

Titre de la section Modification programmatique du frontmatter

Vous pouvez ajouter des propriétés au frontmatter de tous vos fichiers Markdown et MDX en utilisant un plugin remark ou rehype.

  1. Ajoutez une propriété customProperty à l’objet data.astro.frontmatter présent dans l’argument file de votre plugin :

    example-remark-plugin.mjs
    export function exampleRemarkPlugin() {
      // Tous les plugins remark et rehype renvoient une fonction distincte
      return function (tree, file) {
        file.data.astro.frontmatter.customProperty = 'Propriété générée';
      }
    }

  2. Appliquez ce plugin à votre configuration d’intégration markdown ou mdx :

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
    

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

    ou

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
    

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

Maintenant, chaque fichier Markdown ou MDX aura une propriété customProperty dans son frontmatter, ce qui la rendra disponible lors de l’importation de votre Markdown et à partir de la propriété Astro.props.frontmatter dans vos mises en page.

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

Étendre la configuration Markdown à partir de MDX

Titre de la section Étendre la configuration Markdown à partir de MDX

L’intégration MDX d’Astro étend par défaut la configuration Markdown existante de votre projet. Pour remplacer des options individuelles, vous pouvez spécifier leur équivalent dans votre configuration MDX.

L’exemple suivant désactive l’option GitHub-Flavored Markdown et applique un ensemble différent de plugins Remark pour les fichiers MDX :

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


export default defineConfig({
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // `syntaxHighlight` hérité de Markdown


      // Markdown `remarkPlugins` ignoré,
      // seul `remarkPlugin2` est appliqué.
      remarkPlugins: [remarkPlugin2],
      // `gfm` remplacé par `false`
      gfm: false,
    })
  ]
});

Pour éviter d’étendre votre configuration Markdown depuis MDX, mettez l’option extendMarkdownConfig (activée par défaut) sur false :

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


export default defineConfig({
  markdown: {
    remarkPlugins: [remarkPlugin],
  },
  integrations: [
    mdx({
      // La configuration Markdown est désormais ignorée
      extendMarkdownConfig: false,
      // Pas de `remarkPlugins` appliqué
    })
  ]
});

Coloration syntaxique

Titre de la section Coloration syntaxique

Astro est livré avec un support intégré pour Shiki et Prism. Cela permet de mettre en évidence la syntaxe pour :

Shiki est activé par défaut, préconfiguré avec le thème github-dark. La sortie compilée sera limitée à des styles intégrés au HTML sans classes CSS, feuilles de style ou JS côté client supplémentaires.

Configuration de Shiki

Titre de la section Configuration de Shiki

Shiki est notre colorateur syntaxique par défaut. Vous pouvez configurer toutes les options via l’objet shikiConfig comme suit :

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  markdown: {
    shikiConfig: {
      // Choisir parmi les thèmes intégrés de Shiki (ou ajouter les vôtres)
      // https://shiki.style/themes
      theme: 'dracula',
      // Alternativement, fournir plusieurs thèmes
      // Voir la note ci-dessous pour l'utilisation de deux thèmes clair/foncé
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // Désactiver les couleurs par défaut
      // https://shiki.style/guide/dual-themes#without-default-color
      // (Ajouté dans la v4.12.0)
      defaultColor: false,
      // Ajouter des langages personnalisés
      // Note : Shiki a d'innombrables langages intégrés, y compris .astro !
      // https://shiki.style/languages
      langs: [],
      // Ajouter des alias personnalisés pour les langues
      // Associer un alias à un identifiant de langue Shiki : https://shiki.style/languages#bundled-languages
      // https://shiki.style/guide/load-lang#custom-language-aliases
      langAlias: {
        cjs: "javascript"
      },
      // Activer le retour à la ligne pour éviter le défilement horizontal
      wrap: true,
      // Ajouter des transformateurs personnalisés : https://shiki.style/guide/transformers
      // Trouver des transformateurs communs : https://shiki.style/packages/transformers
      transformers: [],
    },
  },
});

Ajouter votre propre thème

Titre de la section Ajouter votre propre thème

Au lieu d’utiliser l’un des thèmes prédéfinis de Shiki, vous pouvez importer un thème personnalisé à partir d’un fichier local.

astro.config.mjs
import { defineConfig } from 'astro/config';
import customTheme from './my-shiki-theme.json';


export default defineConfig({
  markdown: {
    shikiConfig: { theme: customTheme },
  },
});

Nous vous conseillons également de lire la documentation de Shiki sur les thèmes pour en savoir plus sur les thèmes, les bascules entre mode clair et mode foncé, ou le style via les variables CSS.

Colorateur syntaxique par défaut

Titre de la section Colorateur syntaxique par défaut

Si vous souhaitez utiliser 'prism' par défaut, ou désactiver complètement la coloration syntaxique, vous pouvez utiliser l’objet de configuration markdown.syntaxHighlighting :

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  markdown: {
    // Peut être 'shiki' (par défaut), 'prism' ou false pour désactiver la mise en évidence.
    syntaxHighlight: 'prism',
  },
});

Configuration de Prism

Titre de la section Configuration de Prism

Si vous choisissez d’utiliser Prism, Astro appliquera les classes CSS de Prism à la place. Notez que vous devez apporter votre propre feuille de style CSS pour que la coloration syntaxique apparaisse !

  1. Choisissez une feuille de style prédéfinie parmi les Thèmes Prism disponibles.

  2. Ajoutez cette feuille de style dans le répertoire public/ de votre projet.

  3. Chargez-la dans la balise <head> de votre page dans un composant de mise en page via une balise <link>. (Voir l’utilisation de base de Prism.)

Vous pouvez également consulter la liste des langages supportés par Prism pour en savoir plus sur ses options et son utilisation.

Récupérer du Markdown à distance

Titre de la section Récupérer du Markdown à distance

Astro n’inclut pas de support intégré pour le Markdown à distance en dehors des collections de contenu expérimentales!.

Pour récupérer directement du Markdown distant et l’afficher en HTML, vous devrez installer et configurer votre propre analyseur 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.

src/pages/remote-example.astro
---
// Exemple : Récupérer du Markdown à partir d'une API distante
// et l'afficher en 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} />

Pages Markdown individuelles

Titre de la section Pages Markdown individuelles

Astro traite tout fichier supporté 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, construira automatiquement une route de page en utilisant le nom de chemin du fichier et affichera le contenu Markdown affiché en HTML.

src/pages/page-1.md
---
titre: Bonjour, le monde
---


# Bonjour !


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


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

Propriété layout du frontmatter

Titre de la section Propriété layout du frontmatter

Pour aider avec la fonctionnalité limitée des pages Markdown, Astro fournit une propriété frontmatter layout spéciale qui est un chemin relatif vers un composant de mise en page Markdown. 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.

src/pages/posts/post-1.md
---
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 :

src/layouts/BlogPostLayout.astro
---
const {frontmatter} = Astro.props;
---
<html>
  <!-- ... -->
  <h1>{frontmatter.title}</h1>
  <h2>Post author: {frontmatter.author}</h2>
  <p>{frontmatter.description}</p>
  <slot /> <!-- Le contenu Markdown est injecté ici -->
  <!-- ... -->
</html>

Vous pouvez également styliser votre Markdown dans votre composant de mise en page.

En savoir plus sur les Mises en page Markdown.
Contribuer

Comment pouvons-nous vous aider ?

Créer une issue GitHub

Le moyen le plus rapide d'alerter notre équipe d'un problème.

Communauté