Wikis and sites¶

Otomo hosts two kinds of site with one framework. Both are MkDocs Material built with --strict by services/wiki.

Site	Content lives in	Served at	Who edits
Technical wiki	this repository, `docs/`	`https://<public host>/docs/`	the otomo team, by pull request
Game site	the game's own repository, never this one	`https://<public host>/`	the game team, by pushing to that repo

Otomo provides the framework (build, image, serving, deployment) and reads a content directory. It contains no game content and no game names. See the wiki service design for the full design.

The content contract¶

A content directory is:

_site.yml        site settings (required)
index.md         the home page
*.md, */*.md     pages; any folder layout
assets/…         images and other static files, linked relatively
README.md        optional; excluded from the site (use it for editing instructions)

_site.yml is a small subset of MkDocs configuration. The framework owns everything else: theme, extensions, search and strictness.

site_name: Example Wiki           # required
site_description: …               # optional
nav: [...]                        # optional; defaults to the folder layout
copyright: …                      # optional
theme:                            # optional, only these keys
  palette: {primary: indigo, accent: amber}
  logo: assets/logo.png
  favicon: assets/favicon.png
extra: {...}                      # optional, passed through

Unknown keys fail the build with a message naming them, so a typo cannot silently do nothing. services/wiki/example/ is a minimal, game-neutral content directory you can copy as a starting point.

Previewing¶

From an otomo checkout, run the same pinned builder with live reload:

services/wiki/preview.sh <content dir>

Use ../docs to preview the technical wiki, or a checkout of a game's content directory to preview that site.

Publishing¶

Technical wiki: by pull request. Edit docs/ in this repository and open a pull request into staging. The wiki-docs Compose service builds ../docs with mkdocs build --strict and is tagged with the commit SHA of this repository. A broken link or a bad config fails the build, and the running site is never replaced by a broken one.

Game site: by pushing to its own repository's main. The game team edits Markdown in the content repository and pushes to main. Nothing is published from otomo's repository.

content repo ──push──► GitHub webhook ──► :5009 webhook proxy ──► Jenkins job `otomo-site-deploy`
                                                   (Generic Webhook Trigger, own token, main only)
      └── sudo -u <deploy user> deploy/site/deploy-site.sh   (the only command Jenkins may run as that user)
            1. git fetch + reset the content checkout to origin/main (read-only deploy key)
            2. build wiki-site (mkdocs --strict); on failure stop, and the old site keeps serving
            3. push to the local registry as otomo-wiki-site:<content sha>, record the tag in deploy/.env
            4. recreate wiki-site and wait for it to answer

The webhook carries no content. It only says "main moved", and the host fetches from GitHub itself with a read-only deploy key, so a forged webhook can at most redeploy what is already on main.

What fails a build¶

A broken link, including a relative link to a page that does not exist.
A page named in nav that is missing.
An unknown key in _site.yml.
Any other warning that mkdocs build --strict raises.

When the build fails, the running site keeps serving. The framework adds no cookies and makes no external requests (no web fonts, no analytics), applies a strict CSP and X-Content-Type-Options, and runs search in the browser.

Rollback¶

Rollback is a re-point, like every other service. For the game site, set the tag to the previous content SHA and recreate the service:

# set OTOMO_WIKI_SITE_TAG to the previous content SHA in deploy/.env, then
cd deploy && docker compose --env-file .env -f compose.yaml up -d wiki-site

Tags are immutable, so the previous image is still in the local registry. For the technical wiki, revert the commit in this repository and rebuild wiki-docs, or re-point wiki-docs's image tag to the previous commit SHA the same way.