Building a Markdown editor (Markflow)

IgorKha — Fri, 24 Apr 2026 08:16:35 +0000

I’ve been working with Markdown editors both as a user. At some point I wanted to better understand how they actually behave under the hood, especially when documents get more complex (code blocks, math, diagrams, etc.).

As a small exploration, I built a minimal editor to experiment with these ideas:
https://github.com/IgorKha/markflow

You can try it here:
https://igorkha.github.io/markflow/

This post is not an announcement, but a summary of a few implementation decisions that might be useful if you’re building something similar.

Starting point

The initial goal was simple:

keep Markdown as the source of truth
support common extensions (code, math, diagrams)
avoid introducing a separate document format

From there, most of the work ended up around how editing is handled, not rendering.

Using Monaco as the editor layer

The editor is built on top of Monaco.

This gives:

a mature text editing model
good performance characteristics
predictable behavior for selections, undo/redo, etc.

At the same time, Monaco operates on plain text, while Markdown has an implicit structure. Bridging that gap becomes the central problem.

Working with Markdown as a structure

Instead of treating Markdown purely as a string, the implementation keeps track of its structure (via parsing into an AST).

This allows reasoning in terms of:

blocks (paragraphs, headings, lists)
fenced regions (code, math, diagrams)
document hierarchy

Even partial structural awareness helps avoid some classes of issues when editing mixed content.

Synchronizing structure and editor state

One of the core pieces is keeping two representations in sync:

the text inside Monaco
the parsed Markdown structure

This synchronization is used to:

detect which block the cursor is currently in
apply transformations without breaking surrounding content
keep rendering consistent with the editor state

This part is still evolving, but it defines most of the internal complexity.

Rendering pipeline

Rendering is based on standard tools from the Markdown ecosystem:

syntax highlighting via highlight.js
math rendering via KaTeX
diagrams via Mermaid

These are applied on top of the parsed Markdown rather than directly on raw text, which keeps responsibilities separated:

parsing → structure
rendering → visual output

Mobile behavior

The editor is designed to work in a browser without assuming a desktop environment.

Some adjustments were made so that:

layout adapts to smaller screens
scrolling and input remain usable
documents can be viewed and edited on mobile devices

This is not a separate mobile version — just the same editor adapted to different screen sizes.

Sharing without a backend

There is no backend in this project.

To make sharing possible, the document state can be encoded into a URL. Opening that link reconstructs the document in the editor.

This approach:

does not require storage
does not persist data server-side
works for quick sharing or examples

It’s intentionally simple and limited by URL size, but sufficient for lightweight use cases.

Closing

This project is mainly a technical exploration of how Markdown editing can be structured internally while still using a standard text editor as a base.

If you’re working on something similar, feedback or discussion would be useful.

Repo: https://github.com/IgorKha/markflow
Demo: https://igorkha.github.io/markflow/

DEV Community: IgorKha