Como usar acs2md para migrar de Confluence a Obsidian: buenas practicas y consejos para una transicion fluida

Si el objetivo es mover un patrimonio documental de Confluence a Obsidian, la pregunta practica no es si puede generarse Markdown. La pregunta practica es si el Markdown exportado conservara suficiente estructura como para seguir siendo util en el trabajo diario, la revision, la busqueda y la continuidad.

Ahí es donde acs2md importa. Esta pensado para flujos de espacio completo y de patrimonio documental, lo que lo vuelve mas adecuado que el tooling orientado a pagina cuando el resultado buscado es un vault util en Obsidian y no una exportacion puntual.

Las migraciones mas fluidas ocurren cuando los equipos dejan de pensar en copiar paginas y empiezan a pensar en operar un patrimonio Markdown aguas abajo. Ese cambio modifica la preparacion, los comandos, las validaciones y el modelo de retencion.

Empieza por el patrimonio y no por paginas aisladas

Obsidian se vuelve realmente util cuando sobreviven el contenido relacionado, las referencias internas y la estructura de carpetas. Una migracion basada en exportaciones aisladas suele perder ese contexto.

Usa acs2md cuando necesites una o varias de estas cosas:

• un espacio Confluence convertido a un subarbol de vault
• jerarquia preservada a traves de muchas paginas
• nombres de archivos consistentes y reescritura de enlaces
• exportaciones recurrentes que mantengan el patrimonio Markdown al dia
• un corpus aguas abajo que despues pueda servir para Git, busqueda empresarial o RAG

Si el problema de negocio es solo una pagina, acp2md es la opcion mas simple. Si el problema es un patrimonio de conocimiento, acs2md es el punto de partida correcto.

Buena practica 1. Valida la ruta de exportacion antes de prometer una fecha de migracion

Los equipos suelen planificar el cutover primero y validar el entorno fuente despues. Eso esta al reves.

Antes de la primera exportacion seria, ejecuta un preflight corto:

acs2md doctor
acs2md space list --limit 10
acs2md space pages by-key DOCS --tree

Eso hace tres cosas pronto:

• confirma que la maquina y las credenciales sirven
• confirma que el espacio objetivo es realmente el correcto
• muestra si el arbol de contenido ya esta lo bastante limpio para una exportacion a vault

Si el arbol es confuso en Confluence, el vault no va a arreglarlo por si solo.

Buena practica 2. Limpia la arquitectura de informacion antes de la primera ejecucion masiva

Las mejores migraciones a Obsidian se ganan casi enteras antes de empezar la conversion.

Revisa el espacio fuente en busca de:

• paginas duplicadas o casi duplicadas
• paginas hijas obsoletas que convenga archivar antes de exportar
• titulos enganosos que luego seran malos nombres de archivo Markdown
• paginas gigantes que en realidad contienen varios documentos
• paginas de navegacion que aportan poco valor fuera de Confluence

Este paso importa tanto para compliance como para usabilidad. La informacion documentada de ISO 9001 debe mantenerse actual e identificable. Exportar material obsoleto o ambiguo a un vault solo reproduce el problema de gobierno en un segundo sistema.

Buena practica 3. Usa un directorio de salida estable desde el primer dia

No ejecutes migraciones serias contra carpetas desechables.

Si el destino va a convertirse en un vault de Obsidian, exporta al directorio que realmente mantendra el corpus de trabajo:

acs2md space convert by-key DOCS 
  --output-dir ./vaults/ops-knowledge 
  --rewrite-links 
  --include-metadata

Eso da al equipo una ruta estable para:

• indexacion de Obsidian
• seguimiento con Git
• jobs de backup
• comprobaciones de integridad
• ejecuciones futuras de sincronizacion

Cuanto mas estable sea la ruta, mas facil sera documentar el flujo y automatizarlo de forma segura.

Buena practica 4. Conserva la metadata aunque el caso de uso inmediato sea conocimiento personal

Algunos equipos eliminan metadata porque creen que Obsidian solo necesita cuerpos de nota legibles. Esa decision es miope.

La metadata mejora:

• la trazabilidad hacia Confluence
• la visibilidad de cadencia de revision
• el filtrado y agrupacion dentro del vault
• la procedencia de chunks para RAG mas adelante
• la defensa en auditoria cuando las notas exportadas soportan operaciones o compliance

