<!-- Generated by Void for AI agents. -->
<!-- Site: Void Documentation -->
<!-- URL: https://rkriad585.github.io/mkdocs-void/development.md -->
<!-- Generated: 2026-09-10T14:47:04Z -->
<!-- Version: 0.2.0 -->

# Development

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

## Prerequisites

- Python 3.8+
- Node.js 18+
- pip
- npm

## Setup

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

## Build CSS

```bash
npm run build
```

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

## Development Mode

```bash
npm run dev
```

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

## Watch Mode

```bash
npm run start
```

Automatically rebuilds CSS when any `.scss` file changes.

## Serve Documentation

```bash
mkdocs serve
```

Opens a live-reloading dev server at [http://127.0.0.1:8000](http://127.0.0.1:8000).

## Lint

```bash
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

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

### Template Changes

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

### JavaScript Changes

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

### Plugin Changes

1. Edit `void/plugins/void_plugin.py`
2. 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

1. Run `mkdocs build --clean` to verify the site builds without errors
2. 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](https://www.conventionalcommits.org/) 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](identity.md#translating-void)
for onboarding: which keys exist, how flat aliases map to nested groups, and
how to verify a translated build.

---

[Back to README](index.md)


<!-- End of markdown mirror. -->