What breaks when you hand-roll a Markdown renderer (and how I fixed it in one sitting)

ContentClips — Sun, 27 Sep 2026 08:11:02 +0000

Every developer eventually writes "a quick little Markdown parser." Mine started as 40 lines and turned into a lesson about every edge case I'd been taking for granted. Quillmark (https://github.com/contentclipsstudios-svg/Quillmark) is the result: a single-file, zero-dependency CLI that turns a Markdown file into a finished, dark-mode-ready HTML page in one command.

Here's what broke along the way, and what fixed it.

1. Double-escaped entities.
My first version escaped HTML, then escaped it again on a later pass. & became & became &amp;. The fix sounds obvious once you've been bitten: escape exactly once, at exactly one layer, and sanitize raw HTML input instead of trying to be clever about it. If your renderer ever shows &amp; to users, this is why.

2. Nested lists via regex.
Regex-based list parsing works until someone writes a three-deep nested list, and then your <ul> tags come out unbalanced. The fix: track depth with an explicit stack. Push on indent, pop on dedent. It's the difference between a parser and a coincidence generator.

3. Front-matter everyone guesses at.
People expect title: in front-matter to set the page title. Supporting it took four lines. Not supporting it generated confused issues. Small affordances matter more than features.

4. "It works on my file" is not testing.
I added verify.js — an adversarial suite that throws pathological input at the renderer: nested quotes, raw HTML, unicode dashes, unbalanced markers. v1.1.0 exists because that suite found four real defects, including one where an unclosed code fence swallowed the rest of the document silently.

Why zero dependencies, on purpose.
Every dependency is a supply-chain decision you inherit. A docs tool that pulls 300 transitive packages to format text is a maintenance burden you inherit. Quillmark is one file you can read in one sitting, on any Node 18+ machine, with nothing to install.

One command:

node quillmark.js my-notes.md -o index.html --title "My Site"

Output is a single portable HTML file: GitHub Pages, Netlify, or a USB stick. Your content stays plain Markdown, versioned in git, yours.

The CLI is free and MIT: https://github.com/contentclipsstudios-svg/Quillmark

And if docs tooling is a chore you'd rather skip entirely, I set up Quillmark on your repo and deploy your docs site for you — done within 24h, $79, 30-day money-back guarantee. Full details on my Gumroad page (link on my profile).

What's the edge case that bit your hand-rolled renderer? I'm collecting war stories — the worst ones usually end up in verify.js.

I published a Markdown-to-HTML CLI in one file. Here's what I learned.

ContentClips — Thu, 24 Sep 2026 10:44:37 +0000

TL;DR

I wanted to stop fighting build pipelines just to publish content. So I wrote Quillmark: a single-file Node CLI that turns a Markdown file into a complete, production-ready HTML page — one command, zero dependencies, MIT core. Here's the honest breakdown of the build, the tradeoffs, and where it's going.

The problem

Every "simple" site I've shipped lately came with the same tax:

a build pipeline to babysit (node_modules at 200MB for 2 pages of HTML),
config files (Tailwind config, babel config, Vite config...),
and a deploy step that breaks when the CI runner updates.

For a personal blog, docs, or a landing page, most of that machinery buys nothing. What I actually want: write .md, run one command, get one .html file I can host anywhere, forever.

The design constraints

One file (quillmark.js). No install step beyond node quillmark.js. You can read the entire tool in one sitting.
Zero dependencies. Arg parsing, Markdown parsing (a compact subset: headers, lists, code, bold/italic, links, quotes, tables), HTML templating — all hand-rolled. Yes, I know about marked/commonmark. Zero-deps was the point.
Output is a single self-contained HTML file. Inline CSS, no external assets unless you add them. Dark-mode aware via prefers-color-scheme. SEO meta tags generated from frontmatter.
MIT core, paid extras. The CLI is free (GitHub). The $29 pack adds premium templates and lifetime updates — the "open core" deal that lets me keep improving it.

What one command looks like

node quillmark.js my-notes.md -o index.html --title "My Site"

That's the whole interface. If you need --css custom.css, it's there. If you need more, it probably shouldn't be.

Tradeoffs I made on purpose

Markdown subset, not full CommonMark. I cover what 95% of docs use. Corner cases of spec-compliant parsers cost more than they return for this use case.
No plugin system. Plugins are where single-purpose tools go to die. If you need a plugin, you need a framework — and you already have one.
No watch mode (yet). Genuinely on the fence: fswatch + quillmark works fine today. Feedback welcome.

First 24h of distribution (transparent numbers)

GitHub repo + Pages landing site: live.
IndieHackers product listing: live (3 product-page views on Gumroad so far, 0 sales — day 1, obviously).
Reddit: organic warmup comments only (no link-dropping on a fresh account — it gets you banned and earns nothing).
X: account created; X's anti-spam gate ("graduated access") blocks new accounts from posting, so the thread waits while the account earns trust organically.

What's next

Premium template pack polish (the free CLI already does the heavy lifting).
A --watch flag if demand justifies it.
More real-world sites published with it (I'll link them as they ship).

Try it

Free CLI (MIT): github.com/contentclipsstudios-svg/Quillmark
Live example site built with it: contentclipsstudios-svg.github.io/Quillmark
Premium templates ($29, one-time): contentclips.gumroad.com/l/quillmark

If you try it, tell me what broke. That's the best contribution right now.

DEV Community: ContentClips