La guia definitiva para migrar de Confluence a Docs-as-Code sin perder el formato

Confluence suele ser el lugar donde empieza la documentacion critica del negocio, pero casi nunca es el lugar donde deberian terminar los flujos modernos de documentacion.

Los equipos que quieren adoptar Docs-as-Code necesitan mucho mas que una exportacion puntual. Necesitan contenido versionable, revisable, sincronizable, buscable, archivado y reutilizable en ingenieria, soporte, cumplimiento e IA. Ahi es donde fallan la mayoria de las migraciones: no en el titular del proyecto, sino en los detalles operativos que importan cuando el primer export ya esta en disco.

Por que las exportaciones nativas de Confluence rompen los flujos Docs-as-Code

El problema no es que Confluence no pueda exportar contenido. El problema es que las salidas por defecto no producen un patrimonio Markdown durable y amigable para automatizacion.

Los fallos habituales se ven asi:

• las tablas quedan mal aplanadas o dificiles de revisar en Git
• los bloques de codigo pierden una presentacion limpia y consistente
• los enlaces internos siguen apuntando a Confluence en lugar del arbol local
• la jerarquia se pierde y el espacio deja de comportarse como un conjunto navegable de documentacion
• la busqueda, la publicacion estatica y la ingestion para RAG heredan ruido o formatos propietarios

Docs-as-Code no es solo una preferencia de formato. Es un modelo operativo. Eso significa que la exportacion debe soportar diffs revisables, rutas predecibles, automatizacion y ejecucion repetida.

Empieza con el alcance correcto de migracion

Antes de elegir un comando, decide si el trabajo es de precision por pagina o de alcance completo sobre un patrimonio documental.

Usa acp2md cuando la unidad real de trabajo es una pagina

Usa acp2md cuando la tarea de migracion parte de un ID de pagina, un titulo o una URL y necesitas control exacto.

Es ideal para:

• paginas de alto valor regulatorio o de cumplimiento
• pilotos de migracion sobre un documento concreto
• revisar problemas de formato antes de una migracion mas amplia
• generar un artefacto Markdown listo para retencion legal o ingestion por IA

Usa acs2md cuando el objetivo es un espacio completo

Usa acs2md cuando el requisito es mover un espacio completo de Confluence a Markdown portable preservando jerarquia, reescribiendo enlaces internos y soportando refrescos repetibles.

Es la opcion correcta para:

• migraciones documentales de gran escala
• copias de continuidad
• flujos gobernados de backup
• pipelines CI y tareas programadas
• patrimonios Docs-as-Code que deben mantenerse al dia

Que formato necesita preservarse de verdad

La pregunta real no es si Markdown es mas simple que Confluence. La pregunta real es si la conversion preserva la semantica que importa cuando el contenido sale de Confluence.

Para un flujo serio de Docs-as-Code eso suele significar conservar:

• encabezados con un esquema de documento utilizable
• bloques de codigo en Markdown cercado
• listas y estructura anidada
• citas, paneles y bloques legibles
• tablas revisables en Git
• imagenes y medios referenciados
• suficiente metadata para generadores estaticos y pipelines internos

La familia ac2md trabaja sobre Atlassian Document Format en lugar de hacer una transformacion superficial. Eso importa porque el modelo fuente contiene estructura que un flujo posterior en Markdown puede conservar de forma mucho mas fiable.

Un flujo de migracion practico que no se rompe en el segundo paso

La ruta mas segura no es exportar primero y limpiar despues. Es descubrir primero, validar la estacion de trabajo, confirmar el alcance y luego exportar.

1. Valida el entorno

Tanto acp2md como acs2md documentan un flujo orientado al operador basado en doctor, configuracion y validacion de licencia antes del primer trabajo real.

acp2md doctor
acs2md doctor

Eso detecta problemas de credenciales, licencia o conectividad antes de lanzar una migracion contra contenido real de Confluence.

2. Confirma el alcance exacto

Para trabajo por pagina, confirma antes la pagina correcta.

acp2md page get by-id 2973106197
acp2md page count marks by-url "https://company.atlassian.net/wiki/spaces/DEVOPS/pages/2973106197"

Para trabajo por espacio, inventaria el espacio antes de convertir.

acs2md space pages by-key DOCS
acs2md space convert by-key DOCS --output-dir ./site-content --sync

Esa secuencia importa porque hace que la planificacion parta del arbol real de paginas y no de suposiciones.

3. Exporta a Markdown portable, no a un artefacto sin salida

Cuando el objetivo es Docs-as-Code, la salida debe aterrizar en una estructura que pueda vivir en Git, ser publicada por un sitio estatico o alimentar procesos internos.

Para exportacion por pagina:

acp2md page convert by-id 2973106197 --output ./docs/architecture/target-page.md

Para exportacion por espacio completo:

acs2md space convert by-key DOCS --output-dir ./docs --rewrite-links --sync

En ese momento la migracion deja de ser teorica. Ya tienes Markdown controlado por el cliente y almacenado en disco.

Donde preservar el formato pasa a ser un problema operativo

El formato no es solo una capa visual. Afecta directamente a tres sistemas de salida.

Revision en Git

