Vuepress: Custom header links

Created on 29 Jul 2018 · 7Comments · Source: vuejs/vuepress

Feature request

What problem does this feature solve?

In Vue Test Utils, we have headers generated from method names. Some of these include arguments, which leads to ugly headers and URLS:

## is(selector)
sidebar: is(selector)
path: /api/wrapper/#is-selector

What does the proposed API look like?

Add a way to control the generated header link:

## is(selector) <!-- HeaderLink: is -->

How should this be implemented in your opinion?

As a markdown comment.

Are you willing to work on this yourself?**

Not at the moment, no

feature request

Source

eddyerburgh

👍2

Most helpful comment

Solved! Plugin markdown-it-custom-header-link was created

abernov on 24 Oct 2019

🎉1 👍1

All 7 comments

A quick question, only for the customization of links generation, not including headers, right?

ulivz on 29 Jul 2018

Yes , but it would also be good to customize the Header link text:

## is(selector) 

eddyerburgh on 29 Jul 2018

OK, but recently I'm working for next major version (leverage monorepo, refine default theme / plugin / theme API), I will work for that after we finalized next version.

ulivz on 29 Jul 2018

👍2

Something like this would be really useful for us for a slightly different use-case.

If we could mark headers with a unique code or reference then we could refer to that block of content even if it is moved between pages.

Currently as we are developing our docs the structure is changing frequently and so we can't trust that links won't be broken. It would be great to be able to refer to a section in a canonical way that allows us to link to it more safely externally.

For example, an href referring to some part of our help documentation might currently be: example.com/getting-started.html#creating-your-first-user. If the page name is changed to 'first-steps.md' then the link will break, or if the whole heading + content is moved to a new page it will also be broken. If we could instead go:

```getting-started.md

Creating Your First User

```

Or similar. Then we could potentially have inbound links like: example.com/?ref=create-user. Although my suggested solution and use-case is slightly different, having a precedent set for adding metadata to a heading would be really useful. (I also saw a pull request which mentioned adding badges to headers which this could also theoretically be used for).