Discussion: Re-Usable Glossary #369

New Issue

OVERLORD · 2026-02-04T19:06:44+03:00

OVERLORD commented

2026-02-04 19:06:44 +03:00

Originally created by @Shackelford-Arden on GitHub (Jul 7, 2017).

So, I was writing up some documentation and noticed that I use acronyms rather often. While I know that the audience who would be reading my content are likely to understand what they all mean, I also like ensuring that there is no room for assumptions.

I got to thinking. What could I do to help ensure that acronyms (or even other uncommon words/phrases) are understood by all readers, regardless of background?

I thought of a re-usable set of terms that would be stored with their respective definition.

I imagine this being implemented in a way that you'd simply highlight the word or phrase and then link it to an item in the glossary. Users could then click on the acronym and a small pop up (in context, not a new window) would show with the term and it's respective definition.

Thoughts?

Originally created by @Shackelford-Arden on GitHub (Jul 7, 2017). So, I was writing up some documentation and noticed that I use acronyms rather often. While I know that the audience who would be reading my content are likely to understand what they all mean, I also like ensuring that there is no room for assumptions. I got to thinking. What could I do to help ensure that acronyms (or even other uncommon words/phrases) are understood by all readers, regardless of background? I thought of a re-usable set of terms that would be stored with their respective definition. I imagine this being implemented in a way that you'd simply highlight the word or phrase and then link it to an item in the glossary. Users could then click on the acronym and a small pop up (in context, not a new window) would show with the term and it's respective definition. Thoughts?

OVERLORD added the ☕ Open to discussion label 2026-02-04 19:06:44 +03:00

OVERLORD closed this issue

2026-02-04 19:06:50 +03:00

OVERLORD commented

2026-02-04 19:07:03 +03:00

@Ethanb00 commented on GitHub (Sep 28, 2017):

I really like this idea. And can see a few potential iterations/questions for how it would look.

Would I use it to define acronyms system-wide, book-wide, chapter-wide, page-wide?

How extensive can the explanation be? For example, can I use the same tool to expand the acronym WSUS as I would use for a brief explanation of AuthPrimary as my primary Domain Controller with its IP address and basic configs, etc.

@Ethanb00 commented on GitHub (Sep 28, 2017): I really like this idea. And can see a few potential iterations/questions for how it would look. Would I use it to define acronyms system-wide, book-wide, chapter-wide, page-wide? How extensive can the explanation be? For example, can I use the same tool to expand the acronym WSUS as I would use for a brief explanation of AuthPrimary as my primary Domain Controller with its IP address and basic configs, etc.

OVERLORD commented

2026-02-04 19:07:17 +03:00

@Shackelford-Arden commented on GitHub (Sep 29, 2017):

@Ethanb00 Personally, I was looking at more like global level words or acronyms. That's just my use case though.

As for the explanations, I'd look at something no more than a few sentences. Potentially with a link to another page that is more of a glossary page or something that includes more information?

@Shackelford-Arden commented on GitHub (Sep 29, 2017): @Ethanb00 Personally, I was looking at more like global level words or acronyms. That's just my use case though. As for the explanations, I'd look at something no more than a few sentences. Potentially with a link to another page that is more of a glossary page or something that includes more information?

OVERLORD commented

2026-02-04 19:07:23 +03:00

@Ethanb00 commented on GitHub (Sep 30, 2017):

I think my preference would be for a book level glossary...or appendix I guess.

I also like the idea of a mouse-over tooltip style HUD for the info. And agreed regarding a strict, short text limit.

@Ethanb00 commented on GitHub (Sep 30, 2017): I think my preference would be for a book level glossary...or appendix I guess. I also like the idea of a mouse-over tooltip style HUD for the info. And agreed regarding a strict, short text limit.

OVERLORD commented

2026-02-04 19:07:31 +03:00

@mainmachine commented on GitHub (Jul 3, 2019):

Could you do this via custom CSS...?

@mainmachine commented on GitHub (Jul 3, 2019): Could you do this via custom CSS...?

