Editar Markdown Localmente en el Navegador: Guía de Herramientas y Arquitectura

Editar archivos Markdown localmente en el navegador es una necesidad para quienes trabajan con documentación técnica, notas personales o repositorios de código. Pero no todas las herramientas cumplen lo mismo: algunas reescriben todo el documento, otras preservan solo lo que modificas.

Editor Markdown con dos paneles: uno para escribir código y otro para ver el resultado
Vista dividida entre edición de código y preview del documento

Las opciones existentes

Existen tres caminos principales para editar Markdown en el navegador:

  1. Aplicación web local: programas ejecutados en localhost que editan archivos de tu disco.
  2. Extensión de navegador: añade un editor a Chrome y permite trabajar con archivos locales.
  3. Editor web existente: aprovechas proyectos como CodeMirror o Milkdown sin reinventar el motor.

De las extensiones encontradas, tres destacan por su enfoque en edición avanzada:

  • MarkLeaf: edición visual por bloques, tablas, diagramas y fórmulas. Afirma reescribir solo las partes modificadas, preservando el resto del archivo.
  • Markside: edición de código con vista previa dividida, CodeMirror y soporte para Mermaid, KaTeX y YAML frontmatter.
  • SharpMD: edición visual de párrafos, títulos y tablas sin convertir todo el documento.

También hay proyectos de código abierto como MD Viewer que pueden servir como punto de partida para desarrollar una solución propia.

¿Programarlo tú misma?

Técnicamente no es un proyecto demasiado complicado. La arquitectura ideal sería:

Explorador de archivos → Editor Markdown → Vista previa sincronizada → Guardado directo en disco

Los componentes esenciales serían:

  • CodeMirror 6: editor de texto y sintaxis Markdown
  • Marked o markdown-it: renderizado del contenido
  • File System Access API: abrir y guardar archivos locales sin servidor
  • Mermaid: diagramas visuales
  • KaTeX: fórmulas matemáticas
  • DOMPurify: sanitización del HTML generado

La cuestión realmente importante: respetar el formato

Aquí es donde muchas herramientas fallan. Existen dos filosofías:

  • Source-first: el documento original es protagonista. Editas Markdown directamente y la vista previa refleja los cambios.
  • WYSIWYG: editas visualmente y el programa reconstruye el Markdown completo cada vez.

La segunda es más cómoda, pero puede introducir modificaciones indeseadas: cambiar viñetas, normalizar tablas, alterar saltos de línea o modificar frontmatter YAML. Si quieres preservar documentos existentes, prioriza:

  1. No modificar líneas que no hayas editado
  2. Preservar frontmatter, comentarios HTML y bloques de código
  3. Respetar enlaces relativos e imágenes locales
  4. No normalizar automáticamente espacios ni saltos de línea
  5. Comparación antes/después mediante diff
  6. Copias de seguridad y detección de conflictos

Mi recomendación: probaría primero Markside y MarkLeaf. Especialmente este último por su propuesta de edición quirúrgica del documento, aunque verificaría esa característica con archivos reales y comparaciones Git.

Una pregunta que cambia la recomendación

¿Qué clase de edición quieres conseguir? Tres factores determinan:

  1. Cómo quieres editar: como Word (visual), como editor de código (Markdown visible) o híbrido.
  2. Qué necesitas abrir: archivos individuales, carpetas completas o un vault tipo Obsidian.
  3. Qué es más importante: preservar el Markdown original, herramientas avanzadas o equilibrio entre ambas cosas.

Para modo híbrido, alcance vault y prioridad balance, la solución ideal es desarrollar un editor web local con arquitectura Source-first y edición visual integrada. Funciona en Chrome, sin cuentas, sin nube y sin depender de servicios externos.

Arquitectura recomendada

La combinación ganadora sería:

  • CodeMirror 6: conserva el control absoluto del texto con soporte específico para Markdown
  • Milkdown: aporta edición visual, tablas, matemáticas y extensibilidad mediante plugins
  • Markdown-it + plugins: renderizado flexible con extensiones configurables
  • File System Access API: acceso directo al disco sin backend PHP ni Docker

