Skip to content

The docs site

https://khyretos.github.io/kk-engine/ is built from this folder with MkDocs and the Material theme, by .forgejo/workflows/docs.yml on git.kreative-kompas.com on every push to main, which pushes the built site to the gh-pages branch. Forgejo's push mirror copies that branch to GitHub, where GitHub Pages serves it for free (a public repository).

Working on it

pip install -r tools/docs_site/requirements.txt
mkdocs serve           # http://127.0.0.1:8000, rebuilds as you save
mkdocs build --strict  # what CI runs: any warning fails the build
  • Pages and menus: mkdocs.yml at the repository root. A new doc in docs/ also needs a line in its nav: (and a row in docs/README.md for people browsing on GitHub).
  • Links out of docs/ (../ROADMAP.md, ../games/...) are written as ordinary relative links, so they work on GitHub; on the site tools/docs_site/hooks.py turns them into links to the file on GitHub.
  • The Lua API reference is generated on every build from the engine's registerFunction calls by tools/docs_site/lua_api.py (python3 tools/docs_site/lua_api.py prints it). Descriptions come from the API table in SCRIPTING.md: add a row there when you add a table.
  • Demo pages (demos/<demo>.md) are the demos' own games/<demo>/README.md, added by hooks.py; their links are rewritten so they work on the site too. A new demo with a README gets a page by itself; add it to the Demos part of nav: and to demos/index.md.
  • The front page is index.md; this folder's README.md is left out of the site.
  • Devlog: add a section to devlog/index.md, newest first.

First deployment

GitHub Pages has to be switched on once: repository Settings > Pages > Build and deployment > Source: Deploy from a branch, branch gh-pages, folder / (root). From then on every push to main updates the site.