Ability to customize heading IDs

[roll]

What version of starlight are you using?

0.24.4

What is your idea?

It would be great to be able to customize heading IDs as in https://www.markdownguide.org/extended-syntax/#heading-ids or at least using some plugin/hook

Why is this feature necessary?

As a use case example, we're a working group developing data standards and for us it's critical to have human-readable URL fragments. Currently, we had to patch build artifacts to achieve this (we might be missing something but all the attempts with rehype plugins didn't work out).

An example:

• https://datapackage.org/specifications/data-package/#resources
• before patching, the fragment was #resources-required

Do you have examples of this feature in other projects?

• https://www.markdownguide.org/extended-syntax/#heading-ids
• https://kramdown.gettalong.org/syntax.html#headers

Participation

• I am willing to submit a pull request for this feature.

[HiDeoo]

As specified in the Markdown Cheat Sheet from The Markdown Guide linked in the documentation, custom heading IDs are part of the extended syntax which is not supported out of the box by all Markdown applications. This is the case for Starlight but Starlight and Astro supports adding 3rd-party plugins for Markdown & MDX.

In this case, you would need to install a plugin like remark-custom-heading-id and add it to your configuration:

import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import { remarkHeadingId } from "remark-custom-heading-id";

export default defineConfig({
  integrations: [starlight({ title: "My Docs" })],
  markdown: {
    remarkPlugins: [remarkHeadingId],
  },
});

After that, a syntax like ## My Title {#custom-id} should work as expected like in this small example I made.

You can also find more details in this guide: https://docs.astro.build/en/guides/markdown-content/#markdown-plugins

[roll]

Thanks @HiDeoo!

I'm going to try this. The problem we had previously is that whatever we do in the markdown section of the astro config

  markdown: {
    remarkPlugins: [remarkHeadingId],
  },

are ignored by the Starlight's TOC generator. So we achieved it on the page but TOC was still referencing old ids

[roll]

Thanks a lot!

I've made it work. The problem was that I used rehypeHeadingIds (as in the tutorial - https://hideoo.dev/notes/starlight-heading-links/#configure-the-plugin) instead of remarkHeadingIds

[roll]

The full config to have both configurable ids and clickable headings:

  markdown: {
    remarkPlugins: [remarkHeadingId],
    rehypePlugins: [
      rehypeHeadingIds,
      [
        rehypeAutolinkHeadings,
        {
          behavior: "wrap",
        },
      ],
    ],
  },

[HiDeoo]

Ah, I see, amazing, good to hear you figured it out.

Thanks for sharing the full config to get both custom IDs and heading links 🙌

[roll]

Thanks!