La decisión importante es que ambos editores no deben convertirse mutuamente el documento completo cada vez que cambias de modo. La edición visual debe operar sobre bloques o secciones delimitadas para reducir modificaciones indeseadas.

Funcionalidades prioritarias

Una tabla de prioridades ayuda a planificar:

  • Imprescindible: explorador de carpetas, pestañas múltiples, edición fuente/visual, vista previa sincronizada, guardado automático configurable, búsqueda global.
  • Alta: backlinks y enlaces internos, gestión de imágenes y adjuntos, frontmatter YAML, historial y comparación de versiones.
  • Media: Mermaid y KaTeX, renombrado seguro de archivos y enlaces.

Una característica especialmente importante: soporte para enlaces del tipo [[Nombre de nota]], además de los enlaces Markdown convencionales. Eso permite trabajar con vaults estilo Obsidian sin perder sus relaciones.

Cómo acceder a los archivos

Utilizaría la File System Access API de Chrome. El usuario selecciona una carpeta y el navegador obtiene acceso autorizado a sus archivos y subdirectorios, permitiendo leerlos y escribirlos directamente sin subirlos a un servidor.

La condición: requiere contexto seguro como localhost y autorización explícita del usuario. Ejecutarías con:

npm run dev -- --host 127.0.0.1

Chrome abre http://localhost:5173. Sin backend PHP, sin Docker, sin nube y sin necesidad de instalar una aplicación de escritorio.

Alternativa que vale la pena probar

Antes de desarrollar todo, probaría también TOAST UI Editor. Tiene dos modos de edición, vista previa, sincronización de desplazamiento, soporte CommonMark/GFM y plugins. Lo utilizaría como referencia funcional para comprobar cómo serializa documentos particulares.

Plan de desarrollo

Lo dividiría en tres entregas:

  1. Fase 1 — MVP funcional: abrir carpeta como vault, navegador de archivos, editor CodeMirror, vista previa, guardado directo, pestañas y búsqueda.
  2. Fase 2 — Edición avanzada: modo visual Milkdown, tablas editables, frontmatter YAML, Mermaid y KaTeX, enlaces internos y backlinks, imágenes y adjuntos.
  3. Fase 3 — Integridad del vault: diff antes de guardar, detección de cambios externos, backups, renombrado seguro con actualización de enlaces, historial de versiones.

Entorno tecnológico definitivo

La elección final sería:

Diagrama mostrando estructura de directorios para gestión de imágenes y documentos
Organización recomendada de archivos y recursos en un vault
  • Entorno: Windows 10/11, localhost
  • Runtime: Node.js
  • Frontend: React + TypeScript + Vite
  • Editor fuente: CodeMirror 6
  • Editor visual: Milkdown
  • Renderizado: Markdown-it con plugins
  • Archivos: File System Access API
  • Persistencia auxiliar: IndexedDB
  • Versionado: Git opcional

Una precaución: no soportar todas las extensiones de Obsidian desde el primer día. Primero Markdown estándar, GFM, YAML y wikilinks; después callouts, embeds y demás particularidades.

¿Es universal el formato Markdown?

Sí. Se ha convertido en un lenguaje común para escribir documentación, notas y contenido estructurado en Internet. Pero hay un matiz: Markdown es bastante universal en su sintaxis básica, aunque no existe una única interpretación universal de todas sus extensiones.

Dónde se utiliza

GitHub/GitLab (README, documentación, issues), wikis personales, WordPress (mediante plugins), Obsidian, Jekyll/Hugo, Reddit, Discord, Stack Overflow y ChatGPT. Una precisión: WordPress utiliza principalmente HTML y Gutenberg, aunque existen plugins que permiten escribir y convertir Markdown.

El problema: existen variantes

