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:

Graham provides other resources, including an XML schema for the Confluence storage format, and associated documentation: Graham’s Confluence resources page.

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.
  • Use the wiki markup to create your page template in Confluence.

Caveats

See Graham’s comment announcing the Wikifier.

An extract from that comment:

What Wikifier is, and is not

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 hope this is as useful to you as it is to me. :)

About these ads

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 7 June 2012, in Confluence, technical writing, wiki and tagged , , . Bookmark the permalink. 15 Comments.

  1. Useful information! It would also be useful to see the schema for each version coming from Atlassian.

  2. 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.
    :)

  3. Hi Charles,

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

  4. 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.)

    • Hallo Graham :)

      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:

      https://wikitechcomm.onconfluence.com/display/CONF/Advanced+Confluence+Tips

      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?

      Cheers
      Sarah

  5. Hi Sarah,

    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.

    Cheers,
    Graham

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

  7. Wikifier RT is a new web page that converts Confluence 4 rich text editor content to wiki markup:

    http://www.amnet.net.au/~ghannington/confluence/wikifier/rt/

  8. Is there any way we can apply this to multiple files automatically?

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

  9. Jim,

    I’ve not revisited this project for a few months. The XSLT that Wikifier uses to convert Confluence 4 XML (which I think of as being synonymous with “Confluence (4) storage format”) is at:

    http://www.amnet.net.au/~ghannington/confluence/wikifier/confluence2wiki.xsl

    Feel free to contact me about this via email (see the comment header in the XSLT).

    I bundle a slightly back-level version of the above XSLT with a package that also contains an Confluence XML schema. That package has a readme, which contains some information on Wikifier:

    http://www.amnet.net.au/~ghannington/confluence/readme.html#wikifier

    You might also be interested in this thread of comments on the storage format (in particular, export files):

    https://confluence.atlassian.com/display/DOC/Feedback+on+Confluence+Storage+Format?focusedCommentId=284366422#comment-284366422

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

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

  12. Just tried the wikifier … wow, pretty nice!

    I was trying to take a doc out of Confluence 4 to massage into Markdown, and the XML-to-Markdown would have been a bit more of a bear. Much easier to convert the wiki format with a bit of regex.

    How about a simple Markdown-to-PDF? Some people don’t like to review docs that are in Markdown.

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

Follow

Get every new post delivered to your Inbox.

Join 1,499 other followers

%d bloggers like this: