How to search for macros and macro parameters in Confluence 4

Do you need to find all pages that use a given macro with given parameters and parameter values? For example, do you need to find all pages that use the Excerpt Include macro to include content from a given page? Or all pages that display the children of another page? Or all pages that display a given PDF file?

In a standard Confluence 4 installation, that is not possible because the macro parameters are not indexed. There is a new plugin available that makes the search possible: the Confluence Macro Indexer plugin.

A quick note before we start

Using the standard Confluence functionality, you can already search for occurrences of a given macro (but not its parameters). Enter the following in the Confluence search box, assuming that your macro name is “x”:

macroName: x*

You don’t need a plugin to use the above syntax. For details, see my previous post: How to search Confluence for usage of a macro

What’s new

The Confluence Macro Indexer plugin enhances the Confluence search, so that you can search for specific macros, macro parameters and/or parameter values. With the plugin installed, your Confluence site will allow a new search field name that you can enter into the Confluence search box, followed by a colon, like this:

wikiMarkup:

The plugin is available for Confluence 4.0 and later. I’m using Confluence 4.3.

How to use the macro search

Before you can use the macro search, you or your administrator must install the plugin onto your Confluence site. Installation structions are at the end of this post.

To use the search:

1. Enter 'wikiMarkup:' followed by the macro name and/or parameter, into the Confluence search box at top right of the Confluence screen, or on the standard Confluence search screen.
   For example: To find all occurrences of the Include macro that include a page called ‘Introduction to chocolate’:

   wikiMarkup:"include:Introduction to chocolate"

   There are more examples below.

2. Press Enter or choose Search. The search results will appear as usual.
   

Notes:

• After installing the plugin (see instructions below), you will need to reindex Confluence to ensure that all macros on existing pages are added to the index. See the guide to administering the Confluence content index.
• The field name is case sensitive. You must enter ‘wikiMarkup:‘, not ‘wikimarkup:‘ or any other combination of case.
• The macro names, parameter names and parameter values are not case sensitive.
• You will need to include double quotation marks around the text after the field name, if the text includes special characters such as a colon. For example, enter the following code to find all occurrences of the Include macro that include a page called ‘Introduction’:

  wikiMarkup:"include:Introduction"

• To use the search, you need to know the wiki markup for the macro name, the parameter names, and the accepted parameter values. The Confluence 4.x documentation contains such information for some of the macros. See https://confluence.atlassian.com/display/DOC/Confluence+Wiki+Markup+for+Macros. For the other macros, please refer to the Confluence 3.5 documentation: http://confluence.atlassian.com/display/CONF35/Working+with+Macros.
• The plugin enhances the search only for macros and macro parameters – not for URLs in links or other such items.
• The works for user macros too.

Examples

Find all pages that use a given macro

To find all pages that use the Excerpt Include macro:

wikiMarkup:excerpt-include

It works with quotation marks too:

wikiMarkup:"excerpt-include"

Find all pages that include an excerpt from a given page

To find all occurrences of the Excerpt Include macro that include content from a page called ”Introduction to chocolate’:

wikiMarkup:"excerpt-include:Introduction to chocolate"

Find all pages that include a given page

To find all occurrences of the Include macro that include a page called ‘Introduction to chocolate’:

wikiMarkup:"include:Introduction to chocolate"

Note: In fact, the above search will find the occurrences of the Include macro as well as the Excerpt Include macro.

Find all pages that include any page with a name starting with a given string

To find all occurrences of the Include macro and the Excerpt Include macro that reference any page that has a name starting with ‘Introduction’:

wikiMarkup:"include:Introduction"

Find all pages that display a given PDF file using the View PDF macro

To find all occurrences of the View PDF macro that display the file ‘ChocRecipe.PDF’:

wikiMarkup:"viewpdf:name=chocrecipe.pdf"

Find all pages that display the children of a given page

To find all occurrences of the Children macro that display the children of a page called “Chocolate home”:

wikiMarkup:"children:page=chocolate home"

Find all occurrences of all macros referencing a specific parameter

You can find all macros that have a specific parameter and a specific value assigned to that parameter. For example: If there are two macros, MacroA and MacroB, that have the parameter "page=My page name", then your search will pick up all pages that contain either MacroA or MacroB.

This search query will pick up all Children macros, just like the previous example. It will also pick up any other macros that have the same “page” parameter.

wikiMarkup:"page=chocolate home"

Screenshots