OVERLORD commented

2026-02-04 19:07:35 +03:00

@ssddanbrown commented on GitHub (May 20, 2022):

There's been very little demand/requirement for this since it was originally requested, so I'm going to close this off.
I think an official implementation would raise questions, such as scope of glossary terms, as reflected above, and this could essentially be achieved via an additional page at whatever level was desired.

@ssddanbrown commented on GitHub (May 20, 2022): There's been very little demand/requirement for this since it was originally requested, so I'm going to close this off. I think an official implementation would raise questions, such as scope of glossary terms, as reflected above, and this could essentially be achieved via an additional page at whatever level was desired.

OVERLORD commented

2026-02-04 19:07:46 +03:00

@demlak commented on GitHub (Sep 23, 2023):

the world keeps turning.. bookstack, too.
6 Years later in a World, where "Accessibility" on the web has more focus then ever.. we use a similar Glossary on our website.. since we want to extend our project more and more with bookstack, we would love to see this on bookstack, too.

In our case, predefined/tagged Text is highlighted in a specific color to show "this phrase has a glossary entry". People can mouse-over to get a popup with a very short description.

We released this with Drop-Component of UIKit..
https://getuikit.com/docs/drop

Since Bookstack seem to have some components from Bootstrap.. whatabout the "popovers"-component?
https://getbootstrap.com/docs/5.0/components/popovers/

See Video for example:

https://github.com/BookStackApp/BookStack/assets/11285006/c4f035cc-7eb1-46b4-8a42-bb9b559c3570

In our case the predefining is centralised and we can use a Tag in our CMS to call the entry.
Example from the Video above:
Wesentlich ist dafür das Bemühen um einen (glossary: suffizienz text: genügsamer Lebensstil).

Thats how we can access entries of the glossary on our website:
( starts the tag
glossary: is the Name of the tag
suffizienz is the name of the glossary-entry
text: is an attribute
genügsamer Lebensstil is the highlighted phrase to show
) closes the tag

Maybe you can reopen this issue? I would like to see if the interest in 2023 got grown.

@demlak commented on GitHub (Sep 23, 2023): the world keeps turning.. bookstack, too. 6 Years later in a World, where "Accessibility" on the web has more focus then ever.. we use a similar Glossary on our website.. since we want to extend our project more and more with bookstack, we would love to see this on bookstack, too. In our case, predefined/tagged Text is highlighted in a specific color to show "this phrase has a glossary entry". People can mouse-over to get a popup with a very short description. We released this with Drop-Component of UIKit.. https://getuikit.com/docs/drop Since Bookstack seem to have some components from Bootstrap.. whatabout the "popovers"-component? https://getbootstrap.com/docs/5.0/components/popovers/ See Video for example: https://github.com/BookStackApp/BookStack/assets/11285006/c4f035cc-7eb1-46b4-8a42-bb9b559c3570 In our case the predefining is centralised and we can use a Tag in our CMS to call the entry. Example from the Video above: `Wesentlich ist dafür das Bemühen um einen (glossary: suffizienz text: genügsamer Lebensstil).` Thats how we can access entries of the glossary on our website: `(` starts the tag `glossary:` is the Name of the tag `suffizienz` is the name of the glossary-entry `text:` is an attribute `genügsamer Lebensstil` is the highlighted phrase to show `)` closes the tag Maybe you can reopen this issue? I would like to see if the interest in 2023 got grown.

OVERLORD commented

2026-02-04 19:07:52 +03:00

@nmdemarco commented on GitHub (Oct 18, 2023):

@demlak your video doesn't play, so I can't be sure what you're proposing.

At one point, our team used a Confluence add-in similar to this one. We didn't solicit formal feedback from our wiki users. My sense, however, was that people found the inline links and hover tooltips distracting.

This might be a case where the feature sounds excellent, but all implementations fall short of expectations.

