Why I rewrote my CLI tool into an Isomorphic Monorepo

#javascript #productivity #opensource #webdev

I love tools like Docusaurus and Mintlify. They are powerful. But sometimes, they feel like bringing a bazooka to a knife fight.

I found myself spending more time configuring Webpack, fixing hydration errors, or dealing with heavy node_modules than actually writing the documentation for my side projects. I wanted something that felt like the old days of static HTML—fast, simple, robust—but with modern features like search and dark mode.

So I built docmd.

It started as a simple script. But with the release of v0.4.0 this week, it has evolved into something much more interesting. Here is the journey of how (and why) I refactored a Node.js CLI into an isomorphic engine that runs entirely in the browser.

The Philosophy: Zero-Config, Zero-Hydration

The core rule of docmd is simple: You write Markdown. We give you HTML.

There is no React runtime. There is no hydration process. The output is pure, semantic HTML and CSS. This makes the generated sites blazing fast and perfectly SEO-friendly by default.

The v0.4.0 Challenge: Going Isomorphic

For the latest release, I wanted to build a Live Editor—a place where users could type Markdown and see the preview instantly without a server round-trip.

To do this, I had to tear the project apart.

The Monorepo Split: I separated the logic into @docmd/core (the CLI runner) and @docmd/parser (the pure logic).
Removing Node Dependencies: The parser had to be stripped of all fs (file system) calls. It now accepts strings and returns objects.
The Browser Bundle: I used esbuild to bundle the parser + UI templates into a single < 15kb file.

The result? You can now run docmd live to spin up a local editor where the compilation happens 100% in your RAM. It’s instant.

What makes it special?

Aside from the architecture, here are the features I’m most proud of:

Offline Search: It builds a search index at compile time. The search bar works without an internet connection and requires no API keys (looking at you, Algolia).
AI Context (llms.txt): As of v0.4.6, it automatically generates an /llms.txt file, making your documentation easily consumable by AI agents like Claude or Cursor.
Mermaid.js Support: Built-in. Just use a code fence, and it renders the diagram.
Self-Closing Buttons: I hated the verbose syntax for containers, so I wrote a custom parser rule for buttons. ::: button "Click Me" /link is all you need.

Where we are going

docmd isn't trying to replace Docusaurus for enterprise-scale apps with complex dynamic needs. It’s for library authors, API documenters, and developers who just want to ship docs.

It is 100% Open Source (MIT). I’d love for you to try it out, break it, and tell me what you think.