Blog Archives

Confluence tip – how to hide child pages in the Documentation theme

This hint is for people who are using the Documentation theme in Confluence wiki, and want to hide the child pages that are shown at the bottom of every page. After all, the left-hand navigation bar in  the Documentation theme shows a page tree, including all parent and child pages. So it’s probably overkill to show the children at the bottom of every page too.

Confluence tip - how to hide child pages

To hide the child pages, add some CSS to the space. This is the CSS you need:

#children-section{   
display:none;   
}

I’ve tested the above CSS in Confluence 4.3 and 5.0.

To add the CSS to your space, you need space administrator permissions. Go to BrowseSpace AdminStylesheet, edit the stylesheet and dump the above code into the text box.

The documentation has more guidelines on using custom stylesheets: Styling Confluence with CSS.

Have fun!

The Confluence, Tech Comm, Chocolate wiki has moved to a shiny new site

The Confluence, Tech Comm, Chocolate wiki is a companion to my book about technical communication, technical writers, wikis and chocolate. This week we moved the site to a shiny new Confluence OnDemand server. Please take a look, sign up if you like, and also please consider changing any external links you may have pointing to content on the site.

The new address of the Confluence, Tech Comm, Chocolate wiki is: https://wikitechcomm.atlassian.net/

The old address was: https://wikitechcomm.onconfluence.com/

What does the move to Confluence OnDemand mean?

Confluence, Tech Comm, ChocolateConfluence OnDemand is Atlassian’s new hosted platform. Our site will now automatically get the latest and up-to-datest version of Confluence. It’s currently running an early version of Confluence 5.0! So we’ll be able to play with the latest Confluence features before anyone else. If you’re interested, keep a watch on the frequently-updated Atlassian OnDemand release summary.

My seat-of-the-pants feeling is that the new site is significantly faster than the old one. 🙂

The hosted platform restricts certain functionality, primarily add-ons and customisations of the wiki. I won’t be able to install add-ons or plugins that are not pre-approved by Atlassian. This won’t have a big effect on people using the site. We no longer have the awesome add-ons from K15t Software for creation of ePub and DocBook exports. The Copy Space plugin isn’t there either. Gliffy, for drawing diagrams, is available in Confluence OnDemand, along with the add-ons listed here: Atlassian OnDemand Plugin Policy.

Existing content, redirects, and external links pointing to the site

This bit is for the 77 people already using the wiki. 🙂 All your pages, blog posts, comments and other pieces of information are safely on the new site. Please let me know if you spot anything amiss.

Atlassian has put redirects in place. If you try to go to the old address, you should automatically end up on the new site. The old site will be decommissioned in a few weeks’ time. There’s no scheduled date for the shutting down of the redirect service, but it’s probably a good idea to update any external links you may have, to point to the new site.

The book

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s about developing documentation on a wiki. It’s also about technical communicators. And chocolate.

Do come and join the fun at the book’s wiki site: Confluence, Tech Comm, Chocolate wiki.

How to change the username for all pages in a Confluence space

Sometimes you may want to do a bulk update of the usernames on all pages in a Confluence space, to change the creator of all the pages. This may be necessary if someone leaves the company, for example, and for some reason you need to change the “owner” of all pages. Or perhaps you have changed your name, and want the pages to be registered in your new username. There isn’t an easy way of changing a username in Confluence. This post describes a partial solution to the problem, with some caveats.

There isn’t any easy way of changing usernames in Confluence. (See the feature request.) The current process involves some heavy database manipulation, as described in the documentation: Changing Usernames.

A partial solution for changing the creator of all pages in a space

This is an alternative solution that may be useful under specific conditions – see the caveats below. You can install the Copy Space plugin and use it to copy the space to a new space. Untick the option called “Use existing authors and dates”.

Copying a space

This will copy your space to a new space, with a new space key. The author of all the pages will be the person who copied the space.

Please note the following caveats:

  • All links coming into the space from outside will be broken, because the new space has a new space key. This affects URLs that use the space key and page name, including links from outside the wiki and from other Confluence spaces on the same wiki. However, you can get round this by deleting the original space, then copying the new space a second time and specifying the original space key.
  • All links that use tiny links (permalinks) will be broken, because every page gets a new tiny link in the new space. Every page gets a new identifier too.
  • The Copy Space plugin copies only pages, with their attachments and comments. It does not copy blog posts or mail archives.
  • You will lose all page history. The plugin copies only the latest version of each page.
  • This solution changes the creator of every page in the space, not just those added by a given username.

In other words, the above method may be useful if the above points are not a drawback in your situation.

It’s definitely worth testing the solution in a test environment and assessing the results before using it for real.

