I’ve tried many markdown editors over the past few years. None of them had all the features I wanted in one place.

Typora is excellent but it’s desktop-only and paid. Obsidian is powerful but oriented towards notes, not technical documentation. HackMD has collaboration but the UX doesn’t convince me. And the ones I was most interested in, the free online editors are… basic, very basic.

After spending time with various alternatives and none fully convincing me, I decided to build my own. That’s how MarkView was born: a modern markdown editor, with real-time preview, GitHub and Google Drive synchronization, and offline support as a PWA.

The problem I wanted to solve

My markdown workflow includes:

1. Project documentation that lives in GitHub repos
2. Technical notes that I want to access from any device
3. Post drafts that I eventually publish on my blog
4. README and changelogs that I edit frequently

I tried the GitHub web editor for GitHub docs (I don’t like it). For notes I tried Notion (didn’t convince me either). For posts I used local VS Code (no auto sync, only on my PC, etc).

I wanted a single tool that:

• Works in the browser, no installation required
• Has a powerful editor with keyboard shortcuts
• Shows real-time preview
• Syncs directly with GitHub and Google Drive
• Works offline when I don’t have a connection

The architectural decisions

Why CodeMirror 6

The editor is the main part of the application. I evaluated three options:

I chose CodeMirror 6 for three reasons:

1. Modularity — I only import the extensions I need
2. Performance — Native virtual scrolling for long documents
3. Extensibility — I can create custom extensions without touching the core

CodeMirror 6’s architecture is different from the previous version. Everything is immutable and functional. It was confusing at first, but once I understood the State → Transaction → New State model, the code became very predictable.

1
// Example of custom extension to insert 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 }, // Position cursor at title
8
    });
9
    return true;
10
  },
11
});

Why Zustand and not Redux or Context

State management was another important decision. MarkView has multiple state domains:

• Documents — Content, metadata, version history
• UI — Open modals, active panel, sidebar collapsed
• Settings — Theme, font size, auto-save interval
• GitHub — Repos, branches, remote files
• Google Drive — Folders, files, sync state
• Sync — Operation queue, connection state

With Redux, this would be 6 slices with a lot of boilerplate. With Context, it would be 6 nested providers with unnecessary re-renders.

Zustand allows me to have 6 independent stores that subscribe granularly:

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
// In a component, I only subscribe to what I need
17
const content = useDocumentStore(
18
  (state) => state.documents.find((d) => d.id === activeId)?.content
19
);

This avoids unnecessary re-renders. If I change a document’s content, only the components using that specific content re-render.

Why Hono for the backend

The backend is minimal: it handles OAuth, proxies requests to GitHub/Google APIs, and stores user preferences.

I chose Hono over Express or Fastify because:

1. Ultra lightweight — ~14KB vs ~200KB of Express
2. Edge-ready — Works on Vercel Edge, Cloudflare Workers, Deno
3. Type-safe — Native integration with Zod for validation
4. Excellent DX — Similar to Express but more modern

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
  );

Real problems and how I solved them

Scroll sync between editor and preview

The problem: I wanted scrolling the editor to move the preview to the corresponding section (and vice versa). But markdown doesn’t have a 1:1 relationship with the rendered HTML.

A heading ## Title takes up one line in markdown but can be an <h2> with variable padding and margin in the preview. A 10-item list in markdown is 10 lines, but in HTML they’re <li> elements with different heights depending on the content.

The solution: I created a rehype plugin that annotates each HTML element with its source line:

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
}

With this, each preview element has a data-source-line attribute. When I scroll the editor, I find the preview element closest to the visible line and scroll it into the 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
}, []);

Editing conflicts with cloud services

The problem: The user can edit a document locally while someone (or themselves from another device) modifies it on GitHub or Google Drive. Without conflict handling, whoever saves last wins and changes are lost.

The solution: I implemented a conflict detection system based on ETags and timestamps:

