Compatibilidad experimental de ID de encabezado de Markdown

Tipo: boolean
Predeterminado: false

Agregado en: astro@5.5.0

El flag experimental.headingIdCompat hace que los IDs generados por Astro para los encabezados de Markdown sean compatibles con plataformas comunes como GitHub y npm.

Para habilitar la compatibilidad de ID de encabezado, establece el flag en true en tu configuración de Astro:

astro.config.mjs

import { defineConfig } from "astro/config"

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

Uso

Sección titulada Uso

Este flag experimental te permite conservar los guiones finales al final de los IDs para los encabezados de Markdown que terminan en caracteres especiales, creando IDs compatibles con los generados por otras plataformas comunes. No requiere un uso específico y solo afecta cómo Astro genera el id para tus encabezados escritos usando la sintaxis Markdown.

Astro, como muchas plataformas, utiliza el popular paquete github-slugger para convertir el contenido de texto de un encabezado de Markdown en un slug para usar en los IDs. Este flag experimental te permite omitir el paso de procesamiento predeterminado adicional de Astro que elimina un guión final del final de los IDs para los encabezados que terminan en caracteres especiales.

Por ejemplo, el siguiente encabezado de Markdown:

<Picture />

Sección titulada <Picture />

generará el siguiente HTML en Astro de forma predeterminada:

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

Usando experimental.headingIdCompat, el mismo Markdown generará el siguiente HTML, que es idéntico al de plataformas como GitHub:

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

En una futura versión principal, Astro cambiará para usar el estilo de ID compatible de forma predeterminada, pero puedes optar por el comportamiento futuro anticipadamente usando el flag experimental.headingIdCompat.

Uso con el plugin rehypeHeadingIds

Sección titulada Uso con el plugin rehypeHeadingIds

Si estás usando el plugin rehypeHeadingIds directamente, opta por el modo de compatibilidad al pasar el plugin en tu configuración de Astro:

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, { headingIdCompat: true }],
      otherPluginThatReliesOnHeadingIDs,
    ],
  },
});