Introduccion a acs2md: que es y por que es util para desarrolladores

acs2md es el convertidor masivo de espacios dentro del portfolio de Climakers. Esta pensado para el momento en que un equipo deja de preguntar “como exportamos esta pagina” y empieza a preguntar “como movemos o preservamos toda esta base documental sin perder control”.

Esa diferencia importa. Una herramienta de pagina unica resuelve un problema local. Un convertidor a escala de espacio resuelve migracion, continuidad, cumplimiento, gobernanza e ingestion para IA de forma operativa y repetible.

acs2md en una frase

acs2md convierte un espacio completo de Atlassian Confluence Cloud en Markdown mientras preserva la jerarquia de paginas, reescribe enlaces internos y sigue futuras actualizaciones mediante .convert-sync-state.json.

En la practica, eso permite:

• mantener una copia de continuidad fuera de Confluence
• preparar una migracion a docs-as-code en Git
• construir un corpus repetible de Markdown para RAG o busqueda empresarial
• inspeccionar permisos, propiedades e inventario antes de exportar nada
• hacer que las siguientes ejecuciones omitan paginas sin cambios

Por que les importa a los desarrolladores

La mayoria de equipos no compra un convertidor de espacios porque le guste convertir. Lo hace porque hay un flujo mas grande bloqueado.

Las razones tipicas del lado tecnico incluyen:

• una migracion a sitio estatico necesita estructura, no un monton de archivos planos
• un repositorio Git necesita enlaces locales que sigan funcionando despues de exportar
• un pipeline RAG necesita Markdown repetible en vez de un formato propietario
• un plan de continuidad necesita una copia local que pueda revisarse, respaldarse y auditarse fuera de la plataforma fuente
• un programa de migracion necesita comandos de descubrimiento antes de una exportacion masiva

La documentacion posiciona acs2md como una herramienta para continuidad, payloads de migracion, exportaciones gobernadas y portabilidad documental a escala. Ese encuadre es mucho mas util que llamarlo solo “CLI de exportacion masiva”.

Que cubre realmente acs2md

acs2md es mas amplio que space convert. La superficie operativa se parece mas a un pequeno toolkit:

Esa separacion es util porque las migraciones reales rara vez son un solo comando. Los operadores necesitan validacion, descubrimiento y comprobaciones posteriores.

Por que importa para programas de cumplimiento y continuidad

Si tu equipo opera en un entorno regulado, acs2md tambien es el artefacto que convierte el contenido de Confluence en evidencia. Varios de los controles que pesan a tus auditores piden lo mismo: una copia actual, restaurable e inspeccionable de la informacion documentada que no dependa de que la plataforma de origen este disponible.

• ISO 9001:2015 clausula 7.5 exige que la informacion documentada este controlada, vigente y disponible. Un patrimonio Markdown en Git satisface el requisito de “control de la informacion documentada” sin atrapar el registro dentro del portal de un proveedor.
• ISO/IEC 27001:2022 A.5.30 (preparacion TIC para la continuidad de negocio) y A.8.13 (copia de seguridad de la informacion) exigen recuperacion probada y backups repetibles. Una corrida programada de acs2md space convert --sync cumple exactamente eso.
• ISO/IEC 27017:2015 CLD.12.1.5 trata la seguridad operacional del cliente cloud. Un acceso GET de solo lectura contra Confluence Cloud, ejecutado desde tu propia automatizacion, es justo el tipo de control admin-side que pide la norma.
• NIS 2 Articulo 21(2)(c) exige continuidad de negocio, gestion de copias y gestion de crisis para entidades esenciales e importantes. Una copia versionada en Git te da el artefacto y el rastro auditable de una sola vez.
• SOC 2 Disponibilidad (A1.2 y A1.3) pide procesos de backup y pruebas de recuperacion. Los commits etiquetados son puntos de restauracion y acs2md doctor produce evidencia de que la ruta de recuperacion sigue funcionando.

Por eso la documentacion habla de continuidad, gobernanza e ingestion para IA en la misma frase: en un patrimonio documental regulado, son el mismo flujo.

Cuando acs2md es la herramienta correcta

Usa acs2md cuando la pregunta sea sobre toda una base documental.

Eso incluye:

• migraciones a docs-as-code donde la jerarquia debe sobrevivir
• copias de continuidad con refrescos recurrentes
• programas de archivo que deben sobrevivir a borrados en Confluence
• ingestion para RAG o busqueda que debe regenerarse de forma programada
• trabajo de gobernanza donde permisos y metadatos importan tanto como el contenido

Si la necesidad real es una pagina exacta, acp2md sigue siendo la herramienta mas precisa. La documentacion lo dice claramente, y tiene sentido: los flujos de pagina y los flujos de espacio no son el mismo problema operativo.

Limites que conviene saber desde el principio

La documentacion actual deja varias condiciones muy claras:

• acs2md soporta solo Confluence Cloud
• los binarios publicados estan disponibles para macOS y Linux
• la herramienta es de solo lectura y usa peticiones GET contra Confluence
• los trabajos largos muestran progreso por stderr para no contaminar stdout

No son detalles menores. Te dicen si la herramienta encaja con tu plataforma, tu modelo de seguridad y tu pipeline antes de invertir tiempo.

Un flujo realista para el primer operador

La primera ejecucion recomendada no es improvisada. La documentacion de cliente y el manual en GitHub coinciden en una secuencia muy concreta:

acs2md doctor
acs2md space list --format json --limit 5
acs2md space pages by-key TEAMDOCS --tree
acs2md space convert by-key TEAMDOCS --output-dir ./docs --rewrite-links

Ese flujo hace cuatro cosas en orden:

1. demuestra que la maquina esta lista
2. confirma que el espacio objetivo es el correcto
3. muestra la jerarquia antes de convertir
4. produce un arbol portable de Markdown con enlaces locales

Esa es exactamente la disciplina que los equipos necesitan cuando la exportacion esta ligada a una ventana de migracion, una revision con cliente o un compromiso de backup.

Por que el state file importa mas de lo que parece

acs2md usa .convert-sync-state.json para comparar las versiones actuales de paginas con las de ejecuciones anteriores. Eso permite que las exportaciones futuras omitan contenido sin cambios y reconviertan solo lo que realmente se movio.

Eso importa porque la herramienta no sirve solo para una migracion puntual. Tambien esta pensada para flujos recurrentes de mantenimiento.

Ese archivo hace posibles dos modos clave:

• --sync para espejos vivos que borran archivos locales si la pagina desaparece del origen
• --incremental para exportaciones tipo archivo que conservan el contenido local aunque haya borrados aguas arriba

Los dos patrones aparecen constantemente en programas reales de documentacion.

Recomendacion final

Trata acs2md como una herramienta de control y portabilidad para espacios de Confluence, no solo como un convertidor. Si tu equipo necesita exportaciones repetibles, propiedad local de la documentacion o un corpus Markdown que pueda alimentar Git, cumplimiento o flujos de IA, acs2md es un muy buen punto de partida.

Empieza por la vision general y pasa enseguida a la guia de primeros pasos y al documento sobre --sync frente a --incremental. Esa secuencia te lleva de la posicion del producto a un flujo realmente operativo.