Saltar a contenido

🗒️ Guía práctica: Importar un vault de Obsidian

Quien lleva un tiempo reuniendo sus notas en Obsidian ya posee justo el material para el que se creó KnowledgeBase Builder: notas enlazadas con una estructura difícil de ver. Un script de importación gratuito convierte un vault completo en una base de datos de KnowledgeBase Builder: cada nota se convierte en un elemento, cada [[wikilink]] en una relación visible y la estructura de carpetas en categorías.

El script escribe directamente en el archivo SQLite (.kdb). No hace falta ningún servidor en ejecución ni la interfaz web, y el resultado puede abrirse igualmente con las versiones de escritorio, móvil y web.

1. Qué se convierte en qué

El script no se limita a copiar texto. Lee el vault tal como lo entiende Obsidian y traduce cada construcción a su equivalente en el diagrama:

Obsidian KnowledgeBase Builder
Archivo Markdown Elemento, con el texto de la nota como adjunto HTML
Carpeta Elemento de la categoría Folder, más una relación contains
Carpeta superior Categoría del elemento
#tag y tags: del frontmatter Etiquetas
[[wikilink]] Relación links to, más un enlace en la nota que carga el destino como nueva raíz del diagrama
![[incrustación]] Relación embeds; ![[nota#encabezado]] y ![[nota#^bloque]] se resuelven en línea, hasta tres niveles
campo:: [[destino]] (Dataview) Relación etiquetada con el nombre del campo
title: del frontmatter, primer # encabezado, primer alias Nombre del elemento
aliases: del frontmatter Nombres adicionales, para resolver los enlaces
description: / summary: del frontmatter, si no el primer párrafo Descripción del elemento
Primera URL externa de la nota DirectLinkURL del elemento
Imágenes del texto Incrustadas en la nota; la primera pasa además a ser el icono del elemento
Bloque ```mermaid Renderizado a SVG e incrustado si mermaid-cli está disponible; si no, queda como código fuente
$fórmula$ / $$fórmula$$ MathML, renderizado por el propio navegador
==resaltado==, ~~tachado~~, > [!callout] Convertidos a HTML; los %%comentarios%% se descartan

Un emoji al principio del nombre de una nota pasa a su propia celda de la etiqueta del nodo y se muestra así más grande que el texto contiguo, la misma estructura que produce la propia aplicación.

2. Obtener el script

El importador forma parte del repositorio gratuito de adaptadores y se descarga desde GitHub. Tómalo siempre de allí, porque es donde está la versión actual:

https://github.com/inforapid/knowledgebase-builder-adapter/tree/main/obsidian

El directorio contiene tres archivos: el script obsidian_to_kbb.py, su README y empty.kdb, la base de datos vacía de plantilla que el importador copia cuando el archivo de destino aún no existe. El repositorio se publica bajo licencia MIT.

Se requiere Python 3.6 o posterior. Para una importación básica basta con la biblioteca estándar. Cuatro paquetes opcionales mejoran el resultado y se utilizan automáticamente en cuanto están instalados:

pip install markdown pyyaml pillow latex2mathml
Paquete Sin él
markdown Se usa un convertidor interno frugal que solo cubre los casos habituales
pyyaml El frontmatter lo lee un analizador de reserva mínimo (clave: valor y listas con -)
pillow Las imágenes se incrustan a tamaño original en lugar de reducirse
latex2mathml Las fórmulas LaTeX quedan como código fuente

Los diagramas Mermaid necesitan además mermaid-cli. Si falta, el bloque de código simplemente queda como código fuente y no se descarga nada. La opción --install-mermaid lo obtiene temporalmente mediante npx; eso requiere Node.js y, la primera vez, unos cientos de megabytes para el navegador sin interfaz que lleva consigo.

3. La primera importación

Ejecuta el script en el directorio donde se encuentra y señálale tu vault:

python obsidian_to_kbb.py --vault ~/Obsidian/MiVault --db mivault.kdb

mivault.kdb se crea a partir de empty.kdb en la primera ejecución. La opción --template solo hace falta si llamas al script desde otro directorio o quieres usar otra plantilla.

Después abre el archivo en la aplicación: Base de conocimiento → Abrir; en la versión web lo subes allí. Todo lo del capítulo Base de conocimiento se aplica a la base importada igual que a una construida a mano.

Antes de sobrescribir una base de conocimiento existente: haz una copia del archivo .kdb. El importador escribe directamente en la base de datos y una importación masiva no se puede deshacer paso a paso.

4. Qué aspecto tiene el diagrama después

En la primera ejecución el script formatea también el diagrama, para que no te encuentres con un montón de nodos sin ordenar: disposición radial de mapa mental, coloreado por categoría, la paleta Spectral, un fondo de punto de cruz y elementos transparentes. Si prefieres formatearlo tú mismo, o si reimportas sobre un diagrama que ya has diseñado, usa --no-format-diagram. Todo lo de Formatear diagrama puede aplicarse después como de costumbre.

Dos detalles que conviene conocer al empezar a explorar:

  • Los wikilinks de una nota no son texto muerto. Un clic carga el elemento enlazado como nueva raíz del diagrama. El importador los escribe como enlaces con la forma itemid://<ID>, que el panel de notas resuelve dentro de la base de datos en lugar de abrir una ventana del navegador. Todo lo demás sobre ese panel está en Notas del elemento.
  • Las carpetas se convirtieron en elementos y en categorías. Puedes recorrer la estructura del vault en el diagrama y a la vez filtrar por ella en Elementos en categoría.

5. Mantener la base de datos al día

La importación no es un camino de ida. Sigue trabajando en Obsidian y vuelve a ejecutar el script después:

python obsidian_to_kbb.py --vault ~/Obsidian/MiVault --db mivault.kdb --prune

El script crea en la base de datos una tabla ObsidianSync y recuerda una suma de control del contenido por archivo, de modo que solo se reescriben las notas modificadas. Las notas que incrustan una nota modificada también se reescriben, para que sus transclusiones sigan siendo coherentes. --force reescribe todo y --prune elimina además los elementos cuyo archivo Markdown ya no existe; sin esa opción, las notas borradas permanecen en la base de datos.

Los elementos y las relaciones se reencuentran mediante URIs estables derivadas del objeto de origen:

obsidian:note:<ruta>                elemento de una nota
obsidian:folder:<ruta>              elemento de una carpeta
obsidian:rel:<de>|<a>|<tipo>        relación

Ese es el motivo por el que tu trabajo manual no se pierde. Una reimportación no toca las posiciones, los colores ni ninguna otra propiedad de los elementos; solo se actualizan el nombre, la descripción, la URL y el texto de la nota. Un diagrama que hayas ordenado y coloreado a mano sobrevive a cualquier número de ejecuciones.

6. Vaults grandes y páginas índice

Vaults como el Obsidian Hub contienen notas de mapa de contenidos que enlazan con cientos de notas. Convertir todos esos enlaces en relaciones sepultaría la estructura real del vault bajo una maraña, así que el script detecta esas notas —muchos enlaces, poco texto— y omite sus enlaces.

El umbral se adapta al vault: es como mínimo cuatro veces la mediana de enlaces por nota. Tres opciones lo controlan, por si la decisión automática no encaja con tu vault:

Opción Significado
--index-page-links N A partir de cuántos enlaces una nota cuenta como página índice
--index-page-words N Hasta cuántas palabras una nota cuenta como página índice
--keep-index-page-links Desactiva la detección; todos los enlaces se convierten en relaciones

7. Las opciones más útiles

--help las enumera todas; estas son las que conviene conocer:

Opción Significado
--template ARCHIVO Base de datos vacía que se copia cuando --db aún no existe (por defecto empty.kdb en el directorio actual)
--category folder\|fixed\|none De dónde procede la categoría de un elemento (por defecto: el nombre de la carpeta)
--category-name NOMBRE Categoría para --category fixed y para las notas de la carpeta raíz
--no-folder-nodes No crear un elemento por carpeta
--root-name NOMBRE Nombre del elemento de carpeta superior (por defecto Vault)
--no-images Omitir por completo las imágenes
--no-mermaid, --install-mermaid, --mermaid-cli RUTA Controlan la representación de Mermaid
--link-relation, --embed-relation, --folder-relation Etiquetas de las relaciones generadas
--no-dataview-relations Tratar campo:: [[destino]] como un wikilink corriente
--pipe-as-relation-label Usar el texto tras la \| de [[destino\|texto]] como etiqueta de la relación
--no-format-diagram Dejar intacto el formato del diagrama
--prune Eliminar los elementos cuyo archivo Markdown ya no existe
--force Reescribir todas las notas, incluidas las no modificadas
--keep-undo Dejar activos los disparadores de deshacer durante la importación (más lento, archivo mayor)

8. Conviene saber

  • Versión de la base de datos. Una base antigua se actualiza a la versión 4 si hace falta: se crean las tablas de etiquetas y sus disparadores de deshacer cuando faltan.
  • Deshacer. Durante la importación los disparadores de deshacer se eliminan y se restauran después, y el registro de deshacer se vacía. Una importación masiva no está pensada para deshacerse paso a paso. --keep-undo lo evita, a costa de velocidad y tamaño de archivo.
  • Tamaño del archivo. Una actualización deja atrás blobs antiguos. Base de conocimiento → Reducir tamaño de la base de datos los elimina en la aplicación.
  • Copia de seguridad. Haz una copia de la base de datos antes de la primera ejecución sobre una base de conocimiento existente.