Si encabezados, tablas y bloques son inestables, los diffs se vuelven ruidosos y los revisores dejan de confiar en la exportacion.

Publicacion estatica

Si los enlaces no se reescriben y la jerarquia se pierde, el arbol exportado no se comporta como un sitio de documentacion. Se comporta como un monton de archivos.

Pipelines de IA y RAG

Si la exportacion elimina demasiada estructura, los fragmentos son mas dificiles de interpretar. Si conserva la semantica correcta, Markdown se vuelve mucho mas util para recuperacion y generacion fundamentada.

Por eso Climakers posiciona estas herramientas como herramientas de migracion, continuidad y Markdown listo para IA, y no como simples exportadores.

Como ayudan la reescritura de enlaces y el front matter

Hay dos capacidades que se vuelven utiles de inmediato una vez que el contenido cae en un repositorio Docs-as-Code.

Reescritura de enlaces internos

En migraciones de espacio completo, reescribir enlaces internos es lo que separa un patrimonio autocontenido de una exportacion que sigue dependiendo de URLs de Confluence.

Front matter

El front matter ayuda a conservar contexto util como autor, fechas, estado, IDs y otros atributos operativos.

Eso sirve para:

• publicacion estatica
• retencion y auditoria
• indexacion de contenido
• validacion de migracion
• automatizacion interna

El alcance Confluence Cloud importa

Las herramientas activas acp2md y acs2md trabajan sobre Confluence Cloud. No soportan Confluence Server ni Data Center.

Ese limite importa porque la planificacion empeora cuando un equipo cree que una herramienta cubre mas modelos de despliegue de los que realmente cubre. Los limites de producto claros forman parte de un flujo de migracion seguro.

Por que Docs-as-Code tambien es una postura de cumplimiento

Migrar de Confluence a Markdown no es solo una decision de herramientas. Es una decision de control de la informacion documentada bajo ISO 9001, ISO 27001, ISO 27017, NIS 2 y SOC 2. El mismo artefacto que hace funcionar Docs-as-Code — un patrimonio Markdown bajo control del cliente en Git — es el artefacto que convierte cada uno de estos marcos en algo que puedes evidenciar de verdad.

• ISO 9001:2015 clausula 7.5 exige control sobre la informacion documentada: creacion, actualizacion, distribucion, recuperacion y obsolescencia. Un repositorio Git codifica esas operaciones como commits, pull requests, ramas y etiquetas. No hay un “sistema de evidencia” separado que mantener.
• ISO/IEC 27001:2022 trata los procedimientos operativos documentados (A.5.31) y la proteccion de registros (A.5.33) como controles del Anexo A. Cuando el procedimiento es un fichero Markdown bajo control de versiones, puedes producir todo el historial, el aprobador y la fecha de obsolescencia con un solo git log.
• ISO/IEC 27017:2015 extiende 27001 al ambito cloud. Almacenar la copia de referencia de la documentacion del cliente cloud fuera del portal del proveedor es justo el tipo de control side-customer que la norma espera.
• NIS 2 exige politicas documentadas sobre gestion de riesgos de ciberseguridad, gestion de incidentes y continuidad de negocio. Un patrimonio Markdown es la via mas directa para satisfacer esa obligacion sin atarte a una plataforma SaaS cuya disponibilidad es en si misma un riesgo.
• SOC 2 Common Criteria CC2.2 y CC2.3 exigen comunicar politicas documentadas. Markdown bajo control del cliente te permite publicar el mismo contenido fuente en portales internos, paginas de confianza externas y a auditores sin divergencia.

Tratar Docs-as-Code como postura de cumplimiento tambien cambia como justificas internamente la migracion. No estas “saliendo de Confluence”. Estas trayendo la informacion documentada que sostiene tu negocio bajo controles que tus auditores ya esperan.

Una checklist sensata para equipos Docs-as-Code

Si quieres la ruta mas corta hacia una migracion controlada, usa esta lista:

1. Decide si el trabajo es por pagina o por espacio completo.
2. Configura credenciales y valida con doctor.
3. Inspecciona la pagina o el espacio antes de convertir.
4. Exporta Markdown a una ruta compatible con Git.
5. Verifica jerarquia, enlaces, bloques de codigo, tablas y medios.
6. Repite la exportacion con --sync o con modos incrementales cuando el objetivo sea continuidad y no una sola corrida.
7. Publica o procesa el Markdown en tu sitio estatico, portal interno o pipeline de IA.

Cierre

La mejor migracion de Confluence a Docs-as-Code no es la que genera mas archivos mas rapido. Es la que da control, portabilidad y una operacion repetible sin perder los detalles de formato que hacen util la documentacion.

Si el problema empieza en una sola pagina, usa acp2md. Si empieza en un patrimonio documental completo, usa acs2md.

En ambos casos el objetivo es el mismo: pasar de conocimiento atrapado en un espacio propietario a Markdown controlado por el cliente, listo para migracion, continuidad, publicacion, reutilizacion por IA y la siguiente auditoria de vigilancia ISO 27001. Cuando estes listo, empieza con acp2md para una sola pagina o elige un plan de acs2md para el espacio completo.