Searching for all occurrences of the Include and Excerpt Include macros that include content from a page called ”Introduction to chocolate’:

Searching for all occurrences of the View PDF macro that displays the file ‘ChocRecipe.PDF’:

How does it work?

In order to understand how to use the enhanced search, it’s useful to know exactly what the plugin does.

The plugin converts the macro code from Confluence 4 storage format to Confluence 3 wiki markup, and then adds the result to the Confluence index, thus making it searchable.

Let’s take the Excerpt Include macro as an example. The plugin takes the following code:

<ac:macroac:name="excerpt-include"><ac:parameter ac:name="nopanel">true</ac:parameter><ac:default-parameter>Introduction to chocolate</ac:default-parameter></ac:macro>

and converts it to this:

{excerpt-include:Introduction to chocolate|nopanel=true}

It then adds the above text to the Confluence index.

How to install the plugin

You can install the plugin via the Confluence plugin manager, just like any other plugin.You need Confluence System Administrator permissions to do this.

If your Confluence site is open to the Internet:

1. In Confluence, choose “Browse” > “Confluence Admin” > “Plugins”.
2. Choose “Install Plugins”.
3. Type “macro indexer” in the search box on the “Install Plugins” tab, and choose “Search”.
4. Click the plugin name “Confluence Macro Indexer” to see the plugin details.
5. Choose “Install”.
6. When the plugin is successfully installed, rebuild the Confluence index to ensure that all macros on existing pages are added to the index. See the guide to administering the Confluence content index.

If your Confluence site cannot access the Internet:

1. Download the plugin JAR from tha Atlassian Marketplace: https://marketplace.atlassian.com/plugins/com.atlassian.confluence.plugins.confluence-macro-indexer-plugin
2. Save the JAR file somewhere on your local computer.
3. In Confluence, choose “Browse” > “Confluence Admin” > “Plugins”.
4. Choose “Install Plugins”.
5. Choose “Upload Plugin”, browse to the saved JAR file, and upload it.
6. When the plugin is successfully installed, rebuild the Confluence index to ensure that all macros on existing pages are added to the index. See the guide to administering the Confluence content index.

The Confluence Macro Indexer plugin installed

Wiki documentation – Splunk on MediaWiki

This week I had the privilege of being given an expert guided tour through a technical documentation site running on MediaWiki. It’s a very cool site. These are the notes I wrote up after the session. I hope you find them useful! It was very interesting for me to have such a detailed look at documentation running on a wiki other than Confluence.

Rachel Perkins walked us through the Splunk product documentation, running on a customised MediaWiki platform. She and the rest of the Splunk documentation team have designed customisations to support their requirements. As well as the tools visible to the general reader on the documentation site, Rachel has added tools that make life easier for the authors on the wiki. In particular, authors can define the product manuals, tables of contents and product versions in text files, with metadata associated with each manual and version. Writers can also branch and inherit documents when a change is required for a specific product release.

Splunk docs home page

First impressions

Here are a few of the things that struck me about the site, even before Rachel walked us through it:

• splunk>docs: What a cool name!
• A very solid, comprehensive documentation site.
• Left-hand navigation bar showing table of contents.
• Feedback form at the bottom of each page, asking “Was this documentation topic useful?“
• Navigation at the bottom of each page, pointing to the start of a section and the next topic.
• PDF export option available on every page.
• Tool at the top allowing you to select the product version and manual that you want.
• Some user comments on the pages, but not very many. (Rachel later explained that they would like to encourage more comments. She wonders if the blue line at the bottom of the page discourages readers from scrolling further down.)
• A separate wiki for general discussion and community input.
• A section called “Hot Wiki Topics” at the top left of the wiki pages.

The walkthrough

Rachel explained that the primary goal in selecting MediaWiki as their platform was to make the documentation as collaborative as possible. This platform made that easy. It is also important that there is a lively community of developers.

The authors value the “live” aspect of the wiki. The content is immediately available, as soon as you save it. At first, authors were a little disconcerted that there was no lengthy publication process. Rachel estimated that it took about two months for them to get over their apprehension. The advantages are that readers always have the latest information, and writers can fix problems at any time. Rachel monitors all updates via RSS feeds, which are a standard feature of MediaWiki.

A page in the Splunk docs

Features:

