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 macros make the site feel like a book — readers can page through all reviews linearly without using the nav sidebar.

Macro reference

Ten built-in macros: content, title, toc, next, prev, up, home, breadcrumb, inputpath, and macro. The set is small and documented at benchristel.github.io/mdsite/reference/macros.html.

The macro macro outputs its arguments as literal text — intended as an escape hatch. In practice it only works for macros other than content: if you escape the content macro it outputs the literal string, which then gets re-expanded when the template inserts the page content, causing infinite recursion.

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.)

Macro expansion is not escapable for recursive macros. Macros expand everywhere — including in backtick code blocks, and in the output of other macros. The macro escape hatch works for most macros but not for content, because the escaped literal gets expanded a second time when the template inserts the page body. This means you cannot write about the content macro in mdsite content without triggering a stack overflow. Any template slot name that collides with a built-in macro is also silently consumed rather than passed through.

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.