docs/guide/10-deploying.org

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.

[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.

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.

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.

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.

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.

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.

<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.

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.

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.