How to convert Confluence XML storage format to wiki markup

Are you looking for a quick, unsupported but still immensely useful way of converting a page, or a small chunk of content, from the new Confluence storage format back to good old wiki markup? The new XML storage format is used in Confluence 4. Wiki markup is used in Confluence 3 and is still required in parts of Confluence 4. Graham Hannington has created a web page that does the conversion for you. His tool is called the Wikifier. Just paste in the Confluence storage format XML on the left, and see the wiki markup appear on the right immediately.

I’m busy documenting the wiki markup and storage format for all the Confluence macros. Graham’s Wikifier is proving very useful indeed, so I thought I’d tell you about it. This is what it looks like, processing the much-beloved Cheese macro:

One use case – converting a page to a template

One problem with Confluence 4.0, 4.1 and 4.2 is that page templates must be written in wiki markup. They do not yet support the new rich text format used by the new editor. If you have developed a page and want to convert it to a template, you’re stuck, because the content of a page is no longer available as wiki markup.

To get round this problem:

View the storage format for the page that you want to use as a template. How? The “View Storage Format” option appears in the “Tools” menu. It is available to Confluence system administrators, and to people who have permission to use the Confluence Source Editor, which is available as a plugin.

Copy the storage format of the page’s content, paste it into Graham’s Wikifier, and grab the wiki markup.

Caveats

Wikifier is a minimal test harness for an XSLT stylesheet I have developed that converts Confluence XML to wiki markup.

The XSLT stylesheet is by no means complete. I welcome your feedback. If Wikifier does not correctly convert some Confluence XML, please let me know (if you like, use the Contact mailto link on Wikifier), and I will do what I can (no promises, though).

Wikifier is not a replacement for the Confluence 3 wiki markup editor view.

Wikifier is only a test harness; it is not intended to be a fully fledged application.

I just used the wikifier to convert a complex wiki page containing tables, panels, scaffolding fields and reporting elements into wiki markup as I needed to transform the page into a template for wider usage. I’m pleased to say the Wikifier did an excellent job. The only hiccup was with a nested table/panel/table, but I think this was actually Confluence having trouble here.

This has saved me hours of week. Thanks to Graham for developing this and Sarah for sharing the details on this blog.:)

Thank you for the positive feedback, it’s made my day! I’m glad that Wikifier was useful to you. Please feel free to contact me directly (follow that Help link on the Wikifier web page) if you find that Wikifier needs tweaking; I have not tested it against all possible combinations of input XML.

(Thank you, too, Sarah, for mentioning Wikifier on your blog, and for pointing me to this feedback from Charles.)

Just a twinkle in my eye: Wikifier/RT (“Wikifier for rich text”, or, er, something like that; don’t ask me about the slash until the twinkle becomes real).

Three columns: rich text, XHTML, and wiki markup.

Here’s the idea: you copy’n’paste content from the Confluence 4 rich text editor into the “rich text” column. The content is displayed in that column in similar fashion to the way it was displayed in the rich text editor. The second column displays the source code for that content (perhaps after being converted to be well-formed; so, possibly requiring replacement of unclosed HTML tags such as with XHTML … details, details). The third column displays the wiki markup.

The contents of all three columns are editable (although I do not plan to offer any editing controls for the “rich text” column; so, just what the browser allows – which is a lot, if you happen to have Firebug!). The second and third columns are editable plain-text ( elements).

The first column has a >> button that refreshes the second and third columns.

The second column has a > button that refreshes the third column.

Idle thoughts. I’m describing it as if it already exists, but it might never happen.

Might be useful to OnDemand users, or anyone else who doesn’t have access to the Confluence Source Editor plugin.

(First, though, maybe I should start my own blog, rather than nesting in someone else’s! Sorry, Sarah.)

You’re welcome on my blog at any time! It’s exciting to hear your ideas and enthusiasm.

Also, I’ve just created a new wiki space for you and anyone else to add sophisticated Confluence tips and techniques. The advantage of using this new space is that you can create and publish your content using the Confluence editor and Confluence macros. People can therefore also copy the content from this wiki to their own Confluence sites:

