mdsite

Static site generator: markdown tree → HTML site.

Goals

Build a navigable HTML site from a directory of markdown files — specifically this reviews site — without configuration overhead. We wanted nav links, breadcrumbs, and a consistent layout auto-generated from the file tree.

Effectiveness

Works well for the use case. Took under an hour from installation to a deployed site. The generated HTML is clean, navigation is automatic, and the template system is flexible enough for a custom layout. Pre-release quality, but solid for flat sites.

What made it effective

Zero configuration beyond -i, -o, and -t flags. No YAML frontmatter, no config files, no build plugins.
Navigation (TOC, breadcrumbs, prev/next links) is auto-generated from the file tree. No manual linking.
mdsite order -i src/ generates order.txt files to control page order — only needed if the default alphabetical order isn't right.

Bonus utility

The Prev / Next template variables make the site feel like a book — readers can page through all reviews linearly without using the nav sidebar.

Friction / pain points / surprises

Template inside the input directory causes a stack overflow. If template.html is inside the -i directory, mdsite includes it in the file tree, processes it as content, applies the template to itself, and recurses until the process crashes. There's no error message — just a stack overflow. The fix: keep the template as a sibling of src/, not inside it. (reviews/template.html, not reviews/src/template.html.)

Template variables expand in content files, even inside code blocks. If a markdown file contains

in a backtick code block, mdsite expands it as a template variable rather than treating it as literal text. The only workaround is HTML entities ({{toc}}), which breaks the authoring experience for any doc that discusses mdsite's own template syntax.

No --help flag. mdsite --help errors immediately because the binary tries to read the input directory before parsing flags. Flags were discovered by reading dist/cli/args.js in the installed package.

Wrangler requires a pre-existing Cloudflare Pages project. wrangler pages deploy fails if the project doesn't exist. First deploy requires creating the project via the CF API or dashboard separately.