Making the include macro’s content appear in the Confluence search results

Confluence wiki provides two macros that you can use to embed content from one page onto another page: {include} and {excerpt-include}. Technical writers find these macros very handy for content reuse. Write the words once, put them somewhere sensible, and then reuse them in a number of different places. Confluence will dynamically copying the content into the page at display time. The trouble is that the Confluence search results pick up the content where it’s originally written, but not where it’s displayed. Or that’s what I thought until now!

Today I learned that you can make the content of the {include} and {excerpt-include} macros appear in the search results for the page where that content is displayed. Magic!

It would be nice if Confluence itself would offer the option to include the macro contents in the search results. If you agree, please comment on or vote for the improvement request: CONF-19054

In the meantime, there’s a workaround. A big thank you to Emily Johnson and David Peterson for finding and sharing this solution, and to Bob Swift for the Cache plugin for Confluence!

The solution in a nutshell

Install the Cache plugin for Confluence. Then wrap your include macros with the {cache} macro, using the “index=true” parameter to make the content of the include macros searchable.

{cache:index=true}
{include:mySPACEKEY:My page name}
{cache}

More about the Cache plugin

Bob Swift develops and maintains the Cache plugin for Confluence. He also provides the support for the plugin.

What does the plugin do? It’s principal function is to allow you to cache part of the page, especially if the content is derived from an external source. This could significantly improve the loading time of the page. You can configure the length of time that Confluence waits before updating the cached content.

For our purposes, one particular option in the Cache plugin is useful: the “index=true” parameter. There are many macros that you can use to display external content on a Confluence page. The {include} and {excerpt-include} macros are two examples. Even though the content appears on a Confluence page, the content will not be included in the Confluence search results, since it is not included in the wiki markup of the page and is therefore not included in the search index. The {cache} macro with parameter “index=true” will ensure that the content is indexed and therefore appears in the search results. See the plugin documentation.

Installing the Cache plugin

The easiest way to install the plugin is using the Confluence plugin manager:

  1. Go to your Confluence Administration Console by clicking “Browse” > “Confluence Admin”.
  2. Click “Plugins” in the left-hand menu.
  3. Click the “Install” tab.
  4. Select “All Available” in the “Plugins to show” dropdown list.
  5. Find the “Cache Plugin” in the list of plugins and click the plugin name. A panel will open up, showing the plugin description.
  6. Click “Install Now”.

If for some reason you can’t use the Confluence plugin manager, then you can download the plugin and install it manually:

  1. Go to the Cache plugin’s page on the Atlassian Plugin Exchange.
  2. Download the plugin JAR file. It has a name something like “cache-plugin-4.1.0.jar”. (The version number will probably change over time.) Save the JAR file on your local computer.
  3. Go to your Confluence Administration Console.
  4. Click “Plugins” in the left-hand menu.
  5. Click the “Install” tab.
  6. Click “Upload Plugin”.
  7. Browse to find the JAR file that you saved, and then click “Upload” to upload it into Confluence.

Let’s try it out

Let’s see what happens when we search for the terms “chocolate” and “cheese”, where those terms are included via the include macros. First we’ll do it without the {cache} macro, then we’ll add the {cache} macro and try the search again.

Example of search results without the Cache macro

First I created some pages.

1. A page called “Favourite food”

This page is in the “CHUNKS” space. The entire content of this page will be embedded into another page later.

Wiki markup:

{cheese}
I like chocolate too.

Displayed content:

I like cheese!

I like chocolate too.

The {cheese} macro is a bit of fun. It’s a real macro, shipped with Confluence. All it does is generate the words “I like cheese!”🙂

2. A page called “Partial content reuse”:

This page is in the “Demonstration (DS)” space.  The excerpt defined on this page will be embedded into another page later.

Wiki markup:

This page has an excerpt defined on it.
{excerpt}I'm partial to chocolate.{excerpt}

Displayed content:

This page has an excerpt defined on it.

I’m partial to chocolate.

3. A page called “Include food page from another space”:

This page is in the “Demonstration (DS)” space.  This page will include the entire content from the “Favourite food” page (page 1).

Wiki markup:

*Tell me about your favourite foods.*
{include:CHUNKS:Favourite food}

Displayed content:

Tell me about your favourite foods.

I like cheese!

I like chocolate too.

4. A page called “Include excerpt from another page”:

