Skip to content

Building and maintaining this wiki

This wiki uses MkDocs and Material for MkDocs, with English search, light/dark themes, copyable code blocks, and responsive navigation. It does not require a database or an application server after building.

Install the tools

Use Python 3.13 for the tested documentation environment. Check python --version first; if it points to another version, use your Python 3.13 executable's full path when creating the virtual environment. Python 3.15 on Windows may cause dependencies such as PyYAML to build from source and request C++ build tools.

From the repository root:

python -m venv .venv-docs
.venv-docs\Scripts\python -m pip install -r requirements-docs.txt
.venv-docs\Scripts\python -m mkdocs serve
python3 -m venv .venv-docs
.venv-docs/bin/python -m pip install -r requirements-docs.txt
.venv-docs/bin/python -m mkdocs serve

Open the local URL printed by MkDocs. Stop the development server when you are finished.

Build

python -m mkdocs build --strict

Run this with the documentation environment active, or use the full path to that environment's Python. Output goes to site/, which is ignored by Git.

use_directory_urls: false keeps page links as .html files, following the local BattleHub wiki's layout. Search works best over HTTP rather than opening files directly.

Regenerate field references

python scripts/generate_wiki_reference.py

This refreshes the editor field and serialized preset field references from fields.json, en_us.json, and TrainerPreset.java. It does not rewrite tutorials or invent feature support.

After changing mod behavior, review the related tutorials and downloadable examples as well as the generated reference.

Validate

python scripts/check_wiki.py
python -m mkdocs build --strict

The wiki checker validates navigation targets, local Markdown links and fragments, code-block JSON syntax, and downloaded example JSON against declared preset fields. A documentation build is not a Minecraft integration test.

Publish

Upload the contents of site/ to a static host, or configure a separate deployment pipeline. Set site_url in mkdocs.yml to the real public URL when a destination is chosen.

No public URL is assumed, and building does not publish the wiki.

Sources

Gameplay details are checked against the current repository source rather than unimplemented feature requests.