Content re-use and automated publishing via Confluence Command Line Interface

This post is about the Confluence Command Line Interface, a tool developed by Bob Swift, and the way we’ve used it to solve a tricky requirement. We needed to copy a large amount of existing documentation for a number of products, and make that documentation available to a specific set of customers. We needed only part of the existing documentation for each product, and we needed to copy it regularly and repeatedly after major or minor updates. A prime candidate for content re-use and automation.

Our target audience is the customers who use our ‘OnDemand’ line of products: pre-installed and configured sites in the cloud. Therefore, large parts of the documentation for each product are applicable to these customers, but a small proportion of the documentation is irrelevant to them. For example, they don’t need to know how to install the product, and some of the configuration options are not available to them. This means that we needed conditional publishing as well as content re-use. We have used the Confluence Command Line Interface (CLI) to craft a solution. This is a specific use case, but I think the CLI is an excellent tool with wide application. So I’m writing to let you know about it. 🙂

The past

Until last week, our OnDemand documentation space contained just the introductions and overviews for people using the cloud-based products. For the product-specific documentation, we gave people a set of links to click, which sent them to the full set of documentation for each product.

When people went to the JIRA OnDemand user’s guide, for example, they would click a link and find themselves in the full JIRA documentation. They clicked happily around, searched with enthusiasm, and started reading about features that are not relevant to OnDemand sites.

The present

The OnDemand space now includes copies of all relevant pages from the Confluence, JIRA, Bamboo, FishEye and Crucible spaces. Pages that are irrelevant (such as the installation and plugin guides) are not included.

How did we do it? We used Bob Swift’s Confluence CLI to push the required pages to the OnDemand space. The CLI is a command line client that you run from your own computer. Just unzip it, give it the address of the Confluence server and a username/password to work with, and Bob’s your uncle. (wink) It uses Confluence’s remote API to access and update the data. One of the things that the CLI can do is copy pages from one space to another. If the page does not exist in the destination space, the CLI will add it. If it does exist, the CLI will update the page by adding a new version of the page. Upon request, the CLI will handle attachments in a similarly sensible way.

We have a number of batch files, one for each product, each containing a list of commands that copy all the relevant pages from the product documentation space to the OnDemand space. We built the batch files by hand, from our knowledge of the pages that are applicable to the OnDemand customers.

The future

In the medium term, we will continue using the CLI solution to update the OnDemand docs. For each product release, we will:

  • Update the CLI commands as required, adding new pages that need to be copied and occasionally removing pages that we don’t need any more. Note: We can leave all the pages in the list, whether they’ve been updated for the new release or not.
  • Run the CLI batch file when the new release has been published in the product documentation space. This will copy across all the updated pages for the new release into the OnDemand space.

We’ll also use the CLI solution to update the OnDemand pages at random times, when we’ve made valuable changes to the product docs during routine maintenance or in response to requests from customers or support.

More conditional publishing coming soon. The CLI allows us to pick and choose the pages that we copy to the OnDemand documentation space, simply by including or excluding the page from the CLI batch file. But there are times when just part of a page needs to be different in the OnDemand documentation and the product documentation. We’ll do that via inclusions. For example, this set of navigation instructions is re-used in a number of pages: Navigating to the Administration Console. We’ll be able to have different instructions in the OnDemand space and the Confluence space, to reflect the fact that the navigation menus are slightly different in the cloud-based products.

You can already see some examples of this method of conditional publishing via inclusions. For example, the Confluence documentation has a re-usable page about prerequisites for the Confluence Office Connector. The OnDemand page is shorter than the full product page, because some of the configuration is done automatically for OnDemand sites.

And soon after that… This new solution also puts us in a good place for the implementation of the Scroll Versions plugin, which will bring us more conditional publishing features as well as sophisticated version control. While implementing the CLI solution, we’ve learned a lot about the effects of having duplicate page content in two spaces, and figured out how to find duplicate page names across spaces. We’ve formulated our content re-use strategy, and made design decisions such as changing the search function so that it displays results from a single space only. We’ve also learned more about our content, which has to be a good thing!

References

An earlier post introduces the Confluence Command Line Interface and how to use it: Confluence CLI for bulk actions like deleting or publishing pages.

The CLI documentation includes some useful examples and a list of all the available actions and parameters.

The batch files for our CLI solution are on Bitbucket: AOD CLI.

We make frequent use of the Include Page macro for content re-use, by including the content of one page into another. This dovetails neatly with our new CLI solution. I’ll write a more detailed post about this some time.

Thank you to Bob Swift for the awesome Confluence CLI! And kudos to our technical writers, who have undertaken a gleeful transmogrification into the Tech writing AOD bot.

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

%d bloggers like this: