Convertir espacios

Los comandos space convert exportan un espacio completo de Confluence, con todas sus páginas, a un directorio de archivos Markdown. La jerarquía de páginas se conserva automáticamente como subdirectorios anidados.

Este es el flujo operativo principal de acs2md y la razón principal por la que la mayoría de equipos licencia el producto.

Convertir por clave

acs2md space convert by-key SPACE_KEY [flags]

La clave del espacio es el identificador corto visible en la URL de Confluence: .../wiki/spaces/MYSPACE/. También aparece en la salida de acs2md space list.

Ejemplos

# Convierte al directorio de salida predeterminado
acs2md space convert by-key MYSPACE
 
# Convierte a un directorio concreto
acs2md space convert by-key MYSPACE --output-dir ./docs
 
# Construye una base de conocimiento RAG, texto plano sin imágenes
acs2md space convert by-key MYSPACE \
  --exclude-marks=true \
  --embed-images=false \
  --output-dir ./rag-knowledge-base
 
# Incluye solo páginas publicadas actualmente
acs2md space convert by-key MYSPACE --status current --output-dir ./docs
 
# Desactiva la reescritura de enlaces internos
acs2md space convert by-key MYSPACE --rewrite-links=false --output-dir ./site
 
# Sincronización incremental: solo reconvierte páginas cambiadas y conserva archivos eliminados
acs2md space convert by-key MYSPACE --incremental --output-dir ./docs
 
# Sincronización completa: reconvierte páginas cambiadas y elimina archivos de páginas retiradas
acs2md space convert by-key MYSPACE --sync --output-dir ./docs

Flags

Convertir por ID

acs2md space convert by-id SPACE_ID [flags]

Convierte un espacio identificado por su ID numérico en lugar de su clave. Usa los mismos flags que by-key.

acs2md space convert by-id 65539 --output-dir ./docs

Flags de conversión

Estos flags están disponibles tanto en by-key como en by-id y controlan como se renderiza cada página.

Contenido y metadatos

Imágenes y multimedia

Obsidian y estilo de salida

Flags de extensión

Rendimiento

space convert convierte 4 páginas a la vez por defecto. La conversión está limitada por la red — varias llamadas a la API por página — así que solapar unas cuantas páginas oculta la mayor parte de la latencia por página.

# Súbelo para un espacio grande en un tenant tolerante
acs2md space convert by-key DEVOPS --output-dir ./docs --concurrency 8
 
# Restaura la conversión estrictamente secuencial
acs2md space convert by-key DEVOPS --output-dir ./docs --concurrency 1

El techo útil es el límite de peticiones de tu tenant de Confluence, no el número de núcleos de CPU, y por eso el valor por defecto es deliberadamente modesto. Subirlo es seguro porque el cliente HTTP respeta la cabecera Retry-After: cuando Confluence responde a una petición limitada con 429 o 503 e indica un retardo, el cliente espera exactamente ese tiempo en lugar de adivinarlo. Es el servidor quien marca el ritmo, en vez de que el cliente lo descubra fallando.

Cada comando informa además de cuánto ha tardado:

✅ Sync complete!
  ✅ Converted: 835
  ❌ Failed: 0
  🔗 Links rewritten: 835 files
  📂 Output: ~/tmp/docs-sec-obsidian/SEC
  ⏱️  Took: 2m 14s

La cifra cubre el comando completo, incluidas las llamadas a la API y las descargas de imágenes.

Reporte de progreso

Las conversiones largas muestran una barra de progreso en tiempo real en stderr con el título actual de la página, el porcentaje completado y el tiempo estimado restante. Esto no interfiere con la salida en stdout que pueda redirigirse a un archivo.

Esa separacion es importante para la automatizacion porque mantiene visibilidad del progreso para humanos sin corromper la salida redirigida.

Si necesitas una transcripcion limpia para CI, demos o capturas de documentación, usa el flag global --no-progress.

Ejecución observada de conversión (anonimizada)

La siguiente salida se capturo de una ejecución real en macOS contra un espacio pequeño y actual, con el nombre y la clave del espacio anonimizados:

📚 Converting space: Team Documentation (TEAMDOCS)
📂 Output directory: /tmp/acs2md-doc-sample

🔄 Mode: incremental — state file: /tmp/acs2md-doc-sample/.convert-sync-state.json

🔍 Fetching page metadata for sync...
  📥 Fetched metadata for 6 pages ✅

📋 Found 6 page(s) to convert (0 up-to-date)

✅ Sync complete!
  ✅ Converted: 6
  ❌ Failed: 0
  ✅ Up-to-date (skipped): 0
  🗑️  Removed from tracking: 0
  🔗 Links rewritten: 1 files
  📂 Output: /tmp/acs2md-doc-sample

