Convertir páginas

Los comandos page convert convierten una página de Confluence a Markdown y escriben el resultado en stdout o en un archivo.

Si vas a aplicar page convert a un caso real de cliente, consulta Flujos y comandos para patrones listos para retención, runbooks, análisis de migración y preparación curada para IA.

Convertir por ID


acp2md page convert by-id PAGE_ID [flags]

El ID de página es el numero que aparece en la URL de la página de Confluence: .../pages/123456/Page+Title.

Ejemplos


# Imprime Markdown en stdout
acp2md page convert by-id 123456
 
# Guarda en un archivo
acp2md page convert by-id 123456 --output page.md
 
# Incluye cabecera de metadatos (YAML front matter)
acp2md page convert by-id 123456 --output page.md --include-metadata
 
# Convierte una versión borrador
acp2md page convert by-id 123456 --get-draft
 
# Convierte una version historica concreta
acp2md page convert by-id 123456 --version 5
 
# Salida en texto plano: elimina todo el formato (negrita, cursiva, colores)
acp2md page convert by-id 123456 --exclude-marks --output plain.md
 
# Envia el ID de página por stdin
echo "123456" | acp2md page convert by-id > page.md

Flags

Flag	Short	Predeterminado	Descripcion
`--output`	`-o`	(stdout)	Ruta del archivo de salida
`--status`	`-s`	`current`	Filtro de estado de página: `current`, `archived`, `trashed`, `deleted`, `draft`
`--version`	`-v`	`-1` (ultima)	Convierte un numero de version concreto
`--get-draft`	`-d`	`false`	Recupera la versión borrador (no publicada)
`--space-key`		(ninguno)	Clave del espacio, necesaria para algunos flags de extension (`--ext-render-recently-updated`, `--ext-render-listlabels`)
`--include-labels`	`-l`	`false`	Incluye etiquetas de página en la salida
`--include-version`	`-V`	`false`	Incluye el numero de version en la salida
`--include-versions`	`-L`	`false`	Incluye el historial completo de versiones en la salida
`--conflict-resolution`		`overwrite`	Como gestionar un archivo de salida existente: `overwrite`, `skip`, `versioned`
`--sync`		`false`	Mantiene un archivo `.convert-sync-state.json` junto a la salida y evita reconversiones cuando la versión de la página no ha cambiado. Elimina el archivo local si la página se ha retirado de Confluence. Es mutuamente excluyente con `--incremental`. No tiene efecto cuando se escribe en stdout.
`--incremental`		`true`	Igual que `--sync`, pero conserva el archivo local si la página se ha retirado de Confluence. Es mutuamente excluyente con `--sync`. No tiene efecto cuando se escribe en stdout.

Convertir por título


acp2md page convert by-title "PAGE TITLE" [flags]

Busca páginas por título exacto, sensible a mayusculas y minusculas, y convierte la mejor coincidencia. Si hay varias coincidencias, el resultado puede acotarse con --sort.

Ejemplos


# Convierte por título exacto
acp2md page convert by-title "API Reference" --output api.md
 
# Ordena por la modificacion mas reciente y toma el primer resultado
acp2md page convert by-title "Release Notes" --sort -modified-date --output notes.md
 
# Salida en texto plano para ingesta de LLM
acp2md page convert by-title "Team Guidelines" --exclude-marks --output guidelines.md
 
# Envia el título por stdin
echo "Project Overview" | acp2md page convert by-title > overview.md

Flags

Se aplican todos los flags de by-id, y ademas:

Flag	Short	Predeterminado	Descripcion
`--sort`	`-S`	(ninguno)	Ordena las coincidencias: `id`, `-id`, `created-date`, `-created-date`, `modified-date`, `-modified-date`, `title`, `-title`

Convertir por URL


acp2md page convert by-url URL [flags]

Alias: url, u

Extrae el ID de página de una URL de Confluence y convierte la página a Markdown. Es útil cuando tienes la URL del navegador y quieres evitar buscar el ID manualmente.

Formatos de URL compatibles:

https://domain.atlassian.net/wiki/spaces/KEY/pages/123456/Page+Title
https://domain.atlassian.net/wiki/spaces/KEY/pages/123456
https://domain.atlassian.net/wiki/pages/viewpage.action?pageId=123456

Ejemplos


# Convierte directamente desde una URL de Confluence
acp2md page convert by-url "https://mycompany.atlassian.net/wiki/spaces/ENG/pages/163928/API+Reference"
 
# Guarda en un archivo
acp2md page convert by-url "https://mycompany.atlassian.net/wiki/spaces/ENG/pages/163928" --output api.md
 
# También funciona con URLs viewpage
acp2md page convert by-url "https://mycompany.atlassian.net/wiki/pages/viewpage.action?pageId=163928" --output page.md
 
# Salida en texto plano
acp2md page convert by-url "https://mycompany.atlassian.net/wiki/spaces/ENG/pages/163928" --exclude-marks --output plain.md
 
# Envia la URL por stdin
echo "https://mycompany.atlassian.net/wiki/spaces/ENG/pages/163928" | acp2md page convert by-url > page.md

Flags

Se aplican todos los flags de by-id.

Flags de conversion

Estos flags están disponibles en by-id, by-title y by-url y controlan que se incluye en la salida Markdown.

Contenido y metadatos

