Auto‑insert `<a.header‑anchor>` for headings rendered by Vue components

[alexchexes]

Is your feature request related to a problem? Please describe.

When a heading comes from a Vue component, it gets an id and shows up in the "On this page" outline, but the invisible <a class="header-anchor">, which appears on mouse hover, is missing.

Minimal repro:

docs/index.md

<script setup lang="ts">
import AComponent from './AComponent.vue'
</script>

## foo {#foo}

<AComponent />

docs/AComponent.vue

<template>
  <h2 id="bar">bar</h2>
  <h2 id="baz">baz</h2>
</template>

Result: ## bar and ## baz appear in the outline and are linkable, but they have no header‑anchor element, so users cannot easily copy a permalink, and the UI feels a bit inconsistent when hovering the mouse over headings added by the component and the ones written in Markdown.

Describe the solution you'd like

During the same client‑side pass that builds the outline, scan for any <h1‑h6> with an id but lacking .header-anchor, and inject an anchor with the same markup VitePress generates for Markdown headings.

Describe alternatives you've considered

Manually adding the anchor works...

<h2 id="qux">
  qux
  <a class="header-anchor" href="#qux" aria-label='Permalink to "qux {#qux}"'>&ZeroWidthSpace;</a>
</h2>

...but is somewhat boilerplate and is brittle. It must be manually added to each place where <h1‑h6> is used and will break if the theme changes.

Additional context

Screencast of how the repro example looks:

chrome_2025-07-30--19-07-12--488.mp4

Validations

• Follow our Code of Conduct
• Read the docs.
• Read the Contributing Guidelines.
• Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[brc-dd]

We can, but I don't think we should add extra markup on client. Also, it will most likely cause issues with hydration.

will break if the theme changes

It's not dependent on theme. It will only change in a major version. You can safely create a heading component and reuse it.

[alexchexes]

I don't think we should add extra markup on the client. Also, it will most likely cause issues with hydration.

Ahh, you're right, agreed. Then what do you think about providing a built-in directive like v-header-anchor, so that users could add it to their component headings like this?

<template>
  <h2 id="bar" v-header-anchor>bar</h2>
</template>

It would still be opt-in — developers would have to add it manually — but it would encapsulate the exact classes / ARIA attributes / other details, so users wouldn't need to worry about how VitePress handles them internally, even if those details change in a future major release.

A built-in Vitepress component could work as well, but the directive seems more appealing from a user's point of view, IMO.

[brc-dd]

Yeah, but there is an issue with directive, there is no good way to get the text content from slot. Like we will need that bar text here for aria-label. With the component we can accept text as prop instead of slot.

[alexchexes]

Right, I forgot about that limitation. In that case, a dedicated component does seem like the most practical option for now.