Forem: Ghazi

Why I rewrote my CLI tool into an Isomorphic Monorepo

Ghazi — Mon, 16 Feb 2026 06:52:17 +0000

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.

npm install -g @docmd/core
docmd init

Repo: github.com/docmd-io/docmd
Live Demo: live.docmd.io

Suggestions will surely improve the project potential.

Ghazi — Sat, 02 Aug 2025 20:48:21 +0000

Brian Sprout

Aug 1 '25

Best Lightweight Docusaurus Alternative? I Think It’s "docmd" - A Refreshingly Minimal Docs Generator

#documentation #javascript #webdev #productivity

Comments 1

2 min read

Interesting.

Ghazi — Sat, 02 Aug 2025 20:47:27 +0000

Brian Sprout

Aug 1 '25

Best Lightweight Docusaurus Alternative? I Think It’s "docmd" - A Refreshingly Minimal Docs Generator

#documentation #javascript #webdev #productivity

Comments 1

2 min read

Surely people are picking it up now. A well written and analyzed piece for a very early release project.

Ghazi — Sat, 02 Aug 2025 20:46:39 +0000

Brian Sprout

Aug 1 '25

Best Lightweight Docusaurus Alternative? I Think It’s "docmd" - A Refreshingly Minimal Docs Generator

#documentation #javascript #webdev #productivity

Comments 1

2 min read

Docmd: Markdown to Docs, No Bullshit Documentation Generator

Ghazi — Thu, 31 Jul 2025 22:14:34 +0000

Writing documentation shouldn’t require a framework, a theme system, and a master's in YAML. Markdown is simple. So the output should be too.

Docmd is a Node.js-based static site generator for documentation. It takes a folder of .md files and spits out a responsive HTML site — with themes, sidebars, nested components, the usual stuff — without touching React, Vue, or anything that thinks hydration is necessary to show text.

Why Docmd?

Here’s the reality:

Docusaurus is bloated.
MkDocs is Python-based.
Mintlify wants a subscription.
GitHub’s own markdown rendering is mid.

So I built something for developers who just want this:

npm install -g @mgks/docmd
docmd init

That’s it. You get a working documentation site.

Features (aka what actually works):

Multiple themes (sky/ruby/retro)
Nested custom containers: :::tabs, :::card, :::steps, etc.
Sidebar config, breadcrumb, favicon, metadata, theme-modes
GitHub Pages support
Local dev server (docmd dev)
Zero client-side JS frameworks (no React, no Bootstrap, no clutter)
Built-in plugins (SEO, sitemap, GA)
Pure markdown + YAML frontmatter - no templating drama

Built For People Who:

Write code, not content for marketing
Prefer folders over CMSes
Want to deploy docs to GitHub Pages without 30 extra steps
Hate “init” scripts that install 200MB of dependencies

Not For:

People who want live search, Algolia (sorry dev.to team), or page transitions
Anyone emotionally attached to React
Marketing teams with a Figma addiction

Try docmd

🔗 docmd.mgks.dev
📦 @mgks/docmd
🔧 github.com/mgks/docmd

No setup wizard. No plugins just to get tabs. No weird templating syntax.

Just markdown in → docs out.

That’s the whole pitch.