The Detail Department

  • Our Services
    • Strategy
    • Analysis
    • Implementation
    • Training
  • Applications
    • Salesforce
    • Confluence
    • WordPress
    • Other Apps
  • About Us
    • Jodie Miners
    • Projects
    • Privacy Policy
  • Blog

© The Detail Department Pty Ltd 2016

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

Building a Glossary in Confluence

13-Aug-2011 by Jodie Miners

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.

Share this:

  • Click to share on Twitter (Opens in new window)
  • Click to share on LinkedIn (Opens in new window)
  • More
  • Click to print (Opens in new window)

Filed Under: confluence, Work

Jodie Miners

Jodie Miners is the Director of The Detail Department. She can help your business move from vision to reality with the right systems for your business.
Her eye for detail and her understanding of the ‘bigger picture’ will create and integrate seamless business systems. Read More about Jodie…

View My Blog Posts

Comments

  1. Jay Abramoff says

    22-Oct-2012 at 3:25 PM

    Thank you very much, Jodie.

  2. Jodie Miners says

    22-Oct-2012 at 10:58 AM

    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.

  3. Jay Abramoff says

    21-Oct-2012 at 8:16 PM

    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

  4. Will L says

    18-Apr-2012 at 7:59 AM

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

  5. Jodie Miners says

    18-Jan-2012 at 8:02 AM

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

  6. Thijs van Putten says

    18-Jan-2012 at 1:21 AM

    Hello Jodie,

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

  7. Jodie Miners says

    17-Jan-2012 at 2:46 PM

    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.

  8. Siddharth says

    17-Jan-2012 at 2:02 PM

    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.

  9. Giuseppe says

    4-Jan-2012 at 9:20 PM

    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.

  10. Jodie Miners says

    4-Jan-2012 at 5:02 PM

    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

  11. Giuseppe says

    4-Jan-2012 at 8:57 AM

    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.

  12. Jodie Miners says

    22-Aug-2011 at 4:12 PM

    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.

  13. Michael Roff says

    22-Aug-2011 at 3:42 PM

    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.

  14. Jodie Miners says

    19-Aug-2011 at 3:23 PM

    Having the glossary in the tooltip is exactly what my Macros do. Have I not explained it well enough?

  15. Michael Roff says

    19-Aug-2011 at 2:49 PM

    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?

Search this Website

Subscribe to Blog Posts

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Latest Posts

Advice for Salesforce Career Progression

So, you want to learn Salesforce?

Your Business Needs More Than Just a Website

Q and A: Apps for Service Delivery

Using Wufoo Forms with Salesforce

Integrations are The New Black

We need to talk about Documentation

Tools to help write help documents

Moving away from Command and Control

My ultimate guide to getting started with Gmail