Deploying#

Static, which is almost always the answer#

mdssg build

public/ now holds plain files. Upload it. Nothing runs on the server.

When site.url is configured, the build also writes sitemap.xml, canonical links on every page, and feed.xml for dated notes.

Rebuilds only rewrite files whose contents actually changed, so rsync, aws s3 sync and every other mtime-based tool upload the pages you edited rather than the whole site. See How It Works.

GitHub Pages#

This repository ships .github/workflows/pages.yml, ready to build and deploy the documentation. In the repository settings, choose Pages → Source → GitHub Actions once; pushes to main handle the rest.

The workflow reads the public URL from GitHub itself. Project sites live below the repository name, such as /mdssg/, and mdssg keeps that path in links, assets, feeds, canonical URLs and the sitemap. No pip install step is needed. Before Pages is enabled, the workflow still builds, checks and uploads the artifact, then skips deployment with a clear warning instead of failing.

Netlify, Vercel, Cloudflare Pages#

Build command python -m mdssg build, publish directory public.

Render on demand, over CGI#

Some hosting is a directory, an FTP login and a cgi-bin. mdssg runs there too — see CGI.

What to commit#

public/
.mdssg/

Both are derived from your markdown. public/ is the output; .mdssg/ is the build cache and the precomputed graph. Deleting either costs one rebuild.