How to search Confluence for usage of a macro
Do you need to find all pages on your Confluence site that use a given macro? You can do it via the Confluence search. Here’s how, in Confluence 4.0 and Confluence 3.5.
Confluence 4.0
Enter the following in the Confluence search box, assuming that your macro name is “x”:
macroName: x*
For example, let’s say that you want to search for all “include” macros:
macroName: include*
Or let’s say that you want to search for all “excerpt-include” macros:
macroName: excerpt-include*
Notes:
- The key word is case sensitive. It must be “macroName”, and not “macroname” or any other variation.
- There is a space between the colon and the macro name.
- The macro name (x, include, excerpt-include, and so on) is the value that you supply in wiki markup. (It is the name of the macro as defined in the “atlassian-plugin.xml” file.)
- The asterisk at the end of the macro name is required, to ensure that the search picks up all references. (Evidently the reason for this is that the value in the query is stemmed, but the value in the Lucene index is not stemmed. The asterisk will prevent the stemmer from kicking in.)
Searching for a macro in Confluence 4.0
Confluence 3.5
In Confluence 3.5, you can enter the curly brackets and the macro name surrounded by double quotation marks, like this:
“{excerpt-include”
Or this:
“{children”
Or even this, to find all occurrences of the include macro that include a given page:
“{include:my page name”
The trouble is that this will pick up all occurrences of the search term, both with and without the curly brackets.
As an alternative, try this plugin, which provides a user interface for a Confluence 3.5 macro search: The Macro Usage plugin. It is not (yet) compatible with Confluence 4.
Thank you
Thank you to Daniel Kjellin, the Confluence developer who wrote the Confluence 4.0 macro usage search, and who told me all about it! I just discovered it today. I hope you find it useful too.
Update on 4 September 2012
There’s a new plugin available that makes it possible to search for macro parameters as well as macro names. See this post: How to search for macros and macro parameters in Confluence 4.
Posted on 4 November 2011, in Confluence, technical writing, wiki and tagged Confluence, Confluence 4.0, f, macro search, technical documentation, technical writing, wiki. Bookmark the permalink. 15 Comments.
ffeathers 
A note: It is not possible to search for macro parameters. This means, for example, that you cannot discover where a particular excerpt or page is included into another page.
Cheers, Sarah
Thanks for this. I didn’t know about it before and have already used it a couple of times in the last few weeks.
Thanks Gareth, I’m so glad it’s useful!
Cheers, Sarah
Sarah – after nagging my company for months – we finally moved up to Confluence 4.1 – at which point my entire landing page – which is a thing of beauty – disintegrated because the adapativist content formatting macros are not supported. I am soooo sad. Do you have any suggestions? If you email me privately – I can show you how lovely my landing page is and maybe you can point me to something in 4.1 that is supported? Looking forward to hearing from you!
This is an open source site that I based my landing page on. http://www.gigaspaces.com/wiki/display/XAP66/6.6+Documentation+Home
Hallo mumpy
That page is indeed a thing of beauty. I wonder when Adaptavist is planning to update their macros for Confluence 4. It may be worth dropping them a line.
You should be able to achieve a similar effect using the core Confluence macros and a bit of CSS.
To get the three main columns, use a section and 3 column macros.
To get the search and pagetree in the left/hand column, use the pagetree macro. It includes the search by default, but you can turn that off and use a separate pagetree-search macro if you prefer.
To get the pretty icons and text lined up, use a table within the middle column macro. Put the table inside a panel, And define the colours for the panel as you need them. The one trick is to get rid of the table borders. Here’s where the CSS comes in. By default, Confluence includes borders around tables. But when using the Documentation theme, a table inside a panel does not have borders. I’m guessing you don’t want to use the Documentation theme, otherwise you wouldn’t need the pagetree. So, if not using the doc theme, you would need to copy the relevant CSS for tables inside panels, and add it to your space.
Let me know if you have any luck with this solution. If it looks promising, I can do some research and find the CSS for tables within panels.
Instead of tables, maybe just left-aligning the images inside the panels would work. That makes the text appear on the right of the image. See my earlier post about how to wrap text around images in Confluence 4.
Let me know how it works. 🙂
Cheers, Sarah
Okay – in order for this to work – I would need the CSS for tables within panels (how much research is this for you?).
I tried the left-aligning thing and I couldn’t see how to do it coz there is no wiki markup!! I miss wiki markup!!
OK – now that I’ve realized that I”m an idiot and I can insert the wiki markup myself – let me play around a bit and get back to you!!
I’ve tried the macroName search in Confluence 4.3.6 (our upgrade target) to collect macro/plugin usage stats. However, we’ve discovered that the search doesn’t return all instances of the macro. In one case we’ve disabled a plugin based on the results only to have a test user on our stage host point out that their “run” plugin macros are no longer working. We’ve reindexed several times but can’t figure out why “macroName: run*” is returning an incomplete list. Has anyone else observed this behavior?
Hallo Tom
It could be that the search index on your Confluence site is not up to date. Try requesting a manual re-index of the site, then do the search again.
Cheers, Sarah
Hello Sarah,
is it possible that this search doesn’t work for all Macro?
I tried to search like this ” macroName: Link in New Window* ” and ” macroName: Include Page* ” but I didn’t get any results.
I use confluence 4.3.2 .
Thanks in advance
Jan
Hallo Jan
The macro name must be the code name of the macro. So, for the Include Page macro, it’s just “MacroName: include*”. I don’t know the macro you’re using for opening a link in a new window. I’m guessing it’s supplied by a plugin. To find the name of the macro, look at the source code of the page. For the macros that are bundled with Confluence, I’ve started documenting the code for the macro names and parameters for each macro. See the “code samples” on each page. I haven’t finished them all yet!
I hope this helps!
Cheers, Sarah
Hallo all
If the Confluence search fails you, you could try this solution that I’ve just blogged about: Confluence full-text search using Python and grep:
Cheers
Sarah
Hi,
This is so useful – thank you! Can you tell me if it’s possible to search for pages that contain images? I have this requirement for turnover to the translation team.
Thanks,
Giri
Pingback: How to search for macros and macro parameters in Confluence 4 « ffeathers