mdstack
Docs

Drop a folder of markdown. Get a site.

Zero-config static-site CLI.
Dev, build, deploy. Four themes. 


            $
            npx @exor404/mdstack ./docs
Read the docs Star on GitHub
  • npm v0.2.1
  • MIT
  • Node 18+

How it works

From folder to site in one command.

No config to write. No framework to learn. Just point mdstack at a folder.

01 POINT

A folder of markdown

docs/
├ index.md
├ guide.md
└ images/
02 RUN

One command

$ mdstack ./docs

→ HMR dev server
→ live reload
→ ⌘K palette
03 SHIP

A static site

dist/
├ index.html
├ guide/...
├ sitemap.xml
└ robots.txt

Features

Everything you need. Nothing you don't.

The features below are what mdstack ships with today — no plugin marketplace, no hidden tiers.

  • Markdown that does more

    GFM tables, footnotes, ==highlights==, <kbd>, GitHub-style callouts, and <details>.

  • Math, server-side

    Inline $a^2 + b^2$ and block $$\int$$ rendered with KaTeX. Fonts auto-bundled.

  • Mermaid diagrams

    Fenced ```mermaid blocks render as SVG and follow the active light/dark theme.

  • Syntax highlighting

    Shiki tokenizes every fenced code block, theme-matched per built-in theme.

  • ⌘K command palette

    Fuzzy search over titles, headings, and body prose. Matches show a highlighted snippet.

  • Auto TOC + scroll-spy

    The sidebar fills itself from your headings. Active section highlights as you scroll.

  • Light & dark out of the box

    Toggle in the header, persisted in localStorage. Honors the system preference on first load.

  • Real builds

    Self-contained dist/ with robots.txt and sitemap.xml. Deploy anywhere static.

  • Four themes

    angular, vue, nuxt, homebrew. Pick one, override with --theme any time.

Themes

Pick a vibe. Or keep the default.

Four themes, one config line. Switch any time.

Install

Pick your package manager.

Five ways to get mdstack on your machine. The CLI binary is always called mdstack.

Install

  • npx @exor404/mdstack ./docs npx
  • npm i -D @exor404/mdstack npm
  • pnpm add -D @exor404/mdstack pnpm
  • yarn add -D @exor404/mdstack yarn
  • npm i -g @exor404/mdstack global

Quick start

  • mdstack ./docs # dev server with HMR
  • mdstack build ./docs # static build → ./docs/dist/
  • mdstack preview ./docs # serve the built dist/

CLI

CLI

One binary. Three verbs. One flag that matters.

Command What it does
dev Dev server with HMR (default if command omitted)
build Static build to <folder>/dist/
preview Serve the built dist/

Flags

--theme, -t <name>    override the theme from mdstack.config.js
                      one of: angular, vue, nuxt, homebrew

FAQ

Frequently asked.

What does mdstack actually do?
You point it at a folder of markdown files. It runs a dev server with HMR while you write, and produces a static dist/ directory when you build. No config required — drop the folder, get a site.
How is this different from VitePress, MkDocs, or Docusaurus?
Smaller surface area and more opinions. A single CLI binary, four built-in themes, and zero React/Vue config knowledge required to get started. If you need a plugin marketplace and a multi-locale routing system, those projects will serve you better. If you just want your folder of markdown to be a site, mdstack is shorter to read and shorter to run.
Can I customize the theme?
Today: pick one of angular, vue, nuxt, or homebrew via mdstack.config.js or the --theme flag. Custom theme authoring is on the roadmap — for now you can fork a theme CSS file and load it locally.
Where do I deploy the output?
Anywhere static. dist/ is self-contained — drop it on Vercel, Netlify, GitHub Pages, Cloudflare Pages, S3 + CloudFront, an nginx server, or a Docker container with any static file server.
Is it stable?
Pre-1.0. APIs and CLI flags may change before 0.x → 1.0. Pin your version in package.json and read the changelog before bumping.