Deploying

Wikven writes a self-contained dist/ directory of static files, with no server or database behind it. Host it anywhere that serves static files.

GitHub Pages

This workflow rebuilds and publishes the site on every push. It bakes the source with the Wikven composite action, then uploads dist/ to Pages.

name: Deploy
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    steps:
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
        with:
          # Whole history, so each page is dated at the commit that last changed
          # its source file. A shallow checkout knows only the latest commit.
          fetch-depth: 0
      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d  # v6.0.0
      - uses: chaotic-ground/wikven/actions/bake@19392b75d379de9e349ef2963c11ec5545c3e6ab  # v1.0.0
        with:
          source: src
          output: dist
      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
        with:
          path: dist
      - id: deploy
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128  # v5.0.0

Enable Pages for the repository under Settings → Pages → Build and deployment → Source: GitHub Actions. This documentation site is published this way.

A GitHub project page is served from a subdirectory (username.github.io/repo/). Page-to-page links keep working because Wikven writes them relative, but anything that needs an absolute path must include that base path: set search's SifterSearchBundlePath to /repo/pagefind/ (this site uses /wikven/pagefind/). A user/organization page (served at the domain root) needs no such setting.

Any static host

Because dist/ is just files, you can serve it from any static host (Netlify, Cloudflare Pages, an object store like S3, or a plain web server). Build the site in your CI or locally, then point the host at the dist/ directory, or upload its contents to the server's document root.

Preview locally

Open dist/index.html directly, or serve the directory so links and assets resolve exactly as they will in production. Wikven has a built-in serve command for this.

With the standalone binary, it serves dist/ on http://localhost:8080 (override with --listen):

wikven serve

With the Docker image, run the serve command and publish the port (the build output must already be in the mounted dist/):

docker run --rm -p 8080:8080 \
  -v "$(pwd)/dist:/workspace/dist" \
  ghcr.io/chaotic-ground/wikven serve

Any static server works too, for example cd dist && python3 -m http.server.

← Translating

Troubleshooting →