Development¶

How to set up, build, and contribute to mkdocs-void.

Prerequisites¶

Python 3.8+
Node.js 18+
pip
npm

Setup¶

git clone https://github.com/rkriad585/mkdocs-void.git
cd mkdocs-void
pip install -e .
npm install

Build CSS¶

npm run build

Compiles void.scss + components.scss into void.css via Sass and PostCSS.

Development Mode¶

npm run dev

Builds with expanded CSS and inline source maps for easier debugging.

Watch Mode¶

npm run start

Automatically rebuilds CSS when any .scss file changes.

Serve Documentation¶

mkdocs serve

Opens a live-reloading dev server at http://127.0.0.1:8000.

Lint¶

ruff check void/

Project Layout¶

Path	Description
`void/templates/`	Jinja2 templates and static assets
`void/templates/assets/stylesheets/`	SCSS source files
`void/templates/assets/javascripts/`	JavaScript source
`void/plugins/`	MkDocs plugin
`docs/`	Documentation Markdown source
`tools/build.js`	SCSS build script
`tools/emit_benchmarks.py`	Regenerates `docs/benchmarks.md` (page-weight table)
`tools/emit_changelog.py`	Regenerates the `[Unreleased]` changelog block
`tools/emit_config_reference.py`	Regenerates the generated config reference

Making Changes¶

CSS Changes¶

Edit files in void/templates/assets/stylesheets/
Run npm run build or npm run start (watch mode)
Reload the browser

Template Changes¶

Edit files in void/templates/ or void/templates/partials/
Run mkdocs serve (auto-reloads on template changes)

JavaScript Changes¶

Edit void/templates/assets/javascripts/void.js
Reload the browser (no build step required for dev)

Plugin Changes¶

Edit void/plugins/void_plugin.py
Restart mkdocs serve

Code Style¶

CSS: BEM naming with void- prefix. No utility frameworks.
JavaScript: Vanilla ES6+, IIFE-wrapped, no dependencies. Uses $() and $$() helpers.
HTML: Jinja2 templates. Follow MkDocs template conventions.
Python: Standard MkDocs plugin pattern. Use ruff for linting.

Testing¶

Run mkdocs build --clean to verify the site builds without errors
Run mkdocs serve and manually test:
Dark/light mode toggle
Search functionality
Responsive layout (mobile/desktop)
Keyboard shortcuts (/, ?, Esc)
Navigation toggle
Code copy button
Back-to-top button
Reading progress bar

Commit Guidelines¶

Commits follow Conventional Commits so the changelog can be machine-checked:

feat: — a new user-facing feature or config surface
fix: — a bug fix
docs: — documentation-only changes
chore: / refactor: / perf: / ci: — non-user-facing changes

tools/emit_changelog.py turns the commit list into the [Unreleased] block of CHANGELOG.md (a CI workflow opens a PR whenever it changes), so the prefix is part of the feature — keep it accurate and use focused commits. Other rules:

Keep commits focused on a single change
Use clear, descriptive commit messages
Do not commit site/, node_modules/, or __pycache__/

Translating Void¶

UI strings are centralized in _VOID_DEFAULT_I18N (void/plugins/void_plugin.py) and overridable per site via theme.void.i18n. See Translating Void for onboarding: which keys exist, how flat aliases map to nested groups, and how to verify a translated build.

Back to README