Commands

Every way of running Wikven — the Docker image, the standalone binary and the GitHub actions — drives the same build. This page is the reference for all three: what you can run, what you can pass it, and what it reads from the environment.

The working directory

Wikven works out of a single directory, and everything else is derived from it:

<workdir>/src: Your wikitext, images and .wikven.yaml. Read, never written, except by the translation helpers.
<workdir>/dist: The built site. Emptied at the start of each build.
<workdir>/.cache: The throwaway database and MediaWiki's scratch space. Nothing here is part of your site, and it can be deleted between builds.

The Docker image has the working directory at /workspace, which is why builds mount src and dist under it. The binary uses the current directory. Either way, WIKVEN_WORKDIR overrides it.

`build`

Builds src/ into dist/. This is the image's default command, so the Docker form needs no argument:

wikven build

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

It takes no options; everything a build can be told is in your .wikven.yaml. A failed build exits non-zero and says which page or step failed.

`serve`

Serves an already-built dist/ for local preview, on port 8080. It builds nothing: run build first.

wikven serve
wikven serve --listen 127.0.0.1:3000

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

Only the binary takes --listen; the container always listens on 8080 inside, and you choose the outside port with Docker's own -p.

`translate`

The four helpers behind Translating. They work on your source tree and exit without building anything.

These are available in the Docker image only. The standalone binary registers build and serve and nothing else, so wikven translate is not a command it has.

translate mark: Inserts  markers into the still-unmarked units of a source page. Keeps the numbers already there, so it is safe to re-run.
translate scaffold <language>: Writes an empty marker per source unit into <Page>/<language>.wikitext, as a skeleton to translate into. Keeps what is already translated.
translate stamp: Records the source version each translated unit matches, marking it up to date.
translate check: Reports broken source pages, and translations that are out of date or missing. Writes nothing.

Each takes a single file, or --all for every page under the source directory. mark, scaffold and stamp write into your source, so mount it writable; check only reads.

docker run --rm -v "$(pwd)/src:/workspace/src" \
  ghcr.io/chaotic-ground/wikven translate mark --all

docker run --rm -v "$(pwd)/src:/workspace/src" \
  ghcr.io/chaotic-ground/wikven translate scaffold ko "Getting Started.wikitext"

docker run --rm -v "$(pwd)/src:/workspace/src:ro" \
  ghcr.io/chaotic-ground/wikven translate check --gate

check takes two more:

--gate: Exit non-zero when a source page is broken. A translation that is stale or missing is reported either way and never fails the run, because translating is not the job of whoever edited the English page.
--path-prefix <prefix>: Prepend a prefix to reported file names, so they read as repository paths rather than paths inside the container.

Environment variables

WIKVEN_WORKDIR: The working directory described above. Defaults to /workspace in the image and to the current directory for the binary.
SOURCE_DATE_EPOCH: The Unix time the build should claim its content was written, as in the reproducible-builds convention. The build runs with the clock frozen at it, so every timestamp in the output is stable. Unset, a fixed date is used — a wrong but unmoving one being easier to live with than one that moves each bake. The bake action sets it to the commit being built.
WIKVEN_BUILD_JOBS: How many skin render passes may run beside each other. Unset, the build uses one per processor it is allowed — the container's allowance, not the host's. Only a site built with more than one skin has passes to run in parallel; set it to 1 to make a bake sequential, for a machine short of memory or a log you want in order.

There is one more, WIKVEN_BUILD_SKIN, which the build sets on itself to run one skin's render pass. Setting it by hand is not useful.

The `bake` action

Bakes a source tree with the Docker image, on a GitHub Actions runner. See Deploying for a complete workflow.

- uses: chaotic-ground/wikven/actions/bake@main
  with:
    source: src
    output: dist

Input	Default	What it does
`source`	`src`	Directory holding the wiki source to bake.
`output`	`dist`	Directory the static site is written to.
`image`	the release the action was cut from	The image to run. Override to pin another tag.
`cache`	`true`	Cache the pulled image between runs, keyed on the image reference. Set to `false` to always pull fresh.
`date-epoch`	the commit date of `HEAD`	`SOURCE_DATE_EPOCH` for the bake, so every bake of a commit dates its pages identically.

The action also dumps the source tree's git log and hands it to the build, which is how each page is dated at the commit that last changed it. That needs the whole history: check out with fetch-depth: 0, or every page is dated at the commit being built. The action says so in the log when it happens.

The `check-translations` action

Runs translate check over a source tree and reports each finding as an annotation on the file it belongs to.

- uses: chaotic-ground/wikven/actions/check-translations@main
  with:
    source: src

Input	Default	What it does
`source`	`src`	Directory holding the wiki source to check.
`image`	the release the action was cut from	The image to run.
`cache`	`true`	Cache the pulled image between runs.
`gate`	`true`	Fail the step when a source page is broken. A stale or missing translation is reported and never fails the step.

← Standalone binary

Development →

The working directory

build

serve

translate