How to: contribute to the wiki

Set up the local wiki authoring environment before editing documentation. The wiki uses pre-commit hooks and Vale to enforce Markdown structure, Diátaxis page types, and Canonical style rules.

Install pre-commit and vale on the authoring machine.

On Ubuntu, install pre-commit with apt:

sudo apt update
sudo apt install -y pre-commit

On Ubuntu, install Vale from the Snap Store:

sudo snap install vale --classic

Use one workflow for each documentation change.

For proposal mode, read the current wiki from the optional .wiki/ checkout, then include the proposed changes in the contribution summary. Use .agents/templates/wiki-update-proposal.md from the main repository when an AI agent prepares the proposal.

For direct wiki edits, work from a standalone snap-pi-hole.wiki checkout or from the ignored .wiki/ checkout in the main repository. From the repository root, pull the latest wiki content before editing:

git -C .wiki pull --ff-only

Commit direct wiki edits from inside the wiki repository. Do not include .wiki/ changes in a main repository commit.

From the repository root, initialize the submodules that provide the Canonical Documentation Style Guide rules:

git submodule update --init --recursive

The wiki Vale configuration reads local rules from .vale/styles and shared Canonical rules from the initialized submodule.

From the repository root, register the hooks:

pre-commit install

The hooks run Vale, verify the custom table of contents format, and check Snapcraft link formatting for Markdown files in the wiki root.

Use the following rules when editing wiki pages:

• Match the filename to the Diátaxis page type, such as How-to:-*.md, Reference:-*.md, or Explanation:-*.md.
• Start pages with a short introduction, not an H1 heading.
• Include the required <details> table of contents block.
• Keep TOC links internal and make each TOC item match the anchored heading text.
• Use numbered lists for ordered procedures.
• Use bullets for prerequisites, options, and non-sequential information.
• Wrap commands, paths, ports, configuration keys, and package names in backticks.
• Use descriptive link text instead of here or click here.
• Use standard Markdown links, such as [Install on Linux](./How-to:-install-on-Linux). Do not use GitHub wiki link syntax.
• Avoid first-person pronouns.
• Keep bold list labels on their own line with the description indented beneath them.

From the repository root, run all pre-commit checks:

pre-commit run --all-files

From the repository root, run Vale directly for one file:

vale 'How-to:-contribute-to-the-wiki.md'

From the repository root, run the custom TOC checker directly when editing headings or TOC entries:

python3 .hooks/check_toc.py 'How-to:-contribute-to-the-wiki.md'