@nmdemarco commented on GitHub (Oct 18, 2023): @demlak your video doesn't play, so I can't be sure what you're proposing. At one point, our team used a Confluence add-in similar to [this one](https://marketplace.atlassian.com/apps/1211800/glossary-for-confluence?tab=overview&hosting=cloud). We didn't solicit formal feedback from our wiki users. My sense, however, was that people found the inline links and hover tooltips distracting. This might be a case where the feature sounds excellent, but all implementations fall short of expectations.

OVERLORD commented

2026-02-04 19:07:57 +03:00

@demlak commented on GitHub (Oct 18, 2023):

thx for the info.. i just uploaded a converted version of the video..

@demlak commented on GitHub (Oct 18, 2023): thx for the info.. i just uploaded a converted version of the video..

OVERLORD commented

2026-02-04 19:08:08 +03:00

@JNR8 commented on GitHub (Apr 29, 2024):

I would greatly use something like this. For my purposes I would require certain words or phrases in Japanese to automatically link to a centralised glossary entry which would provide an explanation in English.

I would like two methods of displaying this on a page with an option to choose which display option to be default either by page or by book:

Creating an link for that word or phrase that displays the English explanation when hover over the link.
Suggesting terms and phrases when typing a Japanese term and injecting both the Japanese and English inline when choosing one of the suggestions (i.e. Japanese [English] )

Currently I end up having to type the English directly after the Japanese on the page and keep a separate page listing all terms.

This is very time consuming and difficult to make adjustments should I need to change a translation.