Una migracion que se ve limpia pero pierde senales de propiedad o tiempo no es realmente una migracion profesional fuerte.

Buena practica 5. Reescribe enlaces para que el vault se comporte como un vault

Una de las mayores diferencias de calidad entre una exportacion demo y un patrimonio realmente util en Obsidian es el comportamiento de los enlaces.

Si las referencias internas siguen apuntando a URLs del navegador en Confluence, los usuarios salen del vault cada vez que persiguen contexto. Eso rompe el objetivo del reuse Markdown aguas abajo.

Usa reescritura de enlaces locales al convertir el espacio para que el patrimonio exportado se comporte como un grafo documental coherente y no como una carpeta de archivos desconectados.

Buena practica 6. Haz un piloto con un subconjunto representativo antes de una migracion completa

No juzgues la migracion sobre las paginas mas faciles.

Elige un subconjunto pequeno pero realista que incluya:

• una pagina tipo politica
• un runbook operativo
• un articulo rico en contenido con muchos encabezados
• una pagina con adjuntos o capturas
• una pagina con varias referencias internas

Si ese piloto funciona bien en Obsidian, la migracion completa tiene una base creible. Si no funciona, el piloto dira si el problema esta en el contenido fuente, en la configuracion de exportacion o en la estructura de destino.

Buena practica 7. Decide el modelo de retencion antes de las ejecuciones repetidas

Los equipos suelen descubrir demasiado tarde que las exportaciones repetidas necesitan una politica de borrado.

Si la copia en Obsidian debe reflejar el estado actual de Confluence, usa --sync en las ejecuciones recurrentes:

acs2md space convert by-key DOCS 
  --output-dir ./vaults/ops-knowledge 
  --sync

Si el objetivo es continuidad de archivo o retencion historica, manten el patrimonio en modo incremental:

acs2md space convert by-key DOCS 
  --output-dir ./vaults/ops-knowledge 
  --incremental

El punto importante no es que un modo sea mejor de forma universal. El punto importante es que la regla sea explicita, aprobada y documentada.

Buena practica 8. Separa exportaciones gobernadas de notas personales

Obsidian es lo bastante flexible como para favorecer una mala higiene si nadie define limites.

Mantén el material exportado desde Confluence en carpetas claramente nombradas y evita mezclarlo con notas personales, borradores o analisis especulativos salvo que el equipo tenga un metodo deliberado para hacerlo. Una separacion simple como esta ya ayuda:

vaults/ops-knowledge/
  exported-confluence/
  personal-notes/
  synthesis/
  .obsidian/

Esa separacion facilita las revisiones y reduce el riesgo de que el contenido controlado se cambie de forma casual sin ruta de retorno a la fuente autorizada.

Buena practica 9. Construye una checklist corta de revision de migracion

Toda migracion seria deberia terminar con una revision ligera pero repetible.

Usa una checklist como esta:

1. Los titulos son legibles como nombres de archivo y de nota
2. Los enlaces internos resuelven en local
3. La metadata esta presente y es comprensible
4. Los adjuntos siguen siendo accesibles
5. La estructura de carpetas refleja de forma razonable la jerarquia fuente
6. La regla espejo frente a archivo esta documentada
7. El comando de rerun esta anotado en el runbook del equipo

Aqui es donde la migracion pasa de ser ad hoc a operativa.

Como ayuda a los objetivos profesionales de indexacion y compliance

Los equipos suelen empezar el viaje de Confluence a Obsidian por productividad, pero el mismo flujo ayuda en contextos mas formales.

De nuevo, la herramienta no crea compliance por si sola. Lo que hace es dar a la organizacion un flujo documental mas limpio y mas defendible para ponerlo bajo los controles que ya tenga.

Recomendacion final

Usa acs2md para una migracion de Confluence a Obsidian cuando el objetivo sea un patrimonio documental real y no una coleccion de paginas copiadas. Valida pronto, limpia la jerarquia fuente, conserva metadata, reescribe enlaces y deja explicita la decision entre espejo y archivo.

Eso es lo que convierte una migracion en una transicion fluida y no en una exportacion puntual en la que nadie confia dos semanas despues.