acp2md

acp2md significa “Atlassian Confluence Page to Markdown”.

Es la herramienta de precisión a nivel de página dentro del portafolio de Climakers. Se utiliza cuando la necesidad no es “exportar todo el espacio”, sino trabajar sobre una página concreta con alcance controlado, salida predecible y tratamiento posterior bajo control del cliente.

Qué hace

• Convierte una página de Confluence a Markdown por ID de página, título o URL de Confluence.
• Recupera esa misma página en ADF o Storage sin convertirla.
• Cuenta nodos ADF y marcas y lista propiedades de página cuando hace falta análisis fino.
• Controla metadatos, imágenes embebidas, renderizado de macros y conflictos de salida.
• Refresca exportaciones recurrentes con un archivo local .convert-sync-state.json junto a la salida.
• Trabaja con versiones current, draft, archived e historical de una página.

Por qué los clientes lo usan

Los clientes suelen comprar acp2md cuando una sola página concentra mucho valor operativo o regulatorio. Puede ser una política, un procedimiento, un runbook de recuperación, una página de evidencia o un documento de referencia que tiene que salir de Confluence con control total del alcance.

• Exportar una página crítica para retención, cumplimiento o revisión legal.
• Inspeccionar salida nativa en ADF o Storage durante una migración o una incidencia.
• Llevar un runbook o un procedimiento operativo a Git bajo control del cliente.
• Construir un conjunto curado de fuentes para RAG o búsqueda interna.
• Responder rápido cuando el equipo comparte una URL y necesita la página exacta, no un proyecto de exportación masivo.

Instalación y configuración inicial

Si es la primera vez que usas el producto, empieza por la ruta de configuración inicial antes de pensar 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 acp2md doctor
6. validar el alcance con space list y space pages
7. lanzar la primera exportacion 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 entender dónde encaja acp2md dentro del conjunto de herramientas de Climakers y qué flujo de página corresponde al trabajo.

Después pasa a la guía que mejor se ajuste a la operación real:

• Instalación y configuración inicial para la primera ejecución correcta
• Configuración para la configuración de conexión y credenciales
• Convertir páginas para flujos de exportación a Markdown
• Extensiones y macros para extensiones compatibles de Confluence, renderizado de macros y gestión de medios
• Recuperar páginas para recuperación nativa en ADF o Storage
• Conteo y análisis para análisis estructural de ADF
• Propiedades de página para inspección de metadatos
• Flujos y comandos para escenarios operativos listos para usar
• Utilidades para doctor, tree, support y completion

Esa estructura mantiene esta página centrada en la toma de decisiones mientras las subpáginas contienen el detalle operativo.

Extensiones y macros compatibles

acp2md puede renderizar una amplia variedad de extensiones de Confluence, macros de marketplace, contenido incrustado y tipos de medios, en lugar de reducirlos a marcadores opacos. Eso incluye diagramas de draw.io y Roadmap Planner, macros de listado como Page Tree y Recently Updated, 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 no puede renderizarse con el contexto disponible para esa ejecución, acp2md 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 los requisitos de contexto a nivel de página para las macros que dependen de información del espacio.

Resultados de negocio

Copia de seguridad y retención

acp2md ayuda a crear copias portables de páginas críticas para el negocio en un formato neutral respecto al proveedor. Eso importa cuando un equipo necesita retención de evidencias, respaldo de una página concreta o una exportación fiable antes de editar, eliminar o mover contenido.

Continuidad de negocio y recuperación ante desastres

Para continuidad, una exportación en Markdown es mucho más fácil de replicar, versionar y recuperar que una representación propietaria. Los equipos pueden guardar páginas convertidas en Git, almacenamiento de objetos, archivos cifrados, regiones secundarias o repositorios internos.

Cumplimiento y soporte de auditoría

Como la salida es texto plano con metadatos opcionales, las páginas exportadas se pueden inspeccionar, clasificar, archivar y comparar con mucha más facilidad. Eso da soporte a auditoría, controles internos, legal hold y gobernanza documental.

Preparación para RAG y LLM

