Contributing to the Documentation¶
Last updated: 2026-08-26
This covers the documentation site specifically. For contributing to Kawa, see CONTRIBUTING.md at the repository root.
Where Documentation Lives¶
| Section | Path | Authoritative repository |
|---|---|---|
| Home, Getting Started | docs/index.md, docs/getting-started.md |
This repository (kawa) |
| How It Works | docs/concepts/ |
This repository |
| Service (API, authentication) | docs/service/ |
This repository |
| SDKs | docs/sdks/<name>/ |
The corresponding SDK's own repository |
Service documentation, including the pipeline concepts and the API reference, is authored directly in this repository's docs/ directory, on main.
Change it the same way you'd change any other file here: a pull request against main.
SDK documentation is imported, not written here
If you're changing SDK-facing content, that change belongs in the SDK's own repository, not here. This repository only aggregates and displays it.
The Python SDK's docs come from makimoto-ai/makimoto-python, pinned to a release tag in .github/workflows/documentation.yml.
Currently, there is no automatic rebuild when the SDK repo changes: a new SDK release does not, by itself, update what's shown here.
To pick up SDK changes, a code owner must run the CI workflow manually via workflow_dispatch (which still rebuilds against whatever ref: is currently pinned, so the ref: bump has to happen first).
Previewing locally¶
pip install -r docs/requirements.txt
mkdocs serve
Open the URL it prints (typically http://127.0.0.1:8000/kawa/, matching the site_url in mkdocs.yml). The server watches docs/ and mkdocs.yml
and reloads on save.
Previewing a pull request's changes¶
Every documentation pull request gets a comment from the bot with a link to
a downloadable preview build of that PR's site (a zip, expires after 14
days). This is not a live URL, GitHub Pages only serves one deployment for
this repository, and that one is reserved for main.
To view a preview: download and unzip it, then from inside that folder run a local static server, for example:
python -m http.server 8000
and open http://localhost:8000/kawa/ in your browser. Opening index.html
directly (via file://) won't navigate between pages correctly, MkDocs
generates directory-style URLs that only resolve through an actual server.
Diagnosing a failed documentation build¶
Both the PR check and the deploy step run:
mkdocs build --strict
--strict turns warnings, most commonly a broken internal link or a nav entry in mkdocs.yml pointing at a file that doesn't exist, into build failures. Reproduce it locally with the command above; the error message names the offending file and link.
A build that fails before that step (dependency install, YAML parsing) usually means a syntax error in mkdocs.yml or docs/requirements.txt; check the failed run's log under the repository's Actions tab for the exact step and error.
Review¶
Documentation pull requests go through the same review process as any other change to this repository; see CONTRIBUTING.md.