Level 4 — Contributor¶

Time: ongoing

You'll understand the architecture, run the full test suite, and make your first contribution.

What you'll learn¶

• How the codebase is organized
• How to run the development environment
• How the test harnesses work
• How to make and verify a change
• How to open a PR

Prerequisites¶

• Completed Level 3 — Customizer
• Git installed
• GitHub account

Step 1 — Fork and clone¶

# Fork on GitHub, then:
git clone https://github.com/your-username/mkdocs-void.git
cd mkdocs-void
pip install -e .
npm install

Step 2 — Understand the architecture¶

Read Architecture for the full picture. The key files:

Step 3 — Run the dev environment¶

# Terminal 1: watch CSS
npm run start

# Terminal 2: serve docs
mkdocs serve

Edit SCSS in void/templates/assets/stylesheets/ — changes rebuild automatically. Edit void.js — reload the browser.

Step 4 — Run the full test suite¶

# JS smoke tests
npm test

# Doc lint
python tools/check_docs.py

# Strict build
mkdocs build --strict --clean

All three must pass before opening a PR.

Step 5 — Make a change¶

Pick a good first issue or create a small improvement:

1. Create a branch:

git checkout -b fix/your-fix

1. Make your change.

2. Run the checks:

npm test
python tools/check_docs.py
mkdocs build --strict --clean

1. If you changed plugin config, regenerate the reference:

python tools/emit_config_reference.py

1. Commit with a Conventional Commit prefix:

git commit -m "fix: correct search result highlighting"

Step 6 — Open a PR¶

1. Push your branch:

git push origin fix/your-fix

1. Open a pull request against main.

2. Fill in the PR template:

3. What changed and why

4. Screenshot for visual changes

5. Checklist: mkdocs build --clean, npm test, check_docs.py all pass

6. Wait for CI to go green.

Testing recipes¶

Adding a new init function¶

1. Write the function in void.js.
2. Call it from the boot IIFE.
3. Add a smoke test in tests/void.test.js:

const myBoot = bootIIFE({
  location: { origin: "https://x", pathname: "/page/", search: "", href: "https://x/page/", hash: "" },
  config: { base: "/", components: {}, content: {}, void_search: { enabled: false }, translations: {} },
  searchDom: null,
  stored: {},
})
check("my feature boots without throwing", myBoot)

1. Run npm test.

Adding a new config key¶

1. Add the default in void/plugins/void_plugin.py (_VOID_DEFAULT_*).
2. Add the key to _VOID_TOKEN_MAP.
3. Run python tools/emit_config_reference.py.
4. Document the key in the relevant docs page.
5. Run python tools/check_docs.py.

Adding a new doc page¶

1. Create the .md file in docs/.
2. Add the nav entry in mkdocs.yml.
3. Run python tools/check_docs.py — the nav sync check confirms it's wired.

Verify you got it¶

• Forked and cloned the repo
• npm test passes (55/55)
• python tools/check_docs.py passes (8/8)
• mkdocs build --strict builds clean
• Made a change and verified it locally
• Opened a PR with a Conventional Commit title
• CI is green

Back to Learn