Deploying

The output is a directory of files. Everything after that is your host's problem.

The production build

orgo build content -o _site --strict

Two differences from the build you run while writing:

• --strict turns broken internal links and parse diagnostics into a non-zero exit, so a bad build fails rather than shipping.
• No --drafts, so pages marked #+DRAFT: stay out.

Everything in _site is the site: HTML, the generated syntax.css, theme.css if the config names a theme, and every asset copied from the source. There is no runtime, no server requirement and no build step downstream.

Set base_url for production

[site]
base_url = "https://example.com"

Relative URLs work anywhere, which is why the default is empty — but two things need absolute ones: feeds, because a feed is read away from the site that served it, and canonical links. Without a base URL the absolute filter is an error rather than a quietly relative link, so a feed template will tell you.

No trailing slash.

One thing to exclude

The build writes .orgo-cache.json into the output directory. It is a dot-file, so most static hosts ignore it, but it is not part of the site — exclude it if your host uploads everything:

rsync -a --delete --exclude '.orgo-cache.json' _site/ user@host:/var/www/site/

Keeping the cache between deploys, where the CI runner can see it, is what makes CI builds incremental. Keeping it on the server achieves nothing.

Continuous integration

name: build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo install --path .
      - run: orgo build content -o _site --strict
      - uses: actions/upload-artifact@v4
        with:
          name: site
          path: _site

--strict is the point of running this in CI at all: it turns a broken link into a failed build.

Caching between runs

Cache _site/.orgo-cache.json and _site together, or not at all. The manifest describes files it expects to find; a cache without its outputs simply triggers a full rebuild, which is correct but pointless.

Given how fast a full build is — a 179-page site in well under a second — caching CI builds is rarely worth the configuration.

Static hosts

Nothing here is orgo-specific; a built site is ordinary static files.

• Netlify, Vercel, Cloudflare Pages: publish directory _site, build command cargo install --path . && orgo build content -o _site --strict.
• GitHub Pages: upload _site as the Pages artifact.
• Any web server: copy _site to the document root.

URLs end in .html

orgo writes blog/post.html and links to it that way, so the site works with no server configuration at all — including opening it from a filesystem path.

If you prefer extensionless URLs, that is a server-side rewrite, and you should also set base_url and check that your rewrite rules do not break the relative links in the pages.

Checking a build before shipping

orgo build content -o _site --strict
orgo serve content -o _site

Serving the production build locally is the last check worth doing: it catches a missing asset or a broken relative link in the browser, where you would notice.

What a clean build looks like

built 182 page(s) (182 rendered, 0 cached), copied 3 asset(s) from content -> _site (0 unresolved link(s), 0 diagnostic(s))

Both zeros matter. Unresolved links are internal links pointing at nothing; diagnostics are malformed org that degraded rather than failing. With --strict neither can reach this line, because either would have failed the build.

Do not publish the cache

<output>/.orgo-cache.json is a build artefact that happens to live in the output directory, because it describes exactly that directory. Nothing breaks if it is served — it holds hashes and paths, not secrets — but it is not part of your site, so leave it behind:

rsync -r --delete-before --exclude '.orgo-cache.json' _site/ server:/var/www/example.com/

Anything that uploads a directory wholesale needs the same exclusion. A deploy that deletes it on the far side is worse than one that copies it: the next build then has no cache to reuse and re-renders everything.

Telling a search engine where things are

A build with site.base_url set writes sitemap.xml at the site root, listing every page. Point a robots.txt at it if you want one:

Sitemap: https://example.com/sitemap.xml

robots.txt is an ordinary file — put it beside your org files, or in a directory named by [build] assets, and it is copied through.

After an upgrade

The first build on a new version is worth running with --no-cache, so you compare the new output to the old rather than to a cache written by both. What a version number promises — and what it does not — is in Versioning and upgrades.