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 pagina en ADF o Storage sin convertirla.
• Cuenta nodos ADF y marcas y lista propiedades de pagina cuando hace falta analisis fino.
• Controla metadatos, imagenes 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 pagina.

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 pagina critica para retencion, cumplimiento o revision legal.
• Inspeccionar salida nativa en ADF o Storage durante una migracion 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 busqueda interna.
• Responder rapido cuando el equipo comparte una URL y necesita la pagina exacta, no un proyecto de exportacion 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 version instalada y la ubicacion 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 conexion y credenciales
• Convertir páginas para flujos de exportación a Markdown
• 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 pagina centrada en la toma de decisiones mientras las subpaginas contienen el detalle operativo.

Resultados de negocio

Copia de seguridad y retencion

acp2md ayuda a crear copias portables de paginas criticas para el negocio en un formato neutral respecto al proveedor. Eso importa cuando un equipo necesita retencion de evidencias, respaldo de una pagina concreta o una exportacion fiable antes de editar, eliminar o mover contenido.

Continuidad de negocio y recuperación ante desastres

Para continuidad, una exportacion en Markdown es mucho mas facil de replicar, versionar y recuperar que una representacion propietaria. Los equipos pueden guardar paginas convertidas en Git, almacenamiento de objetos, archivos cifrados, regiones secundarias o repositorios internos.

Cumplimiento y soporte de auditoria

Como la salida es texto plano con metadatos opcionales, las paginas exportadas se pueden inspeccionar, clasificar, archivar y comparar con mucha mas facilidad. Eso da soporte a auditoria, controles internos, legal hold y gobernanza documental.

Preparacion para RAG y LLM

El contenido de Confluence es valioso, pero no siempre esta listo para sistemas de recuperacion. acp2md convierte paginas a un formato mas facil de fragmentar, indexar, enriquecer y reutilizar para busqueda interna, asistentes y flujos de IA.

Soberania de datos y propiedad en texto claro

Markdown es texto claro por diseno. En este contexto, eso es una ventaja.

• Tu conocimiento exportado deja de estar bloqueado dentro de un formato propietario de editor.
• Tu decides donde viven los archivos resultantes: disco local, Git interno, almacenamiento aprobado en la nube, almacenamiento de objetos regional, bovedas de respaldo o archivos fuera de linea.
• Puedes aplicar tus propios controles sobre ese contenido, incluidos cifrado en reposo, control de acceso, reglas de retencion, DLP, object lock, legal hold y requisitos de residencia regional.
• Puedes inspeccionar el contenido con herramientas estandar sin depender de una plataforma para leer tu propia documentación.

Solo lectura por diseno: acp2md 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 correcta

La primera ejecución estandar 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 validacion 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 pagina 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
• estas preparando contenido para sitios estaticos, RAG, auditorias o retencion a largo plazo

Usa page get cuando

• quieres contenido nativo de Confluence en lugar de Markdown
• necesitas atlas_doc_format para análisis de ingenieria o migración
• necesitas salida storage para depuracion o trabajo de transformacion 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 publicacion
• 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
• estas investigando propiedades anadidas por aplicaciones, estado de migración o metadatos de gobernanza

Elegir deliberadamente la forma de entrada

• by-id es la opción mas 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 mas rápida cuando soporte, cumplimiento o ingenieria comparten enlaces del navegador directamente.

Utilidades compartidas para operadores

acp2md tambien incluye los comandos de apoyo que hacen falta alrededor de la exportacion:

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