How to customize heading anchor links instead of automatically generating them based on heading text?

[yangxuan74]

What version of starlight are you using?

0.31.1

What is your idea?

When internationalizing, it is important to maintain consistency in anchor links. For example, in English, the anchoris ## Introduction, and the generated link is https://xx/en/xxx#introduction But after translating the Chinese, the generated link is https://xx/zh/xxx#**简介**. How to make anchor links consistent between Chinese and English, for example https://xx/**en**/xxx#**introduction** and https://xx/**zh**/xxx#**introduction**?

Why is this feature necessary?

When internationalizing, it is important to maintain consistency in anchor links.

Do you have examples of this feature in other projects?

In Antora, the AsciiDoc syntax can be used to add an ID before the anchor heading.

https://docs.asciidoctor.org/asciidoc/latest/attributes/id/#anchor

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 old example I made in the past.

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