• PDF exports. All manuals are available as PDF files. Customers can generate them on the fly, for the entire manual. The way it works is that the tool caches the PDF file and serves it up to each reader. It only regenerates the PDF file if there has been a change to the content. This functionality is provided by an open source plugin that Splunk has customised. PDF versions of the manuals are very popular.
• Documentation structure. Splunk have added wiki customisations to support the division of documentation into manuals, chapters and pages. To create the structure, writers edit a text file. One text file defines the list of manuals shown in the dropdown list at the top of the screen. Another text file defines the table of contents of each manual. If you load that page in view mode, you can click through from the table of contents to each page. If the page does not exist, then the tool creates a new shell page and populates it with template content.
• Versions. Similarly, there is a text file to define the versions of the product. Each version has metadata that defines its status, such as released and unreleased.
• Branching and inheritance. What is branching? Let’s assume you need to change a page because the functionality it describes has changed in the latest release. You would then branch the page, so that you leave one branch documenting the earlier version of the product and another branch for the new version. One page can apply to many versions. You can branch a page, a set of pages, a manual or the entire documentation suite. Splunk have created a tool called the “Branch and Inheritance Console”, where you choose the version you are branching from and to, choose the manual or pages that you want to branch, and then complete a number of selection fields to create the branch. There is no awareness of the content itself. So, for example, if you change the content of an earlier version, you may need to apply the same change to the later versions too, and you would have to do that manually. Note that a page may or may not need changing for a particular version. Note from Sarah: This is very neat! Permission control (via MediaWiki’s access groups) is by version. The general public will only see the newest version when you change its status to released. Everyone can see the versions numbers across the top of the page, indicating which version(s) the page applies to. This means that all contributors know which version to edit.
• Context-sensitive online help. This is another wiki customisation, done via tags (labels) on the pages. Each page can have any number of tags, and those tags form a kind of unique help ID for the page. Rachel recommends a minimum of three tags to ensure a unique combination. There is a file that maps the tags and product version on the page to the link from the application screen. This means that writers can move and rename documentation pages without changing the help links in the product. If a help link points to a non-existent mapping, it goes to a default page.
• Search. The search backend is a wiki customisation. They use the Google Mini Search Appliance. Rachel wants to improve aspects of the search, for example it does not recognise word stems. It’s pretty neat, though. It returns results for the version that you are currently in, or for the latest version if none is specified. Splunk uses the same backend for all its sites, not just the documentation. This means that you see search results from various sites, such as the documentation and the wiki, all on one search results page. A very nice feature is the “Search tips” panel that appears at the top of the search results sometimes. Rachel’s team have written a paragraph of tips that matches certain search terms, and will appear in the panel if someone searches for a matching term. People really like this, Rachel says.
• Feedback form. There is a feedback form at the bottom of each page, asking “Was this documentation topic useful?” The resulting feedback is mailed directly to the documentation team. Each team member responds if they have something useful to say. They love getting this feedback. The tool does not use any external service to collect the feedback. Rachel is not sure whether it is part of MediaWiki or a plugin.
• Left-hand navigation bar. This is a customisation, not a standard part of MediaWiki.
• New version of the platform. Rachel and the team are working on a 2.0 version of the platform. It will support multiple products (currently it only supports one) and will have a new look and feel.

Search results showing a custom search tip at the top

Rachel mentioned that she is very happy with the documentation platform. I am very impressed too. 🙂

Splunk is in the process of making the customisations (all except the search) available as an open source project, headed up by Taylor Dondich.  The open source project, not yet publicly available, has a working name of “Ponydocs“. Cute!

Thank you so much for a great walkthrough, Rachel! And congratulations to the Splunk team for this excellent set of documentation.

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.

Search showing "chocolate" only when on page

Searching for “cheese”:

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

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.

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.

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.

Solving a problem with the Confluence Copy Space and Gliffy plugins

Last week I used the Copy Space plugin to create an archive of the Confluence 3.1 documentation, because we’ll be releasing Confluence 3.2 very soon. I ran into a problem when the space copying procedure encountered a fairly old Gliffy diagram. It’s possible that you may hit the same problem next time you use the Confluence Copy Space plugin. Here’s the workaround.

In short: Open the offending diagram in the Gliffy editor and then save it again. There’s no need to make any changes. Start the space copying procedure again. You’ll need to do this for each diagram that triggers the error.

A bit of background

We write and publish our technical documentation on Confluence wiki, and we use wiki spaces as the mechanism for version control. For each major release of the software that we’re documenting, we create a separate space containing the documentation specific to that version. We use the Copy Space plugin to copy the current documentation into a new space. I’ve written more about this procedure in an earlier blog post. (A by the way: Atlassian support does not cover the Copy Space plugin — but we use it.)

