Search and Replace Confluence Plugin

Installation

Visit the Confluence Plugin Repository in your Confluence installation and search for “Search and replace” in the plugin manager. If you have installed a compatible version of confluence, the plugin should appear in the result list. Follow the steps on the screen to install the plugin.

Usage

After a successful installation a menu entry “Search and replace” appears in the left section of your admin page. When you follow the link, the following page will appear:

Searching & Replacing Plain Text

Go to the first tap “Search and Replace”. Now select the scope you want the string to be replaced in. It is recommended to test your replacements on a single page first before you apply it to a bigger scope. 

The next step is to enter the string you want to search for. Be aware that the search and replace is applied to the plain storage format. So the search results may be different from what you get when you search Confluence via the normal search. In addition to this, be aware that some characters are encoded. So, for example, the umlaut ‘ü’ is encoded as ‘ü’. You have to match your search queries and replace texts to these characters.

With a click on ‘Occurrences’, a search for the selected parameters is started. The result is shown in the lower section of the page.

Note: Search processes can take some time or even time out your connection depending on the number of pages in the scope. The plugin was tested up to several hundred pages and performed quite well (Search in “Demonstration Space”, 40 pages, <1s).

Searching & Replacing Macro Parameters 

This lets your search for specific macros and their parameters in different scopes. Make sure to test your replaces on a single page first.

Since version 1.5,  user macros are officially supported.

The functionality is best explained by a common example:

Imagine the “content by label” macro is used in several pages of a space with the same labels as search query. Now you want to add a label to these existing macros.

First you select the “Search and Replace Macro” tab.

Second, select the scope “space”. Now enter the space you want the replacements to happen via the auto completer. Then type “contentbylabel” into the “Macro name” field. You can already perform a search which lists you the occurrences of the macro.

Next, enter the parameter name, in our case “labels”. If you are not sure about the parameters, look at the documentation of the macro, the search results of this plugin or the storage format of the page containing it.

If you want to replace only parameters where the old value matches a specific value, you can specify the “old value” parameter. In our case, we would put the old labels in this field.

Notice that replacing typed parameters such as pages and spaces are not yet supported.

Next run a search again by pressing “Occurrences” to make sure the right macros are selected. Enter the new labels in the “New Value” field separated by commas or spaces and press “Replace all”.

You can validate the successful replace by running a search again or taking a look at the modified pages.

Searching & Replacing Macros

This lets you delete a macro in a scope selected by you. In addition you can specify a text which should be inserted instead of the macro. An example would be if you are using a macro in several locations of your space and it is not supported any more.

First enter the Macro name and the scope you want the replacement to happen in. Next, specify the text you want to appear instead of the macro. You can leave this empty if you want. Again, take care of encoding the special characters.

Since version 1.5, replacing and deleting user macros is officially supported.

‘Occurrences’ again lists the macros that are going to be replaced.

You can also replace a macro by an other macro. You just have to insert the new macro with all it’s parameters in storage format as replacement text. To get the storage format of a macro, look at it’s documentation or insert it into a page and click at ‘view storage format’  in the page actions.

When you set the check box ""

Search and Replace with Regex

Since version 1.5, searching and replacing with regular expressions is supported. To use this feature, navigate to the "Search and Replace Regex" tab under the admin section "Search and replace". You can now search with regular expressions. For a guide on how to use regular expressions, see www.regexe.com or  regexr.com. 

Examples

Input regex: "\bword\b"
Input replacement:  "banana"
 
Sample page content:
"Replace every word that matches with another word."
 
Result:
"Replace every banana that matches with another banana."

Input regex: "<a href='https://rumpelcoders.atlassian.net/'>(.*?)</a>"
Input replacement:  "<b>$1</b>"
 
Sample page content:
"Somewhere in the text is a <a href='https://rumpelcoders.atlassian.net/'>link</a>"
 
Result:
"Somewhere in the text is a <b>link</b>"

In this example, the group (.*?) is referenced with $1 in the output text.

Input regex: "(John) (Doe)"
Input replacement:  "$2 $1"
 
Sample page content:
"Somewhere John is mentioned on his own, this is ignored, but not John Doe."
 
Result:
"Somewhere John is mentioned on his own, this is ignored, but not Doe John."

Input regex: "\b(\d{2})\.(\d{2})\.(\d{4})\b"
Input replacement:  "$2/$1/$3"
 
Sample page content:
"This page was created on 22.01.2016."
 
Result:
"This page was created on 01/22/2016."

Search and Replace for Space Admins

Since version 1.6, the search and replace functionality can be enabled for space admin too. By default this settings is disabled, but you can activate it in the settings panel (as seen in the picture below). You can define, which options are enabled for the space admins. Keep in mind that this will be seen from each space admin.

If you activate one of this settings, each space admin is able to use this functionality inside his spaces. Global search and replace will be only available for admins. The space admins will find the search and replace in the space settings (see pictures below).