Getting Started#
Requirements#
Python 3.11 or newer. That is the whole list.
3.11 is the floor because tomllib arrived in it, which is what reads
Configuration without a dependency or a hand-written parser.
Install#
Either take the single file:
python tools/build_pyz.py # produces mdssg.pyz
python mdssg.pyz --version
mdssg.pyz is a zipapp: a zip archive with a shebang. Copy it anywhere. On
Linux it runs directly, on Windows the py launcher handles the .pyz
extension. There is nothing to install and nothing to uninstall.
Or install it as a normal package:
pip install -e .
mdssg --version
Create a site#
mdssg init my-site
cd my-site
mdssg serve
init writes a Configuration file and two notes. serve builds the site,
opens it on http://127.0.0.1:8000/, and rebuilds when anything changes. The
page reloads on its own.
The layout it creates:
my-site/
mdssg.toml settings
content/ your markdown, arranged however you like
static/ copied to the output untouched
Every build also creates /search/, /graph/, a styled 404.html, and the
small assets they need. Search is local to the browser; no search server or
account is involved.
The commands#
| command | what it does |
|---|---|
mdssg init [dir] | scaffold a new site |
mdssg build | render the site into public/ |
mdssg build --clean | discard previous output and the build cache first |
mdssg build --index-only | precompute the graph for CGI, render nothing |
mdssg serve | preview locally, rebuilding on change |
mdssg new "A Title" | create a note |
mdssg new "A Title" --post | create a note with today's date, making it a post |
mdssg doctor | report on the graph: seeds, likely typos, orphans |
mdssg doctor --explain-related X | show why notes are related to X |
Every command takes -C DIR to work on a site somewhere else, and -v to say
more about what it is doing.
Posts and notes#
There is no setting for this, and no folder convention. A note with a date
is a post. A note without one is a note.
---
title: On Writing Small Tools
date: 2026-07-18
---
Posts appear in reverse chronological order under Writing on the home page and in the RSS feed. Notes appear under Notes, sorted by title, and never reach the feed. The distinction already exists in your frontmatter, so mdssg reads it rather than asking you to state it twice.
Publishing#
mdssg build writes plain files into public/. Upload that directory
anywhere: GitHub Pages, Netlify, an S3 bucket, a folder on a web server.
Nothing needs to run on the server. If your host is old enough that this is not true, see Deploying for the CGI path.