Migration of Azure DevOps(ADO) Wiki - Confluence

Question

Has anyone been involved in migrating Azure DevOps (ADO) Wiki to Confluence?

If yes, I'd appreciate your inputs on what's the best possible way to migrate the data.

Mesut Sözüer · Answer

Hi Sambhav, a few things that make this easier:

* Get the files. A project wiki is a Git repo behind the scenes (named <Project>.wiki). Use "Clone wiki" from the wiki's ... menu and you get every page as a .md file, the .order files that hold the page order, and the .attachments folder with images.
* Plan the conversion. Plain Markdown converts well: pasting raw Markdown into the Confluence Cloud editor turns headings, lists, tables, task lists, links and code blocks into Confluence formatting. ADO-specific syntax does not: ::: mermaid blocks, [[_TOC_]] and [[_TOSP_]], and links that use the dashed file names (spaces in page names become "-" in file names). Replace these first: a Table of Contents macro for [[_TOC_]], a Children Display macro for [[_TOSP_]], and a diagram app or images for Mermaid.
* Pick the method by size. For a few dozen pages, paste page by page. For more, use a script or CLI against the Confluence REST API (md2cf, mentioned above, or mark). Walk the .order files so the page tree comes out in the same order, and upload the .attachments images as page attachments.
* Decide what should not move. Pages that describe code (READMEs, runbooks, ADRs) often belong next to the code in Azure Repos, so they get reviewed in the same pull request. Those can stay there and be shown on a Confluence page instead of being copied.

Disclosure: I build SourceDocs, a Forge app that shows a Markdown file from Azure Repos (also GitHub, GitLab, Bitbucket) on a Confluence page, private repos included. It does not migrate the wiki and does not render the ADO-only syntax above, so steps 1 to 3 are still the way to move the wiki itself.

Sebastian Krzewiński · Answer

Hi @Sambhav Swain

I don't know if there is a easy way to migrate it.

You can try to use this (didn't test it) -> https://pypi.org/project/md2cf/  because Azure DevOps uses Markdown and Confluence uses XHTML, native copy-pasting may lose formatting.

Regards,

Seba