mdssg#

A static site generator for a folder of linked markdown notes. One file, no dependencies, Linux and Windows.

This site is its own documentation. Everything you are reading lives in example/content/ as ordinary markdown, and the site you are looking at was built from it by running mdssg build -C example. If a feature is described here, it is also being demonstrated here.

python mdssg.pyz init my-site
python mdssg.pyz serve -C my-site

The idea#

Most generators treat a markdown file as a document that happens to sit in a folder. mdssg treats the collection as a graph, and the folder as an implementation detail of how you like to organise things.

That single change is where the four things below come from.

• Wikilinks resolve by name, from anywhere. Folders never appear in a URL.
• Seed Pages mean a link to an unwritten note is not a dead link. It is a page assembled from every sentence that mentioned it.
• Backlinks quote the sentence they came from, not just the title.
• Related Notes come from the shape of the graph, with no tags to maintain and no model to run.
• The global /graph/ view turns that structure into a compact, clickable SVG.
• Every note shows its immediate graph neighbours, and /search/ searches the complete site without a server or external service.

Start here#

• Getting Started — install, create a site, publish it
• Markdown — exactly what is supported, and what is deliberately not
• Configuration — every option
• Templates — the theme, and how to replace parts of it
• Deploying — static hosting, and render-on-demand over CGI
• How It Works — the design, and the parts that were harder than expected

What it does not do#

It has no plugin system, no taxonomy engine, no shortcodes, and no asset pipeline.

It has an empty dependency list and the intent is to keep it that way.

Status#

This project is finished, and will rarely be updated. It does what it was built to do, and staying small matters more than growing.

So do not wait on an update: fork it and change it. Rename it, strip it down, take the parser or the graph code and build something else, ship it commercially. The MIT licence already permits all of that — this note only says so out loud, so nobody has to wonder whether it was meant.