Deploy overview

plasmoid’s job ends at producing a static tree. There is no runtime, no app server, and no required deploy tool — you serve the directory build produced from any static host. Deploying is deliberately out of the core: targets vary too much to bake one in.

The flow

# 1. build
plasmoid build --docs ./docs --site ./public

# 2. ship the tree (rsync preserves the alias symlinks)
rsync -a --delete ./public/ web:/srv/www/site/

# 3. serve it — see the nginx recipe

The landing at /

The site root (/) is chosen by a simple precedence:

1. Prebuilt static landing — if [landing] dir points at a directory, plasmoid copies it to / verbatim (your separately-built marketing page). plasmoid never compiles it; it only mounts the finished output.
2. Markdown home — otherwise, if the default locale has an index.md, its rendered home page is mounted at /.
3. Redirect — otherwise / redirects to /docs/.

This lets a flashy project ship a bespoke landing while a simple one gets a clean markdown home, with no code change in plasmoid.

Connecting the landing and the docs

When a real landing sits at / (tiers 1 and 2), plasmoid wires the two together automatically — no manual URL plumbing:

• Docs → landing. The docs chrome’s brand/logo links to / (the landing), so clicking it from any doc page returns to the landing instead of looping back into the docs. With a redirect-only root (tier 3) the brand stays on /docs/.
• Landing → docs. Point your landing’s Read the docs button at the stable /docs/ alias. It resolves to the current version’s default-locale docs and survives every release, so the link never goes stale.

That’s the whole contract: drop a landing in, link it to /docs/, and the round trip just works.

Stable entry points

However you host it, link people to the stable aliases: /docs/ (current default-locale docs) and /latest/ (current version). They survive version bumps so external links and bookmarks don’t rot.

Hosting options

• nginx — the documented recipe handles clean URLs, the custom 404, archive downloads, and caching. It’s the reference target.
• Object storage / static hosts — work too. If your host doesn’t preserve symlinks, build with [deploy] aliases = "copy" so the aliases are real directories. See Aliases.