Alternatively, being able to utilise the Tagging System for this purpose would also be suitable. (i.e. creating a Tag with a value on the page and being able to add that tag on line of text that uses the display options I previous mentioned.

@JNR8 commented on GitHub (Apr 29, 2024): I would greatly use something like this. For my purposes I would require certain words or phrases in Japanese to automatically link to a centralised glossary entry which would provide an explanation in English. I would like two methods of displaying this on a page with an option to choose which display option to be default either by page or by book: 1. Creating an link for that word or phrase that displays the English explanation when hover over the link. 2. Suggesting terms and phrases when typing a Japanese term and injecting both the Japanese and English inline when choosing one of the suggestions (i.e. Japanese `[English]` ) Currently I end up having to type the English directly after the Japanese on the page and keep a separate page listing all terms. This is very time consuming and difficult to make adjustments should I need to change a translation. Alternatively, being able to utilise the Tagging System for this purpose would also be suitable. (i.e. creating a Tag with a value on the page and being able to add that tag on line of text that uses the display options I previous mentioned.

OVERLORD commented

2026-02-04 19:08:17 +03:00

@kristiandg commented on GitHub (Nov 11, 2024):

I just created an FR for this very thing. Funny, when I did my initial search, I was searching for "in-line definitions". Only as I was writing out the FR, did I realize the term Glossary, and updated my FR to have that terminology.

But I see great use for this feature... Here's the FR I created - based on the different comments about how to implement, maybe folks would like what I proposed, as it would seem to cover most use cases mentioned above. :)

https://github.com/BookStackApp/BookStack/issues/5316

@kristiandg commented on GitHub (Nov 11, 2024): I just created an FR for this very thing. Funny, when I did my initial search, I was searching for "in-line definitions". Only as I was writing out the FR, did I realize the term Glossary, and updated my FR to have that terminology. But I see great use for this feature... Here's the FR I created - based on the different comments about how to implement, maybe folks would like what I proposed, as it would seem to cover most use cases mentioned above. :) https://github.com/BookStackApp/BookStack/issues/5316

OVERLORD commented

2026-02-04 19:08:19 +03:00

@ssddanbrown commented on GitHub (Nov 13, 2024):

If anyone here still desires this, in #5316 with @kristiandg I played around with the idea of achieving the core goal of this via just added JavaScript + CSS, and have cleaned this up into a hack here:

https://www.bookstackapp.com/hacks/dynamic-glossary/

It allows a global glossary, with the option to override-via/use a book-level glossary.

glossary-terms.webm

@ssddanbrown commented on GitHub (Nov 13, 2024): If anyone here still desires this, in #5316 with @kristiandg I played around with the idea of achieving the core goal of this via just added JavaScript + CSS, and have cleaned this up into a hack here: https://www.bookstackapp.com/hacks/dynamic-glossary/ It allows a global glossary, with the option to override-via/use a book-level glossary. [glossary-terms.webm](https://github.com/user-attachments/assets/2494ff73-558f-4cec-ac6d-9fae4c59ab77)

OVERLORD commented

2026-02-04 19:08:32 +03:00

@JNR8 commented on GitHub (Nov 15, 2024):

Thank you so much. Annoyingly I do need to use multiple words as I need to translate japanses phrases to english using this method. but will work with hyphen for now to avoid spaces.

Do the Gloarry pages (either global or bok based) need to be visible to the end users in order for them to see the term explainations in the hover popup text or can they be hidden by permissions, but still viewable?

@JNR8 commented on GitHub (Nov 15, 2024): Thank you so much. Annoyingly I do need to use multiple words as I need to translate japanses phrases to english using this method. but will work with hyphen for now to avoid spaces. Do the Gloarry pages (either global or bok based) need to be visible to the end users in order for them to see the term explainations in the hover popup text or can they be hidden by permissions, but still viewable?

OVERLORD commented

2026-02-04 19:08:38 +03:00

@kristiandg commented on GitHub (Nov 15, 2024):

I’m betting they do because their browser needs to index it and can only do that if being viewed. Kristian GuntzelmanSent from my mobile device...On Nov 15, 2024, at 12:16 PM, Jennerate @.***> wrote:
Thank you so much. Annoyingly I do need to use multiple words as I need to translate japanses phrases to english using this method. but will work with hyphen for now to avoid spaces.
Do the Gloarry pages (either global or bok based) need to be visible to the end users in order for them to see the term explainations in the hover popup text or can they be hidden by permissions, but still viewable?

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: @.***>

@kristiandg commented on GitHub (Nov 15, 2024): I’m betting they do because their browser needs to index it and can only do that if being viewed. Kristian GuntzelmanSent from my mobile device...On Nov 15, 2024, at 12:16 PM, Jennerate ***@***.***> wrote: Thank you so much. Annoyingly I do need to use multiple words as I need to translate japanses phrases to english using this method. but will work with hyphen for now to avoid spaces. Do the Gloarry pages (either global or bok based) need to be visible to the end users in order for them to see the term explainations in the hover popup text or can they be hidden by permissions, but still viewable? —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

OVERLORD commented

2026-02-04 19:08:42 +03:00

@JNR8 commented on GitHub (Nov 18, 2024):

I am trying to get my head around how to implement this for my use case.

I have a shelf with many books related to Karate. Each book contains Japanese terms and phrases that I would like to be referenced by a single dynamic glossary page at the shelf level. Right now it seems I can create a page per book or globally, but not per shelf. Each book on this shelf contains shared terms and phrases which when using the current model I would either need to repeat in a glassary page per book (resulting in duplicating the glossary mutiple times) or create a global glosssary.

Creating a Global Glossary could lead to problems where there may be duplicate terms with different descriptions depending the topic of the book. For example terms or phrases in a book about Karate could over lap (although unlinkely) with books about IT related support processes. I.e. A description for a Japanses term being could be displayed in a book about scripting in PowerShell, (unlikely, but possible).

Would it be possible to modify the script to look for glossaries at the Shelf level asl well?

@JNR8 commented on GitHub (Nov 18, 2024): I am trying to get my head around how to implement this for my use case. I have a shelf with many books related to Karate. Each book contains Japanese terms and phrases that I would like to be referenced by a single dynamic glossary page at the shelf level. Right now it seems I can create a page per book or globally, but not per shelf. Each book on this shelf contains shared terms and phrases which when using the current model I would either need to repeat in a glassary page per book (resulting in duplicating the glossary mutiple times) or create a global glosssary. Creating a Global Glossary could lead to problems where there may be duplicate terms with different descriptions depending the topic of the book. For example terms or phrases in a book about Karate could over lap (although unlinkely) with books about IT related support processes. I.e. A description for a Japanses term being could be displayed in a book about scripting in PowerShell, (unlikely, but possible). Would it be possible to modify the script to look for glossaries at the Shelf level asl well?

OVERLORD commented

2026-02-04 19:08:46 +03:00

@JNR8 commented on GitHub (Nov 20, 2024):

After implementting a global glossary to test this out I have come across a few issues:

1: Terms in a header are highlighted, when perhaps they should not be.
2: The term being highlighted is duplicated (but not all the time, see attached image).

3: Terms are not always displayed. Different browsers have different results. MS Edge for example throws an exception:

Uncaught (in promise) QuotaExceededError: Failed to execute 'setItem' on 'Storage': Setting the value of 'bsglossary:/books/global-glossary/page/index' exceeded the quota.
    at addTermMapToStorage (9th-to-8th-kyu-red:193:29)
    at getGlossaryFromPath (9th-to-8th-kyu-red:183:9)
    at async Promise.all (index 0)
    at async getMergedGlossariesForPage (9th-to-8th-kyu-red:135:49)
    at async highlightTermsOnPage (9th-to-8th-kyu-red:85:26)

@JNR8 commented on GitHub (Nov 20, 2024): After implementting a global glossary to test this out I have come across a few issues: 1: Terms in a header are highlighted, when perhaps they should not be. 2: The term being highlighted is duplicated (but not all the time, see attached image). ![image](https://github.com/user-attachments/assets/e3e9948f-c594-41e0-94f5-4612ef24fdd0) 3: Terms are not always displayed. Different browsers have different results. MS Edge for example throws an exception: ```` Uncaught (in promise) QuotaExceededError: Failed to execute 'setItem' on 'Storage': Setting the value of 'bsglossary:/books/global-glossary/page/index' exceeded the quota. at addTermMapToStorage (9th-to-8th-kyu-red:193:29) at getGlossaryFromPath (9th-to-8th-kyu-red:183:9) at async Promise.all (index 0) at async getMergedGlossariesForPage (9th-to-8th-kyu-red:135:49) at async highlightTermsOnPage (9th-to-8th-kyu-red:85:26) ````

OVERLORD commented

2026-02-04 19:09:14 +03:00

@ssddanbrown commented on GitHub (Nov 22, 2024):

@JNR8 Yeah, this is only a quick hack implementation so there can be limitations/issues. I updated the hack yesterday to avoid issues when the term is the first word in a line, which is maybe what you're running into there. The hack does not target specific content types, it just targets all page content.

Would it be possible to modify the script to look for glossaries at the Shelf level asl well?

Anything is possible with enough time, but it's not something I'd offer as it does complicate things further, especially with content not belonging to specific shelves, and since I don't want to increase the scope of the hack any wider and/or spend too much further time on it.

@ssddanbrown commented on GitHub (Nov 22, 2024): @JNR8 Yeah, this is only a quick hack implementation so there can be limitations/issues. I updated the hack yesterday to avoid issues when the term is the first word in a line, which is maybe what you're running into there. The hack does not target specific content types, it just targets all page content. > Would it be possible to modify the script to look for glossaries at the Shelf level asl well? Anything is possible with enough time, but it's not something I'd offer as it does complicate things further, especially with content not belonging to specific shelves, and since I don't want to increase the scope of the hack any wider and/or spend too much further time on it.

OVERLORD referenced this issue

2026-02-04 19:09:49 +03:00

Document formatting #371

OVERLORD referenced this issue

2026-02-04 19:24:07 +03:00

Give the possibility to choose between Markdown or TinyMCE at the page creation #392

OVERLORD referenced this issue

2026-02-05 00:41:55 +03:00

Use ToastUI as the markdown editor #1362

OVERLORD referenced this issue

2026-02-05 00:51:49 +03:00

Switch between markdown and wysiwyg (page specific) #1423