Codeberg Pages

This documentation site is deployed to Codeberg Pages using Woodpecker CI. Every push to the main branch automatically rebuilds and publishes the docs.

How it works

1. You push to main
2. Woodpecker CI builds the VitePress site (docs/)
3. The built static files are force-pushed to the pages branch
4. Codeberg Pages serves the pages branch at YOUR_USERNAME.codeberg.page/REPO_NAME

One-time setup

1. Enable Woodpecker CI for your repo

1. Go to ci.codeberg.org
2. Sign in with your Codeberg account
3. Click Add repository and activate your homepage repo

2. Create a Codeberg access token

Woodpecker needs push access to deploy to the pages branch.

1. On Codeberg, go to Settings → Applications → Access Tokens
2. Click Generate Token
3. Name it WOODPECKER_PAGES and grant the repository scope
4. Copy the token — you won't see it again

3. Add the token as a Woodpecker secret

1. In Woodpecker, open your repo's Settings → Secrets
2. Click Add Secret
3. Name: CODEBERG_TOKEN, Value: paste the token
4. Save

4. Create the pages branch

Woodpecker will push to this branch automatically, but it needs to exist first:

git checkout --orphan pages
git rm -rf .
echo "placeholder" > index.html
git add index.html
git commit -m "init pages branch"
git push origin pages
git checkout main

5. Push to trigger the first build

git push origin main

Watch the build at ci.codeberg.org. On success, the docs will be live at:

https://YOUR_USERNAME.codeberg.page/REPO_NAME/

Custom domain

To use a custom domain, add a .domains file to the root of the pages branch containing your domain name, then configure a CNAME DNS record pointing to codeberg.page.

Woodpecker config reference

The .woodpecker.yml at the root of the repo defines the pipeline:

steps:
  - name: build
    image: node:20-alpine
    commands:
      - cd docs
      - npm install
      - npm run build

  - name: deploy
    image: bitnami/git
    environment:
      CODEBERG_TOKEN:
        from_secret: CODEBERG_TOKEN
    commands:
      - git config --global user.email "[email protected]"
      - git config --global user.name "Woodpecker CI"
      - git clone https://[email protected]/YOUR_USERNAME/YOUR_REPO.git /tmp/deploy
      - cd /tmp/deploy
      - git checkout pages
      - git rm -rf .
      - cp -r /workspace/docs/.vitepress/dist/. .
      - touch .nojekyll
      - git add .
      - "git commit -m 'Deploy docs [ci skip]' || echo 'Nothing to commit'"
      - git push origin pages
    when:
      branch: main

Updating the docs

Edit any file under docs/ and push to main. The pipeline runs automatically and the live site updates within a minute or two.

To preview locally before pushing:

cd docs
npm install   # first time only
npm run dev

Then open http://localhost:5173.