doc-guia-MarkeUp

Orden de lectura recomendado: doc-readme → doc-guia → doc-arquitectura → doc-operacion → doc-auditoria

---

1. Requisitos previos

En el Mac de build

Herramienta	Versión mínima	Verificación
Node.js	20+	node --version
npm	10+	npm --version
Git	2+	git --version
Syncthing	Cualquiera	syncthing --version
ffmpeg	4+	ffmpeg -version
watchman	Cualquiera	watchman --version
Python	3.9+	python3 --version
Ollama	latest	ollama --version
Modelo Ollama	qwen2.5-coder:7b-64k	ollama list

En Android

• Obsidian instalado desde Google Play
• Syncthing instalado desde F-Droid o Google Play
• Plugin Templater instalado en Obsidian

---

2. Configuración de Syncthing

Syncthing sincroniza la carpeta src/content/posts/ entre Android y Mac de forma peer-to-peer.

En el Mac

1. Instalar Syncthing: brew install syncthing
2. Iniciar el servicio: brew services start syncthing
3. Abrir interfaz web: http://localhost:8384
4. Añadir carpeta: ruta ~/markeup/src/content/posts/
5. En la pestaña “Compartir”, seleccionar el dispositivo Android

En Android

1. Abrir Syncthing, ir a “Dispositivos” → añadir el Mac (por ID)
2. Añadir carpeta con ID idéntica a la del Mac
3. Ruta de la carpeta en Android: donde Obsidian guarda el vault

Verificar sincronización: Crear un archivo de prueba en Android. Debe aparecer en src/content/posts/ del Mac en 1-5 segundos.

---

3. Configuración de Obsidian + Templater

El plugin Templater automatiza la creación de nuevos posts generando el frontmatter correcto y el slug.

Estructura del vault

vault/
├── posts/              ← Se sincroniza con src/content/posts/
├── templates/          ← Plantillas de Templater
└── img/                ← Imágenes para posts

Plantilla Templater para nuevos posts

Crear templates/post-template.md:

---
title: <% tp.file.title %>
slug: <% tp.file.title.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9áéíóúüñ-]/g, '') %>
description: 
type: post
lang: es-ES
draft: true
authors:
  - Admin
pubDate: <% tp.date.now("YYYY-MM-DDTHH:mm:ss.000Z") %>
updatedDate: <% tp.date.now("YYYY-MM-DDTHH:mm:ss.000Z") %>
categories: []
tags: []
featured: false
image: /img/placeholder.webp
imageAlt: 
---

Configuración en Templater

1. En Obsidian → Settings → Templater
2. Template folder location: templates/
3. Activar “Trigger Templater on new file creation”
4. Activar “Folder templates”: asignar post-template.md a la carpeta posts/

Con esto, cada nuevo archivo creado en posts/ tendrá el frontmatter completo automáticamente.

---

4. Instalación del proyecto

# Clonar el repositorio
git clone https://github.com/uriszarernesto-blip/markeup.git
cd markeup

# Instalar dependencias
npm ci

# Verificar que todo funciona
npm run build

El build debe completarse con 192 páginas y 0 errores.

---

5. Configuración del generador automático de artículos

El script generar_articulo.py permite crear posts completos a partir de una URL usando Ollama como motor de generación. Requiere configuración adicional independiente del ecosistema npm.

5.1 Instalar Ollama y el modelo

# Instalar Ollama (servidor local de LLMs)
brew install ollama

# Iniciar el servicio
ollama serve

# Descargar el modelo requerido (7B params, 64K contexto)
ollama pull qwen2.5-coder:7b-64k

# Verificar que el modelo está disponible
ollama list

5.2 Instalar dependencias Python

# Instalar librerías Python necesarias
uv pip install requests trafilatura beautifulsoup4

5.3 Verificar la instalación

# Probar que Ollama responde
curl http://localhost:11434/api/tags

# Probar que el script se ejecuta (modo interactivo)
uv run python src/generar_articulo.py

Si todo está correcto, el script pedirá una URL. Pega cualquier URL de prueba (ej. Wikipedia) y espera 3-6 minutos a que genere el artículo.

---

6. Flujo de trabajo diario

Crear un nuevo post manualmente

1. En Obsidian (Android o desktop), crear nueva nota en posts/
2. Templater genera el frontmatter automáticamente
3. Escribir el contenido en Markdown
4. Cambiar draft: false cuando esté listo para publicar
5. Syncthing sincroniza el archivo al Mac

Crear un nuevo post automáticamente (desde URL)

# Con URL como argumento
uv run python src/generar_articulo.py "https://es.wikipedia.org/wiki/Inteligencia_artificial"

# Modo interactivo (pide la URL)
uv run python src/generar_articulo.py

El script automáticamente:

1. Descarga y extrae el texto de la URL
2. Detecta la categoría más adecuada (Biodanza, Documentación, Tecnología, Opinión, Literatura)
3. Genera entre 3 y 8 tags relevantes a partir del contenido
4. Construye un prompt detallado y lo envía a Ollama
5. Recibe el artículo Markdown completo (3000-5000 palabras)
6. Guarda el archivo en src/content/posts/<Categoría>/[slug].md

Aviso: La generación tarda entre 3 y 6 minutos. El script muestra mensajes de estado en cada etapa.

Añadir imágenes

1. Colocar la imagen en src/content/posts/img/
2. Ejecutar npm run images (o esperar al build, que lo hace automáticamente)
3. Referenciar en el frontmatter: image: /img/nombre.webp

Publicar

# Verificar build local
npm run build

# Si todo OK, publicar
git add .
git commit -m "Nuevo post: título del post"
git push origin main

GitHub Actions hace el build y despliega automáticamente en Cloudflare Pages.

---

7. Configuración de Hermes Agent

Hermes Agent es el Editor Jefe del vault: un asistente IA que corre sobre Ollama y gestiona el contenido de forma inteligente. Usa el mismo modelo qwen2.5-coder:7b-64k que el generador de artículos.

7.1 Requisitos previos

• Ollama corriendo en http://127.0.0.1:11434 (misma instalación de la sección 5.1)
• Modelo qwen2.5-coder:7b-64k descargado (ollama pull qwen2.5-coder:7b-64k)
• Hermes Agent instalado (which hermes → /Users/ernestouriszar/.local/bin/hermes)

7.2 Iniciar Hermes

# Iniciar chat interactivo (Hermes usará la config en ~/.hermes/config.yaml)
hermes chat

La configuración de Hermes (~/.hermes/config.yaml) ya apunta a Ollama:

model:
  default: qwen2.5-coder:7b-64k
  provider: custom
  base_url: http://127.0.0.1:11434/v1
  api_key: ollama
  api_mode: chat_completions
  context_length: 65536

7.3 Sistema de gestión del vault

Hermes lee y escribe en src/content/posts/hermes/:

• SOUL.md — su personalidad y reglas
• memory/vault-index.md — índice de los 63 posts del vault
• memory/backlog.md — 22 ideas de posts priorizadas
• skills/ — flujos de trabajo (crear, ampliar, wikilinks, auditar, documentar)

7.4 Comandos útiles en Hermes

Comando	Qué hace
Crea un post sobre [tema] en [categoría]	Genera nota con frontmatter + wikilinks
Amplía [slug] con una sección sobre [X]	Expande contenido existente
Revisa los wikilinks de [slug]	Escanea y enriquece enlaces
Audita el vault	Informe completo de salud del vault
Revisa la documentación	Verifica que los docs estén actualizados

---

8. Personalización

Temas

El sitio incluye 6 temas DaisyUI. El tema por defecto para modo oscuro es dark. Los temas están configurados en tailwind.config.cjs:

daisyui: {
  themes: ["light", "cupcake", "corporate", "dark", "dim", "sunset"],
  darkTheme: "dark",
}

Imagen por defecto

Los posts sin imagen usan /img/placeholder.webp. Para cambiar la imagen por defecto, modificar content.config.ts:

image: z.string().optional().default('/img/placeholder.webp'),

Añadir una nueva categoría

1. Crear la carpeta en src/content/posts/<categoria>/
2. Los posts dentro usarán automáticamente esa categoría en el frontmatter
3. La página /category/<categoria> se genera automáticamente en el build

Personalizar categorías del generador automático

Para añadir o modificar las categorías que detecta generar_articulo.py, editar las variables en el script:

CATEGORIAS = ["Biodanza", "Documentación", "Tecnología", "Opinión", "Literatura"]

KEYWORDS_CATEGORIAS = {
    "Biodanza": ["biodanza", "danza", "movimiento", ...],
    "Tecnología": ["tecnología", "software", "ia", ...],
    # Añadir nueva categoría aquí
}

---

9. Resolución de problemas comunes

Syncthing no sincroniza

• Verificar que ambos dispositivos están en la misma red
• En Android, desactivar optimización de batería para Syncthing
• Verificar permisos de carpeta en Mac: ls -la src/content/posts/

El build falla después de añadir un post

• Verificar que el frontmatter tiene todos los campos requeridos
• draft: true evita que posts incompletos aparezcan en producción
• Las fechas pubDate deben ser válidas (formato ISO 8601)

Imágenes no aparecen

• Ejecutar npm run images -- --force
• Verificar que la ruta en frontmatter empieza con /img/
• La extensión debe ser .webp
• Imágenes externas (Unsplash) se referencian con URL completa: https://images.unsplash.com/...

El generador automático falla

Síntoma: ❌ No se pudo extraer contenido o error de conexión.

Causas y soluciones:

Error	Causa probable	Solución
❌ No se pudo extraer contenido	URL inaccesible, sin internet, o página bloquea scrapers	Verificar URL en navegador. Probar con otra URL
⚠️ El contenido es muy corto (<500 caracteres)	La página tiene poco texto o es principalmente JS	Probar otra URL o responder s para continuar igual
Error de conexión a Ollama	Ollama no está corriendo	ollama serve o brew services start ollama
model not found	El modelo no está descargado	ollama pull qwen2.5-coder:7b-64k
Timeout (>10 min)	El modelo tardó demasiado o se colgó	Verificar que Ollama tiene recursos suficientes. Reintentar
El artículo no tiene bloque ````markdown`	El modelo devolvió la respuesta sin el bloque de código	El script usa toda la respuesta como fallback. Revisar el archivo generado

---

10. Documentos relacionados

Documento	Contenido
doc-readme	Visión general y stack
doc-arquitectura	Arquitectura y componentes
doc-operacion	Comandos y troubleshooting
doc-auditoria	Auditoría y deuda técnica