Cuatro dialectos importantes:

  • CommonMark: base de interoperabilidad que elimina ambigüedades de la sintaxis original.
  • GitHub Flavored Markdown (GFM): añade tablas, listas de tareas, tachado, autolinks y otras características.
  • Obsidian Markdown: wikilinks, callouts, embeds, propiedades y extensiones propias.
  • Pandoc Markdown: variante potente para documentos académicos, citas, tablas y conversiones.

Si desarrollas un editor local, establecería tres niveles de compatibilidad: Universal (CommonMark), Extendido (GFM) y Especializado (Obsidian, Pandoc y extensiones configurables). Añadiría una propiedad muy importante: no convertir automáticamente las extensiones desconocidas.

Imágenes en Markdown

La sintaxis estándar es prácticamente idéntica a la de los enlaces:

![Descripción de la imagen](imagenes/fotografia.jpg)

Markdown no almacena las imágenes dentro del documento. Normalmente guarda una referencia a un archivo externo. Una estructura recomendable sería:

MiVault/ → README.md, articulos/, assets/ (con fotografías y diagramas)

Desde articulos/articulo1.md podrías utilizar:

![Fotografía](../assets/fotografia.jpg)

La ruta es relativa al archivo Markdown, no al navegador.

Otras posibilidades

  • Ruta relativa: recomendada
  • URL externa: depende de Internet
  • Ruta absoluta: poco portable
  • Base64: aumenta muchísimo el tamaño del MD

También existe la sintaxis de Obsidian: ![[fotografia.jpg]], que permite insertar imágenes usando el sistema de referencias internas del vault.

Ejemplo de documento Markdown antes y después del renderizado
Cómo se transforma el Markdown en HTML final

Gestión visual de imágenes en el editor

Funciones esenciales:

  • Arrastrar y soltar imágenes dentro del editor
  • Pegar imágenes directamente desde el portapapeles
  • Copiar imágenes al directorio de recursos del vault
  • Generar automáticamente la referencia Markdown
  • Mostrar miniaturas en la vista previa
  • Cambiar tamaño de visualización sin modificar el original
  • Detectar imágenes faltantes y enlaces rotos
  • Administrar imágenes sin referencias

Por ejemplo, al pegar una imagen, el editor podría guardarla automáticamente en:

MiVault/assets/2026/11/imagen_001.png

Y escribir:

![Descripción](../assets/2026/11/imagen_001.png)

Además, conservaría el archivo original sin recomprimirlo.

Una decisión de diseño importante

¿Queremos que el editor administre las imágenes o simplemente que las muestre? Yo elegiría administrarlas. Eso significa incorporar un pequeño gestor de recursos con miniaturas, búsqueda, referencias y detección de archivos huérfanos.

Y hay otra ventaja: podríamos incorporar imágenes WebP, GIF, SVG y formatos fotográficos sin convertirlas innecesariamente. Mi recomendación es que el editor tenga una carpeta assets configurable, pero que también respete las rutas y ubicaciones existentes.

Conclusión

Markdown tiene una ventaja que HTML, Word y otros formatos no ofrecen de la misma manera: es legible incluso sin un programa especializado. Puedes abrir un .md con Notepad, editarlo con VS Code, publicarlo en GitHub, procesarlo con Pandoc o convertirlo a HTML.

Por eso, para un editor de vaults, mi filosofía sería: el archivo Markdown es el documento original. El editor es solamente una herramienta para trabajar con él.

Eso permite que dentro de diez años puedas seguir utilizando tus documentos aunque nuestro editor haya desaparecido. Esa independencia me parece muchísimo más valiosa que tener un editor lleno de funciones espectaculares.

Y hay una característica que pondría por encima de casi todas las demás: que puedas abrir un documento de 2.000 líneas, modificar tres párrafos en modo visual y guardar sin que el programa reformatee las otras 1.997. Ese sería el verdadero criterio de calidad del proyecto. No que se vea bonito, sino que sea un editor en el que puedas confiar.