Markleft vs md2rich: the two halves of an AI-assisted Markdown workflow

This article walks through what Markleft is, why the "comments in the document, not instructions in the chat" idea is the right direction for working with AI, and how it pairs cleanly with a client-side converter like md2rich to take a draft from a rough AI pass to a published post — without ever letting your writing leave your machine.

Why normal AI iteration feels broken

Lysk's argument starts with an analogy. Imagine emailing a colleague a five-page document and asking for feedback. They would never reply with a prose description of everything they dislike, then a completely rewritten document, and expect you to diff the two files yourself. That workflow — "Email me a description, I send you a rewrite, then you compare" — was solved decades ago by comments and tracked changes in Word, and by Suggesting mode in Google Docs.

Yet that is exactly how most people iterate with AI. You paste a prompt describing a change, the model returns a new version of the whole document, and you are left with two problems: finding the change (diffing rendered Mermaid diagrams, tables, and SVGs by eye is genuinely hard) and recovering the intent (which part of your original instruction was this change meant to satisfy, and did it actually satisfy it?). The prompt that explained your intent lives and dies in the chat window; the document carries no trace of it.

The core problem: describing a location in prose is imprecise

Lysk demonstrates the precision problem with a tiny prompt asking Claude to write a Markdown story about a pelican on a bike plus an SVG illustration. A critique like "fix the pelican's head, put the left foot on a pedal, and make the bird look sportier" sounds specific but isn't. "The headline" only works because a toy document has one obvious headline; in a longer article you need to describe which headline. "The left foot" is worse — prose cannot point at the exact shape inside an SVG. That is why design tools like Figma let you comment directly on the design surface instead of describing coordinates in words.

Now scale that to a multi-page document with repeated headings, nested tables, diagrams, and code, and a request like "move the backup server to the top right, next to the second database server, in read-only mode." There is also an attention problem: while reading paragraph one, you think "this doesn't make sense," but you do not want to stop reading and draft a prompt. You want to leave a mark and come back later. The document needs an annotation layer, not more chat.

What Markleft actually is

Markleft (MIT-licensed, on GitHub) is built from three components that work together:

1. A WYSIWYG Markdown editor that runs as a Chrome bookmarklet. Open a local .md file in Chrome, click the bookmark, and a full editor loads that reads the file, parses its Markleft footnotes into comments and suggestions, and renders them.
2. A Markdown-compatible annotation spec. Comments are ordinary Markdown footnotes with reserved identifiers. A text range uses an ID like range-prev-12-chars-14824-a1b2; an image annotation uses image-X-Y-* with normalized coordinates; code ranges use code-line-L-col-C-len-N-*. Blocks get stable IDs injected as HTML comments, and replies to comments use comment-*.
3. A prompt that teaches the AI how to respond. When you save, the editor compiles the annotations into a prompt that explains Markleft to the model and tells it to address each comment by appending suggestions — not by rewriting the file.

The key safety property is that suggestions are append-only footnotes. A suggestion ID looks like suggestion-s2-update-block-babf825b, and its body is the proposed replacement Markdown. Because the AI only appends a footnote definition and never touches the document's actual content, it can propose a change without receiving permission to alter the file it is reviewing. You see every change as a reviewable suggestion, with text diffed inside corresponding rendered elements and image replacements shown as before-and-after sliders.

A worked example: the annotation spec in action

Say your Markdown draft contains a bloated sentence you want tightened. With Markleft you select the sentence and comment on it. The editor injects a footnote anchor that encodes a fingerprint of the exact text, plus the comment body:

This sentence needs less ceremony.[^range-prev-12-chars-14824-a1b2]

[^range-prev-12-chars-14824-a1b2]: Make this more direct.

Here range-prev-12-chars says the annotation covers the previous twelve visible, non-whitespace characters, and the rest of the ID is identity plus a content fingerprint so Markleft can detect when an anchor has gone stale. To a normal renderer — GitHub, for example — this is just a footnote. To the AI and the Markleft editor, it points at a specific sentence. The AI responds by appending a suggestion footnote rather than rewriting the paragraph:

[^suggestion-s2-update-block-babf825b]: Trim the qualifying clause for a more direct opening.

Replaces the selected block. Accepts with one click in the editor.

Because the suggestion stays a footnote at the end of the file, the rest of your document is untouched until you review and accept it. That is a radically better loop than "paste a rewrite, then spot the difference."

Where md2rich fits: the publish half of the same workflow

The whole point of keeping a Markdown file as your source of truth is that the same file serves every stage — drafting, AI iteration, review, and publishing. Markleft covers the review stage. Once you have accepted the AI's suggestions and your document is clean, the remaining step is turning it into a formatted post for a rich-text platform. That is the job md2rich does best.

Here is a small finished Markdown block after a Markleft review:

## Better working with AI

- Keep your feedback in the document, not the chat.
- Ask the model to propose, then review each suggestion.
- Publish the same Markdown as a formatted post.

Feed that through md2rich and the same content becomes formatted rich text — real headings, bold, bullet lists — ready to paste into LinkedIn, X Articles, Medium, or Notion without losing formatting. You do not copy-and-paste raw Markdown and hope the target platform renders it; you get clean, styled output with the structure intact.

Markleft and md2rich side by side

They operate on the same file without conflict: Markleft's footnotes are valid Markdown that any other tool, including md2rich, simply sees as footnotes. You accept the suggestions you want, and what remains is clean Markdown ready to convert.

Why "Markdown stays the source of truth" is the through-line

Both tools rest on the same philosophy that has driven the recent Markdown-for-AI-agents movement: the plain-text file, not the chat or the platform, is the durable asset. When your comments, your AI's suggestions, and your final prose all live in versioned Markdown, you get three things normal chat iteration cannot give you.

• Auditability. Git shows you how the document — and every suggestion you accepted or rejected — evolved, the same way code review does.
• Portability. The same file works with any AI tool, any editor, and any publishing platform. Nothing is locked into one vendor's chat history.
• Reusability. One source becomes your post, your newsletter, and your documentation — converted to rich text only at the moment you publish.

This is the same loop behind our earlier guides on why client-side conversion matters and Markdown to rich text. Write in plain text, keep the working draft close, and convert only when you ship.

The complete pipeline, end to end

Putting it together, a modern AI-assisted writing workflow looks like this:

1. Draft in Markdown. Open a local .md file, write in your editor of choice, commit it so the history is auditable.
2. Get a first AI pass. Have a model expand, tighten, or structure your draft into a first full version.
3. Review with Markleft. Open the file with the bookmarklet, comment on the sentences, blocks, or images you want changed, and let the AI propose append-only suggestions.
4. Accept what works. Review each suggestion in context and accept or reject it — the document is never opaque-rewritten behind your back.
5. Publish with md2rich. Convert the finished Markdown to rich text and paste it into LinkedIn, X Articles, Medium, or Notion.

Every stage touches the same plain-text file. Your comments, the AI's proposals, and your final prose are all preserved in Markdown, and nothing is uploaded to a server you do not control.

FAQ

Published by md2rich. This article is for informational purposes; the workflow it describes is a general pattern, and the Markleft facts are sourced from the project's GitHub repository and the author's blog post. md2rich is referenced only for the conversion step.