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?

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 19 February 2012, in Confluence, technical writing, wiki and tagged , , , , , , . Bookmark the permalink. 10 Comments.

  1. Great – Roll on ConfluenceDITA round-tripping!

    • Hallo Ellis🙂

      Yes, wouldn’t that be interesting! It’s more problematic because of DITA’s topic typing, due to the fact that DITA is designed much more for topic-based authoring than DocBook. Still, various people are coming up with some exciting ideas for enforcing structure on a page so that a DITA export makes more sense than it does now.

      Cheers, Sarah

  2. Well, I’m impressed. Mainly because I’d like to be able to import my three O’Reilly books from their docbook sources into Confluence to allow people to comment on them more naturally.

    • Hallo Matt

      That’s an interesting use case. When writing my book, we did have the reviewers commenting on the pages on the wiki.

      Now that the book is in production, I’ve also opened up the Confluence site now for ongoing conversation about the book and all things related. But I’m not making the pages of the book themselves accessible to the general public, though of course they’re still there on the wiki.

      When you had people review your book, how did it work? Did you send them PDF or Word files generated from the DocBook?

      BTW, I’m putting together a proposal for a Summit presentation about publishing a book with Confluence and DocBook.If the proposal is accepted, that will be my ticket to Summit 2012. So any stories about how things work without a wiki will be a good counterpoint to add to my presentation.🙂

      Cheers, Sarah

  3. Hi Sarah!

    Do you know if there’s a any plan to support the plugin for Confluence 4 and to work with these hiccups? I think this feature and case study make Confluence the killer-app for technical and DIY publishing !!!

    • Hallo David
      I think you’re right about Confluence being a killer app for publishing.🙂 I don’t know if the guys at RedHat have any plans to upgrade the importer to support Confluence 4. The Scroll DocBook Exporter already does support Confluence 4.

      BTW, here’s another very interesting app: Booktype by Sourcefabric. I haven’t had a chance to play with it yet, but from reading the blurb it looks very cool.

      Cheers, Sarah

  4. Hello Sarah,
    I am really interested in your experience using the RedHat Confluence import plugin.
    You wrote, that images were present. I have not managed any docbook-import with images.
    What format did you use? I have tried png and svg.
    And do you know how to get a table of contents or indices on the imported confluence site? Is there a way to have the plugin to create a index for chapters or sections?

    • Hallo Jörg

      It’s been a while since I’ve used Confluence (more than a year) so I can’t answer your questions. I’m sure the wiki had changed quite a bit in that time.😉 The best place to ask questions is the Atlassian Answers forum: answers.atlassian.com. There are many knowledgeable and helpful people there. Good luck with finding the best solution!
      Cheers
      Sarah

  5. Hello sir,

    I need one help. I want to edit the code of docbook importer plugin and provide the functionally for article support. I want some guidance regarding this. How i edit the code of plugin which IDE I needed which Library i need and how i do this ? Please help me.

  6. >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.

    As part of the ever expanding Red Hat Docs Alumni, I can provide more detail about this.

    This tool was designed to allow JBoss.org developers to migrate their docs from Publican [1] DocBook 4.5/5 XML to the (at the time) new collaborative shiny Confluence collaborative system.

    The goal with this mass migration of community docs was to removed perceived barriers between XML contributions vs Wiki contributions.

    The specific structures in this import tool catered for DocBook (Preface and Chapters) and (preface, parts, appendix) type documents.

    Just in case someone happens across this post in their quest to get single-sourced docs managed outside of Confluence into confluence as a static site host, this tool might allow you to use Asciidoctor to output DocBook and import as a docs node into Confluence. Confluence currently does not have any support for AsciiDoc.

    [1] https://jfearn.fedorapeople.org/en-US/Publican/4.2/html/Release_Notes/

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: