acs2md

acs2md significa “Atlassian Confluence Space to Markdown”.

Es la herramienta de exportación a escala de espacio dentro del portafolio de Climakers. Se utiliza cuando la necesidad es una base documental gobernada, una copia de continuidad, una carga de migración o un flujo repetible sobre un espacio que tiene que seguir siendo operativo con el tiempo.

Qué hace

• Convierte todas las páginas de un espacio de Confluence a Markdown con un solo comando.
• Preserva la jerarquía del espacio como carpetas y archivos.
• Reescribe automáticamente los enlaces internos de Confluence a rutas relativas locales.
• Utiliza flujos de sync e incremental con .convert-sync-state.json para no reprocesar páginas sin cambios.
• Lista espacios accesibles e inspecciona inventarios, propiedades y permisos.
• Ejecuta comandos page convert, page get, page count y page properties desde el mismo binario cuando hace falta trabajo puntual.

Por qué los clientes lo usan

Los clientes suelen comprar acs2md cuando el problema no es una sola página, sino un patrimonio documental completo. La necesidad suele ser continuidad, migración, portabilidad, cumplimiento, IA o gobernanza a escala.

• Mantener una copia de continuidad actual de un espacio documental completo.
• Construir un archivo de recuperacion ante desastres fuera de la plataforma de origen.
• Llevar una base documental a flujos basados en Git sin perder estructura.
• Crear un corpus repetible en Markdown para RAG, búsqueda y asistentes internos.
• Ejecutar inventario, revisión de accesos e inspección de metadatos desde el mismo binario que exporta.

Instalación y configuración inicial

Si es la primera vez que usas el producto, empieza por la configuración inicial antes de entrar en comandos concretos.

La secuencia recomendada es:

1. instalar el binario publicado para la plataforma objetivo
2. comprobar la versión instalada y la ubicación de los archivos de trabajo
3. activar la licencia adquirida
4. configurar el acceso a Confluence
5. ejecutar acs2md doctor
6. descubrir el alcance con space list y space pages
7. lanzar la primera exportacion masiva real

Usa Instalación y configuración inicial como guía principal para nuevos usuarios.

Cómo usar esta documentación

Lee primero esta vista general cuando necesites decidir si el requisito es una exportación a escala de espacio, un flujo gobernado de sincronización o una tarea de inventario o gobernanza.

Después entra en la guía operativa que corresponda al trabajo:

• Instalación y configuración inicial para la primera ejecución masiva
• Configuración para la configuración de conexión y credenciales
• Convertir espacios para la exportación completa a Markdown
• Extensiones y macros para extensiones compatibles de Confluence, renderizado de macros y gestión de medios a escala de espacio
• Recuperar contenido del espacio para recuperación en formato nativo
• Listar espacios para descubrimiento e inventario
• Listar páginas para confirmar alcance y jerarquía
• Permisos del espacio para revisión de accesos
• Propiedades del espacio para inspección de metadatos
• Flujos y comandos para escenarios operativos listos para usar
• Utilidades para doctor, tree, support y completion

Esa separación mantiene esta página centrada en el modelo operativo y la toma de decisiones, no en duplicar cada flag.

Extensiones y macros compatibles

acs2md puede renderizar una amplia variedad de extensiones de Confluence, macros de marketplace, contenido incrustado y tipos de medios a lo largo de una conversión completa de un espacio. Eso incluye diagramas de draw.io y Roadmap Planner, macros de listado como Page Tree y Content by Label, macros de personas y actividad como Contributors y Task Report, macros de control documental como Page Signatures, macros de documentos QC, inline cards y medios alojados en Confluence.

Cuando un elemento sigue sin poder renderizarse con los datos disponibles en la ejecución, acs2md lo conserva como un comentario HTML seguro en lugar de descartarlo en silencio.

Usa Extensiones y macros para ver las categorías compatibles, los flags exactos de renderizado y el comportamiento de caché compartida que ayuda a mantener eficiente la resolución repetida de macros durante una exportación masiva.

Seguimiento del progreso

Las operaciones largas muestran barras de progreso en tiempo real en stderr para no interferir con la salida de stdout cuando se redirige.

• space convert muestra el progreso de conversión con el título de la página actual y el tiempo estimado restante.
• space get muestra el progreso de descarga para exportaciones en formato nativo.
• --resolve-users muestra progreso cuando se resuelven varios IDs de cuenta a nombres visibles.

Esto hace que los trabajos recurrentes de exportación sean observables sin romper la automatización. La salida de progreso permanece en stderr, por lo que los comandos que canalizan o redirigen stdout siguen siendo utilizables para automatización e informes.

Resultados de negocio

Copia de seguridad y retención a largo plazo

acs2md produce una exportación en Markdown a escala de espacio que es más fácil de guardar, replicar, comparar, auditar y archivar que una representación ligada a la plataforma. Esto da soporte a estrategias internas de copia de seguridad, escrow documental, archivos de cierre de proyecto y flujos de retención regulada.

Continuidad de negocio y recuperación ante desastres

