Skip to content

Contribution Guidelines

This page explains how to make changes, add new pages, and submit a pull request for this website.

The content is all published and hosted on Github.

Prerequisites

  • Ensure you have Python 3.8+ and pip installed
  • (Optional but recommended) Create a virtual environment: python -m venv .venv and activate it (source .venv/bin/activate on Mac/Linux, source .venv\Scripts\activate on Windows).
  • Ensure you have git installed

Local setup

# First clone the repository
git clone git@github.com:UoaWDCC/wdcc-docs.git      # with ssh
git clone https://github.com/UoaWDCC/wdcc-docs.git  # with https

# cd into the directory
cd wdcc-docs

# Create and activate a virtual environment (see Prerequisites)

# Install dependencies
pip install -r requirements.txt

# Run the website locally
mkdocs serve

Visit http://localhost:8000/ to preview changes live during development.

Adding or editing pages

  • Add new markdown files under docs/ (e.g., docs/my-page.md).
  • Use relative links for other docs pages and store images under docs/assets/ or a subfolder.
  • To edit the sidebar, update mkdocs.yml's nav: section
  • Run a local build to validate: mkdocs build --strict. The --strict flag fails on broken links.

Commit messages and branches

  • Before committing your changes, make a new branch (git checkout -b "<new-branch-name>")
  • Once you are happy with your edits, stage and commit the changes using git add . and git commit -m "<your-commit-msg>"
  • Keep changes focused and use a descriptive commit message, e.g. docs: add guide for X.
  • Use topic branches per change (one feature or fix per branch).

Pull requests

  • Push your branch (git push -u origin <new-branch-name>) and open a PR targeting main on GitHub.
  • In the PR description include what changed and why; link any related issue (optional).
  • The repository runs a CI workflow (.github/workflows/pr-build.yml) that builds the site on PRs. Ensure the build passes before requesting review.

Reporting issues

If something on the site is wrong or unclear, open an issue on GitHub with: - The page path (e.g. docs/guide/xyz.md), - A short description of the problem, - A suggested fix if possible.

Contact: tech@wdcc.co.nz or ping on discord.

Thanks for contributing :D — contributions are always welcome!