Configuración

Este modelo de configuración aplica solo a Atlassian Confluence Cloud. acp2md no es compatible con Confluence Server ni Confluence Data Center.

Las versiones publicadas están disponibles actualmente solo para macOS y Linux. No hay artefactos publicados para Windows en la versión actual.

acp2md aplica la configuración desde cuatro fuentes, en orden creciente de prioridad:

Prioridad	Fuente	Ejemplo
1 (mas baja)	Valores integrados por defecto
2	Archivo de configuración	(ver mas abajo)
3	Variables de entorno	`ACP2MD_CONFLUENCE_DOMAIN`
4 (mas alta)	Flags de CLI	`--log-level debug`

En la practica, esto te permite mantener ajustes estables en el archivo de configuración, inyectar secretos mediante variables de entorno y sobrescribir el comportamiento por ejecución con flags de CLI.

Ubicacion del archivo de configuración

La ubicacion predeterminada del archivo de configuración depende del sistema operativo. Ejecuta:


acp2md config where

Uso recomendado:

mantener los valores no secretos en el archivo de configuración
inyectar secretos mediante variables de entorno siempre que sea posible
reservar los flags de CLI para sobrescrituras por ejecución y depuracion

Para crear un archivo de configuración con todos los valores por defecto rellenados:


acp2md config create

macOS

~/Library/Application Support/acp2md/

- - - - config.yaml
      - license.bin

Referencia completa del archivo de configuración


# Confluence connection
confluence:
  domain: mycompany.atlassian.net # Dominio de tu instancia de Confluence
  username: you@example.com # Correo de tu cuenta de Atlassian
  api_token: YOUR_API_TOKEN # Token API de id.atlassian.com
 
# HTTP client behaviour
http:
  client:
    max_retries: 3 # Numero de reintentos en caso de error
    base_timeout: 10ms # Tiempo de espera inicial de la petición
    max_timeout: 100ms # Tiempo de espera máximo tras reintentos
    proxy: "" # URL del proxy HTTP (por ej. http://proxy.corp:8080)
 
# Logging
log:
  level: info # debug | info | warn | error
  format: text # text | json
  file:
    "" # Ruta del archivo de log; stdout | stderr | /path/to/file.log
    # Cada ejecución trunca el archivo
 
# Debug mode
debug:
  enabled: false # Activa salida de depuracion detallada
  dir: debug # Directorio para artefactos de depuracion
 
# Image handling
image:
  cache_dir: "" # Directorio para cachear imagenes descargadas
  max_size_bytes: 10485760 # Tamano máximo por imagen (por defecto 10 MB)

Variables de entorno

Cada clave de configuración se puede definir con una variable de entorno anadiendo el prefijo ACP2MD_ y sustituyendo . por _:

Variable de entorno	Clave de configuración	Descripcion
`ACP2MD_CONFLUENCE_DOMAIN`	`confluence.domain`	Dominio de la instancia de Confluence
`ACP2MD_CONFLUENCE_USERNAME`	`confluence.username`	Correo de la cuenta de Atlassian
`ACP2MD_CONFLUENCE_API_TOKEN`	`confluence.api_token`	Token API de Confluence
`ACP2MD_HTTP_CLIENT_MAX_RETRIES`	`http.client.max_retries`	Numero de reintentos
`ACP2MD_HTTP_CLIENT_BASE_TIMEOUT`	`http.client.base_timeout`	Tiempo de espera base de la petición
`ACP2MD_HTTP_CLIENT_MAX_TIMEOUT`	`http.client.max_timeout`	Tiempo de espera máximo
`ACP2MD_HTTP_CLIENT_PROXY`	`http.client.proxy`	URL del proxy HTTP
`ACP2MD_LOG_LEVEL`	`log.level`	Nivel de logging
`ACP2MD_LOG_FORMAT`	`log.format`	Formato del logging
`ACP2MD_LOG_FILE`	`log.file`	Archivo de salida del logging
`ACP2MD_DEBUG_ENABLED`	`debug.enabled`	Activa el modo debug
`ACP2MD_IMAGE_CACHE_DIR`	`image.cache_dir`	Directorio de cache de imagenes
`ACP2MD_IMAGE_MAX_SIZE_BYTES`	`image.max_size_bytes`	Tamano máximo de imagen

Flags globales de CLI

Estos flags están disponibles en todos los comandos:

Flag	Predeterminado	Descripcion
`--config-file`	(ver `config where`)	Ruta de un archivo de configuración personalizado
`--log-level`	`info`	Verbosidad del logging: `debug`, `info`, `warn`, `error`
`--log-format`	`text`	Formato del logging: `text` o `json`
`--log-file`	(descartado)	Escribe logs en `stdout`, `stderr` o una ruta de archivo
`--debug`	`false`	Atajo de `--log-level=debug`
`--image-cache-dir`	(ninguno)	Directorio para cachear imagenes descargadas
`--image-max-size-bytes`	`10485760`	Tamano máximo en bytes para imagenes cacheadas

Practicas seguras de configuración

Prefiere variables de entorno para los tokens API en sistemas compartidos o gestionados.
Usa config create para establecer la forma esperada del archivo antes de editarlo manualmente.
Ejecuta doctor despues de cambios de configuración para validar conjuntamente licencia, credenciales y conectividad.
Usa un --config-file personalizado cuando necesites configuraciones aisladas de prueba y produccion en la misma máquina.

Detras de un proxy corporativo


acp2md config set http.client.proxy "http://proxy.corp.example.com:8080"

Con autenticación:


acp2md config set http.client.proxy "http://user:password@proxy.corp.example.com:8080"

Evita guardar credenciales del proxy en el archivo de configuración si se comparte o se versiona. Usa en su lugar la variable de entorno ACP2MD_HTTP_CLIENT_PROXY.

Logging a un archivo


acp2md page convert by-id 123456 --log-file app.log

Cada ejecución trunca el archivo de log, de modo que siempre contiene solo la salida de la ejecución mas reciente. Usa stdout o stderr para enviar los logs a tu terminal:


acp2md page convert by-id 123456 --log-file stdout