Skip to main content

Deploying docs

These docs are served at https://orun.dev/docs/ from sourceplane/orun-website, the repository that also holds the orun.dev landing page and the installer at https://orun.dev/install.sh. It is an Orun product built from the docusaurus baseline, in the orun-website workspace on Orunbase, and it deploys itself: merging a change to main builds the site and deploys it to stage, then prod.

The pages are Markdown and MDX under apps/web/content/docs/; the sidebar is apps/web/sidebars.js; the site settings are apps/web/docusaurus.config.js. They used to live in website/ in sourceplane/orun, published by hand to a Cloudflare Pages project; that host, orun-docs.pages.dev, is no longer updated.

Local validation​

pnpm install
pnpm -F @app/web dev          # http://localhost:3000/docs/
pnpm -F @app/web build        # the docs into build/docs/, the landing page and installer at the root of build/
pnpm -F @app/web serve        # serve the docs build locally
pnpm -F @app/web preview      # the whole site through its Worker (wrangler dev), as it deploys

Both onBrokenLinks and onBrokenMarkdownLinks are set to throw, so a broken internal link fails the build — treat a green build as the link check. pnpm -F @app/web typecheck also checks that the vendored apps/web/root/install.sh is byte-identical to the canonical script in sourceplane/orun (pnpm -F @app/web sync-install re-vendors it).

Deploy​

Open a pull request against main; its checks build the site. Merge it, and the convergence run on main builds and deploys orun-website-web-stage, then orun-website-web-prod, and smoke-checks each: the landing page, install.sh as plain text, a docs page, the sitemap and the 404 page. There is no manual publish step.

Tracking what the docs cover​

When you document a release, add its page under release-notes/ and list it first in the release-notes sidebar. The Releases navbar link points at the GitHub releases page and needs no update.

Notes​

  • build/ is generated output, not source of truth.
  • The docs' base URL is /docs/ and they are routed from it (routeBasePath: '/'), so a page's own root-relative links (/cli/orun) resolve under /docs/.
  • New pages need an entry in apps/web/sidebars.js to appear in the navigation.