Playing with DITA2Confluence

Lisa Dyer has recently announced the latest version of the DITA2Confluence tool forย  converting DITA XML to Confluence wiki pages. It’s part of DITA2wiki, an open source project on SourceForge. I found it via Anne Gentle’s excellent overview. Thank you Anne and Lisa! So I’ve been playing with it. It’s very very cool.

I downloaded the DITA2Confluence binary and used it to import the sample documentation set, which also happens to be the user guide for the tool. I thought it might be useful for others to see the steps I followed. I’m using Windows Vista and Confluence 2.9.

From this:

Playing with DITA2Confluence

Playing with DITA2Confluence

To this:

Playing with DITA2Confluence

Playing with DITA2Confluence

Basic Setup

First, install and set up all the bits and pieces:

  1. Download an evaluation version of Confluence. (I used the Standalone ZIP archive, but you can use the automated installer. Click “Show All” near the top right of the installation page to see the download file for the automated installer.)
  2. If you’re using the ZIP file, unzip it to a folder of your choice.
  3. If you’re using the ZIP file, navigate to <<your chosen unzip folder>>\confluence-2.9-std\confluence\WEB-INF\classes and open the file in a text editor. (Notepad will do.) Set a location for your Confluence home directory. This is where Confluence will store its data. You can just choose the default location by removing the # sign in the last line of the file. Confluence will create this folder on startup if it doesn’t exist yet. Save the properties file.
  4. I already had Java 6, and had set my JAVA_HOME variable. If you’re using the ZIP file and you haven’t got Java 5 or 6 yet, you’ll need to download and install Java and set JAVA_HOME. (There’s more on setting environment variables in a step below.)
  5. Start Confluence by navigating to <<your chosen unzip folder>>\confluence-2.9-std/bin and running startup.bat.
  6. Start your web browser and go to http://localhost:8080. You should see the Confluence setup wizard.
  7. Follow the instructions to set up Confluence. Choose the default installation. It will ask you to specify a username and password for the administrator. To make things easy, just choose a username of “admin” and a password of “admin” ๐Ÿ™‚
  8. Download the DITA2Confluence “binary” and unzip it into a folder somewhere.
  9. Navigate to the folder where you unzipped DITA2Confluence and open the file in a text editor. (Notepad will do.)
  10. Check the URLs in the file. They tell the tool where to find Confluence on your machine. If you didn’t change any of the defaults when installing Confluence, then these URLs will be fine.
  11. Check the user and password in the file. The tool will use these credentials to log in to your Confluence instance. If you set your administrator username and password to “admin/admin” when installing Confluence, then there’s no need to change them here. If you chose some other username and password, change them in this file. Save the file.
  12. In the same folder, take a look at the file. I didn’t need to change anything in this file. It points to the location of the sample documentation set which you’ll import into Confluence. The DITA2Confluence User Guide tells you more about it. (See the PDF file included in the download.)
  13. Download Ant and unzip it somewhere. I just chose the straight zip archive (
  14. Now you’ll need to edit your Windows environment variables, to add Ant to your path and to set up ANT_HOME. In Windows Vista, go to “Start” –> “Control Panel” –> “System”. Click “Advanced System Settings”. Assure Vista that yes, you really did mean to do this. Click the “Advanced” tab. Click the “Environment Variables” button.
  15. Under “System Variables”, select “Path” and click the “Edit” button. Now it’s easiest to copy all the text that’s there and paste it into Notepad for easier editing. Add a semi-colon to the end of the string, then paste the address of your Ant bin folder. Then paste the entire text string back into the environment variable and click “OK”. So my path looks like this now: %SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem;C:\Program Files\Microsoft SQL Server\90\Tools\binn\;C:\Program Files\ATI Technologies\ATI.ACE\Core-Static;C:\PROGRA~1\ULTRAE~1;C:\Program Files\QuickTime\QTSystem\;D:\Ant\apache-ant-1.7.1\bin
  16. Still under “System Variables”, click “New”. Add a variable called “ANT_HOME”ย  and paste the address of your Ant unzip folder. Mine is:ย  D:\Ant\apache-ant-1.7.1

That’s the basic setup done. You can run the DITA2Confluence tool now, and it will happily import the sample content into Confluence, creating a brand new space with a number of pages. I did this, just to see what it would look like. The only issue is that a couple of plugins are missing. So your pages will have some pink banners saying that Confluence could not find the {multi-excerpt-include} macro and the {set-sort-id} macro.

A couple of Confluence plugins

My understanding is that it’s quite possible to design DITA documentation sets that don’t invoke these macros and therefore don’t require the two extra plugins. You’ll need them because you’ll be importing the sample documentation, which does ask for the macros.

So let’s install the plugins into Confluence first, in case you don’t like pretty pink error messages ๐Ÿ˜‰

  1. In your browser, make sure you have Confluence open (at http://localhost:8080) and that you are logged in as the admin user.
  2. Let’s do the Adaptavist Builder Theme plugin first. In Confluence, go to the “Browse” menu and select “Confluence Admin”. Click “Plugin Repository” in the left-hand navigation panel. The page will take a while to load. When it’s finished, search the page for “Builder Theme” and click the “Install” link next to it. This will also take a while. When it’s finished, the page will re-load and the word “Installed” will appear next to the “Builder Theme”. This is the Theme Builder plugin from Adaptavist, and they kindly allow you to use an evaluation version while you are evaluating Confluence. (BTW, if your Plugin Repository is giving problems, you can install the plugin directly from the jar. We’re about to do that for another plugin, and the Adaptavist docs tell you where to find their jar.)
  3. Now let’s do the Multi-Excerpt Plugin. The jar for this one is included in your DITA2Confluence download. In Confluence, still in Confluence Admin, click “Plugins” in the left-hand navigation panel. Click the “Browse” button and navigate to the folder where you unzipped DITA2Confluence. Open the “lib” folder and select the file called “multiexcerpt-plugin-2.0.jar”. Click the “Upload” button to upload the file into the Confluence plugins. The Multi-Excerpt Plugin is from Artemis Software, and you can use an evaluation version of this one too.
  4. All done.

Running the DITA-to-Confluence conversion tool

Now for the fun bit. Your Confluence site will magically acquire the DITA2Confluence user guide in its own Confluence space:

  1. Make sure Confluence is running.
  2. In Windows, open the command-line interface. (In Vista, go to “Start” –> “Run” then type “cmd” and click “OK”.)
  3. Navigate to the folder where you unzipped DITA2Confluence. (This is where the “build.xml” file resides.)
  4. Run the Ant command: ant
  5. Done!

In Confluence, you should now see the new content. Go to your Confluence Dashboard, and check to see if the “dita2confluence” space has appeared. Click through to the space and its pages to see the nifty new content.

In conclusion

This is a very exciting new tool, and it’s awesome that it’s open source. Good on ya, Lisa and friends.

At the moment, the tool allows you to convert content from DITA to Confluence. It doesn’t yet allow you to convert from Confluence to DITA. Two things are relevant here:

  • Lisa is calling for help with the round-trip DITA-Confluence-DITA conversion.
  • There’s another Confluence plugin under development, called Scroll Wiki Exporter, which I’ve blogged about before. It converts from Confluence to DocBook XML, and there are plans to add DITA soon.

At this stage, I haven’t done much more than try out the tool, import the sample content and write this rather lengthy blog post ๐Ÿ˜‰ But I’m totally enamoured of the possibilities this tool exposes, for including Confluence import/export into the overall documentation management process and for providing output in the many different media types which different readers require.

Wikis bring indisputable benefits in terms of collaboration on content, working in an agile environment, and involving the whole organisation/community in ownership of the documentation. Up to now, wikis have not been so strong on the document management and release management side of things. The wiki-DITA-wiki tools are an excellent way of filling this gap.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 26 October 2008, in atlassian, Confluence, open standards, technical writing, wiki, xml and tagged , , , , , , , , , , , , . Bookmark the permalink. 33 Comments.

  1. Great write up. It’s fantastic to see DITA and Confluence working together.

  2. I’m so glad you got to try it out! I am impressed at how easy it was to get the 30-day trial of Confluence running locally and then the DITA2Wiki tool “just worked” – built, populated, everything – once I had the paths right. Great fun, to be able to get a wiki populated with a few build commands. ๐Ÿ™‚

  3. Roger Shuttleworth


    Thanks for this very useful information. Just one comment on the installation of plugins. After going to the Plugin Repository in IE7, the plugins would not load. Instead, an error message appeared saying [Object error] and the “Loading plugins” message stayed for ever until I closed IE. I tried again in Firefox 3 and it worked fine.

    I thought you might like to know about this.


  4. Hallo Roger

    Thank you for mentioning this problem ๐Ÿ™‚ I’ve seen it happen in IE7 and I’ve had a bit of a browse around our issue tracker. Evidently it’s an IE problem, which Microsoft have fixed in Windows Service Pack 3. There’s also a hot fix. Details are on our JIRA site at CONF-10837.

    I’m glad you managed to get things working using Firefox. An alternative is to upload the plugin jar into Confluence manually, via the “Plugins” option in the Administration Console.

    Happy DITA ๐Ÿ™‚

  5. Excellent article.

    I tested that this plugin works great for maps but does not work for bookmaps. Hopefully next version will support.

  6. I mean this tool works great for maps but not for bookmaps yet

  7. Thank you Sameer, that is good to know! I’m really keen to hear about people using DITA and Confluence ๐Ÿ™‚

    I see that the DITA2wiki forums are attracting some discussion now. If you like, it may be a good idea to post some results from your testing there too, and see if other people respond. I’m sure Lisa Dyer and the team would be delighted to hear about people trying it out too.

    Here’s the forum link:

  8. Thanks for SF forum link. Forgot my username so in process of reworking.

    In the meantime, yet another observation is that currently the tool only allows to upload content directly under confluence wiki space. I did not find any configuration to mention if the content should be uploaded under a specific page in the space as children. (I tried using the spackey property and mention the value as SPACE_NAME|Page_Title but did not work.) In case the feature does not exists, then definitely this is a very useful(or rather a must) feature.

  9. Congrats on this – this is really great. You have no idea how much this pleases me. Your doc architecture is a reference example for the industry (as you know, or should) – a very powerful one!!

  10. Sarah,

    Thanks for directing DITA2Confluence users to the SourceForge project home – it’s definitely the best place to log feature requests and bugs.

    Sameer, I believe I replied to you elsewhere, but if you missed it: the next release of DITA2Confluence (1.3, scheduled for early 2009) will include support for setting a wiki page as parent to a content module (=ditamap).

    Support for the bookmap specialization is a good request. If you would pls open a feature request on SourceForge, I’ll get that into the queue.

    – lisa

  11. This transform is outstanding and I know that we’ll be incorporating our large sets of documentation to Confluence thanks to Lisa and crew. Our DITA files contain heavy use of audience, platform, and otherprops metadata. I am a little confused how to call the ditaval file. The current path in the build.xml file is:

    When I change the value to an absolute path, it does not work and I can’t find an instance of “aehelp.ditaval” in the sample.

    I’ve also tried to create a new entry into the file:


    But that too doesn’t seem to have any affect.

    Does anyone know where I can place the ditaval and set the parameter to get it to work? Has anyone successfully filtered their content?


  12. It looks like the path that i submitted in my previous blog didn’t publish. To clarify it’s located in DITA2Confluence\doc\userguide\build.xml and its value is property name=”dita.input.valfile” value=”${ant.file.dir}/aehelp.ditaval

  13. Hallo all, I’m just back from holiday and delighted to see all your comments on my blog post. Instead of replying via comments, I’ve written a blog post: Back from holiday and thanks for comments.

    And just a quick one to Joe: I’m really excited about your project to move all your documentation to Confluence. For questions about the DITA2Confluence tool, the best place would be the DITA2wiki forums:

  14. Hello Sarah,

    thanks for this very helpful presentation of the interesting DITA 2 Confluence concept !

    Today, the urls for “Theme Builder plugin”
    can be

    For Scroll, I appreciated the Video from Atlassian Blog ->

    For the {set-sort-id} problem, I didn’t understood easily in your post that this problem was linked to the Theme Builder.. but now I know ๐Ÿ˜‰

    >Lisa is calling for help with the round-trip DITA-Confluence-DITA conversion.
    Great! Great! Great! Exactly what I expect ๐Ÿ˜€
    I can’t really help for dev part but let me know if you need a beta tester ๐Ÿ™‚

    Thanks again for this post !

    Best Regards


    • Hallo scheb,

      Thank you so much for the updated URLs and new information! I’m sure Lisa and the DITA2wiki projects would be delighted with any help you can offer. I haven’t heard any news of the wiki to DITA side of things.
      Cheers, Sarah

  15. Hello!
    There’s a little problem with the latest version of Adaptavist’s Theme Builder Plugin (4.0.2 and maybe any earlier versions).
    Here’s an overview. Briefly, TB distro doesn’t contain set-sort-id macro anymore.

    Best regards,

    • Hallo Kate, thanks so much for letting me and the other readers know about this. I’m glad that Lisa has let the Adaptavist guys know about it. Thanks for the link to her report. I hope a lot of people will add weight to the request by adding comments to that page.
      Cheers, Sarah

  16. Hi Sarah

    A colleague and I have started working with the DITA2Wiki plug-in and are excited about the results. However, we’ve hit the issue with unavailability of the set-sort-id. I’ve been in contact with the Adaptavist people and they are due to carry out an assessment in August of what it will take to fix. I hope that they’ll come back with good news. However, in exchanges with Lisa Dyer it seemed that the better longer term solution would be for the native Confluence page ordering functionality to be exposed via the public API. I believe there was some discussion of this a while back and wondered if anything had come of this — and how we might further the cause.



    • Hallo Rodrik
      Oh, that’s a good one! There is a request on the Confluence issue tracker: “Expose a remote API to set custom ordering of pages” at

      I see that Lisa raised the request, and that you have already voted for it. I’ve sent a few emails around internally, asking if anyone can give a response on the above issue and suggesting that our tech writers may like to vote on the issue too.

      I’ve also added a comment to the issue, wondering if it should be classified as a bug fix (as it currently is) or rather as an improvement request.

      The best way to further the cause is to do what you’ve already done, and to rally other people to vote for and comment on the issue, letting Atlassian know how valuable the fix would be.

      Cheers, Sarah

    • Hallo again Rodrik and all

      Here’s some more feedback, after discussions with the Confluence dev team. At the moment, extensions to the SOAP API are not a priority, so it’s unlikely we’ll be able to do any work on this request in the foreseeable future.

      One way around this problem is to write a plugin that creates a new remote API call to give DITA2Confluence the capability it needs. You can mix and match the Confluence-provided remote APIs with those provided by plugins.

      I’ve added a page to our plugin wishlist. It’s possible that a community developer may like to take up the challenge. You can “watch” the page to see if any activity happens. Please feel free to comment on and/or update the page itself too:

      Here’s the permalink, in case someone changes the page title:

      • Sarah,

        I wanted to reach out and say, thanks so much for your lobbying and guidance in support of our collaborative quest to get a solution to the set-sort-id issue!

        I also wanted to just update this thread for others who might be following, that a new macro to replace set-sort-id has passed initial testing, and hopefully soon it will freely available to the community. So, stay tuned ๐Ÿ™‚

        I must say this has been a tremendously rewarding process for my, personally, to witness the power of the community, and I be will posting a blog on this project at GA. (Yes, I know it’s been like 5 years since my last posting;)


        – lisa

      • Hallo Lisa
        That’s fantastic news! Thanks so much for letting us know.
        Cheers, Sarah

  17. I haven’t been able to get dita2wiki to work at all with Confluence 3.4.3. The ant command fails with the following error:

    [Dita2Confluence] com.lombardisoftware.confluence.dita2confluence.exception.ConfigException: java.lang.ClassCastException: java.util.ArrayList cannot be cast to org.w3c.dom.NodeList
    [Dita2Confluence] at com.lombardisoftware.confluence.dita2confluence.ConfluenceConfig.loadContentMapping(

  18. I have tried the steps in this article. I got the following error:

    C:\\DITA2Confluence\build.xml:72: Error running execute: AxisFault

    After resolving the above mentioned error, I am getting an Http Error Code:


    Could you please tell me how I can resolve this issue?



  19. I have tried the steps in this article. I got the following error:

    C:\\DITA2Confluence\build.xml:72: Error running execute: AxisFault

    After resolving the above mentioned error, I am getting an Http Error Code:


    Could you please tell me how I can resolve this issue? We are evaluating Confluence and want to publish content from DITA XML to Confluence Wiki.



    • I resolved the HttpErrorCode issue as well. Ran the ant command to build build.xml file. It generated the build and I could see the dita2confluence space in the Dashboard. However, the content/pages do not appear. Why is it happening? Command Prompt shows the following error:

      ERROR The add or update failed for C:\DITA2Confluence\doc\userguide\ditamap

      Could you please help me resolve this?


  20. Hello,

    This is a shot in the dark considering how old this post is, but I was wondering if you might be aware of any other tools that might convert XML into Confluence?

    The Dita2Confluence tool appears to have been mainly abandoned, with some people poking at it now and then but not really producing anything that others can use.

    I’ve looked at ePublisher but that’s a rather complex system just to convert some file formats, and have yet to actually be successful.

    If you aren’t aware of anything, is there a group I could approach who might be? Maybe a Confluence Tech Writer group or something like that.

    Any help on this is appreciated.



    • Hallo Anthony
      I’m sorry, I haven’t been keeping up with the world of Confluence over the last couple of years. One place to look for answers is – but folks there tend to send you to Dita2Confluence the minute anyone mentions DITA, so it’d probably be worth keeping the word DITA out of the conversation. For a really knowledgable answer, the team at K15t is excellent. I don’t know of any of their products that suit your requirement, but they would know the more general answer of the current state of Confluence and XML.

      • Hi Sarah,

        As I said, it was a bit of a shot in the dark. Thanks for getting back to me on it though.

        I’ll definitely try posting to Atlassian, and as you said keep DITA out of it. I’ll also give the K15t people a try as well.

        Appreciate the leads.



  1. Pingback: Update - Playing some more with DITA2Confluence « ffeathers — a technical writer’s blog

  2. Pingback: Links Roundup: DITA and Wikis | Shanghai Tech Writer

Leave a Reply

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

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

Google photo

You are commenting using your Google 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 )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

<span>%d</span> bloggers like this: