ColaMD: a WYSIWYG Markdown editor that stays in sync with the disk

An editor that removes the chrome

ColaMD is an open-source, free Markdown editor for writing, notes and documentation, and the first line of the README states the design position: a free, elegant Markdown editor anyone can pick up, with no toolbars, no clutter, and the file on disk always what you see.

The elaboration is more specific. It is built for people who just want to write, with no toolbars, no status bar and nothing to configure, just your text and a file list, and with a tab strip appearing only when you open a second document.

That is a much stronger position than a preference. A tab strip that only exists when it is needed, a permanent sidebar that does not exist, a status bar that has been removed: the interface is the product, and the whole bet is that a person who opens the app and starts typing is more likely to write than a person who opens the app and looks for a button.

The editing model is described as true WYSIWYG. You type Markdown and see rich text directly, with no split-pane preview. That is a real design decision rather than a slogan, because a split preview is the usual answer and the split is the usual source of friction. Here the rendered form is the editing surface and the markup is what is underneath.

The project is MIT licensed, written in TypeScript on Electron, with the last push to the repository on 2026-10-19 and the current release v2.7.6 from 2026-10-08.

Always in sync, and why an agent workflow makes it matter

The feature that the README puts first, above everything else, is always in sync. Whenever the file changes on disk, from an AI agent, a script or another editor, the editor updates immediately, with no reopening and no manual refresh.

This is the differentiator, and the reason it appears in the top level description rather than in a list of conveniences. The scenario it addresses is specific: you ask a coding agent to edit a document, and you want to see what it did. In a normal editor the file on disk has changed and your buffer has not, and the resolution is a reload that throws away your cursor position and your undo history, or a warning that the file changed on disk.

The project names the agents in question in the README, an AI agent such as Claude Code or Codex, a script, or another editor. The claim is that whatever writes the file, ColaMD shows the new content right away.

The roadmap shows how much work sits behind that claim. Version 1.6 is listed as robust live sync with atomic-save rename detection, watcher self-recovery and spellcheck off. Version 1.7 adds live updates when agents create or remove files, not just when they change them. So the sync layer handles the awkward cases that a naive file watcher gets wrong, and the project has clearly been fixing them over several releases.

There is a companion detail in the version history. Version 1.6 also turned spellcheck off, which is a small thing that tells you the author cared about the editor not fighting you.

The Markdown dialect, and the features that make it feel like a word processor

The feature list is long, but a few entries say more about the editor than the rest.

Highlights and LaTeX: you write the equals-delimited highlight syntax and mathematical formulas are rendered with KaTeX. Mermaid diagrams render as diagrams in an isolated hidden iframe with strict parsing, and clicking a diagram lets you edit its source. Search and replace works on the current document with the usual shortcut, replacing the current match or all matches.

Smart line breaks is the one that changes how you write. Single newlines render as line breaks, and the README gives the reason, it matches how people and AI tools write Markdown. That is a considered choice, and it is the opposite of the CommonMark default, where a single newline is just a space. An agent writing a file will often use single newlines as paragraph breaks, and a strict renderer will join them into one paragraph.

Task lists are interactive, with clickable checkboxes and a keyboard shortcut. Rich text copy preserves formatting when you paste into WeChat, email and other rich-text editors, which is a practical detail for anyone who writes in Markdown and publishes elsewhere.

Other entries are about navigation and safety rather than authoring. There is a file browser for the selected folder and a document outline for heading navigation, a source mode for inspecting or editing raw Markdown directly, heading anchors that work with CJK text, recent files and session restore for the last ten documents, multiple windows each with its own save queue and close protection, and a quiet titlebar indicator that shows unsaved or saved and then fades.

Twelve themes, and CSS files you can read

There are twelve built-in themes, six light and six dark, and the inspirations are named, Bear, Notion, iA Writer, Kindle, Solarized, Nord, Gruvbox and Dracula.

What makes this worth a section is that every theme is also a standalone CSS file in the themes directory, with a guide to writing your own and a commented template to copy. So the theme set is not a set of opaque blobs inside the application binary. It is a set of stylesheets on disk that you can read, take apart and use as the starting point for a thirteenth.

That matters for a text editor because a theme is a claim about typography, and the only way to judge a claim about typography is to look at the values. A line height, a measure, a weight, a colour pair, all of it is in the file.

The project also ships a script that checks theme colours, check-theme-colors.mjs, and a separate verification script for themes, which suggests that the themes are treated as something that can regress and be tested, rather than as decoration that gets eyeballed once.

For comparison, the alternatives named in the README are Obsidian, Typora and VS Code, and the framing is that ColaMD works alongside them, all sharing the same .md files, with each tool doing what it does best. That is a positioning against a vault application rather than a competition with it.

Getting the document out: PDF, HTML, Word and images

The export section is where a writing tool has to prove it is more than an editor, and ColaMD covers four output paths.

A document becomes a themed PDF, a self-contained HTML file, or an editable Word document. The Word export is implemented with the docx library in the dependency list, and the PDF and HTML paths have their own verification scripts in the package manifest, which means the exports are covered by the repository's own checks rather than only by manual testing.

Image export is the unusual one. You can share a Markdown document as one continuous PNG at the desktop or mobile reading width, with longer documents continuing as numbered pages. That is a feature aimed at people who need to post a document somewhere that does not take Markdown, and the reading width choices are the detail that makes it usable, since a document rendered at a phone width reads very differently from one rendered at a desktop width.

Portable image paths are the other thing in this area. Local images use safe file URLs for display and return to relative paths when the document is saved, so a document with screenshots can be moved between machines without leaving absolute paths behind.

The version history also shows the export story being revised rather than added once. Version 1.6.2 temporarily removed HTML export, and version 1.8.1 removed Mermaid rendering so that code blocks stayed native and editable. Version 2.0.0 brought Mermaid back with luminance-aware colours, and version 1.9.0 added the Word export, the image export, the document outline and themed PDF pages. So the project has been willing to remove a feature when it did not fit, which is a good sign about how the rest of the list is curated.

The repository, the verification scripts and the build

The layout shows an Electron application with a web build alongside it, which is a modern arrangement and explains the separate TypeScript configurations.

The repository has a base tsconfig and separate files for the main process, the preload, the renderer and the web build, plus a vite.web.config.ts next to the electron.vite.config.ts. The web build is a separate script, build:web, and the mobile directory suggests a phone build is planned rather than shipped.

The editor itself is built on CodeMirror 6, with the markdown language package, the lezer parser, the commands and search extensions, and remark-gfm for the GitHub flavoured markdown. KaTeX and Mermaid are the renderers, and electron-updater handles the update channel.

What stands out is the family of verification scripts, because a small project usually has one test command and this one has a dozen.

    "check:theme-colors": "node scripts/check-theme-colors.mjs",
    "verify:markdown": "node scripts/verify-markdown.mjs",
    "verify:links": "node scripts/verify-links.mjs",
    "verify:features": "node scripts/verify-features.mjs",
    "verify:scroll-render": "node scripts/verify-scroll-render.mjs",
    "verify:image-export": "node scripts/verify-image-export.mjs",
    "verify:export-pdf": "node scripts/verify-export-pdf.mjs",
    "verify:themes": "node scripts/verify-themes.mjs"

Each of those names a feature area that is easy to break silently, and the naming convention is uniform so a contributor can see at a glance what the project checks. The principles file at the repository root, alongside the design document and the agent instructions, suggests the project keeps its rules in writing.

The limits and the pace of the project

Three things to weigh before you make it your daily editor.

The first is the format. ColaMD works on plain Markdown files in a folder. It is not a vault, it has no backlinks graph, no plugin system and no proprietary format, and the README does not claim any of them. A user whose notes depend on a graph view or on plugins is not in the target audience, and the project is explicit that it works alongside Obsidian, Typora and VS Code rather than replacing them.

The second is that the feature set is young and moving fast. The releases are frequent, v2.7.4, v2.7.5 and v2.7.6 within three days, and the roadmap in the README is a list of version notes rather than a plan. Features appear and are removed again, as the Mermaid and HTML export episodes showed, and the version numbers suggest a project that is still finding its own shape rather than one with a settled feature set.

The third is the packaging reality. The downloads are a dmg for macOS, an exe for Windows and an AppImage or a deb for Linux, which is a small footprint by the standards of an Electron application, and the project uses electron-updater so the update path is handled. But an Electron editor is still an Electron editor, and the README's own promise that the file on disk is always what you see comes with the usual cost of an application that owns a buffer.

What the project has going for it is that the rules are written down and the checks are named. A principles file, a design document and a directory of verification scripts are a better basis for trusting a young project than a feature list is.

Editorial conclusion

Adopt ColaMD if you write Markdown in a plain folder and want an editor that shows the rendered result while you type and that notices when an agent rewrites the file under you, because both are the reasons the project exists. Do not adopt it if you need a vault with backlinks, plugins or a proprietary format, since the editor works on ordinary .md files and claims no such features. Before you rely on it, run the project verification scripts in the package manifest, since the repository ships checks for themes, exports, links and Markdown handling that will tell you more than the feature list will.

Frequently asked questions

Official sources

1. License: MIT
2. marswaveai/ColaMD on GitHub
3. Project website
4. README
5. Releases