The Detail Department

You are here: Home / confluence / Building a Glossary in Confluence

Building a Glossary in Confluence

by

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

We call the Glossary Macro on our Glossary Page with the following code entered into the Wiki Markup of the page.
{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}
You end up writing the ToolTip again in the the body, but as both bits of content are stored in the same place, it is easy to update them.
This will display on the page as:

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

This is the macro that allows us to use the Glossary term in the main content of the Confluence site and link back to the Glossary page, as well as show the ToolTip on hover over the link.
The macro text is simply to use the multi-excerpt include macro to show the multi-excerpt text we set up on the Glossary page.
{multi-excerpt-include:pageTitle=Glossary|name=$paramName|nopanel=true}
This will display our Glossary phrase as such:
This is My Glossary Phrase used in a sentence.
  • 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.

Comments

  2. 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

  4. 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.

  5. 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

  6. 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. 🙂

  7. @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 🙁

  8. Hello Jodie,

    I am curious. Why do you think that many plugins will never be upgraded to support Confluence 4?

  9. 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.

  10. 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.

  11. 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.

  12. 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

  13. 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.

  14. 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.

  17. 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?