Configuration#

Everything lives in mdssg.toml beside your content/ directory. TOML, because tomllib is in the standard library.

An unknown section or key is a build error, listing what was expected:

error: [site]: unknown option(s): titel. Known: author, description, language, repository, title, url

A typo in a config file is the first mistake most people make, and ignoring it hands you a site that is quietly not the one you asked for, with nothing on screen to explain why.

Every option#

[site]
title = "An mdssg site"
url = ""                    # no trailing slash. Required for the RSS feed.
description = ""
author = ""
language = "en"
repository = ""

[theme]
accent = "#000080"
logo = ""
width = 1152

[paths]
content = "content"
output = "public"
static = "static"
templates = "templates"

[seeds]
enabled = true
noindex = true
in_sitemap = false
excerpts_per_source = 2
near_miss_cutoff = 0.86

[related]
enabled = true
count = 5
hub_cap = 32

[feed]
enabled = true
count = 20

Notes on a few of them#

site.url has no default because there is no sensible one, and the RSS feed cannot exist without it — a feed reader shows your markup on its own domain, so every link in it has to be absolute. Set it and mdssg rewrites the site's own links accordingly. It also enables canonical links and sitemap.xml. Leave it unset and the feed and sitemap are skipped.

site.repository is optional. When set to a safe HTTP(S) URL, the theme adds a source-code link. Leaving it empty keeps a generated site from pointing back to the mdssg repository by mistake.

site.language selects the built-in interface strings. English is the fallback; pt and variants such as pt-BR use Portuguese.

theme.accent, theme.logo, and theme.width are the entire visual configuration surface. The accent is a six-digit hex colour. The logo is empty for the bundled mark, a root-relative path copied through static/, or a safe HTTP(S) URL. Width is limited to 640–2400 pixels. Deeper changes still belong in a template or stylesheet override.

seeds.in_sitemap controls whether unwritten seed pages appear in sitemap.xml. It defaults to false: seeds remain reachable from the notes that mention them, but search engines are not asked to index unfinished ideas. Set seeds.noindex = false as well when opting in; a noindex page is never placed in the sitemap.

paths.* must stay inside the site. An absolute path, or one containing .., is rejected. The check uses Windows path semantics on every platform, because /var/www is not absolute on Windows — it is drive-relative — so the obvious check passes on Linux and silently does nothing on Windows.

seeds.near_miss_cutoff is how similar an unwritten name has to be to a real one before mdssg warns that you may have made a typo. Lower it to catch more, at the cost of more noise.

related.hub_cap is explained in Related Notes. It is the setting most worth understanding before changing.

Changing config rebuilds what it affects#

Every option that can change a rendered page is hashed into the build cache. Edit mdssg.toml and the affected pages are rewritten on the next mdssg build — there is no cache to clear and no --force to remember. See How It Works.