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

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.

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

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

Voici mon _incroyable_ billet !

---
import * as greatPost from '../posts/great-post.md';
const posts = Object.values(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

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

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 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, 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 />.

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

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 :

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

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

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 :

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

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.

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

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

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

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

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

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

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

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 :

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 :

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

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. 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/`

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

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

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

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.

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

Contribuer

Communauté

Markdown

Organiser les fichiers Markdown

Expressions dynamiques de type JSX

Propriétés disponibles

Interroger les collections

Importation de Markdown

Le composant `<Content />`

ID des titres

ID des titres et plugins

Plugins Markdown

Ajouter des plugins remark et rehype

Personnaliser un plugin

Modification programmatique du frontmatter

Étendre la configuration Markdown à partir de MDX

Pages Markdown individuelles

Propriété `layout` du frontmatter

Récupérer du Markdown à distance

Comment pouvons-nous vous aider ?

Créer une issue GitHub

Envoyez-nous un commentaire

Envoyez-nous un commentaire

Markdown

Organiser les fichiers Markdown

Expressions dynamiques de type JSX

Propriétés disponibles

Interroger les collections

Importation de Markdown

Le composant <Content />

ID des titres

ID des titres et plugins

Plugins Markdown

Ajouter des plugins remark et rehype

Personnaliser un plugin

Modification programmatique du frontmatter

Étendre la configuration Markdown à partir de MDX

Pages Markdown individuelles

Propriété layout du frontmatter

Récupérer du Markdown à distance

Le composant `<Content />`

Propriété `layout` du frontmatter