This page is in the “Demonstration (DS)” space.  This page will include just the excerpt defined on another page (page 2).

Wiki markup:

*What do you really really like?*
{excerpt-include:Partial content reuse|nopanel=true}

Displayed content:

What do you really really like?

I’m partial to chocolate.

5. A page called “This page has chocolate in the title”:

I created this page just to test that the search is working.

Searching for “chocolate”:

I’ve restricted the search to the “Demonstration Space”. We have not yet added the {cache} macro to any of our pages. As expected, the Confluence search shows only those pages that include the word “chocolate” in the title, page content, attachments or labels. It does not pick up any pages where the word “chocolate” is displayed as a result of an include macro.

Making the include macro's content appear the Confluence search results

Search showing "chocolate" only when on page

Searching for “cheese”:

Similarly, the search does not pick up the word “cheese” at all.

Making the include macro's content appear the Confluence search results

Search does not pick up the word "cheese" at all

Example of search results after adding the Cache macro

Next I added the {cache} macro to the two pages that contain include macros. Let the magic begin.

Adding the {cache} macro to the page called “Include food page from another space”:

Wiki markup:

*Tell me about your favourite foods.*
{cache:index=true}
{include:CHUNKS:Favourite food}
{cache}

The displayed content of the page remains the same as before.

Adding the {cache} macro to the page called “Include excerpt from another page”:

Wiki markup:

*What do you really really like?*
{cache:index=true}
{excerpt-include:Partial content reuse|nopanel=true}
{cache}

Again, the displayed content of the page is unchanged.

Now let’s try searching for “chocolate”:

The Confluence search results now show the pages where the word “chocolate” is displayed as a result of an include macro.

Making the include macro's content appear the Confluence search results

The Confluence search picks up "chocolate" from the content of the include macros

Searching for “cheese”:

Yaayyy, the search picks up the word “cheese” too.

Making the include macro's content appear the Confluence search results

The Confluence search picks up "cheese" from the {cheese} macro inside an {include} macro

Doubly magic

That’s right! The Confluence search picks up the word “cheese” that was generated by the {cheese} macro embedded inside an {include} macro!

Update on 18 May 2011: I’ve just heard that the use of the {cache} macro means that the inclusion will ignore any page restrictions that you may have added to the included page. I haven’t tested this myself, and it’s unlikely that you’d want to include a page that has restrictions. But there are some applicable use cases, so please be aware of this possibility.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 15 May 2011, in Confluence, technical writing, wiki and tagged , , , , , , , , , , . Bookmark the permalink. 6 Comments.

  1. Giles Gaskell

    Thank you so much for writing this post Sarah!

    A big thanks also for Emily, David and Bob!

    At last – a solution to this lingering Confluence search issue!

  2. This an awesome write-up and yet another great plugin idea by Bob.

    How about wrapping the cache&include-macro combo in a user macro? As you haven’t mentioned this, is there a reason for not doing that?

    -Stefan

  3. one small glitch with this approach:

    from the documentation:
    “{excerpt} – if the excerpt is defined within a cache, you will not be able to retrieve it’s contents using the {excerpt-include} macro.”

    I use the excerpt macro extensively, and I was hoping to be able to just put the Cache at the top and bottom of my page, to cache and search on the entire contents (using the user macro idea as above, which I have already created to include my pages), so I will just have to see how it goes.

    • Hallo Jodie

      Hmm, interesting. In recent times (the last couple of years), we’ve steered away from defining excerpts in a page that contains other content, just because it makes the excerpts more difficult to see and manage. Instead, we put each excerpt into a separate page in our “inclusions library”. That makes it more obvious to all authors, including our community authors, that the excerpt is potentially reused across a number of pages. So I guess we wouldn’t run into this problem.

      Thanks for pointing this out. Please let me know how it goes!

      Cheers, Sarah

      • Yes — I think I have the same issue as you, Jodie. I use the excerpt-include macro extensively, in coordination with an Inclusions Library. But, putting this cache macro around the {excerpt-include} content means that the content is never again updated on that page! This means that this solution is useless to me.

        I understand what you mean Sarah about only using {include}. However, this really isn’t possible at my company, where we are trying to coordinate the efforts of several writers. We use the other parts of these “excerpt master pages” (as I call them) to keep a record of all the pages pulling the excerpt, so that we know which pages to check when we update the information.

        Any other suggestions of a fix for this?! Any help appreciated –Arwen

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: