Probé muchos editores markdown durante los últimos años. Ninguno tenía en un solo lugar todas las características que me hubieran gustado tener.

Typora es excelente pero es desktop-only y de pago. Obsidian es potente pero orientado a notas, no a documentación técnica. HackMD tiene colaboración pero la UX no me convence. Y los que más me interesaban, los editores online gratuitos son… básicos, muy básicos.

Después de un tiempo de usar varias alternativas y que ninguna me terminó de convencer, decidí construirme una. Así nació MarkView: un editor markdown moderno, con preview en tiempo real, sincronización con GitHub y Google Drive, y soporte offline como PWA.

El problema que quería resolver

Mi workflow con markdown incluye:

1. Documentación de proyectos que vive en repos de GitHub
2. Notas técnicas que quiero acceder desde cualquier dispositivo
3. Borradores de posts que eventualmente publico en mi blog
4. README y changelogs que edito frecuentemente

Probé para docs de GitHub, el editor web de GitHub (no me gusta). Para notas probé Notion (tampoco me convenció). Para posts usaba VS Code local (sin sync automático, solo en la pc, etc).

Quería una sola herramienta que:

• Funcione en el navegador, sin instalación
• Tenga un editor potente con atajos de teclado
• Muestre preview en tiempo real
• Sincronice directamente con GitHub y Google Drive
• Funcione offline cuando no tenga conexión

Las decisiones arquitectónicas

Por qué CodeMirror 6

El editor es la parte principal de la aplicación. Evalué tres opciones:

Elegí CodeMirror 6 por tres razones:

1. Modularidad — Solo importo las extensiones que necesito
2. Performance — Virtual scrolling nativo para documentos largos
3. Extensibilidad — Puedo crear extensiones custom sin tocar el core

La arquitectura de CodeMirror 6 es diferente a la versión anterior. Todo es inmutable y funcional. Al principio fue confuso, pero una vez que entendí el modelo de State → Transaction → New State, el código se volvió muy predecible.

1
// Ejemplo de extensión custom para insertar frontmatter
2
const insertFrontmatter = StateCommand({
3
  run(view) {
4
    const frontmatter = '---\ntitle: \ndate: \n---\n\n';
5
    view.dispatch({
6
      changes: { from: 0, insert: frontmatter },
7
      selection: { anchor: 10 }, // Posicionar cursor en title
8
    });
9
    return true;
10
  },
11
});

Por qué Zustand y no Redux o Context

La gestión de estado fue otra decisión importante. MarkView tiene múltiples dominios de estado:

• Documentos — Contenido, metadata, historial de versiones
• UI — Modales abiertos, panel activo, sidebar collapsed
• Settings — Tema, font size, auto-save interval
• GitHub — Repos, branches, archivos remotos
• Google Drive — Carpetas, archivos, estado de sync
• Sync — Cola de operaciones, estado de conexión

Con Redux, esto serían 6 slices con mucho boilerplate. Con Context, serían 6 providers anidados con re-renders innecesarios.

Zustand me permite tener 6 stores independientes que se suscriben granularmente:

1
export const useDocumentStore = create<DocumentState>((set, get) => ({
2
  documents: [],
3
  activeDocumentId: null,
4

5
  setContent: (id, content) => {
6
    set((state) => ({
7
      documents: state.documents.map((doc) =>
8
        doc.id === id ? { ...doc, content, modified: true } : doc
9
      ),
10
    }));
11
    // Trigger auto-save
12
    get().scheduleAutoSave(id);
13
  },
14
}));
15

16
// En un componente, solo me suscribo a lo que necesito
17
const content = useDocumentStore(
18
  (state) => state.documents.find((d) => d.id === activeId)?.content
19
);

Esto evita re-renders innecesarios. Si cambio el contenido de un documento, solo se re-renderizan los componentes que usan ese contenido específico.

Por qué Hono para el backend

El backend es mínimo: maneja OAuth, hace de proxy a requests a GitHub/Google APIs, y almacena preferencias de usuario.

Elegí Hono sobre Express o Fastify porque:

1. Ultra ligero — ~14KB vs ~200KB de Express
2. Edge-ready — Funciona en Vercel Edge, Cloudflare Workers, Deno
3. Type-safe — Integración nativa con Zod para validación
4. DX excelente — Similar a Express pero más moderno

1
const github = new Hono()
2
  .use('/*', authMiddleware)
3
  .get('/repos', async (c) => {
4
    const user = c.get('user');
5
    const repos = await octokit.repos.listForAuthenticatedUser();
6
    return c.json(repos.data);
7
  })
8
  .post(
9
    '/files/:owner/:repo/*',
10
    zValidator('json', saveFileSchema),
11
    async (c) => {
12
      const { content, message } = c.req.valid('json');
13
      const path = c.req.param('*');
14
      // ... save to GitHub
15
    }
16
  );

Problemas reales y cómo los resolví

El scroll sync entre editor y preview

El problema: Quería que al scrollear el editor, el preview se moviera a la sección correspondiente (y viceversa). Pero el markdown no tiene una relación 1:1 con el HTML renderizado.

Un heading ## Título ocupa una línea en markdown pero puede ser un <h2> con padding y margin variables en el preview. Una lista de 10 items en markdown son 10 líneas, pero en HTML son elementos <li> con alturas diferentes según el contenido.

La solución: Creé un plugin de rehype que anota cada elemento HTML con su línea de origen:

1
function rehypeLineNumbers() {
2
  return (tree: Root) => {
3
    visit(tree, 'element', (node) => {
4
      if (node.position?.start?.line) {
5
        node.properties = {
6
          ...node.properties,
7
          'data-source-line': node.position.start.line,
8
        };
9
      }
10
    });
11
  };
12
}

Con esto, cada elemento del preview tiene un atributo data-source-line. Cuando scrolleo el editor, busco el elemento del preview más cercano a la línea visible y lo scrolleo al viewport.

1
const syncPreviewToEditor = useCallback((editorLine: number) => {
2
  const elements = previewRef.current?.querySelectorAll('[data-source-line]');
3
  let closest = null;
4
  let minDistance = Infinity;
5

6
  elements?.forEach((el) => {
7
    const sourceLine = parseInt(el.getAttribute('data-source-line') || '0');
8
    const distance = Math.abs(sourceLine - editorLine);
9
    if (distance < minDistance) {
10
      minDistance = distance;
11
      closest = el;
12
    }
13
  });
14

15
  closest?.scrollIntoView({ behavior: 'smooth', block: 'center' });
16
}, []);

Conflictos de edición con servicios cloud

El problema: El usuario puede editar un documento localmente mientras alguien (o él mismo desde otro dispositivo) lo modifica en GitHub o Google Drive. Sin manejo de conflictos, el que guarda último gana y se pierden cambios.

La solución: Implementé un sistema de detección de conflictos basado en ETags y timestamps:

1. Al abrir un archivo, guardo su etag o modifiedTime
2. Antes de guardar, verifico si cambió en el servidor
3. Si cambió, muestro un modal de resolución con tres opciones:
   • Usar versión local — Sobrescribir el servidor
   • Usar versión remota — Descartar cambios locales
   • Merge manual — Mostrar diff y dejar que el usuario decida

1
async function checkForConflicts(doc: Document): Promise<ConflictResult> {
2
  if (doc.source === 'github') {
3
    const remote = await fetchGitHubFile(doc.path);
4
    if (remote.sha !== doc.remoteSha) {
5
      return {
6
        hasConflict: true,
7
        localContent: doc.content,
8
        remoteContent: remote.content,
9
        localTimestamp: doc.lastModified,
10
        remoteTimestamp: remote.committedAt,
11
      };
12
    }
13
  }
14
  return { hasConflict: false };
15
}

El modal de conflictos usa un diff viewer side-by-side que resalta las diferencias. Fue más trabajo del que esperaba, pero evita pérdida de datos.

Performance del preview con Mermaid y KaTeX

