How to disable the build-in anchor feature and use my own fork instead?

[otomad]

I found that VitePress use its own patch of markdown-it-anchor, and seems bundle it to the dist package.

However I found markdown-it-anchor internal uniqueSlug function can escape failOnNonUnique, but authors cannot access it directly.

https://github.com/valeriangalliat/markdown-it-anchor/blob/174c1369cd91682c7ba76f08a09077fe1e09ef57/index.js#L12-L23

For example, if you write this:

## Title 1 {#title-1}

## Title 1 {#title-1}

It will raise an error:

[plugin:vitepress] User defined `id` attribute `title-1` is not unique. Please fix it in your Markdown to continue.

However, this will not raise any error:

## Title 1

## Title 1

Actually, I want to use my other markdown-it plugins to automatically generate title id, but this annoying error troubles me, the id was generated by other plugins, if markdown-it-anchor find it duplicated, just rename the id instead of raise an error.

So I want to fork the markdown-it-anchor and use it for myself. Just change it to:

-  if (failOnNonUnique && Object.prototype.hasOwnProperty.call(slugs, uniq)) {
+  if (false && failOnNonUnique && Object.prototype.hasOwnProperty.call(slugs, uniq)) {
     throw new Error(`User defined \`id\` attribute \`${slug}\` is not unique. Please fix it in your Markdown to continue.`)
   } else {

But it seems VitePress use it own markdown-it-anchor instead of the installed one. Even with config:

import anchorPlugin from "markdown-it-anchor"; // The forked package.

export default defineConfig({
	markdown: {
		anchor: {
			permalink: undefined,
		},
		config: md => {
			md.use(anchorPlugin);
		},
	},
});

It will still raise the error. How to solve it?

[yhay81]

The key is plugin order. VitePress installs its own markdown-it-anchor before markdown.config runs, so adding your fork in config is too late: the built-in core rule throws first.

For this particular change, the least invasive solution is to run your fork in preConfig:

import { defineConfig } from 'vitepress'
import anchorPlugin from 'your-fork-of-markdown-it-anchor'

export default defineConfig({
  markdown: {
    preConfig(md) {
      // If another plugin creates heading ids, install it before this line.
      md.use(anchorPlugin, {
        permalink: false
      })
    }
  }
})

Your fork's core rule then runs first and changes the second explicit title-1 to title-1-1. VitePress's own anchor rule runs afterward, sees two unique IDs, and can still add VitePress's normal header permalinks. Keeping permalink: false on the fork prevents it from adding a second permalink.

If you truly need to replace the built-in rule, this also works in config:

markdown: {
  config(md) {
    md.core.ruler.disable('anchor')
    md.use(anchorPlugin)
  }
}

However, that removes VitePress's custom anchor behavior (including its accessible header-anchor permalink renderer) unless you reproduce those options in your fork. It can also make heading IDs diverge from VitePress's TOC/header extraction, so preConfig is preferable for your deduplication-only use case.

Why this works is visible in VitePress's current setup order: preConfig runs before built-ins, VitePress then registers its anchor rule, and config runs last.