Un plan de continuidad es más fuerte cuando el conocimiento operativo puede recuperarse fuera de la plataforma de origen. acs2md ayuda a mantener una copia actual de un espacio de Confluence en un formato que puede restaurarse, revisarse, republicarse o consultarse fuera de Confluence.

Cumplimiento y gobernanza

Las exportaciones en texto plano con una organización previsible de archivos son útiles para la recogida de evidencias, la gestión documental, los controles internos y el soporte de auditoría. Los equipos pueden aplicar etiquetas de retención, control de versiones, revisión de accesos y políticas de respaldo inmutable con las herramientas de almacenamiento y gobernanza que ya conocen.

Habilitacion para RAG y LLM

Markdown es un formato práctico para fragmentación, indexación, embeddings y recuperación. acs2md convierte un espacio de Confluence en un corpus más fácil de alimentar a flujos de IA empresarial mientras preserva estructuras útiles como títulos, listas, tablas y metadatos.

Soberanía de datos y propiedad en texto claro

acs2md exporta la documentación a archivos Markdown estándar que el cliente puede guardar y gobernar dentro de su entorno.

• Los archivos resultantes pueden quedarse en una región, un límite de red o una plataforma de almacenamiento elegida por el cliente.
• La salida es legible sin un visor propietario.
• Se pueden aplicar herramientas estándar para cifrado, DLP, legal hold, control de versiones, respaldo, clasificación y retención.
• La documentación puede moverse entre equipos, repositorios, sistemas de respaldo o proveedores cloud sin bloqueo de formato.

Markdown es texto claro. Eso es lo que hace que la exportación sea portable, revisable e interoperable. Si el corpus exportado contiene contenido sensible, debe tratarse con los mismos controles de seguridad que se aplican a otros registros confidenciales del negocio.

Solo lectura por diseño: acs2md solo lee desde Confluence. Nunca crea, modifica ni elimina páginas, espacios, propiedades, permisos ni ningún otro recurso de la instancia del cliente. Todas las llamadas API son solicitudes GET de solo lectura.

Primera ejecución masiva correcta

La primera ejecución masiva estándar sigue una secuencia previsible:

1. activa la licencia
2. configura el acceso a Confluence
3. ejecuta acs2md doctor
4. lista espacios candidatos con acs2md space list --limit 5
5. confirma el alcance con acs2md space pages by-key TEAMDOCS --format json --limit 10 o --tree
6. exporta el primer espacio con acs2md space convert by-key TEAMDOCS --output-dir ./docs-export

Ese flujo valida el entorno, confirma la base documental objetivo y produce una exportación portable en Markdown en una sola pasada.

Flujo operativo recomendado

1. activa la licencia
2. configura el acceso a Confluence
3. ejecuta acs2md doctor
4. descubre el objetivo con space list y space pages
5. usa tree --short cuando necesites un inventario compacto de la versión antes de una exportación programada o de cara al cliente
6. ejecuta space convert, space get, space properties o space permissions

Elegir el comando de espacio adecuado

Usa space convert cuando

• quieres un conjunto portable de documentación en Markdown
• estás preparando una copia de continuidad, una carga de migración, una fuente para sitio estático o un corpus RAG
• quieres preservación de jerarquía y reescritura opcional de enlaces

Usa space get cuando

• quieres cargas nativas de Confluence en lugar de Markdown
• estás haciendo ingeniería de migración o procesamiento descendente personalizado
• necesitas salida bruta en atlas_doc_format o storage para todo un espacio

Usa space list cuando

• necesitas descubrir primero los espacios disponibles
• estás construyendo un inventario o seleccionando el alcance correcto
• quieres salida estructurada para informes o planificación previa a la migración

Usa space pages cuando

• necesitas confirmar el contenido de un espacio antes de convertirlo
• quieres inspeccionar jerarquía, recuento de páginas y orden
• quieres validar el alcance con un cliente o stakeholder antes de una ejecución masiva

Usa space permissions o space properties cuando

• importa la gobernanza, la auditoría o la revisión de accesos
• necesitas metadatos de apoyo sobre el espacio, no solo el contenido

Archivo de estado y eficiencia de sincronización

Las exportaciones recurrentes de una base documental no deberían volver a descargar contenido sin cambios innecesariamente. Por eso acs2md es compatible con --sync y --incremental con .convert-sync-state.json:

• --sync actualiza las páginas cambiadas y elimina archivos locales cuando la página origen desaparece de Confluence
• --incremental actualiza las páginas cambiadas pero conserva los archivos locales aunque la página de origen se elimine después

Eso hace que la herramienta sirva tanto para espejos estrictos de continuidad como para flujos orientados a archivo.

Utilidades compartidas para operadores

acs2md incluye los mismos comandos de apoyo que reducen la fricción en ejecuciones repetibles:

• doctor para comprobaciones del entorno
• tree --short para un inventario compacto de la superficie de comandos disponible
• support para generar un paquete de diagnóstico que pueda compartirse con Climakers
• completion para configurar autocompletado de shell
• config where para localizar el archivo de configuración activo

Escenarios tipicos de cliente

Herramienta complementaria

Para convertir páginas individuales, consulta acp2md.