Skip to content
blak.nvim

Contributing

Blak is optimized for maintainability first. A feature belongs in core only if most users benefit from it. Everything else should be an extra.

Design rules

Section titled “Design rules”
  1. Prefer native Neovim APIs before adding plugins.
  2. Keep defaults boring, memorable, and documented.
  3. Do not add hidden keymaps. Every keymap needs a description and should appear in :BlakKeys.
  4. Stable updates must not silently change a user’s picker, completion engine, explorer, or LSP strategy.
  5. Extras must be reversible.
  6. Default and extra plugin specs must be startup-safe: lazy-load through cmd, event, ft, keys, or explicit lazy = true unless they own startup UI, directory buffers, or the initial colorscheme.
  7. Keep config startup data-only where possible. Defer runtime-path scans, tool checks, and provider setup until the feature actually runs.
  8. If a smart simple solution solves the problem without compromise, use it.

See Philosophy for the reasoning behind these.

Pick the right track

Section titled “Pick the right track”
Track When
Core change Affects most users (defaults, commands, keymaps, options).
New extra Optional capability for some users → see Writing an extra.
Bug fix Open a PR directly with a reproduction.
Docs only Open a PR directly.
New provider (picker, package backend) Open an issue first to align on the interface.

For non-trivial changes, open an issue first describing the problem you’re solving. The maintainers will tell you which track fits.

Dev loop

Section titled “Dev loop”
Terminal window
git clone https://github.com/binbandit/blak.nvim ~/Developer/blak.nvim
cd ~/Developer/blak.nvim
./dev-install.sh                                  # symlinks → ~/.config/blak-dev
blak-dev                                          # launches NVIM_APPNAME=blak-dev

Edits in the checkout are live on next launch. Plugin state and rollback snapshots live under ~/.local/{share,state}/blak-dev/ — fully isolated from any production blak install. Full options in Dev install.

Validate before you push

Section titled “Validate before you push”
Terminal window
make validate            # static checks, no Neovim required
make smoke               # isolated Neovim tests against committed plugin pins

Both run in CI on pushes to main and pull requests. Details in Validation & CI.

Use StyLua to check the Lua files you change. CI currently runs the structural validator and smoke suites.

Code style

Section titled “Code style”
  • StyLua for formatting (stylua .).
  • Two-space indent.
  • Keep modules cheap to load. Use local M = {} for stateful helpers and returned tables for plugin specs and extras.
  • Errors use error() with a descriptive message. User-facing notifications go through require("blak.util").notify.
  • Comments only when the why isn’t obvious from the code.

Documentation

Section titled “Documentation”

The site you’re reading lives under docs/ and is built with Astro Starlight.

Terminal window
make docs-install        # cd docs && npm install
make docs-dev            # http://localhost:4321/
make docs-build          # produces docs/dist/ for GitHub Pages

Auto-deploys to getblak.dev after successful builds for relevant changes on main via .github/workflows/docs.yml.

When you add a feature, update the relevant page so the site stays the source of truth. New file? Add it to the sidebar in docs/astro.config.mjs.

License

Section titled “License”

Blak is MIT-licensed. By contributing, you agree your changes will ship under the same license.