diff --git a/astro.sidebar.ts b/astro.sidebar.ts
index 5037ada5ba839..5e8d9be3f437f 100644
--- a/astro.sidebar.ts
+++ b/astro.sidebar.ts
@@ -147,7 +147,6 @@ export const sidebar = [
'reference/experimental-flags/live-content-collections',
'reference/experimental-flags/client-prerender',
'reference/experimental-flags/content-intellisense',
- 'reference/experimental-flags/heading-id-compat',
'reference/experimental-flags/chrome-devtools-workspace',
],
}),
diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx
index a4bef60b8c2d7..48f0841f0224b 100644
--- a/src/content/docs/en/guides/upgrade-to/v6.mdx
+++ b/src/content/docs/en/guides/upgrade-to/v6.mdx
@@ -420,13 +420,14 @@ The following experimental flags have been removed and **their corresponding fea
Remove these experimental flags from your Astro config if you were previously using them:
-```js del={5-6} title="astro.config.mjs"
+```js del={5-7} title="astro.config.mjs"
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
preserveScriptOrder: true,
staticImportMetaEnv: true,
+ headingIdCompat: true,
},
})
```
@@ -536,7 +537,7 @@ Review your links to your custom endpoints that include a file extension in the
-In Astro 5.13, the `experimental.staticImportMetaEnv` was introduced to update the behavior when accessing `import.meta.env` directly to align with [Vite's handling of environment variables](https://vite.dev/guide/env-and-mode.html#env-variables) and ensures that `import.meta.env` values are always inlined.
+In Astro 5.13, the `experimental.staticImportMetaEnv` flag was introduced to update the behavior when accessing `import.meta.env` directly to align with [Vite's handling of environment variables](https://vite.dev/guide/env-and-mode.html#env-variables) and ensures that `import.meta.env` values are always inlined.
In Astro 5.x, non-public environment variables were replaced by a reference to `process.env`. Additionally, Astro could also convert the value type of your environment variables used through `import.meta.env`, which could prevent access to some values such as the strings `"true"` (which was converted to a boolean value), and `"1"` (which was converted to a number).
@@ -585,6 +586,131 @@ If you need more control over environment variables in Astro, we recommend you u
Learn more about [environment variables](/en/guides/environment-variables/) in Astro, including `astro:env`.
+### Changed: Markdown heading ID generation
+
+
+
+In Astro 5.x, an additional default processing step to Markdown stripped trailing hyphens from the end of IDs for section headings ending in special characters. This provided a cleaner `id` value, but could lead to incompatibilities rendering your Markdown across platforms.
+
+In Astro 5.5, the `experimental.headingIdCompat` flag was introduced to allow you to make the IDs generated by Astro for Markdown headings compatible with common platforms like GitHub and npm, using the popular [`github-slugger`](https://github.com/Flet/github-slugger) package.
+
+Astro 6.0 removes this experimental flag and makes this the new default behavior in Astro: trailing hyphens from the end of IDs for headings ending in special characters are no longer removed.
+
+#### What should I do?
+
+If you have manual links to headings, you may need to update the anchor link value with a new trailing hyphen. For example, the following Markdown heading:
+
+```md
+## ``
+```
+
+will now generate the following HTML with a trailing hyphen in the heading `id`:
+
+```html ins="-"
+<Picture />
+```
+
+and must now be linked to as:
+
+```markdown ins="-"
+See [the Picture component](/en/guides/images/#picture-) for more details.
+```
+
+If you were previously using the experimental feature to enforce trailing hyphens, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists.
+
+If you were previously using the `rehypeHeadingIds` plugin directly to enforce compatibility, remove the `headingIdCompat` option as it no longer exists:
+
+```js title="astro.config.mjs" del={8} ins={9}
+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 }],
+ [rehypeHeadingIds],
+ otherPluginThatReliesOnHeadingIDs,
+ ],
+ },
+});
+```
+
+If you want to keep the old ID generation for backward compatibility reasons, you can create a custom rehype plugin that will generate headings IDs like Astro 5.x. This will allow you to continue to use your existing anchor links without adding trailing hyphens.
+
+
+
+Create a custom rehype plugin to strip trailing hyphens
+
+
+
+1. Install required dependencies:
+
+
+
+ ```sh
+ npm i github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string
+ ```
+
+
+ ```sh
+ pnpm add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string
+ ```
+
+
+ ```sh
+ yarn add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string
+ ```
+
+
+
+2. Create a custom rehype plugin that will generate headings IDs like Astro v5:
+
+ ```js title="plugins/rehype-slug.mjs"
+ import GithubSlugger from 'github-slugger';
+ import { headingRank } from 'hast-util-heading-rank';
+ import { visit } from 'unist-util-visit';
+ import { toString } from 'hast-util-to-string';
+
+ const slugs = new GithubSlugger();
+
+ export function rehypeSlug() {
+ /**
+ * @param {import('hast').Root} tree
+ */
+ return (tree) => {
+ slugs.reset();
+ visit(tree, 'element', (node) => {
+ if (headingRank(node) && !node.properties.id) {
+ let slug = slugs.slug(toString(node));
+ // Strip trailing hyphens like in Astro v5 and below:
+ if (slug.endsWith('-')) slug = slug.slice(0, -1);
+ node.properties.id = slug;
+ }
+ });
+ };
+ }
+ ```
+
+3. Add the custom plugin to your Markdown configuration in `astro.config.mjs`:
+
+ ```js title="astro.config.mjs" ins={2} ins="rehypeSlug"
+ import { defineConfig } from 'astro/config';
+ import { rehypeSlug } from './plugins/rehype-slug';
+
+ export default defineConfig({
+ markdown: {
+ rehypePlugins: [rehypeSlug],
+ },
+ });
+ ```
+
+
+
+
+
+Learn more about [Heading IDs](/en/guides/markdown-content/#heading-ids).
+
## Community Resources
Know a good resource for Astro v5.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v6.mdx) and add a link below!
diff --git a/src/content/docs/en/reference/experimental-flags/heading-id-compat.mdx b/src/content/docs/en/reference/experimental-flags/heading-id-compat.mdx
deleted file mode 100644
index a19d1c9d01e49..0000000000000
--- a/src/content/docs/en/reference/experimental-flags/heading-id-compat.mdx
+++ /dev/null
@@ -1,75 +0,0 @@
----
-title: Experimental Markdown heading ID compatibility
-sidebar:
- label: Markdown heading ID compatibility
-i18nReady: true
----
-
-import Since from '~/components/Since.astro'
-
-
-
-**Type:** `boolean`
-**Default:** `false`
-
-
-
-The `experimental.headingIdCompat` flag makes the IDs generated by Astro for Markdown headings compatible with common platforms like GitHub and npm.
-
-To enable heading ID compatibility, set the flag to `true` in your Astro configuration:
-
-```js title="astro.config.mjs" ins={4-6}
-import { defineConfig } from "astro/config"
-
-export default defineConfig({
- experimental: {
- headingIdCompat: true,
- }
-})
-```
-
-## Usage
-
-This experimental flag allows you to retain the trailing hyphens on the end of IDs for Markdown headings ending in special characters, creating IDs compatible with those generated by other common platforms. It requires no specific usage and only affects how Astro generates the `id` for your headings written using Markdown syntax.
-
-Astro, like many platforms, uses the popular [`github-slugger`](https://github.com/Flet/github-slugger) package to convert the text content of a Markdown heading to a slug to use in IDs. This experimental flag allows you to omit Astro's additional default processing step that strips a trailing hyphen from the end of IDs for headings ending in special characters.
-
-For example, the following Markdown heading:
-
-```md
-## ``
-```
-
-will generate the following HTML in Astro by default:
-
-```html "picture"
-<Picture />
-```
-
-Using `experimental.headingIdCompat`, the same Markdown will generate the following HTML, which is identical to that of platforms such as GitHub:
-
-```html "picture-"
-<Picture />
-```
-
-In a future major version, Astro will switch to use the compatible ID style by default, but you can opt in to the future behavior early using the `experimental.headingIdCompat` flag.
-
-## Usage with `rehypeHeadingIds` plugin
-
-If you are [using the `rehypeHeadingIds` plugin](/en/guides/markdown-content/#heading-ids-and-plugins) directly, opt in to the compatibility mode when passing the plugin in your Astro configuration:
-
-
-```js title="astro.config.mjs" {8}
-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,
- ],
- },
-});
-```
diff --git a/src/content/docs/es/reference/experimental-flags/heading-id-compat.mdx b/src/content/docs/es/reference/experimental-flags/heading-id-compat.mdx
deleted file mode 100644
index 01f25422a4a2c..0000000000000
--- a/src/content/docs/es/reference/experimental-flags/heading-id-compat.mdx
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: Compatibilidad experimental de ID de encabezado de Markdown
-sidebar:
- label: Compatibilidad de ID de encabezado de Markdown
-i18nReady: true
----
-
-import Since from '~/components/Since.astro'
-
-
- **Tipo:** `boolean`
- **Predeterminado:** `false`
-
-
-
-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:
-
-```js title="astro.config.mjs" ins={4-6}
-import { defineConfig } from "astro/config"
-
-export default defineConfig({
- experimental: {
- headingIdCompat: true,
- }
-})
-```
-
-## 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`](https://github.com/Flet/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:
-
-## ``
-
-generará el siguiente HTML en Astro de forma predeterminada:
-
-```html "picture"
-<Picture />
-```
-
-Usando `experimental.headingIdCompat`, el mismo Markdown generará el siguiente HTML, que es idéntico al de plataformas como GitHub:
-
-```html "picture-"
-<Picture />
-```
-
-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`
-
-Si estás [usando el plugin `rehypeHeadingIds` directamente](/es/guides/markdown-content/#ids-de-encabezados-y-plugins), opta por el modo de compatibilidad al pasar el plugin en tu configuración de Astro:
-
-```js title="astro.config.mjs" {8}
-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,
- ],
- },
-});
-```
diff --git a/src/content/docs/fr/reference/experimental-flags/heading-id-compat.mdx b/src/content/docs/fr/reference/experimental-flags/heading-id-compat.mdx
deleted file mode 100644
index 7edd2b1d12ca3..0000000000000
--- a/src/content/docs/fr/reference/experimental-flags/heading-id-compat.mdx
+++ /dev/null
@@ -1,75 +0,0 @@
----
-title: Compatibilité expérimentale des identifiants de titres Markdown
-sidebar:
- label: Compatibilité des ids de titres Markdown
-i18nReady: true
----
-
-import Since from '~/components/Since.astro'
-
-
-
-**Type :** `boolean`
-**Par défaut :** `false`
-
-
-
-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 :
-
-```js title="astro.config.mjs" ins={4-6}
-import { defineConfig } from "astro/config"
-
-export default defineConfig({
- experimental: {
- headingIdCompat: true,
- }
-})
-```
-
-## 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`](https://github.com/Flet/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 :
-
-```md
-## ``
-```
-
-générera par défaut le code HTML suivant dans Astro :
-
-```html "picture"
-<Picture />
-```
-
-En utilisant `experimental.headingIdCompat`, le même Markdown générera le code HTML suivant, identique à celui de plateformes telles que GitHub :
-
-```html "picture-"
-<Picture />
-```
-
-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 module d'extension `rehypeHeadingIds`
-
-Si vous [utilisez directement le module d'extension `rehypeHeadingIds`](/fr/guides/markdown-content/#id-de-titres-et-modules-dextension), activez le mode de compatibilité lorsque vous transmettez le module d'extension dans votre configuration Astro :
-
-
-```js title="astro.config.mjs" {8}
-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,
- ],
- },
-});
-```
diff --git a/src/content/docs/ko/reference/experimental-flags/heading-id-compat.mdx b/src/content/docs/ko/reference/experimental-flags/heading-id-compat.mdx
deleted file mode 100644
index 1e54b0485ef6c..0000000000000
--- a/src/content/docs/ko/reference/experimental-flags/heading-id-compat.mdx
+++ /dev/null
@@ -1,74 +0,0 @@
----
-title: 실험적 Markdown 제목 ID 호환
-sidebar:
- label: Markdown 제목 ID 호환
----
-
-import Since from '~/components/Since.astro'
-
-
-
-**타입:** `boolean`
-**기본값:** `false`
-
-
-
-`experimental.headingIdCompat` 플래그는 Astro가 Markdown 제목에 대해 생성하는 ID를 GitHub 및 npm과 같은 일반적인 플랫폼과 호환되게 만듭니다.
-
-제목 ID 호환성을 활성화하려면 Astro 구성에서 플래그를 `true`로 설정하세요.
-
-```js title="astro.config.mjs" ins={4-6}
-import { defineConfig } from "astro/config"
-
-export default defineConfig({
- experimental: {
- headingIdCompat: true,
- }
-})
-```
-
-## 사용법
-
-이 실험적 플래그를 사용하면 특수 문자로 끝나는 Markdown 제목의 ID 끝에 후행 하이픈을 유지하여 다른 일반적인 플랫폼에서 생성된 ID와 호환되는 ID를 만들 수 있습니다. 특별한 사용법이 필요하지 않으며 Astro가 Markdown 구문을 사용하여 작성된 제목의 `id`를 생성하는 방식에만 영향을 줍니다.
-
-많은 플랫폼과 마찬가지로 Astro는 [`github-slugger`](https://github.com/Flet/github-slugger) 패키지를 사용하여 Markdown 제목의 텍스트 콘텐츠를 ID에 사용할 슬러그로 변환합니다. 이 실험적 플래그를 사용하면 특수 문자로 끝나는 제목의 ID 끝에서 후행 하이픈을 제거하는 Astro의 추가 기본 처리 단계를 생략할 수 있습니다.
-
-예를 들어 다음 Markdown 제목은 다음과 같습니다.
-
-```md
-## ``
-```
-
-이는 기본적으로 Astro에서 다음 HTML을 생성합니다.
-
-```html "picture"
-<Picture />
-```
-
-`experimental.headingIdCompat`를 사용하면 동일한 Markdown이 다음 HTML을 생성합니다. 이는 GitHub와 같은 플랫폼과 동일합니다.
-
-
-```html "picture-"
-<Picture />
-```
-
-향후 메이저 버전에서 Astro가 호환되는 ID 스타일을 기본적으로 사용하도록 전환하지만 `experimental.headingIdCompat` 플래그를 사용하여 미래 동작을 미리 선택할 수 있습니다.
-
-## `rehypeHeadingIds` 플러그인과 함께 사용
-
-[`rehypeHeadingIds` 플러그인을 직접 사용하는 경우](/ko/guides/markdown-content/#제목-id와-플러그인) Astro 구성에서 플러그인을 전달할 때 호환성 모드를 선택하세요.
-
-```js title="astro.config.mjs" {8}
-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,
- ],
- },
-});
-```
diff --git a/src/content/docs/zh-cn/reference/experimental-flags/heading-id-compat.mdx b/src/content/docs/zh-cn/reference/experimental-flags/heading-id-compat.mdx
deleted file mode 100644
index 08827161c09bf..0000000000000
--- a/src/content/docs/zh-cn/reference/experimental-flags/heading-id-compat.mdx
+++ /dev/null
@@ -1,74 +0,0 @@
----
-title: 实验性 Markdown 标题 ID 兼容性
-sidebar:
- label: Markdown 标题 ID 兼容性
-i18nReady: true
----
-
-import Since from '~/components/Since.astro'
-
-
-
-**类型：** `boolean`
-**默认值：** `false`
-
-
-
-`experimental.headingIdCompat` 标志使 Astro 为 Markdown 标题生成的 ID 与 GitHub 和 npm 等常见平台兼容。
-
-要启用标题 ID 兼容性，请在 Astro 配置中将该标志设置为 `true`：
-
-```js title="astro.config.mjs" ins={4-6}
-import { defineConfig } from "astro/config"
-
-export default defineConfig({
- experimental: {
- headingIdCompat: true,
- }
-})
-```
-
-## 用法
-
-该实验性标志允许你在 Markdown 标题以特殊字符结尾时，保留 ID 尾部的连字符（-），从而生成与其他常见平台兼容的 ID。它无需特定用法，仅影响 Astro 对使用 Markdown 语法编写的标题生成 ID 的方式。
-
-与其他平台一样，Astro 使用流行的 [`github-slugger`](https://github.com/Flet/github-slugger) 包将 Markdown 标题的文本内容转换为 slug 以用于 ID。此实验性标志允许你省略 Astro 的额外默认处理步骤——即当标题以特殊字符结尾时，自动移除 ID 末尾的连字符。
-
-例如以下 Markdown 标题：
-
-```md
-## ``
-```
-
-在 Astro 中默认情况下将生成以下 HTML：
-
-```html "picture"
-<Picture />
-```
-
-使用 `experimental.headingIdCompat`, 相同的 Markdown 将生成以下 HTML，与 GitHub 等平台相同：
-
-```html "picture-"
-<Picture />
-```
-
-在未来的主要版本中，Astro 将默认使用兼容的 ID 样式，但你可以提前使用 `experimental.headingIdCompat` 标志提前启用这一未来行为。
-
-## 与 `rehypeHeadingIds` 插件一起使用
-
-如果你直接[使用 `rehypeHeadingIds` 插件](/zh-cn/guides/markdown-content/#标题-id-与插件)，需在 Astro 配置中传入插件时启用兼容模式：
-
-```js title="astro.config.mjs" {8}
-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,
- ],
- },
-});
-```