Una segunda ejecución contra el mismo directorio de salida produjo:

📚 Converting space: Team Documentation (TEAMDOCS)
📂 Output directory: /tmp/acs2md-doc-sample

🔄 Mode: incremental — state file: /tmp/acs2md-doc-sample/.convert-sync-state.json

🔍 Fetching page metadata for sync...
  📥 Fetched metadata for 6 pages ✅

✅ All pages are up-to-date.

✅ Sync complete!
  ✅ Up-to-date (skipped): 6
  🗑️  Removed from tracking: 0
  📂 Output: /tmp/acs2md-doc-sample

Flujos que combinan espacios y páginas

acs2md también incluye comandos a nivel de página para que los equipos combinen exportación masiva con inspección dirigida desde el mismo binario.

• acs2md page convert by-id, by-title, by-url
• acs2md page get by-id, by-title, by-url
• acs2md page count nodes, page count marks y page properties

Estructura de salida

acs2md crea subdirectorios que reflejan el árbol de páginas de Confluence. Cada página se convierte en un archivo Markdown y las páginas hijas se colocan dentro de una carpeta con el nombre de su página padre.

./output/TEAMDOCS/
├── .convert-sync-state.json
├── Team_Documentation.md
└── Team_Documentation/
  ├── Architecture_decisions.md
  ├── Change_log.md
  ├── Meeting_notes.md
  ├── Product_requirements.md
  └── Retrospectives.md

Los nombres de archivo se derivan de los títulos de página y los conflictos se resuelven usando la estrategia de --conflict-resolution.

Que el archivo Markdown raiz y la carpeta hija compartan el mismo título de página no es teorico; esa estructura salio directamente de una exportación real.

Resolución de conflictos de salida

Cuando dos páginas del espacio generan el mismo nombre de archivo, --conflict-resolution controla el comportamiento:

Modo sync e incremental

En la versión actual documentada, acs2md space convert by-key se observo arrancando en modo incremental cuando no se pasa ni --incremental ni --sync. La herramienta rastrea versiones de página en un archivo .convert-sync-state.json dentro del directorio de salida y solo reconvierte páginas que han cambiado desde la última ejecución.

Los dos flags son mutuamente excluyentes.

Archivo de estado de ejemplo

El archivo de estado creado por la exportación real tenia esta forma tras anonimizarlo:

{
  "last_sync_at": "2026-03-29T10:55:33.744109+02:00",
  "pages": {
    "100101": {
      "converted_at": "2026-03-29T10:55:31.313290+02:00",
      "version_created_at": "2024-01-15T09:00:00.000Z",
      "page_id": "100101",
      "title": "Team Documentation",
      "file_path": "/tmp/acs2md-doc-sample/Team_Documentation.md",
      "version_number": 3
    }
  },
  "space_id": "100001",
  "version": 1
}

Patrones de uso recomendados

• Usa --sync cuando el directorio de salida deba permanecer como un espejo exacto y vivo del espacio de origen.
• Usa --incremental cuando quieras una copia de continuidad o de archivo que conserve contenido eliminado localmente.
• Usa --rewrite-links=false solo cuando no necesites portabilidad local.
• Ejecuta space pages --tree antes de la primera exportación grande si necesitas validar el alcance con stakeholders.

Ejemplos prácticos

Migración completa de un espacio a un sitio estático

acs2md space convert by-key DOCS \
  --include-metadata \
  --output-dir ./site/docs

Base de conocimiento para IA (texto plano, sin imágenes)

acs2md space convert by-key KB \
  --exclude-marks \
  --embed-images=false \
  --ext-render-toc=false \
  --output-dir ./rag

Backup nocturno mediante CI/CD

#!/bin/bash
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 "./backup/$(date +%Y-%m-%d)" \
  --log-file acs2md.log

Sincronización incremental en CI/CD

# Solo reconvierte páginas cambiadas y conserva archivos de páginas retiradas
acs2md space convert by-key DOCS \
  --incremental \
  --output-dir ./docs
 
# Solo reconvierte páginas cambiadas y elimina archivos de páginas retiradas
acs2md space convert by-key DOCS \
  --sync \
  --output-dir ./docs

Exportación orientada a archivo que conserva páginas retiradas

acs2md space convert by-key DOCS \
  --incremental \
  --output-dir ./archive/docs

Exportación sin reescritura de enlaces

# Conserva las URLs originales de Confluence en lugar de reescribirlas a rutas locales
acs2md space convert by-key MYSPACE \
  --rewrite-links=false \
  --output-dir ./export

Para orientación por escenarios en lugar de comandos individuales, sigue con Flujos y comandos.