El contenido de Confluence es valioso, pero no siempre está listo para sistemas de recuperación. acp2md convierte páginas a un formato más fácil de fragmentar, indexar, enriquecer y reutilizar para búsqueda interna, asistentes y flujos de IA.

Soberanía de datos y propiedad en texto claro

Markdown es texto claro por diseño. En este contexto, eso es una ventaja.

• Tu conocimiento exportado deja de estar bloqueado dentro de un formato propietario de editor.
• Decides dónde viven los archivos resultantes: disco local, Git interno, almacenamiento aprobado en la nube, almacenamiento de objetos regional, bóvedas de respaldo o archivos fuera de línea.
• Puedes aplicar tus propios controles sobre ese contenido, incluidos el cifrado en reposo, el control de acceso, las reglas de retención, DLP, object lock, legal hold y los requisitos de residencia regional.
• Puedes inspeccionar el contenido con herramientas estándar sin depender de una plataforma para leer tu propia documentación.

Nota importante: como la salida es Markdown en texto claro, las exportaciones sensibles deben almacenarse en los mismos entornos protegidos que usas para otros registros confidenciales del negocio.

Solo lectura por diseño: acp2md 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.

Archivo de estado, sync y eficiencia incremental

Las exportaciones recurrentes de una página no deberían volver a descargar contenido sin cambios innecesariamente. Por eso acp2md puede mantener un archivo local .convert-sync-state.json junto a la salida.

• --sync actualiza la página cuando cambia y elimina el archivo local si la página origen desaparece de Confluence.
• --incremental actualiza la página cuando cambia pero conserva el archivo local aunque la página origen desaparezca más adelante.
• las exportaciones repetidas siguen siendo prácticas para páginas de alto valor que necesitan refresco controlado con el tiempo.

Esto hace que acp2md sea útil no solo para exportaciones puntuales, sino también para flujos de continuidad y de archivo orientados a páginas.

Primera ejecución correcta

La primera ejecución estándar es deliberadamente simple:

1. activa la licencia
2. configura el acceso a Confluence
3. ejecuta acp2md doctor
4. descubre el espacio con acp2md space list
5. confirma el alcance con acp2md space pages by-key DOCS --limit 25
6. exporta una página con acp2md page convert by-id 123456 -o ./page.md

Eso da un camino operativo limpio desde la validación del entorno hasta la primera salida portable en Markdown.

Flujo operativo recomendado

1. activa la licencia
2. configura el acceso a Confluence
3. ejecuta acp2md doctor
4. descubre el espacio y la página correctos con space list y space pages
5. usa tree --short cuando necesites un inventario compacto de comandos antes de una ejecución orientada al cliente
6. elige el comando de página adecuado: convert, get, count o properties

Elegir el comando de página adecuado

Usa page convert cuando

• quieres una salida legible en Markdown
• quieres guardar una página en Git, almacenamiento de objetos o una pipeline de contenido
• estás preparando contenido para sitios estáticos, RAG, auditorías o retención a largo plazo

Usa page get cuando

• quieres contenido nativo de Confluence en lugar de Markdown
• necesitas atlas_doc_format para análisis de ingeniería o migración
• necesitas salida storage para depuración o trabajo de transformación personalizado

Usa page count cuando

• quieres estimar la complejidad de una página antes de una migración
• quieres inspeccionar la riqueza de formato antes de una ingesta de IA o una publicación
• necesitas un perfil estructural rápido de títulos, tablas, listas, marcas o macros

Usa page properties cuando

• necesitas metadatos de página en lugar de contenido
• estás investigando propiedades añadidas por aplicaciones, estado de migración o metadatos de gobernanza

Elegir deliberadamente la forma de entrada

• by-id es la opción más determinista cuando ya conoces la página exacta.
• by-title es útil cuando conoces el título pero no el ID de la página.
• by-url es la opción más rápida cuando soporte, cumplimiento o ingeniería comparten enlaces del navegador directamente.

Utilidades compartidas para operadores

acp2md también incluye los comandos de apoyo que hacen falta alrededor de la exportación:

• doctor para validar el entorno
• tree --short para descubrir rápidamente los comandos antes de un runbook o una demo
• 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 operaciones masivas sobre un espacio completo, consulta acs2md, el convertidor de espacios.