Skip to content

Custom header links #679

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
eddyerburgh opened this issue Jul 29, 2018 · 7 comments
Closed

Custom header links #679

eddyerburgh opened this issue Jul 29, 2018 · 7 comments
Labels
type: feature request Request to add a new feature

Comments

@eddyerburgh
Copy link
Member

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

@ulivz ulivz added type: enhancement Request to enhance an existing feature type: feature request Request to add a new feature and removed type: enhancement Request to enhance an existing feature labels Jul 29, 2018
@ulivz
Copy link
Member

ulivz commented Jul 29, 2018

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

@eddyerburgh
Copy link
Member Author

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

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

@ulivz
Copy link
Member

ulivz commented Jul 29, 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.

@jameshulse
Copy link

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:

## Creating Your First User <!-- ref: create-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).

@abernov
Copy link

abernov commented Oct 24, 2019

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

@nelson6e65
Copy link
Contributor

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

Thanks! I'll check, @abernov!

@ulivz
Copy link
Member

ulivz commented Oct 25, 2019

Closing this as it's resolved by markdown-it-custom-header-link.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type: feature request Request to add a new feature
Projects
None yet
Development

No branches or pull requests

5 participants