We also use another plugin called Gliffy to draw and display awesome diagrams. I’ve written about Gliffy in an earlier blog post too.

So last week I started the Copy Space plugin and hit a problem.

The symptoms

The space copying procedure runs for a while and then stops. The log files show an error message something like this:

…CopySpaceException: An error occurred while copying an attachment…. AttachmentDataStreamSizeMismatchException: Attachment data stream contains a different number of bytes to the declared size of the attachment.

If you have the very latest version of the Copy Space plugin, you will see a nice neat error message on the screen, including a link to the offending diagram:

Solving a problem with Confluence Copy Space and Gliffy plugins

Here’s the text of the above error message:

An error occurred while copying the space. The copy was cancelled.
The content that could not be copied was titled: <Gliffy image name>. link
The attachment’s size property does not match the attachement’s data size: Attachment: <Gliffy image name, version, attachment ID and author’s username>

Unfortunately, earlier versions of the Copy Space plugin don’t give such a useful error.

If you like, you can take a look at the bug report too.

The problem seems to happen for old diagrams only. (I encountered 3 such diagrams when copying the Confluence documentation this week.)

The solution

The workaround is simple: Open the offending diagram in the Gliffy editor and then save it again. There’s no need to make any changes to the diagram. If you have the latest version of the Copy Space plugin (version 1.2) the error even includes a link to the offending Gliffy diagram.

Start the space copying procedure again.

You’ll need to do this for each diagram that triggers the error.

Software versions

I’m using these versions of the software:

• Confluence 3.2-rc1 (release candidate 1)
• Copy Space plugin 1.2
• Gliffy plugin 2.0.2-RC2

Space jumping in a wiki documentation theme

A couple of weeks ago, I wrote about the new Documentation theme for Confluence wiki. There’s a bit I didn’t write about — something we technical writers requested specifically. It’s called “space jumping” and it’s just as awesome as its namesake. 😉

It’s a cold and wet Christmas long weekend, so I’ve decided to write a blog post about wikis instead of venturing outside:

Space jumping lets you link from a page in one wiki space to a page with the same name in another space, without knowing the name of the page when you create the link. It’s done via the {spacejump} macro that is part of the new Documentation theme.

Why would you need to space jump?

Apart from the sheer thrill of it, you mean? 😉

We use it to put a standard message at the top of our archive spaces, telling people that they’re reading an old version of the documentation and letting them jump quickly to the same page in the latest documentation.

The result looks like this:

Here it is again, in text instead of an image:

This documentation relates to an earlier version of Crowd.
View this page in the current documentation or visit the current documentation home.

And here’s the full screen (click the image to expand it):

If someone clicks the link on “View this page in the current documentation”, they are taken to the latest version of the page:

Here’s a link to the archive page in our documentation, so you can see the space jump in action.

How did we do that?

We’ve put the {spacejump} macro into the theme configuration. Here’s what our wiki markup looks like:

{note:icon=false}*This documentation relates to an earlier version of Crowd.*
View {spacejump:CROWD|alias=this page in the current documentation} or visit the [current documentation home|CROWD:].{note}

The format of the macro is:

{spacejump:SPACEKEY|alias=TEXT}

The ‘SPACEKEY’ parameter is required. Replace ‘SPACEKEY’ with the key of the space you want to jump to.

The ‘alias=TEXT’ parameter is optional. If you use it, replace ‘TEXT’ with the text you want hyperlinked. If you omit the parameter, Confluence will display the page name.

The macro is part of the Documentation theme, so if you have installed the theme then you can use the macro. We’ve used it in the theme configuration, but you can also use the macro on a normal wiki page.

Here’s a screenshot showing our full theme configuration for the archive space (click the image to expand it):

What happens if the page does not exist in the target space?

For the space jump to work, the target space must contain a page with the same name as the page that renders the {spacejump} macro. If the target space does not contain such a page, you will see a broken link. Confluence handles this in its usual manner: the link is coloured red, and if you click it then Confluence offers to create the page for you.

In our particular use case a missing page is not very likely, because we seldom delete pages and our link points to the latest documentation space.

There’s probably a better way of handling unmatched pages. Maybe this is a chance for someone to raise an improvement request in the issue tracker for Jens’s Documentation theme! 😉