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.

Que hace

• Convierte todas las paginas de un espacio de Confluence a Markdown con un solo comando.
• Preserva la jerarquia del espacio como carpetas y archivos.
• Reescribe automaticamente los enlaces internos de Confluence a rutas relativas locales.
• Utiliza flujos de sync e incremental con .convert-sync-state.json para no reprocesar paginas 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 que los clientes lo usan

Los clientes suelen comprar acs2md cuando el problema no es una sola pagina, sino un patrimonio documental completo. La necesidad suele ser continuidad, migracion, 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, busqueda y asistentes internos.
• Ejecutar inventario, revision de accesos e inspeccion 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 version instalada y la ubicacion 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 conexion y credenciales
• Convertir espacios para la exportación completa a Markdown
• Recuperar contenido del espacio para recuperación en formato nativo
• Listar espacios para descubrimiento e inventario
• Listar páginas para confirmar alcance y jerarquia
• Permisos del espacio para revision 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 separacion mantiene esta pagina centrada en el modelo operativo y la toma de decisiones, no en duplicar cada flag.

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 conversion 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 automatizacion.

Resultados de negocio

Copia de seguridad y retencion a largo plazo

acs2md produce una exportación en Markdown a escala de espacio que es mas facil de guardar, replicar, comparar, auditar y archivar que una representacion ligada a la plataforma. Esto da soporte a estrategias internas de copia de seguridad, escrow documental, archivos de cierre de proyecto y flujos de retencion regulada.

Continuidad de negocio y recuperación ante desastres

Un plan de continuidad es mas 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 organizacion previsible de archivos son útiles para recogida de evidencias, gestion documental, controles internos y soporte de auditoria. Los equipos pueden aplicar etiquetas de retencion, control de versiones, revision de accesos y politicas de respaldo inmutable con las herramientas de almacenamiento y gobernanza que ya conocen.

Habilitacion para RAG y LLM

Markdown es un formato practico para fragmentacion, indexacion, embeddings y recuperación. acs2md convierte un espacio de Confluence en un corpus mas facil de alimentar a flujos de IA empresarial mientras preserva estructuras útiles como títulos, listas, tablas y metadatos.

Soberania de datos y propiedad en texto claro

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

• Los archivos resultantes pueden quedarse en una region, un limite de red o una plataforma de almacenamiento elegida por el cliente.
• La salida es legible sin un visor propietario.
• Se pueden aplicar herramientas estandar para cifrado, DLP, legal hold, control de versiones, respaldo, clasificacion y retencion.
• La documentación puede moverse entre equipos, repositorios, sistemas de respaldo o proveedores cloud sin bloqueo de formato.

Solo lectura por diseno: acs2md solo lee desde Confluence. Nunca crea, modifica ni elimina paginas, espacios, propiedades, permisos ni ningun otro recurso de la instancia del cliente. Todas las llamadas API son solicitudes GET de solo lectura.

Primera ejecucion masiva correcta

La primera ejecución masiva estandar 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 exportacion 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
• estas preparando una copia de continuidad, una carga de migración, una fuente para sitio estatico o un corpus RAG
• quieres preservacion de jerarquia y reescritura opcional de enlaces

Usa space get cuando

• quieres cargas nativas de Confluence en lugar de Markdown
• estas haciendo ingenieria 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
• estas construyendo un inventario o seleccionando el alcance correcto
• quieres salida estructurada para informes o planificacion previa a la migración

Usa space pages cuando

• necesitas confirmar el contenido de un espacio antes de convertirlo
• quieres inspeccionar jerarquia, 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 auditoria o la revision de accesos
• necesitas metadatos de apoyo sobre el espacio, no solo el contenido

Archivo de estado y eficiencia de sincronizacion

Las exportaciones recurrentes de una base documental no deberian 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 origen se elimine despues

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 friccion 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 diagnostico 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.