Definitions and linking

xfq commented 2 years ago

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

It would be nice to be able to define a term and link to it.

Now I can only add <dfn id="term1"> to the term and use <a href="#term1> to link to it (see example), but I find that sometimes there is a problem with this. When I click the link, it sometimes jumps to the dfn, sometimes not (I can't find a reliable way to reproduce this issue, though). It seems that VP sometimes intercepts the operation of changing the page's hash?

Describe the solution you'd like

Either <a>some concept</a> or a custom shorthand syntax works for me, as long as I don't have to hand-write the href attribute.

Describe alternatives you've considered

No response

Additional context

Many other documentation systems have this functionality, such as:

Some also support automatic pluralization.

Validations

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

brc-dd commented 2 years ago

When I click the link, it sometimes jumps to the dfn, sometimes not

Yeah this is an issue. It was first reported here: https://github.com/vuejs/vitepress/issues/788#issuecomment-1155803310

I don't have to hand-write the href attribute

[some concept](#some-concept) should work. We just need to fix that router issue.

brc-dd commented 2 years ago

Lets track this at #903

xfq commented 2 years ago

Sorry, I don't think #903 is the same issue. This issue is a feature request, not a bug report. I mentioned <a href="#term1> because there is no automatic definition linking feature in VitePress, and I only use it as a workaround.

As I mentioned above, I'd like to be able to link to a definition without writing href by hand. There are also some examples in the "Additional context" section.

brc-dd commented 2 years ago

Is there any markdown-it plugin for this stuff? I can't find anything relevant on NPM.

brc-dd commented 2 years ago

Also, in your example you are doing this: <a href="#concept">concepts</a> How do you intend to infer href in this case?

brc-dd commented 2 years ago

You can use some config like this:

import { defineConfig } from 'vitepress'
import iterator from 'markdown-it-for-inline'
import slugify from '@sindresorhus/slugify'

const dfnRE = /\[\[~ (.*?)\]\]/g
const linkRE = /\[\[= (.*?)\]\]/g

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(iterator, 'dfn_link', 'text', (tokens, idx) => {
        tokens[idx].content = tokens[idx].content
          .replace(dfnRE, (_, s) => `<dfn id="${slugify(s)}">${s}</dfn>`)
          .replace(linkRE, (_, s) => `<a href="#${slugify(s)}">${s}</a>`)
        tokens[idx].type = 'html_inline'
      })
    }
  }
})

Then in markdown you can do [[~ Some Concept]] to create dfn, and [[= Some Concept]] to create link.

I am closing this issue as it likely will have very less demand and can be achieved using markdown it plugins. If we see much requests for this, then we might consider adding the support officially.

xfq commented 2 years ago

Also, in your example you are doing this: <a href="#concept">concepts</a> How do you intend to infer href in this case?

Ideally, VP should recognize this automatically (at least for documents in English, like 1 and 2). If that's not possible, it would be nice to have a way to manually add variants of a term.

I am closing this issue as it likely will have very less demand and can be achieved using markdown it plugins. If we see much requests for this, then we might consider adding the support officially.

Fair enough. Thank you very much for your help!

brc-dd commented 2 years ago

Ideally, VP should recognize this automatically (at least for documents in English, like 1 and 2). If that's not possible, it would be nice to have a way to manually add variants of a term.

You can do this using some library like https://www.npmjs.com/package/pluralize. In the config I've shown change slugify(s) with slugify(singular(s)). Also that library allows you customize singularization using addSingularRule function.

vuejs / vitepress