Abbreviations and a glossary of terms

[Stephen-Gates]

I checked that...

• ... the documentation does not mention anything about my idea
• ... to my best knowledge, my idea wouldn't break something for other users
• ... there are no open or closed issues that are related to my idea

Description

As suggested on Gitter this request is to implement a site-wide Glossary similar to the functionality offered by ReadMe.com and better handling of abbreviations.

One file would be defined in the site for the collection of terms and descriptions. This file could optionally be displayed as a Glossary page.

Using functionality similar to the Abbr extension when the cursor is over a term on any page, a tooltip is displayed showing the description. Functionality could be added to support mobile user as suggested on Gitter.

As a first step the Abbr extension could be added to the documentation and better support for mobile displays added.

Use Cases

Documentation can contain abbreviations and terms that may be new to the reader. Readers can start reading documentation on any page and may have missed initial explanations of terms. By interacting with the term on the page, the reader can quickly discover the meaning of the term.

By capturing all terms in a single file, it make it easy for the author to maintain terms across multiple pages.

Screenshots / Mockups

Current implementation of Abbr extension

[squidfunk]

Thanks! That's indeed a great idea. It goes beyond the abbr functionality, as we'd have to add some JavaScript to inject the glossary, but I think it could be a great addition to Insiders! In essence:

• Better support for abbr on mobile (Material for MkDocs)
• Enhanced support to inject glossary terms into abbr

[squidfunk]

7151d24 adds documentation on how to use abbreviations and – how to build a glossary with snippets! It turns out that we can use the Snippets extension to keep abbreviations in a central file and then just include them at the bottom of a page:
https://squidfunk.github.io/mkdocs-material/reference/abbreviations/#adding-a-glossary

This is a much better solution than anything that we could come up with JavaScript, as it will run during build-time. Does this work for you, @Stephen-Gates?

[squidfunk]

Tooltip for touch-devices added in 6725ec1:

[squidfunk]

Released as part of 5.5.13.

[Stephen-Gates]

@squidfunk thank you so much for solving this so quickly. I'm on holidays at the moment but will give it a try soon. 🥇

[kcgthb]

It turns out that we can use the Snippets extension to keep abbreviations in a central file and then just include them at the bottom of a page:

I've actually been doing that for some time, and it works great!

But now I'm wondering if the concept could be pushed even further, to avoid having to include that central file in each and every page on the site.

Would there be a way to override a block or a partial, to have the glossary automatically included in every page? I know the glossary is Markdown, the partials are HTML, things are not really happening at the same level, but I feel there may be a way to make this even more convenient. :)

Any recommendation?