Funciones avanzadas de acs2md: personalizacion e integracion

El flujo principal de acs2md es intencionadamente simple: convertir un espacio a Markdown. El valor avanzado aparece cuando empiezas a moldear esa salida para el sistema aguas abajo que va a consumirla.

En ese punto los flags dejan de ser detalles cosmeticos y se convierten en decisiones de arquitectura.

La primera capa de personalizacion: contenido, enlaces y media

La documentacion de space convert organiza los controles mas importantes en tres grupos.

Contenido y metadatos

acs2md space convert by-key DOCS 
  --include-metadata 
  --exclude-marks=false 
  --output-dir ./site

• --include-metadata anade front matter YAML con titulos, autores, fechas, IDs y estado.
• --exclude-marks=true elimina formato inline para una salida mas orientada a texto plano.
• --exclude-marks=false conserva formato inline mas rico cuando el render de destino puede aprovecharlo.

Esa eleccion cambia si la exportacion esta pensada para publicacion, revision de migracion o ingestion para IA.

Enlaces

acs2md space convert by-key DOCS 
  --rewrite-links=false 
  --output-dir ./migration-review

Por defecto, acs2md reescribe URLs de Confluence a rutas locales relativas. Eso es ideal para conjuntos portables de Markdown y documentacion en Git. Desactivarlo solo tiene sentido cuando quieres archivos locales pero necesitas conservar las URLs originales.

Imagenes y media

acs2md space convert by-key KB 
  --embed-images=false 
  --embed-media-images=false 
  --output-dir ./rag-corpus

La documentacion es bastante clara: incrustar imagenes aumenta el tamano de los archivos. Si el objetivo es un pipeline orientado a texto, desactivar imagenes suele ser el tradeoff correcto.

La segunda capa: renderizado de macros y extensiones

acs2md expone un conjunto sorprendentemente util de flags para construcciones comunes de Confluence:

• --ext-render-toc
• --ext-render-recently-updated
• --ext-render-listlabels
• --ext-render-pagetree
• --ext-render-children
• --ext-render-contributors
• --ext-render-page-signatures
• --ext-render-qc-properties
• --ext-render-task-report
• --ext-render-content-report
• --ext-resolve-inline-card-titles

Esa superficie importa cuando el contenido exportado debe seguir siendo legible fuera de Confluence y no solo convertirse tecnicamente.

Por ejemplo:

acs2md space convert by-key DOCS 
  --ext-render-toc 
  --ext-render-task-report 
  --ext-resolve-inline-card-titles 
  --output-dir ./docs

Estas opciones ayudan a transformar estructuras propias de Confluence en Markdown mas util para revisar, publicar o indexar.

Patrones de integracion que aparecen en proyectos reales

La pagina de workflows de cliente deja bastante claro cuales son los usos aguas abajo. Un buen modelo mental seria este:

La idea clave es que la integracion no es un patron unico. El contrato de salida correcto depende de si el consumidor es una persona, Git, un renderer estatico o un pipeline de indexacion.

Cuando space get es la mejor jugada avanzada

Uno de los detalles mas utiles de la documentacion es la diferencia entre space convert y space get.

Usa space convert cuando quieras Markdown portable.

Usa space get cuando quieras primero el payload nativo:

acs2md space get by-key DOCS 
  --format atlas_doc_format 
  --output-dir ./native/docs

Ese es el movimiento correcto para ingenieria de migracion, depuracion de reglas propias o cualquier caso donde quieras la representacion fuente antes de comprometerte con el render a Markdown.

CI, logging y ergonomia para operadores

La documentacion de configuracion y utilidades completa los detalles de automatizacion:

• cualquier clave puede sobreescribirse con variables ACS2MD_...
• --log-file puede enviar logs a archivo, stdout o stderr
• --no-progress deja limpios los logs de CI
• tree --short sirve para runbooks y onboarding
• support crea un bundle diagnostico util para escalado

Una ejecucion programada practica se parece a esto:

export ACS2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACS2MD_CONFLUENCE_USERNAME=$CONFLUENCE_USER
export ACS2MD_CONFLUENCE_API_TOKEN=$CONFLUENCE_TOKEN

acs2md space convert by-key DOCS 
  --output-dir ./scheduled/docs 
  --sync 
  --log-file acs2md.log

Esa es la diferencia entre un comando de demo y una integracion realmente operativa.

Como conectar los flags avanzados con un pipeline de cumplimiento

Los mismos flags que personalizan la salida tambien producen evidencia de control cuando se usan dentro de un job de CI o de un runner programado.

• --log-file con --debug te da un log determinista por corrida, que es justo el artefacto que piden ISO/IEC 27001:2022 A.8.15 (logging) y NIS 2 Articulo 21(2)(f). Fija el plazo de retencion del log en tu politica de control de registros y el control queda defendible.
• --include-metadata y las opciones de front matter conservan la identidad de la fuente y las fechas. Eso permite cumplir ISO 9001:2015 clausula 7.5.3 (control de la informacion documentada) para campos como autor, revision y supersesion.
• space get --format atlas_doc_format produce un snapshot nativo de origen. Ese snapshot, junto con el Markdown renderizado, le da a SOC 2 CC8.1 (gestion de cambios) un artefacto antes/despues limpio.
• Ejecutar acs2md desde CI bajo una identidad fija, con --no-progress y logs estructurados, encaja con ISO/IEC 27001:2022 A.8.31 (separacion de entornos) y A.8.32 (gestion de cambios) cuando los entregables documentales salen de un pipeline controlado.

En resumen: la superficie avanzada tambien es la superficie de auditoria. Los flags que ibas a usar de todos modos son los que producen la evidencia.

Recomendacion final

No trates la superficie avanzada de flags como complejidad opcional. Es la capa que permite que el mismo producto alimente un flujo de publicacion en Git, un archivo de cumplimiento, una revision de ingenieria de migracion o un corpus para RAG sin fingir que esos trabajos son iguales.

Empieza decidiendo que debe hacer la salida despues de exportar. Luego elige metadatos, enlaces, media, renderizado de macros y modo de seguimiento para ajustarlo a ese contrato. Esa es la forma mas limpia de obtener Markdown util en lugar de solo Markdown convertido.