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.

Astuce

Pour des fonctionnalités supplémentaires, telles que l’inclusion de composants et d’expressions JSX dans Markdown, ajoutez l’intégration @astrojs/mdx pour écrire votre contenu Markdown en utilisant MDX.

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 <Content />

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';
     }
   }

   Astuce

   Ajouté à la version : astro@2.0.0

   data.astro.frontmatter contient toutes les propriétés d’un document Markdown ou MDX donné. Cela vous permet de modifier les propriétés existantes du frontmatter, ou de calculer de nouvelles propriétés à partir de ce frontmatter existant.

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é
    })
  ]
});

Pages Markdown individuelles

Titre de la section Pages Markdown individuelles

Astuce

Les collections de contenu et l’importation de Markdown dans les composants .astro offrent davantage de fonctionnalités pour le rendu de votre Markdown et constituent le moyen recommandé pour gérer la plupart de votre contenu. Cependant, il peut arriver que vous souhaitiez simplement ajouter un fichier à src/pages/ et avoir une page simple créée automatiquement pour vous.

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.

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 le rendre 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.

src/pages/remote-example.astro

---
// Exemple : Récupération du contenu Markdown depuis une API distante
// et le rendre 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} />