El problema: El preview se actualiza en cada keystroke (debounced a 300ms). Pero si el documento tiene diagramas Mermaid o ecuaciones KaTeX, cada actualización era lenta porque re-renderizaba todo.

Mermaid especialmente es pesado. Un diagrama de flujo mediano toma ~100ms en renderizar. Con 5 diagramas en un documento, el preview laggea notoriamente.

La solución: Cache de bloques renderizados con invalidación selectiva:

1
const blockCache = new Map<string, { hash: string; html: string }>();
2

3
function getCachedBlock(
4
  type: 'mermaid' | 'katex',
5
  content: string
6
): string | null {
7
  const hash = hashContent(content);
8
  const key = `${type}:${hash}`;
9

10
  if (blockCache.has(key)) {
11
    return blockCache.get(key)!.html;
12
  }
13
  return null;
14
}
15

16
function cacheBlock(type: string, content: string, html: string): void {
17
  const hash = hashContent(content);
18
  const key = `${type}:${hash}`;
19
  blockCache.set(key, { hash, html });
20
}

Ahora, cuando el usuario edita texto normal, los diagramas Mermaid usan la versión cacheada. Solo se re-renderizan cuando el contenido del bloque específico cambia.

Historial de versiones por documento

El problema: Quería un historial de versiones tipo “undo on steroids”, donde puedas ver versiones anteriores de un documento y hacer diff entre ellas. Pero cada pestaña tiene su propio historial independiente.

La solución: Cada documento tiene su array de versiones con timestamps y contenido. El challenge fue el almacenamiento, ya que localStorage tiene límite de ~5MB.

Implementé:

1. Límite de versiones — Máximo 50 versiones por documento
2. Compresión delta — Solo guardo el diff, no el contenido completo
3. Pruning automático — Las versiones viejas se eliminan al superar el límite

1
// stores/documentStore.ts - versioning logic
2
addVersion: (docId, content) => {
3
  const doc = get().documents.find((d) => d.id === docId);
4
  if (!doc) return;
5

6
  const previousContent = doc.versions[doc.versions.length - 1]?.content || '';
7
  const delta = createDelta(previousContent, content);
8

9
  const newVersion: Version = {
10
    id: generateId(),
11
    timestamp: Date.now(),
12
    delta,
13
    contentHash: hashContent(content),
14
  };
15

16
  const versions = [...doc.versions, newVersion].slice(-50); // Keep last 50
17

18
  set((state) => ({
19
    documents: state.documents.map((d) =>
20
      d.id === docId ? { ...d, versions } : d
21
    ),
22
  }));
23
};

El visor de diferencias usa un algoritmo de diff line-by-line con highlighting de cambios. No es tan sofisticado como git diff, pero funciona bien para documentos markdown.

El sistema de temas de preview

Agregué temas para que la preview se vea como en:

• GitHub Light/Dark
• GitLab
• Notion
• Obsidian
• Stack Overflow
• Dev.to

Cada tema es un archivo CSS que intenta replicar los estilos de cada plataforma. No son copias exactas (eso sería complejo y frágil), pero capturan la esencia visual.

1
.preview-theme-github-dark {
2
  --preview-bg: #0d1117;
3
  --preview-text: #c9d1d9;
4
  --preview-heading: #c9d1d9;
5
  --preview-link: #58a6ff;
6
  --preview-code-bg: #161b22;
7
  --preview-blockquote-border: #3b434b;
8
  /* ... más variables */
9
}
10

11
.preview-theme-github-dark h1 {
12
  padding-bottom: 0.3em;
13
  border-bottom: 1px solid var(--preview-blockquote-border);
14
}
15

16
.preview-theme-github-dark code {
17
  background: var(--preview-code-bg);
18
  padding: 0.2em 0.4em;
19
  border-radius: 6px;
20
  font-size: 85%;
21
}

El usuario puede cambiar el tema del preview independientemente del tema de la aplicación. Es útil para ver cómo quedará un README antes de pushearlo.

