Building a Glossary in Confluence
When building a Confluence site, or any Help documentation, it is very important to have a Glossary to help explain some of the terms that will be used in the documentation.
Confluence has a few examples of glossaries in their own help system, but of course I wanted to take it a step further – I wanted my glossary terms to have hover text in the main body of the help system, then with a hyperlink to the full glossary text. Also, the glossary should be on one Glossary page and be able to be included in the printed documents.
So, of course, it’s User Macros to the rescue – that along with a lot of help from the Confluence support forum, here’s what I came up with:
The Glossary Macro
{anchor:$ParamName}
h3. $ParamPhrase
{cloak:id=$ParamName}
{multi-excerpt:name=$ParamName}{html}<a style="text-decoration:none; border-bottom:2px dotted; border-bottom-color:#008000" title="$ParamTooltip" href="Glossary#Glossary-$ParamName">$ParamPhrase</a>{html}{multi-excerpt}
{cloak}
$Body
Create the macro to “Convert wiki markup to HTML”.
Breaking down the macro:
- We create an anchor to come back to this Glossary entry at any time from the main content.
- The Parameter phrase is shown in a heading 3 style. The phrase can contain multiple words – eg “Glossary Entry” may be a phrase for a Glossary term.
- There is a cloaked (hidden) section containing a multi-excerpt macro, which contains some HTML formatted text. The multi-excerpt macro will be used to display the Glossary term in our main content pages.
- The HTML text has a dotted green underline and a hyperlink back to this page, it also has a “title”, which forms the hover text (or Tool Tip) of the Glossary term.
- Finally the body of the macro is shown – this is the full text of the Glossary.
Glossary Macro Usage
{glossary:Name=MyName|Phrase=My Glossary Phrase|Tooltip=My Hover or Tool Tip Text}The main description of the Glossary term.
This can contain as much information as needed.{glossary}
My Glossary Phrase
The main description of the Glossary term.
This can contain as much information as needed.
The rest of the content is hidden because it is inside the cloak macro.
The GL Macro
- When you hover over My Glossary Phrase the text “Hover or Tool Tip Text” will be shown
- When you click on the phrase it takes you straight to that anchor on the Glossary page.
GL Macro Usage
The GL macro is simply called by entering the following text in Wiki Markup mode.
This is {gl:MyName} Phrase used in a sentence.
(macro names are always lower case).
Overall Glossary Page
See the content on the Confluence documentation that I wrote about creating a great looking Confluence Glossary page with an alphabetic index at the top of the page.
So it’s very simple to include Glossary words in the body of your Confluence document, the overall Glossary page looks good, and all of the glossary content is maintained and updated in One Place, Once.
I would love to see if you have any ideas for any improvements in this user macro, or if you have a great Confluence glossary page to show off.
Jodie nice write up.
I use the Glossary Macro which runs fairly well – but is a bit clunky at times.
I have always wanted a glossary macro that would provide tooltips for any terms which are defined in a global glossary … so the glossary actual inserts itself on all Confluence pages and instead of you having to go and lookup the definition, the definition is provided to you in a tooltip.
Have you ever seen anything like this or have any ideas how one would go ahead and create this sort of a macro?
Having the glossary in the tooltip is exactly what my Macros do. Have I not explained it well enough?
No sorry … I didn’t read it well enough
I just stumbled across this which you might find interesting ……..
https://studio.plugins.atlassian.com/wiki/display/BUDICT/BuDict+-+manual
It does cost, but it is sort of nice as it allows you to go through specified page automatically and add links to the dictionary.
Wow that does look very comprehensive. I will keep it in mind for next time I do a glossary. There may be some issues using that plugin on a hosted version of Confluence as you need to install a .js file. Also, it will be very interesting to see how this will upgrade to the 4.0 version of Confluence.
This seems to be the best available on the net. Unfortunately I am completely new to Atlassian and despite carefully going through your description above, I did not manage to create a glossary. Could you post a step by step how-to for dummies? Would extremely appreciate. Thanks.
This comment reads like it’s from a spammer, so if it’s not, can you please give some examples as to where you got stuck and I will try to help. Thanks
I very much appreciate your help. As mentioned I am totally new in Confluence, but find it very user-friendly as compared to wikimedia solution. We use confluence at work and now I want to build up a personal knowledgebase on .NET and C# at home as I stard studying it. In order to explain where I got stuck, I will need to put together some screenshots and mail it to you. Thank you again for your prompt reply.
This is exactly what I am looking for but I guess this is for older versions of Confluence. The is Latest 4.1. I am completely new to Confluence and will like to see how to add the User Macro in 4.1. If you can help me with this, it will be of great help.
Unfortunately the User Macro will not work as it is in Confluence 4 as it is dependant on the Multi Excerpt Plugin https://plugins.atlassian.com/plugin/details/169 and that is not (yet) upgraded to support Confluence 4. (There are many plugins that probably will never be upgraded).
So I think this would need a complete re-think from scratch in Confluence 4. If you do work it out, then let us know. If I ever get a chance to play with Confluence 4 I may re-look at this then.
Hello Jodie,
I am curious. Why do you think that many plugins will never be upgraded to support Confluence 4?
Hi Jodie. I just wanted to mention that Multi-Excerpt has been released for Confluence 4 (in case you do re-implement this macro). Also, I’d love to see this macro someday re-implemented for Confluence 4.
@thijs No, I don’t think that ALL plugins will upgrade to Confluence 4, and the fact that more haven’t upgraded yet is a bit worrying. C4 is a brand new paradigm and it will mean a shift in thinking for a lot of plugins. If you look at this list https://plugins.atlassian.com/plugin/masterlist and sort by Version Number Desc, it looks like there are a lot of plugins that are on C4 already. But look a little further, at the big names of plugin vendors such as Customware, Adaptavist, Appfusions etc and see that there are still a few big ones that are not at C4 yet.
Adaptavist has a page here, and it looks like most of theirs are in beta already, which is great. http://www.adaptavist.com/display/Plugins/2011/09/23/Adaptavist+plugins+and+Confluence+4+-+Introducing+our+EAP
.
Customware say Reporting and Scaffolding are coming soon http://www.customware.net/store/confluence/reporting_plugin.html but they are now charged, rather than free by the looks
Appfusions at least seem to have most on C4 at the moment.
However, it’s always the little plugin that you have found that does one critical thing in your site, that will probably stop you from upgrading.
And don’t even get me started on there being NO plugins allowed on Confluence On Demand except for the very few that they deem suitable http://confluence.atlassian.com/display/AOD/Atlassian+OnDemand+Plugin+Policy
Hi Jodie.
We are looking at Confluence 4.3.x, and I’ve been asked whether we can implement a glossary with term-hover functionality you have described here.
I’m simply wondered whether you have been able to get it to work on 4.3.x.
Thank you.
Jay
Hi Jay,
Not as yet, but it is high on my todo list. Someone has tried, following my steps, but they got stuck on the same thing that I got stuck on building this in the first place. I will post an update as soon as it’s done.
Thank you very much, Jodie.
Hi Jodie,
Does this work in Confluence 5?
I’m trying to follow the instructions but must be setting up the macro incorrectly, as the Glossary page displays:
h3. $ParamPhrase {cloak:id=$ParamName} {multi-excerpt:name=$ParamName}{html}$ParamPhrase{html}{multi-excerpt} {cloak} $Body
It also gives me an “{anchor” field to fill in when I edit the macro from within the Glossary page.
Do I need to change the metadata in a certain way to enable this on v5?
Kind regards,
Bashierah
Hi, I haven’t yet had the time to work it out for Confluence 5, but funnily enough, I don’t need to. Just yesterday I found this app on the Atlassian Marketplace that looks like it will do the job. Explainer for Confluence. https://marketplace.atlassian.com/1211100