Sync e Incremental

acp2md puede mantener un archivo de estado local llamado .convert-sync-state.json junto al archivo de salida cuando usas page convert con --sync o --incremental. Esto hace que las exportaciones repetidas sean eficientes al saltar páginas cuyo contenido no ha cambiado.

Ambos modos usan el mismo archivo de estado y el mismo mecanismo de deteccion de cambios. La unica diferencia es lo que ocurre cuando una página se elimina de Confluence.

Resumen

Como funciona el archivo de estado

Cuando ejecutas un comando de conversion con cualquiera de los dos flags, acp2md:

1. Lee .convert-sync-state.json del mismo directorio que el archivo de salida
2. Compara la versión de la página en Confluence con la versión registrada en el archivo de estado
3. Si la versión es la misma, salta la descarga y la conversion por completo
4. Si la versión cambio, descarga y reconvierte la página, y actualiza el archivo de estado

El archivo de estado registra el ID de página, numero de versión, marca temporal de la versión, ruta del archivo de salida y marca temporal de conversion para cada página.

Ejemplo de archivo de estado

{
  "pages": {
    "4068212885": {
      "converted_at": "2026-04-05T13:47:56.649414+02:00",
      "version_created_at": "2025-07-29T09:27:19.031Z",
      "page_id": "4068212885",
      "title": "Git Signed Commits",
      "file_path": "site.md",
      "version_number": 50
    }
  },
  "versión": 1
}

Modo --sync

--sync esta disenado para espejos activos y copias de continuidad donde la salida local debe reflejar siempre el estado actual de Confluence. Si una página se elimina en Confluence, el archivo local también se elimina.

Primera ejecución

acp2md page convert by-id 4068212885 --sync --output site.md

🔄 Mode: sync — state file: .convert-sync-state.json

La página se descarga, se convierte a Markdown, se guarda en site.md y se crea el archivo de estado.

Segunda ejecución (sin cambios)

acp2md page convert by-id 4068212885 --sync --output site.md

🔄 Mode: sync — state file: .convert-sync-state.json
✅ Page is up-to-date, skipping conversion.

No se realiza ninguna llamada API para descargar el contenido de la página. Solo se comprueba la versión.

Cuando una página se elimina

Si la página ya no existe en Confluence, --sync elimina el archivo local site.md y borra la entrada del archivo de estado.

Cuando usar --sync

• Copias de continuidad que deben coincidir con el estado actual de Confluence
• Exportaciones programadas que alimentan un sistema que espera un espejo limpio
• Pipelines CI/CD donde archivos locales obsoletos causarian problemas

Modo --incremental

--incremental es el modo predeterminado. Esta disenado para flujos de trabajo orientados a archivo donde los archivos locales deben conservarse incluso si la página de origen se elimina de Confluence.

Primera ejecución

acp2md page convert by-id 4068212885 --incremental --output site.md

🔄 Mode: incremental — state file: .convert-sync-state.json

Se comporta igual que --sync en la primera ejecución: la página se descarga, se convierte y se crea el archivo de estado.

Segunda ejecución (sin cambios)

acp2md page convert by-id 4068212885 --incremental --output site.md

🔄 Mode: incremental — state file: .convert-sync-state.json
✅ Page is up-to-date, skipping conversion.

Mismo comportamiento de salto que --sync.

Cuando una página se elimina

Si la página ya no existe en Confluence, --incremental mantiene el archivo local site.md en disco. La entrada se elimina del seguimiento en el archivo de estado, pero el Markdown exportado se conserva.

Cuando usar --incremental

• Archivos de cumplimiento y auditoria que deben retener el contenido exportado independientemente de los cambios en el origen
• Flujos de trabajo de retencion legal donde la eliminacion de evidencia no es aceptable
• Registros historicos donde quieres una copia que sobreviva a eliminaciones en el origen

Exclusividad mutua

--sync e --incremental son mutuamente excluyentes. No puedes usar ambos en el mismo comando.

# ✅ Valido
acp2md page convert by-id 123456 --sync --output page.md
 
# ✅ Valido
acp2md page convert by-id 123456 --incremental --output page.md
 
# ❌ Invalido — mutuamente excluyentes
acp2md page convert by-id 123456 --sync --incremental --output page.md

Elegir el modo adecuado