La PWA y el soporte offline

MarkView funciona completamente offline.

Service Worker strategy

Uso Workbox con una estrategia mixta:

• App shell — Cache-first con actualización en background
• Assets estáticos — Cache-first, versionados por hash
• API calls — Network-first con fallback a cache

1
// sw.ts (simplificado)
2
registerRoute(
3
  ({ request }) => request.destination === 'document',
4
  new NetworkFirst({
5
    cacheName: 'pages',
6
    networkTimeoutSeconds: 3,
7
  })
8
);
9

10
registerRoute(
11
  ({ request }) =>
12
    request.destination === 'script' || request.destination === 'style',
13
  new CacheFirst({
14
    cacheName: 'assets',
15
    plugins: [new ExpirationPlugin({ maxAgeSeconds: 30 * 24 * 60 * 60 })],
16
  })
17
);

Sync diferido

Cuando el usuario está offline, las operaciones de guardado cloud se encolan:

1
const syncQueue: SyncOperation[] = [];
2

3
function queueOperation(op: SyncOperation) {
4
  syncQueue.push(op);
5
  persistQueue(); // Guardar en IndexedDB
6
}
7

8
// Cuando vuelve la conexión
9
window.addEventListener('online', () => {
10
  processQueue();
11
});
12

13
async function processQueue() {
14
  while (syncQueue.length > 0) {
15
    const op = syncQueue[0];
16
    try {
17
      await executeOperation(op);
18
      syncQueue.shift();
19
      persistQueue();
20
    } catch (error) {
21
      // Reintentar después o mostrar error al usuario
22
      break;
23
    }
24
  }
25
}

Onboarding y UX

Por más que lo hice pensando en uso particular mío, la idea era ofertarlo a la comunidad, y en ese caso un editor con unas cuantas features necesita guiar al usuario. Así que implementé:

Tour interactivo

Al primer uso, un tour guía por las features principales:

1. El editor y sus atajos
2. El panel de preview
3. El explorador de archivos
4. La integración cloud
5. Las opciones de exportación

Cada paso resalta el elemento relevante y espera interacción antes de continuar.

Hints contextuales

Pequeños tooltips que aparecen cuando el usuario hace algo por primera vez:

• “Tip: Usá Ctrl+B para negrita”
• “Tip: Podés arrastrar archivos .md aquí”
• “Tip: Hacé click derecho para más opciones”

Los hints se marcan como vistos y no vuelven a aparecer.

Lecciones aprendidas

Lo que funcionó bien

1. CodeMirror 6 — Vale la pena la curva de aprendizaje. La performance y extensibilidad son excelentes.

2. Zustand con stores separados — Mantiene el código organizado y evita re-renders innecesarios.

3. PWA desde el día uno — Agregarlo después hubiera sido mucho más trabajo.

4. Cache agresivo en preview — La diferencia de performance es notable.

Lo que haría diferente

1. Usar IndexedDB desde el inicio — localStorage tiene limitaciones de tamaño que me obligaron a comprimir historial.

2. Tests E2E más tempranos — Los tests unitarios no capturan bugs de integración. Playwright debería haber entrado antes.

Cierre

MarkView empezó como “quiero un editor mejor” y terminó siendo un proyecto de 3, casi 4 semanas con muchas líneas de código. ¿Es perfecto? No. ¿Resuelve mi problema original? Absolutamente.

Lo uso todos los días para documentación, notas, y borradores. La sincronización con GitHub me ahorra saltar entre herramientas. El soporte offline me permite escribir en cualquier lado.

Si tenés un workflow similar o simplemente querés un editor markdown moderno que funcione en el navegador, probalo. Es open source y gratuito.

Las mejores herramientas son las que construís para vos mismo, porque entendés exactamente qué problema resuelven.

Referencias

• MarkView en GitHub — Código fuente
• MarkView Demo — Probalo online
• MarkView - Página del proyecto — Más detalles
• CodeMirror 6 — Documentación del editor
• Unified/Remark — Pipeline de markdown