Please feel free to create your own personal space on that wiki too. If you like, you can blog from the wiki too. If you create your own personal space, you’ll get your own blog.

Everyone is welcome on the wiki. :)

Your idea for a three-column wikifier sounds cool. One thing that struck me is the complication of Confluence macros. When someone copies the rich text from the Confluence page into the wikifier box, they’ll get the rendered content rather than the macro code. Do you have any ideas about that?

If, while viewing (rather than editing) a Confluence page, you were to select and copy the content, and paste it into the first column of (this currently imaginary tool named) Wikifier/RT, then, as you say, you’d get the rendered content rather than the macro code.

However, the idea is not to copy from (a saved, read-only view of; or even a preview of) a Confluence page, but to copy content from the Confluence rich text editor, so that you get the HTML from the TinyMCE-based rich text editor. (I’ll have to be careful here with how I represent HTML markup in this WordPress comment; it didn’t turn out so well in my previous comment!)

This means that, for each macro, you’d get an HTML table element with class attribute value “wysiwyg-macro”.

Side issue: I know that the Confluence rich text editor generates images for the title bar of macro placeholders. I’ve been experimenting with CSS (in recent browsers) that enables you to insert the value of an attribute – such as data-macro-name – into the page (so that these images are not required).

Creating the underlying XSLT stylesheet for Wikifier/RT should (I hope!) be relatively simple, because I’ll be reusing much of the existing Wikifier XSLT stylesheet. The rich text editor HTML and the elements in the Confluence storage format that have the same names as XHTML elements are similar. The big difference is that, instead of converting proprietary Confluence ac:* and ri:* elements and attributes, the Wikifier/RT XSLT stylesheet will convert rich text editor HTML (for example, for macros, instead of ac:macro elements, the XSLT stylesheet will convert those HTML table elements mentioned above).

Thanks very much for making that (Confluence) wiki available. Much appreciated.

Wikifier RT (the slash was a nostalgic affectation that I have decided to drop) is now more than just a twinkle in my eye. It’s basically working (in my local sandbox). I’m now tweaking the XSLT to cater for nuances in the HTML from the rich text editor. More news to follow (here and/or elsewhere) sooner or later (depending on how much tweaking is necessary).

Some people in the FrameMaker and DITA communities would like to import pages into Confluence 4.0. We have some tools (Mif2Go, DITA2Go) that can convert FM or DITA documents to a set of files in Confluence Storage Format. But there’s no way to import Confluence Storage Format to Confluence 4.x. (!!)

If we could convert our output to Confluence Wiki Markup, then at least we could import those pages to Confluence 4.x. This would be a pretty simple program to write, if we had the XSLT. . .

Thanks. I bookmarked that last link for a good read sometime. Robert Lauriston is still on the case over at the Framers group. From what he said today, it looks like backporting to Wiki Markup wouldn’t help, because the “Import pages from disk” feature doesn’t want that either. It wants the XML format that Confluence 4.x uses to export. I get the impression this is not the same as the Confluence Storage Format, although I could be wrong.

I don’t have a big stake in this. We’re new to Confluence, and we’re just exploring the possibility of adding FrameMaker or DITA-based documentation. If we can, great. If not, oh, well. . .

For importing into Confluence 4, I would only consider using Confluence wiki markup if I were importing from a reasonably similar wiki markup format (and then, perhaps only as an intermediate stage). Otherwise, I would use Confluence XML (aka Confluence storage format). For example, to import DITA into Confluence, I would write an XSLT stylesheet that transforms DITA into Confluence XML. (However, unless you are using a strictly limited subset of DITA, round-tripping will be problematic.)

Yeah, read that link (that includes some of my observations about the Confluence export format). So far, Atlassian has characterized the Confluence storage format as the XML source format for pages. Export files are also XML, and contain pages represented in Confluence storage format, but the rest of the export file XML is not deemed to be “Confluence storage format”. That link should clarify these issues for you; if not, feel free to email me, add another reply here, or send a carrier pigeon.