Flag	Short	Predeterminado	Descripcion
`--include-metadata`	`-m`	`true`	Anade un bloque YAML front matter (título, autor, fechas de creación/modificacion)
`--exclude-marks`	`-x`	`true`	Elimina todo el formato en linea: negrita, cursiva, subrayado, colores y colores de fondo. Usa `--exclude-marks=false` si quieres conservar formato enriquecido.

Imagenes y multimedia

Flag	Short	Predeterminado	Descripcion
`--embed-images`	`-e`	`true`	Incrusta imagenes como URI de datos base64 (aumenta el tamano del archivo)
`--ext-embed-drawio`	`-D`	`true`	Incrusta diagramas draw.io como imagenes base64
`--ext-embed-roadmap`		`true`	Incrusta diagramas de Roadmap Planner como imagenes base64
`--embed-media-images`		`true`	Incrusta archivos multimedia de Confluence (avatares, imagenes en linea) como URI de datos base64

Pasa --embed-images=false para mantener las referencias de imagen como URLs externas en lugar de incrustarlas en linea.

Flags de extension

Flag	Predeterminado	Descripcion
`--ext-render-toc`	`true`	Genera una tabla de contenidos Markdown a partir de los encabezados del documento
`--ext-render-recently-updated`	`true`	Convierte la macro recently-updated en una lista Markdown (requiere `--space-key`)
`--ext-render-listlabels`	`true`	Convierte insignias de etiquetas (requiere `--space-key`)
`--ext-render-pagetree`	`true`	Convierte la macro pagetree en una lista Markdown anidada
`--ext-render-children`	`true`	Convierte la macro children en una lista Markdown plana
`--ext-render-contributors`	`true`	Convierte la macro contributors en una lista Markdown
`--ext-render-page-signatures`	`true`	Convierte tablas de firmas de Document Control
`--ext-render-qc-properties`	`true`	Convierte las macros de propiedades y revision QC con sus valores reales
`--ext-render-task-report`	`true`	Convierte tasks-report-macro en una tabla Markdown (requiere credenciales de Confluence)
`--ext-render-content-report`	`true`	Convierte content-report-table macro en una tabla Markdown (requiere credenciales de Confluence)
`--ext-resolve-inline-card-titles`	`true`	Resuelve enlaces de tarjetas inline de Confluence a sus títulos reales de página

Resolucion de conflictos de salida

Cuando escribes en un archivo con --output, el flag --conflict-resolution controla que ocurre si el archivo ya existe:

Valor	Comportamiento
`overwrite`	Sustituye el archivo existente (por defecto)
`skip`	Deja el archivo existente intacto y omite la conversion
`versioned`	Anade una marca temporal al nombre del archivo

Comportamiento observado al escribir a archivo

Cuando se escribe a un archivo, una ejecución real observo este comportamiento por defecto:


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

Una segunda ejecución contra el mismo archivo produjo:


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

Cabecera de metadatos

Cuando --include-metadata esta activado (por defecto), se anade un bloque YAML front matter al inicio de la salida:


---
Title: Getting Started Guide
AuthorID: 5a1b2c3d4e5f6a7b8c9d0e1f
CreatedAt: 2024-01-15 10:30:00
ID: 123456789
LastOwnerID:
OwnerID: 5a1b2c3d4e5f6a7b8c9d0e1f
ParentID: 987654321
ParentType: page
Position: 424489544
SpaceID: 278077
Status: current
SubType:
VersionAuthorID: 5a1b2c3d4e5f6a7b8c9d0e1f
VersionCreatedAt: 2024-03-10 14:22:00
VersionMessage:
VersionMinorEdit: false
VersionNumber: 6
---
 
# Getting Started Guide
 
...

El bloque de metadatos incluye:

Title — el título de la página tal como aparece en Confluence
AuthorID / OwnerID — los IDs de cuenta de Confluence del autor original y del propietario actual
CreatedAt / VersionCreatedAt — cuando se creo la página y cuando se modifico por ultima vez la versión actual
ID / SpaceID / ParentID — los identificadores de Confluence de la página, el espacio y la página padre
Status — el estado de la página (current, archived, trashed, deleted, draft)
VersionNumber — el numero de versión actual de la página

Esto es útil para generadores de sitios estaticos, seguimiento de migraciones, inventario de contenido y flujos de auditoria.

Ejemplos practicos

Exporta una página para un sitio estatico


acp2md page convert by-id 123456 \
  --include-metadata \
  --output docs/my-page.mdx

Construye una base de conocimiento RAG


acp2md page convert by-id 123456 \
  --exclude-marks \
  --embed-images=false \
  --output rag/123456.md

Archiva un borrador antes de publicarlo


acp2md page convert by-id 123456 \
  --get-draft \
  --output archive/draft-123456.md

Actualiza una exportación gobernada de forma eficiente


acp2md page convert by-id 123456 \
  --output exports/page.md \
  --sync

Pipeline de CI/CD


export ACP2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACP2MD_CONFLUENCE_USERNAME=$CONFLUENCE_USER
export ACP2MD_CONFLUENCE_API_TOKEN=$CONFLUENCE_TOKEN
 
acp2md page convert by-id "$PAGE_ID" --output "docs/$PAGE_ID.md"

Para escenarios completos en lugar de comandos aislados, sigue con Flujos y comandos.