1. When opening a file, I save its etag or modifiedTime
2. Before saving, I check if it changed on the server
3. If it changed, I show a resolution modal with three options:
   • Use local version — Overwrite the server
   • Use remote version — Discard local changes
   • Manual merge — Show diff and let the user decide

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
}

The conflict modal uses a side-by-side diff viewer that highlights differences. It was more work than I expected, but it prevents data loss.

Preview performance with Mermaid and KaTeX

The problem: The preview updates on every keystroke (debounced to 300ms). But if the document has Mermaid diagrams or KaTeX equations, each update was slow because it re-rendered everything.

Mermaid especially is heavy. A medium-sized flowchart takes ~100ms to render. With 5 diagrams in a document, the preview lags noticeably.

The solution: Cache of rendered blocks with selective invalidation:

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
}

Now, when the user edits normal text, Mermaid diagrams use the cached version. They only re-render when the specific block content changes.

Version history per document

The problem: I wanted a version history like “undo on steroids”, where you can see previous versions of a document and diff between them. But each tab has its own independent history.

The solution: Each document has its array of versions with timestamps and content. The challenge was storage, since localStorage has a ~5MB limit.

I implemented:

1. Version limit — Maximum 50 versions per document
2. Delta compression — I only save the diff, not the full content
3. Automatic pruning — Old versions are deleted when the limit is exceeded

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
};

The diff viewer uses a line-by-line diff algorithm with change highlighting. It’s not as sophisticated as git diff, but it works well for markdown documents.

The preview theme system

I added themes so the preview looks like:

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

Each theme is a CSS file that tries to replicate the styles of each platform. They’re not exact copies (that would be complex and fragile), but they capture the visual essence.

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
  /* ... more 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
}

The user can change the preview theme independently of the app theme. It’s useful to see how a README will look before pushing it.

PWA and offline support

MarkView works completely offline.

Service Worker strategy

I use Workbox with a mixed strategy:

• App shell — Cache-first with background update
• Static assets — Cache-first, versioned by hash
• API calls — Network-first with cache fallback

1
// sw.ts (simplified)
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
);

Deferred sync

When the user is offline, cloud save operations are queued:

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

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

8
// When connection returns
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
      // Retry later or show error to user
22
      break;
23
    }
24
  }
25
}

Onboarding and UX

Even though I made it thinking about my own personal use, the idea was to offer it to the community, and in that case an editor with several features needs to guide the user. So I implemented:

Interactive tour

On first use, a tour guides through the main features:

1. The editor and its shortcuts
2. The preview panel
3. The file explorer
4. Cloud integration
5. Export options

Each step highlights the relevant element and waits for interaction before continuing.

Contextual hints

Small tooltips that appear when the user does something for the first time:

• “Tip: Use Ctrl+B for bold”
• “Tip: You can drag .md files here”
• “Tip: Right-click for more options”

Hints are marked as seen and don’t appear again.

Lessons learned

What worked well

1. CodeMirror 6 — Worth the learning curve. Performance and extensibility are excellent.

2. Zustand with separate stores — Keeps code organized and avoids unnecessary re-renders.

3. PWA from day one — Adding it later would have been much more work.

4. Aggressive preview caching — The performance difference is noticeable.

What I’d do differently

1. Use IndexedDB from the start — localStorage has size limitations that forced me to compress history.

2. Earlier E2E tests — Unit tests don’t capture integration bugs. Playwright should have come in earlier.

Closing

MarkView started as “I want a better editor” and ended up being a 3, almost 4 week project with many lines of code. Is it perfect? No. Does it solve my original problem? Absolutely.

I use it every day for documentation, notes, and drafts. Syncing with GitHub saves me from jumping between tools. Offline support lets me write anywhere.

If you have a similar workflow or just want a modern markdown editor that works in the browser, try it. It’s open source and free.

The best tools are the ones you build for yourself, because you understand exactly what problem they solve.

References

• MarkView on GitHub — Source code
• MarkView Demo — Try it online
• MarkView - Project Page — More details
• CodeMirror 6 — Editor documentation
• Unified/Remark — Markdown pipeline