Search code examples
markdownconfluencewiki-markup

How to convert from old Confluence 3.5 markup to markdown?

For historical reasons, we still have a large number of *.confluence files in the old Confluence 3.5 markup format. This format is not very useful (e.g. no editor support, no repository viewer support, ...), so I want to convert the files to markdown.

So how can I convert Confluence 3.5 markup to markdown?

Solution

  • The best solution I have found so far is the following, partially manual process:

    1. Create an empty wiki page in a current version of Confluence (5.x or later) and save it.
    2. Edit the page again.
    3. Go to "Insert" > "Markup" and insert the Confluence markup
    4. Click on "Open in source editor" to show the content in the new XML-based storage format
    5. Copy the content to an XML file
    6. Add the missing header and footer (see https://github.com/highsource/confluence-to-markdown-converter/issues/8)
    7. Convert the XML file to markdown using the c2md.xsl XSLT transformation from the confluence-to-markdown-converter Github project.

    The key idea in this solution is to convert the old Confluence markup to the new Confluence XML-based storage format first. Once converted to XML, further conversions are reasonably easy (assuming you know XSLT) and quite robust.

    I also tried out the Node-base confluence2markdown converter, but the converter fails to parse the Confluence markdown reliably.

    So using Atlassian tooling for parsing the Confluence markup seems to be the way to go. This step can probably be further automated by using the Atlassian SDK, but I haven't explored this option yet.