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.