Migrar Spaces de Confluence a Azure DevOps

Si estás pensando en migrar tu documentación de Confluence a Azure DevOps habrás visto que no es posible hacerlo directamente con los formatos que te ofrece este primero como exportación (HTML, XML y PDF). Las wikis en Azure DevOps están pensadas para hacer uso de markdowns y es por ello que tenemos que ingeniárnoslas para conseguir este formato de nuestros Spaces. En este artículo te cuento mis investigaciones al respecto

Opción 1: Usar la herramienta Markdown Exporter for Confluence

Existe una herramienta llamada Markdown Exporter for Confluence que nos permite descargar como markdown las páginas. Por lo que he podido probar, los archivos obtenidos los convierte perfectamente sin caracteres especiales, súper limpios.

Resultado de la exportación con Markdown Exporter for Confluence

Los dos «peros» de esta herramienta es que tiene la limitación de que no se puede automatizar o elegir un Space completo, por lo que habría que ir página por página descargando el archivo que genera.

Export to Markdown con Markdown Exporter for Confluence

Por otro lado se trata de una herramienta de pago, aunque el precio no es muy elevado.

Opción 2: Exportar el Space a formato HTML y convertirlo a markdown

Uno de los formatos propuestos por Confluence para la exportación de los espacios es HTML. Podemos aprovechar el mismo para convertirlo posteriormente a markdown. Para ello debes ir al Space que quieres exportar y accede al apartado Space Settings > Content Tools > Exports, mantén seleccionada la opción HTML, y haz clic en Next.

Confluence – Space Settings – Content Tools – Export to HTML

En la siguiente ventana mantén la opción Normal Export.

Confluence – Space Settings – Content Tools – Export HTML Options

Una vez haya finalizado el proceso podrás descargarlo a través del siguiente enlace:

Confluence – Export completed

Esto descargará un zip con todos los elementos de tu Space en formato HTML.

Instalar Pandoc

Lo siguiente que necesitas es instalar la herramienta Pandoc, que es un convertidor de documentos. Elige la instalación en base a tu sistema operativo.

Instalar confluence-to-github-markdown

La herramienta confluence-to-github-markdown es la que nos ayudará a reconvertir estos HTMLs en el formato que necesitamos. Puedes instalarla a través del siguiente comando:

Extrae el zip descargado anteriormente de Confluence y utiliza el siguiente comando para la conversión del contenido:

El resultado será un nuevo directorio llamado Markdown con los archivos .md como resultado del comando anterior.

Resultado del comando confluence-to-github-markdown

Si bien esta opción mejora en cuanto al proceso de exportación, a diferencia de la opción 1, el paso de HTML a Markdown no es todo lo limpio que nos gustaría, como si ocurre con la primera opción:

Resultado de la conversión de HTML a markdown con confluence-to-github-markdown

Esto requeriría por nuestra parte hacer limpieza de la documentación una vez exportada. Si tenemos mucha documentación generada esto sería un proceso que necesitaría mucho tiempo por nuestra parte.

Opción 3: Convertir solo el contenido del div main-content

Como tercera opción, lo que he podido comprobar, y que estoy casi segura de que es lo que hace la herramienta de la opción 1, es una vez exportado el contenido del Space a HTML podríamos crear un proceso que solamente dejara como contenido de los HTML lo que hay dentro de main-content y posteriormente utilizar algún conversor de HTML a markdown. Para verlo con el mismo ejemplo, suponiendo que Confluence nos devuelve este HTML:

Si pasamos todo él por una herramienta que convierta a markdown nos daría un resultado parecido al de la opción 2. Sin embargo, si solo cogemos el contenido dentro de main-content obtendremos el resultado que esperamos:

Para este punto me he generado un script en Node.js que hace la limpieza del HTML y la conversión con el módulo turndown:

El código de ejemplo lo tienes en mi GitHub. En el caso de tener imágenes, videos o cualquier otro documento insertado recuerda que también debes copiar la carpeta attachments que se descarga cuando haces el export de Confluence.

Resultado utilizando la opción 3

Crear un repositorio en Azure Repos con el contenido exportado

Independientemente de la opción que utilices para obtener los markdowns de tu documentación en Confluence, el siguiente paso es crear un repositorio en Azure DevOps que almacene todos estos archivos. Dirígete al proyecto donde quieres almacenar esta información y en el apartado Repos crea un nuevo repositorio:

Azure DevOps – Repos – New repositorio

Para este ejemplo lo he llamado wiki y he eliminado el check que me genera un README.md de manera automática.

Ahora accede a través del terminal al directorio donde tienes los archivos markdown a subir y ejecuta los siguientes comandos:

Si todo ha ido bien deberías de ver tus archivos en el nuevo repositorio.

Enlazar el repositorio wiki a Wikis

El último paso de todo este proceso es enlazar el nuevo repositorio al apartado Wikis de tu proyecto en Azure DevOps. Para ello, basta con ir al apartado Overview – Wiki y hacemos clic en la opción Publish code as wiki.