Vuepress: [Feature Request] Glossary reference

Created on 12 Jun 2018 · 6Comments · Source: vuejs/vuepress

Feature request

This is a feature, originally from gitbook.io. I want to bring it up for further discussion.
They have a convention for a GLOSSARY.md file with the following format:

# term
Definition for this term

# Another term
With it's definition, this can contain bold text and all other kinds of inline markup ...

📝 https://gitbookio.gitbooks.io/documentation/format/glossary.html

What problem does this feature solve?

Allows you to specify terms and their respective definitions to be displayed in the glossary.
Based on those terms, vuepress will automatically build an index and highlight those terms in pages.

What does the proposed API look like?

Scan a pre-defined file (eg. GLOSSARY.md) for key/value pairs. Scan the docs copytext where the key matches, add the following markup: <a href="glossary.html#[key]" title="[value]">[key]</a>

How should this be implemented in your opinion?

An example can be found here:

<a href="glossary.html#api" class="glossary-term" title="API is a fun, ambiguous term. It stands for 'Application Programming Interface'. It's a fancy phrase for talking about some agreed-upon way for two programs to talk to each other. It can refer to the specification, as well as the implementation. In recent years, people have often meant 'HTTP API' (or API that uses http as the channel of communication) when talking about APIs. When someone says 'Twitter has an API', they mean Twitter has an HTTP API, which boils down to a special webpage that works as a function. For example, it could be something like twitter.com/api/tweets, which would then respond with a list of all tweets in json format. APIs each have different ways of handling authentication. If you want to see an example of an HTTP api, check out the Co-lab's interactive api documentation page."> API</a>

Are you willing to work on this yourself?**

Nope, i would need a lot of help in js context.

feature request

Source

neumayr

👍8

Most helpful comment

I think adding this to core would be a good idea. Then people can migrate from gitbook to vuepress easier if they want.

ycmjason on 13 Jun 2018

👍7

All 6 comments

I believe this would be a nice addition, but I'd say this would be better suited via plugin :wink:

hmatalonga on 12 Jun 2018

I think adding this to core would be a good idea. Then people can migrate from gitbook to vuepress easier if they want.

ycmjason on 13 Jun 2018

👍7

@neumayr I have recently begun to write a glossarifier. Not particularly for vuepress and I am not planning for it. However it's a tool where you feed markdown in and get markdown out. Thus it is transparent to vuepress and can be integrated as kind of a preprocessing step into a vuepress build pipeline.

If you think glossarify-md is what you are looking for, then you might want to give it a try.

Kudos go to

@wooorm, author of unifiedjs, remarkjs and utility modules which make glossarify-md quite lean
@staltz, author of remark-linkify-regex
and others providing modules and value to glossarify-md