Deployment

A site built with this theme can be published two ways: to vdoc, the voraus documentation portal, or to GitHub Pages.

The build is identical either way. All that differs is url and baseUrl, and getting those wrong is what breaks a deployment, so pick your target before the first release.

Where the site is served

vdoc

One immutable site per release, at https://docs.vorausrobotik.com/<project>/<version>/, for example docs.vorausrobotik.com/voraus-3d-visu/3.1.1/.

Field	Value
url	https://docs.vorausrobotik.com
baseUrl	/static/projects/<projectName>/<version>/

docusaurus.config.ts

export default createConfig({
  title: 'voraus.example',
  projectName: 'voraus-example',
  version: pkg.version,
})

url and baseUrl are absent on purpose. The theme derives both from projectName and version, so a site that restates them can only get them wrong.

GitHub Pages

One site, always showing the current documentation, at https://<org>.github.io/<repository>/.

Field	Value
url	https://<org>.github.io
baseUrl	/<repository>/

docusaurus.config.ts

export default createConfig({
  title: 'voraus.example',
  projectName: 'voraus-example',
  version: pkg.version,
  url: process.env.DOCS_URL ?? 'https://vorausrobotik.github.io',
  baseUrl: process.env.DOCS_BASE_URL ?? '/voraus-example/',
})

url and baseUrl are set explicitly: there is no version in the path, so there is nothing to derive them from. Reading them from the environment lets the workflow pass in what actions/configure-pages reports, which keeps the URL a repository setting rather than a constant; the fallbacks keep a local build identical to what CI deploys.

version matters to both: it is what the navbar badge shows. On vdoc it is also the deployment path, which is why getting it wrong there is worse.

Why baseUrl is not the readable URL

This is a vdoc property, and the single most common deployment mistake.

The readable URL is vdoc's own app. It draws the header, the version picker and the footer links, and frames your site from /static/projects/.... That framed path is what the browser resolves your assets against, so it is what the site has to be built for.

Build for the readable URL instead and vdoc renders its chrome around a page that says "Your Docusaurus site did not load properly".

You still share the readable URL with people. Only baseUrl uses the framed one.

On GitHub Pages the served URL and baseUrl do agree, which is why that tab sets baseUrl directly.

Pass version from your own package.json

import pkg from './package.json'

export default createConfig({
  title: 'voraus.example',
  projectName: 'voraus-example',
  version: pkg.version,
})

That is the file Release Please bumps, and its tag triggers the release build, so the git tag and the published version cannot drift, and it works the same in CI and on your laptop.

On vdoc, leaving version out publishes the site under /static/projects/<project>/dev/, which is right for local and branch builds. A release pipeline that forgets it publishes a real release under dev without complaining.

Publishing

vdoc

vpu docs upload from voraus-pipeline-utils:

uvx --from voraus-pipeline-utils==0.11.0 vpu docs upload \
  --project-name 'voraus-example' \
  --project-version "$VERSION" \
  --api-url 'https://docs.vorausrobotik.com/api' \
  build

--project-version must match the version the site was built with. A mismatch means every asset 404s, so derive both from the same package.json.

Two things to know before automating it:

• Versions are immutable. Re-uploading one that exists is rejected, not replaced. A retry needs a new version.
• Only tag builds should publish. A branch build has no release version and would land under dev.

Credentials are read from the environment, so they never reach the command line or the log.

GitHub Pages

A workflow builds the site and hands it to Pages. Enable Pages first, with its source set to GitHub Actions, or configure-pages fails on the first run.

.github/workflows/docs.yml

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
      - uses: actions/configure-pages@v6
        id: pages
      - run: npm ci
      - run: npm run build
        env:
          DOCS_URL: ${{ steps.pages.outputs.origin }}
          DOCS_BASE_URL: ${{ steps.pages.outputs.base_path }}/
      - uses: actions/upload-pages-artifact@v5
        with:
          path: build

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v5
        id: deployment

origin and base_path are what make the URL a setting rather than a constant. base_path is /<repository>, or empty on a custom domain, which is why the trailing slash is added here.

Unlike vdoc there are no immutable versions, so publishing on every push to the default branch is the normal arrangement: the site always shows the current documentation.

This repository publishes its own documentation exactly this way.