Compatibilité expérimentale des identifiants de titres Markdown

Type : boolean
Par défaut : false

Ajouté à la version : astro@5.5.0 Nouveau

L’option experimental.headingIdCompat rend les identifiants générés par Astro pour les titres Markdown compatibles avec les plateformes classiques comme GitHub et npm.

Pour activer la compatibilité des identifiants de titre, définissez l’option sur true dans votre configuration Astro :

astro.config.mjs

import { defineConfig } from "astro/config"

export default defineConfig({
  experimental: {
    headingIdCompat: true,
  }
})

Utilisation

Titre de la section Utilisation

Cette option expérimentale vous permet de conserver les traits d’union finaux dans les identifiants des titres Markdown se terminant par des caractères spéciaux, créant ainsi des identifiants compatibles avec ceux générés par d’autres plateformes classiques. Il ne nécessite aucune utilisation spécifique et affecte uniquement la manière dont Astro génère l’identifiant pour vos titres rédigés avec la syntaxe Markdown.

Astro, comme de nombreuses plateformes, utilise le paquet populaire github-slugger pour convertir le contenu textuel d’un titre Markdown en un slug à utiliser dans les identifiants. Cette option expérimentale vous permet d’omettre l’étape de traitement supplémentaire par défaut d’Astro qui supprime le trait d’union final à la fin des identifiants pour les titres se terminant par des caractères spéciaux.

Par exemple, le titre Markdown suivant :

## `<Picture />`

générera par défaut le code HTML suivant dans Astro :

<h2 id="picture"><code>&lt;Picture /&gt;</h2>

En utilisant experimental.headingIdCompat, le même Markdown générera le code HTML suivant, identique à celui de plateformes telles que GitHub :

<h2 id="picture-"><code>&lt;Picture /&gt;</h2>

Dans une future version majeure, Astro utilisera par défaut le style d’identification compatible, mais vous pouvez opter pour le comportement futur plus tôt en utilisant l’option experimental.headingIdCompat.

Utilisation avec le plugin rehypeHeadingIds

Titre de la section Utilisation avec le plugin rehypeHeadingIds

Si vous utilisez directement le plugin rehypeHeadingIds, activez le mode de compatibilité lorsque vous transmettez le plugin dans votre configuration Astro :

astro.config.mjs

import { defineConfig } from 'astro/config';
import { rehypeHeadingIds } from '@astrojs/markdown-remark';
import { autrePluginQuiDependDesIdDesTitres } from 'source/du/plugin';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [rehypeHeadingIds, { headingIdCompat: true }],
      autrePluginQuiDependDesIdDesTitres,
    ],
  },
});