ZenMD

What

https://www.npmjs.com/package/zenmd

A convention-over-configuration static site generator, eliminating all boilerplate and framework setup, requires no decisions or input from the user, freeing them to focus solely on their content.

Who

Crafted for the neurodivergent minimalist with ADHD/OCD, who can't remember all the reasons why config files can exceed the content.

Why

It is an attempt in answering:

How many steps does it take to publish markdown to a simple static blog with images and links between pages? 10? 20? Why not less than 5?

— Shao | 少蒙 (@randomor) October 14, 2023

With ZenMD, it's now just two steps:

1. npx zenmd
2. netlify deploy or whatever static hosting platform.

It transforms the following @randomor folder into the dist folder and properly link between them.

├── @randomor
│   ├── WonderWeave Press.md
│   ├── assets
│   │   └── digital_garden.webp
│   ├── index.md
│   ├── posts
│   │   └── index.md
│   ├── zenjournal.md
│   └── zenmd.md
└── dist
	├── assets
	│   └── digital_garden.webp
	├── index.html
	├── posts
	│   └── index.html
	├── sitemap.xml
	├── wonderweave-press.html
	├── zenjournal.html
	└── zenmd.html

How is it different?

Started looking around, yet, no tool does this combination of things:

• With one command, transforms a folder of markdown files (usually takes more than a handful of steps).
• No extra config, no fluff and distractions that's not content.
• Supports internal links: [another page](./another-link.md)
• Supports wiki links: [[another page]]
• Supports images.
• Support dark/light mode with default layout.
• Allows custom layouts in multiple levels of directories.
• Layout support any value from frontmatter.
• Generates sitemap.xml

ZenMD fills the gap above, and also opens up a few interesting workflows:

• (Bring your own) BYO editor, note-taker
  • Tested with simple Obsidian vaults, VS Code (with Markdown Notes extension), Bear Notes exports.
• BYO static site host, Netlify, Vercel, or Cloudflare Pages
• BYO favorite frontend framework, let interactive pages be complex, but leave the content pages pure. Just add && npx zenmd posts -o public/posts to your existing build step. That's how I generated this site for ZenJournal.
• Back to the Future/Past, #nobuild, #noserver:
  • Preview the generated site by opening the .html pages directly, without an app server
  • html layout editing without a build process
• An out-of-the-box minimalist layout that support dark and light theme, using Tailwind Typography.

What is this good for?

• Allow anyone to quickly transform their directory of markdown knowledge base or personal note vault into a digital garden.
• Create a simple wiki, using wiki links and GitHub as the CMS.
• For anyone to create a site in 30 seconds, using their existing markdown content.