Extensiones y macros compatibles
acs2md convierte el formato Atlassian Document Format (ADF) mediante el motor de conversión de Climakers. Ese motor reconoce un catálogo amplio de extensiones de Confluence, macros de aplicaciones del marketplace, embeds y tipos de multimedia, y decide elemento a elemento si renderiza contenido real recuperado de Confluence o si conserva el elemento original como un comentario HTML seguro.
Cómo se renderiza una extensión
Toda extensión reconocida pasa por tres desenlaces posibles, en este orden:
- Renderizado con la API en vivo. La opción
--ext-*o--embed-*está activada y están disponibles las credenciales y el contexto necesarios (clave de espacio, ID de página). La macro se sustituye por contenido real: una tabla Markdown, una lista de páginas resueltas, una imagen en base64. - Marcador de posición como comentario HTML. La extensión está desactivada, faltan credenciales o la llamada a la API falló. El conversor emite un comentario como
<!-- Page Tree -->. Es invisible en el Markdown renderizado, pero deja constancia de que existía una macro en esa posición, así los flujos de auditoría y migración no pierden información. - Degradación elegante. En las extensiones de tipo imagen, una descarga fallida recurre a una referencia simple —
media://UUIDo la URL original de Confluence — de modo que el documento nunca queda roto.
Por eso es seguro dejar activada cualquier extensión que dependa de la API. Cuando el acceso a la API no está configurado, el peor caso es un comentario HTML: nunca un error en tiempo de ejecución ni una macro que desaparece sin avisar.
Qué acceso a Confluence necesita cada extensión
La mayoría de las extensiones necesitan acceso a la API para resolver contenido. Configúralo una vez mediante el archivo de configuración, variables de entorno u opciones persistentes — consulta Configuración.
| Ajuste | Lo necesitan | Notas |
|---|---|---|
confluence.domain | Todas las extensiones que usan la API | p. ej. tu-tenant.atlassian.net |
confluence.username | Todas las extensiones que usan la API | La dirección de correo de la cuenta de Atlassian |
confluence.api_token | Todas las extensiones que usan la API | Se crea en id.atlassian.com |
--space-key | Recently Updated, List Labels, Blog Posts, Content by Label, Task Report | Recurre al parámetro spaces / spaceKey de la propia macro cuando existe. space convert by-key ya lo aporta. |
| Contexto de ID de página | Page Tree, Children, Contributors, Page Signatures, QC Properties | Lo aportan automáticamente todos los comandos space convert y page convert |
Cuando faltan las credenciales o el contexto de una extensión concreta, solo esa extensión se degrada a comentario HTML y se registra un aviso. Las demás extensiones de la página se siguen renderizando.
Matriz de compatibilidad
El inventario canónico. Los nombres de opción son la forma CLI que aceptan acs2md y acp2md.
| Extensión de Confluence | Qué produce | Opción | Predeterminado | Requiere |
|---|---|---|---|---|
| Imágenes en línea (cualquier URL) | URI de datos base64 | --embed-images | true | Acceso HTTP |
| Archivos multimedia de Confluence | URI de datos base64 | --embed-media-images | true | Credenciales |
| Multimedia de Confluence como sidecar | Archivos sidecar + imagen Markdown | --image-sidecars | false (activo con --obsidian) | Credenciales |
| Adjuntos que no son imágenes | Archivos sidecar + enlace Markdown | siempre activo con credenciales | activo | Credenciales |
| Diagramas de Draw.io | PNG en base64 | --ext-embed-drawio, -D | true | Credenciales |
| Roadmap Planner | PNG en base64 | --ext-embed-roadmap | true | Credenciales |
| Table of Contents | Lista de anclajes Markdown | --ext-render-toc | true | — |
| Recently Updated | Lista de viñetas Markdown | --ext-render-recently-updated | true | Credenciales + clave de espacio |
| List Labels | Insignias de etiqueta enlazadas | --ext-render-listlabels | true | Credenciales + clave de espacio |
| Page Tree | Lista Markdown anidada | --ext-render-pagetree | true | Credenciales + ID de página |
| Children | Lista plana o anidada | --ext-render-children | true | Credenciales + ID de página |
| Contributors | Lista Markdown de usuarios | --ext-render-contributors | true | Credenciales + ID de página |
| Content by Label | Lista Markdown de páginas | --ext-render-content-report | true | Credenciales |
| Blog Posts | Lista Markdown de entradas | se resuelve automáticamente | true | Credenciales + clave de espacio |
| Page Signatures | Tabla Markdown | --ext-render-page-signatures | true | Credenciales + ID de página |
| QC Property | Valor resuelto en línea | --ext-render-qc-properties | true | Credenciales + ID de página |
| QC Revision | Valor resuelto en línea | --ext-render-qc-properties | true | Credenciales + ID de página |
| Task Report | Tabla Markdown | --ext-render-task-report | true | Credenciales + clave de espacio |
| Content Report Table | Tabla Markdown | --ext-render-content-report | true | Credenciales |
| CQL Query | Lista Markdown, o una tabla cuando la macro pide columnas | --ext-render-cql-query | true | Credenciales |
| Excerpt | Texto del cuerpo en línea | siempre activo | true | — |
| Anchor | Destino de anclaje Markdown | siempre activo | activo | — |
| Inline cards | Enlace con el título de página resuelto | --ext-resolve-inline-card-titles | true | Credenciales |
| Embed y block cards | Enlace legible de Jira, Confluence o YouTube | se resuelve automáticamente | true | Credenciales |
Extensiones con cuerpo (expand, …) | Contenido del cuerpo + marcador de comentario | siempre activo | comentario activo | — |
Extensiones en línea (status, livesearch, …) | Comentario HTML como marcador | siempre activo | comentario activo | — |
| Otras macros de Confluence | Comentario HTML como marcador | siempre activo | comentario activo | — |
| Extensiones ADF genéricas | Comentario HTML como marcador | siempre activo | comentario activo | — |
| Create from Template | Etiqueta de texto plano | siempre activo | comentario activo | — |
Cómo leer los valores por defecto. Todas las opciones --ext-*,
--embed-* e --include-* vienen activadas. Usa --flag=false para
desactivarla en una ejecución concreta, o define la clave de configuración o
la variable de entorno equivalente para hacerlo permanente.
Imágenes y multimedia
Imágenes en línea
--embed-images (por defecto true) descarga todas las imágenes remotas a las que hace referencia la página y las incrusta como URI de datos base64. El Markdown resultante es autónomo: no depende del servidor de Confluence, de una CDN privada ni del acceso a la red en el momento de leerlo.
Se incrustan: los archivos con extensión de imagen (.png, .jpg, .jpeg, .gif, .webp, .svg, .bmp, .ico), los hosts de imágenes conocidos y cualquier URL cuyo Content-Type empiece por image/.
Se omiten a propósito: las URL de YouTube y otros vídeos, las páginas HTML, los PDF y demás binarios que no son imágenes.
El base64 aumenta el tamaño en bytes alrededor de un 33 %: es el coste normal de un documento autónomo.
Archivos multimedia alojados en Confluence
ADF representa las imágenes subidas, los avatares y los iconos como nodos multimedia con un UUID y una referencia collection del tipo contentId-393325. Sin acceso a la API solo pueden renderizarse como marcadores media://UUID.
Con --embed-media-images activo y las credenciales configuradas, acs2md extrae el ID de página del atributo collection, llama una vez por página a la API de adjuntos (con caché), descarga cada adjunto coincidente y lo incrusta. Una descarga fallida recurre a  en lugar de romper el documento.
Formatos admitidos: PNG, JPEG, GIF, WebP, SVG, BMP, ICO.
Archivos sidecar en lugar de base64
--image-sidecars escribe los bytes en attachments/<page-id>/<filename> y los enlaza de forma relativa:
La exportación sigue siendo autónoma en ambos casos: lo que cambia es la longitud de línea. Consulta Bóvedas de Obsidian para ver por qué una URI de datos de 100 KB en una sola línea deja de renderizarse allí pero funciona en GitHub. Los fallos recurren primero a base64 y después a la URL remota.
Adjuntos que no son imágenes
Los PDF, .docx, .xlsx, .pptx, archivos ZIP y similares se resuelven con la misma API de adjuntos, pero se renderizan como enlaces Markdown normales. Los bytes se descargan una vez y se guardan junto al Markdown:
[MBR Conversion User Guide.pdf](attachments/5814878215/MBR%20Conversion%20User%20Guide.pdf)
[Quarterly KPI workbook.xlsx](attachments/5814878215/Quarterly%20KPI%20workbook.xlsx)- Los archivos aterrizan en
attachments/<page-id>/<nombre-original>, de modo que los adjuntos de muchas páginas comparten un directorio de salida sin colisionar. - Se conservan los nombres originales; los caracteres inseguros en Linux, macOS o Windows se sustituyen por
_. Los hrefs se codifican en porcentaje, así que los espacios y los paréntesis siguen produciendo enlaces que funcionan. - Un archivo de destino que ya existe no se vuelve a descargar: el sistema de archivos hace de caché.
- Una descarga fallida recurre a la URL remota de Confluence con un aviso, así la salida nunca queda rota.
El tipo de archivo se clasifica primero por el tipo de medio que informa Confluence, después por inspección de bytes mágicos (PDF, ZIP / Office Open XML, OLE, RTF, 7z, gzip, tar) y por último por la extensión del nombre.
Esta es la forma recomendada de empaquetar contenido de Confluence para revisión sin conexión, entrega de auditoría o archivado en Git: el Markdown y sus adjuntos forman un único paquete portátil.
Diagramas
| Macro | Opción | Salida |
|---|---|---|
| Draw.io | --ext-embed-drawio, -D | PNG en base64 del diagrama renderizado |
| Roadmap Planner | --ext-embed-roadmap | PNG en base64 del roadmap renderizado |
Ambos necesitan credenciales de Confluence, porque la imagen renderizada se recupera del tenant en lugar de reconstruirse en local. Ambos recurren a un comentario HTML cuando no se pueden resolver.
Macros que listan páginas
| Macro | Opción | Salida | Necesita |
|---|---|---|---|
| Page Tree | --ext-render-pagetree | Lista Markdown anidada de descendientes | ID de página |
| Children | --ext-render-children | Lista plana o anidada de páginas hijas | ID de página |
| Recently Updated | --ext-render-recently-updated | Lista de páginas cambiadas recientemente | Clave de espacio |
| Blog Posts | se resuelve automáticamente | Lista de entradas | Clave de espacio |
| Content by Label | --ext-render-content-report | Lista de páginas con esa etiqueta | Credenciales |
| List Labels | --ext-render-listlabels | Insignias de etiqueta enlazadas | Clave de espacio |
Una conversión de espacio completo ya aporta el contexto de espacio que necesitan estas macros. Al convertir con by-id, pasa --space-key para que puedan resolverse las que lo requieren.
Personas, actividad e informes
| Macro | Opción | Salida |
|---|---|---|
| Contributors | --ext-render-contributors | Lista Markdown de usuarios que han contribuido |
| Task Report | --ext-render-task-report | Tabla Markdown de tareas |
| Content Report Table | --ext-render-content-report | Tabla Markdown del contenido coincidente |
| CQL Query | --ext-render-cql-query | Lista Markdown de resultados enlazados, o una tabla cuando la macro pide columnas |
Control documental y calidad
| Macro | Opción | Salida |
|---|---|---|
| Page Signatures | --ext-render-page-signatures | Tabla de firmas, o una tabla de revisores como alternativa |
| QC Property | --ext-render-qc-properties | El valor resuelto, en línea |
| QC Revision | --ext-render-qc-properties | El valor resuelto, en línea |
Estas macros resuelven los marcadores de plantilla con los metadatos reales de la página, que es lo que hace legible un documento controlado fuera de Confluence.
Cards y embeds
| Elemento | Opción | Salida |
|---|---|---|
| Inline cards | --ext-resolve-inline-card-titles | Un enlace con el título real de la página en lugar de una URL desnuda |
| Embed y block cards | se resuelve automáticamente | Enlaces legibles de Jira, Confluence o YouTube |
La resolución de inline cards es además la base de --wikilinks: necesita un título real antes de poder emitir [[Título de la página]].
Degradación sin pérdida
Los anclajes, los excerpts, las extensiones con cuerpo (expand y compañía), las extensiones en línea (status, livesearch) y cualquier macro que el motor no admita de forma específica se conservan como comentarios HTML. No se descarta nada en silencio: una auditoría de migración puede seguir localizando todas las posiciones donde había una macro.
Cumplimiento de los estándares Markdown
La salida se escribe para satisfacer los linters de Markdown más habituales:
| Regla | Tratamiento |
|---|---|
| MD009 sin espacios finales | Se eliminan; se conservan los saltos de línea duros |
| MD012 sin líneas en blanco múltiples | Se colapsan |
| MD022 líneas en blanco alrededor de encabezados | Se insertan antes de cada elemento de bloque |
| MD028 sin líneas en blanco entre citas | Se fusionan |
| MD031 líneas en blanco alrededor de bloques de código | Se insertan antes de la valla de apertura |
| MD032 líneas en blanco alrededor de listas | Se insertan antes de cada lista de primer nivel |
| MD040 lenguaje en la valla de código | Se aporta un lenguaje por defecto |
| MD045 texto alternativo de imagen | Recurre a image cuando ADF no aporta ninguno |
| MD047 un único salto de línea final | Se aplica siempre |
También se emite sintaxis extendida que conservan GitHub, Obsidian y Pandoc: resaltado, superíndice y subíndice, enlazado automático de URL, alineación de tabla GFM por columna, paneles como alerts o callouts (--panel-style), fórmulas matemáticas ($…$ y $$…$$), IDs de encabezado para enlaces de anclaje y notas al pie.
Caché, límites de tamaño y credenciales
Varias extensiones descargan bytes o realizan llamadas REST. Dos ajustes controlan con qué intensidad se cachean los resultados:
| Ajuste | Predeterminado | Lo usan |
|---|---|---|
--image-cache-dir | <output-dir>/<space-key>/.image_cache/ | --embed-images, --embed-media-images, --ext-embed-drawio, --ext-embed-roadmap |
--image-max-size-bytes | 2097152 (2 MB) | Todas las opciones de incrustación anteriores: una descarga mayor conserva su URL original |
Los sidecar de adjuntos usan el propio directorio de salida como caché: un archivo que ya está en disco no se vuelve a recuperar.
--image-max-size-bytes vale 2 MB por defecto. Las imágenes por encima de ese
tamaño conservan su URL de Confluence en lugar de incrustarse, lo que significa
que esas imágenes concretas necesitan credenciales y acceso a la red para
verse. Sube el límite si te importa más una exportación totalmente sin conexión
que el tamaño de la salida.
Cuando --sync o --incremental está activo, acs2md imprime la ruta del archivo de estado y la de la caché de imágenes antes de empezar la conversión, para que puedas confirmar dónde van a aterrizar los artefactos.
Cuándo desactivar una extensión
| Situación | Qué pasar |
|---|---|
| Construir un índice RAG o de búsqueda: quieres texto, no imágenes | --embed-images=false --embed-media-images=false |
| La salida tiene que ser pequeña y quien la lee ya tiene acceso a Confluence | --embed-images=false |
| Una macro se resuelve despacio en un espacio grande y no la necesitas | Desactiva ese --ext-render-* concreto |
| Necesitas que la exportación sea reproducible e independiente de la API | Desactiva todos los --ext-render-*; las macros pasan a ser comentarios |
| La conversión está limitada por la resolución de macros | Desactiva primero las macros que listan páginas: son las que más llamadas a la API cuestan |
Cada --ext-render-* cuesta llamadas adicionales a la API, porque la macro se resuelve contra Confluence en lugar de leerse del cuerpo de la página. En un espacio grande ese es el coste dominante.
Consulta también
- Convertir espacios — la referencia completa de opciones
- Bóvedas de Obsidian — cómo se renderiza todo esto en una bóveda
- Configuración — credenciales, proxy y ajustes de reintentos