Versioning and upgrades
The stable surface is what you build a site against, not what the code happens to do.
A generator you point at ten years of writing needs to be boring about compatibility. This page says exactly what is promised.
The stable surface
Changing any of this incompatibly requires a major version.
| Stable | What that covers |
|---|---|
orgo.toml keys | Their names, types and meaning. |
| Template context | page, site, nav, root, pages, group, groups, paginator, stylesheet, theme, and the absolute, rfc822 and truncate filters. |
| The CLI | Command names, flags and exit codes. |
| URLs | How a source path becomes an output path, #+SLUG: included. |
URLs are on that list deliberately. A generator that quietly moves your pages breaks every link anyone has ever made to you, and no upgrade note fixes an inbound link.
Adding things — a new config key, a new template variable — is a minor release. Nothing you already wrote stops working.
What is not stable
Three things move freely, so the list above can hold still.
The incremental cache
<output>/.orgo-cache.json is versioned and discards itself on a mismatch. A cache format bump means one full rebuild, and nothing else. It is never a correctness dependency: a missing, stale or corrupt cache produces exactly the same site, more slowly.
Rendered HTML details
orgo aims at what Emacs exports from the same file, and closing a gap changes markup. That is the product working rather than a regression — but it is called out in the release notes every time, because your stylesheet is downstream of it.
The class names the documentation names are the ones to write CSS against: post-list, post-list-item, figure-number, table-number, section-number-N, footnote-ref, verbatim, and the on=/=off=/=trans classes on checkbox items.
What a built-in theme looks like
The names — plain, blog, wiki, docs — and the fact that the chosen one is written to theme.css are stable. Its CSS is not: a theme is a starting point that improves between releases, and a site that cannot afford that should copy the stylesheet it likes into its own assets and stop naming a theme.
The Rust API
The crate is on crates.io so the binary can be installed with cargo install. The library exists to serve the binary, and its types move as the tool does.
The compiler floor
The MSRV is 1.88, checked in CI on every change rather than assumed — which is how it came to be 1.88 rather than the 1.82 orgo's own code needs. The floor is set by dependencies, and a dependency raising its own is invisible until someone on an older compiler tries to build.
Raising it is a minor version, never a patch.
Upgrading
--no-cache makes the first build after an upgrade a full one, so you are comparing the new version's output to the old version's output rather than to a cache written by a mixture of both. --strict turns a link that stopped resolving into a failure.
If you keep your built site in version control, the diff after that command is the upgrade report, and the most useful review a generator can give you.