Obsidian2pdf: de pdf plano a corporativo

Llevo un tiempo usando la herramienta Obisidian para centralizar toda la documentación que realizo, ya sea para proyectos como para notas rápidas o incluso documentación técnica, y siempre me encontraba con el mismo problema, el cliente no quiere un markdown, quiere un PDF explicativo y bonito en el que se vean las identidades de marca, con una plantilla muy marcada

El problema

La documentación en markdown está muy bien, es sencilla, fácil de aprender y sobretodo fácil de portar ya sea HTML o a PDF, Obsidian por defecto puede exportar estos .md a PDFs pero se ven mal, se cortan a mitad o no incluyen la identidad de marca, algo super importante

Es por eso que he creado este pequeño programa, el cual se encarga de pasar tus markdown a PDF, algo sencillo verdad? pero decidí darle una vuelta al flujo.

Flujo de la app

La app revisa el frontmatter de los markdowns y toma toda la información de ahí, usa un módulo llamado "watcher" el cual cada 30s revisa tus bóvedas en busca de un simple cambio en el frontmatter: status pasa de draft a finished. De esa manera, el programa toma el markdown, le añade la portada personalizada y el indice en base a los Titulos/subtitulos del markdown y hace toda la magia.

Archivos de configuración

He decidido mantener la app simple, usa un archivo de configuración escrito en TOML, donde se declara la configuración por defecto (la cual usará en caso de fallback por si no se pasa por el frontmatter).

vaults = []

[general]
output_mode   = "alongside"            # alongside: el PDF se guarda junto a su .md (misma carpeta y nombre)
                                       # central:   todo en output_dir/<bóveda>/...
output_dir    = "~/Documentos/PDF"     # solo se usa con output_mode = "central"
auto_detect_vaults = false             # true: añade también las bóvedas registradas en Obsidian
status_field  = "status"
export_status = "finished"
watch_interval = 30                     # segundos entre comprobaciones en modo --watch (mínimo 5)

[defaults]                              # se usan si la nota no trae author / author_email
author       = ""
author_email = ""

[branding]
company       = "Mi Empresa"
logo          = ""                      # ruta a PNG/SVG, p.ej. "~/.config/obsidian2pdf/logo.png"
primary_color = "#1f3a5f"
accent_color  = "#e07b00"
confidential  = "Documento confidencial"     # pie izquierdo cuando NO hay logo (con logo, el pie muestra el logo)
toc_title     = "Índice"
highlight_style = "pygments"            # resaltado de código: pygments, tango, kate, monochrome, breezedark, zenburn... o none
page_label    = "Página"
date_format   = "%d/%m/%Y"
justify       = true                    # texto justificado
hyphenate     = true                    # guiones automáticos al justificar (según lang)
label_author  = "Autor"                 # etiquetas de la portada
label_date    = "Fecha"
label_version = "Versión"
label_company = "Organización"

Este es un ejemplo del archivo de configuración, es todo modular y nada fijo, de forma que todo se puede cambiar.

Así es como quedaría con la configuración por defecto: puedes ver este ejemplo y más en el repo de github Pero, ¿cómo funciona exactamente en tu día a día?

El poder del frontmatter

Como mencioné en el flujo de la app, el motor principal es el frontmatter de tus notas (los metadatos YAML al principio del archivo). Para que Obsidian2PDF haga su magia, solo necesitas tener algo como esto al principio de tu documento:

---
title: "Documentación Técnica del Proyecto X"
author: "Tu Nombre"
author_email: "tu@email.com"
version: "1.2.0"
status: "draft"
---

Mientras el status sea draft (o cualquier otra cosa), el programa ignorará el archivo. Tú puedes seguir escribiendo, enlazando tus notas y trabajando tranquilamente en Obsidian.

¿El cliente te pide un avance? Simplemente cambias status: "draft" a status: "finished". En menos de 30 segundos, el watcher en segundo plano lo detectará, procesará el Markdown, construirá la portada con los datos del frontmatter (título, autor, versión, fecha), generará el índice interactivo y te dejará un PDF impecable en la carpeta que hayas configurado.

Pruebalo tú mismo y contribuye

Si te pasa como a mí y estás cansado de pelear con las exportaciones a PDF por defecto, o de tener que pasar tus notas a Word para darles formato antes de enviarlas, te invito a darle una oportunidad.

Tienes todo el código fuente, la documentación completa de configuración y las instrucciones de instalación en el repositorio:

Enlace al repositorio de Github

Es un proyecto de código abierto, así que cualquier feedback, Issue reportando algún bug, Pull Request con mejoras, o simplemente una Estrella en el repositorio es enormemente agradecida.

¡Espero que os sirva tanto como me está sirviendo a mí para centralizar toda mi documentación sin perder la identidad visual frente a los clientes!