DocBook export and import round trip with Confluence wiki

This is exciting news for technical communicators. We can export content from Confluence wiki to DocBook and then import it back into Confluence. I’ve just tried it using the Scroll Wiki DocBook Exporter and the RedHat DocBook Import for Confluence.

As you may already know, I’ve written a book. 😉 The book is about Confluence, and the content is on a Confluence site. So I decided to try exporting the book to DocBook XML and then importing it back into a different Confluence space.

In summary:

• I’m running Confluence wiki, version 3.5.3.  (The DocBook Import plugin does not yet support Confluence 4.)
• I used version 2.0.2 of the Scroll Wiki DocBook Exporter, a Confluence plugin from K15t Software, to export the content of my book to DocBook XML.
• Without making any changes to the XML, I used version 1.1.1 of RedHat’s DocBook Import for Confluence to import the content back into Confluence, in a new space that I had created for this purpose.
• There were a few hiccups, but basically it worked well.

A friendly word of warning: The DocBook Import plugin is unsupported. It was originally created for the JBoss Community Project Documentation Editor, and the developers decided to make it publicly available, free of charge. You can read about the plugin and ask questions on the JBoss Community site.

Exporting the content to DocBook XML

I used the Scroll Wiki DocBook Exporter, a Confluence plugin from K15t Software, to export the content of my book to DocBook XML. My earlier post gives quite a bit of detail on how to use the plugin: Writing a book with DocBook and a Confluence wiki. This screenshot shows the settings I used to export the pages from Confluence:

Exporting from Confluence to DocBook XML

A note: I had to use the template called “Book using preface and chapters“. When I chose the template “Book using preface, parts and appendix“, the import pulled in only the home page and the appendices. The explanation lies somewhere in the DocBook formatting, but I don’t know the details.

Importing the XML back into Confluence

I installed RedHat’s DocBook Import for Confluence plugin onto my Confluence site. Then I added a new space in Confluence, and went to the home page of that new space. The plugin adds an option to the “Tools” menu called “JBoss DocBook Importer“:

DocBook import option in Confluence Tools menu

Clicking that option invokes the importer configuration page:

DocBook Import configuration page

As we who know and love Confluence are aware, you cannot have two pages with the same name in a Confluence space. The DocBook Importer accepts a prefix that it will use to resolve such conflicts. But on my first attempt, I did not give it any prefix. I knew that all the page titles in my book were unique, so I thought the import would be good. It turned out that there was a duplicate page title, because I had used a heading level 1 to highlight the book title, and had given the page the same name as the title.

The importer gave me an error message, and I supplied a rather unimaginative prefix “123”.

Message requesting prefix to resolve duplicate page names

This time everything went smoothly. In the following screenshot, you can see the success reported by the importer on the right, and the newly-created table of contents in the left-hand panel:

Import successful

Results

Success!

• All the pages are there, with all content present.
• The images are all present.
• Tables are correctly formatted. My content includes only simple tables.
• List formatting looks good.
• Bold and italic formatting are good.
• Links are good.

One of the book's illustrations by Ryan Maddox

The above screenshot shows one of the illustrations in the book, created by Ryan Maddox and reproduced here with his permission.

A few hiccups

Some things will need fixing, either manually after each import or perhaps in a future version of the importer plugin:

• The images are larger than on the original pages.
• URLs printed on the page have acquired URL encoding rather than retaining the human-readable form.
• The Scroll Wiki DocBook Exporter plugin allows you to add information for a book index and footnotes, via special macros. The reimported pages print the content of the index or footnote entry on the page itself. For example, in the screenshot below I have highlighted an index entry at the top of the page.

Another page imported from DocBook

Thanks to the teams at K15t Software, Red Hat and the JBoss Community for these two plugins!

Using the plugins in earnest

Richard Hamilton, at XML Press, and I have used the Scroll Wiki DocBook Exporter to produce my new book. I haven’t used the DocBook Import, other than to try it out for this blog post. I’d love to know if you’re using either of these two plugins in your documentation or content management procedures. Do you have any stories or tips to share?