Heading ID plugin recommendation results in incorrect header IDs

📚 Subject area/topic

Markdown

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/markdown-content/#heading-ids-and-plugins

📋 Description of content that is out-of-date or incorrect

The section titled "Heading IDs and plugins" recommends applying the satteriHeadingIdsPlugin() before custom plugins when the custom plugins need to access the IDs injected by Astro. However, the code suggestion reads as follows:

hastPlugins: [
  satteriHeadingIdsPlugin(),
  otherPluginThatReliesOnHeadingIDs,
],

This approach creates only one plugin instance (and thus one github-slugger instance) for the whole site, causing header ID disambiguation (e.g., "some-header-1" instead of "some-header") to occur when it's not necessary. For example, if page one has # Heading and page two also has # Heading, one of the pages will get a header ID of "heading" and the other will get a header ID of "heading-1". This behavior is unpredictable and unnecessary, since disambiguation is necessary only within a single page.

Instead, the code snippet should read:

hastPlugins: [
  () => satteriHeadingIdsPlugin(),
  otherPluginThatReliesOnHeadingIDs,
],

(perhaps with an explanation of why that structure is needed) so that a plugin instance is created per-page, preventing disambiguation from occurring unnecessarily and making generated header IDs more predictable.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

Open the “Heading IDs and plugins” section at docs.astro.build/en/guides/markdown-content/#heading-ids-and-plugins and review the hastPlugins example. Update the snippet to create satteriHeadingIdsPlugin() per page, add the explanation about avoiding cross-page ID disambiguation, and verify the example matches the reported behavior.