Skip to content

Optional consistency validation of custom header anchors across localized documents #4765

@clicelee

Description

@clicelee

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

Ref: #3326
When a single document is translated into multiple languages (en/guide.md, ko/guide.md, ja/guide.md …), the internal anchor links (#installation, #설치, #インストール, #instalación …) can easily diverge or disappear in one locale.
As a result, users who switch languages via the locale switcher are taken to the top of the page instead of the correct section, breaking the reading flow and causing frustration for both readers and translators who must hunt down silent 404-style anchor errors.

Describe the solution you'd like

Add an opt-in “anchor consistency check” that project owners can enable either:

  1. At vitepress init time – show a prompt such as
 Enforce custom anchor consistency across locales?
  ( ) Yes, validate during build
  ( ) No, I’ll manage anchors manually
  1. Via site config – e.g.
export default defineConfig({
  anchorConsistencyCheck: 'warn' // 'off' | 'warn' | 'strict'
})

When enabled, VitePress (or an official plugin) would during build:

  • Find files that share the same filename across locale folders.
  • Parse headers with explicit {#custom-anchor} and collect their order.
  • Compare anchors across locales; if mismatched or missing, emit a warning or error according to the chosen mode.

This keeps /en/guide#installation in sync with /ko/guide#installation and so on, without imposing the rule on projects that don’t need it.

Describe alternatives you've considered

Custom scripts / pre-commit hooks – works, but every team must reinvent the wheel.

Manual slugify overrides – e.g. writing a custom slugify for Korean, but this does not guarantee that translators reuse the same IDs.

Third-party plugins – possible today, but an official (or first-party) solution would be easier to discover, configure, and document.

Additional context

Additional context

// Desired state
//en/guide.md
## Installation {#installation}
## Configuration {#configuration}

//ko/guide.md
## 설치 {#installation}
## 설정 {#configuration}

If ko/guide.md accidentally drops {#installation}, a build-time check would surface it immediately instead of shipping a broken link to production. I’ve run into this in Toss’s VitePress docs (toss/frontend-fundamentals#160) and had to roll my own slugify + QA scripts; baking an optional checker into VitePress would help any multilingual project avoid the same pitfalls.

Validations

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions