Apply suggestions from code review

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

Author: florian-lefebvre

src/content/docs/en/guides/upgrade-to/v6.mdx

@@ -590,17 +590,35 @@ If you need more control over environment variables in Astro, we recommend you u
 
 <SourcePR number="14494" title="feat!: stabilize experimental.headingIdCompat"/>
 
-In Astro 5.5, the `experimental.headingIdCompat` flag was introduced 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.
+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.x, Astro had an additional default processing step that stripped trailing hyphens from the end of IDs for headings ending in special characters.
+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 aren't stripped anymore.
+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 were previously using this experimental feature, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists.
+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
+## `<Picture />`
+```
+
+will now generate the following HTML with a trailing hyphen in the heading `id`:
 
-If you were previously using the `rehypeHeadingIds` plugin directly, remove the `headingIdCompat` option as it no longer exists:
+```html ins="-"
+<h2 id="picture-"><code>&lt;Picture /&gt;</h2>
+```
+
+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';
@@ -618,22 +636,11 @@ export default defineConfig({
 });
 ```
 
-If you have manual links to headings, review them to make sure they're still correct. For example, the following Markdown heading:
-
-```md
-## `<Picture />`
-```
-
-will generate the following HTML:
-
-```html del={1} ins={2}
-<h2 id="picture"><code>&lt;Picture /&gt;</h2>
-<h2 id="picture-"><code>&lt;Picture /&gt;</h2>
-```
+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.
 
 <details>
 
-<summary>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. Click to expand.</summary>
+<summary>Create a custom rehype plugin to strip trailing hyphens</summary>
 
 <Steps>