Skip to content
blak.nvim

Why Blak

Blak is a Neovim distribution built around a single product contract:

Everything useful. Nothing escapes.

The name is the promise. A black hole pulls in everything useful for editing code — pickers, LSP, completion, formatting, git, treesitter — and lets nothing escape back out as noise, mystery, or unstable churn.

What Blak is

  • Native-first. Built on Neovim 0.12’s vim.lsp.config() and vim.lsp.enable() for LSP. No wrapper plugin where a one-line native API exists.
  • Useful immediately. Snacks dashboard, fff.nvim picker, blink.cmp completion, gitsigns, oil, native terminal, which-key, treesitter — wired up and consistent on first launch.
  • Boring on purpose. Defaults are memorable, documented, and never silently changed by a stable update.
  • Reversible. Extras are opt-in modules with state stored outside the repo. Disable them, restart, sync, and Blak stops wiring them in.
  • Isolated. Installed under NVIM_APPNAME=blak. Your existing ~/.config/nvim is untouched.

What Blak isn’t

  • Not a kitchen sink. Features land in core only if most users benefit. Everything else is an extra.
  • Not a wrapper that hides Neovim. Read lua/blak/config/defaults.lua, fork it, own it.
  • Not stable-by-marketing. :BlakUpdate snapshots lazy-lock.json, user.lua, extras state, migration state, and update state first. :BlakRollback restores the last known-good set in one step.
// features

A distribution that gets out of the way.

Defaults you can read in an afternoon. Extras you can roll back in one command. Update without losing muscle memory.

core

Native LSP, not a wrapper

Built on Neovim 0.12 — vim.lsp.config() and vim.lsp.enable() drive servers. Mason handles tools.

vim.lsp.config('lua_ls', {
  settings = { Lua = {
    diagnostics = { globals = { 'vim' } },
  } },
})
extras

One command per capability

Languages, AI, alt explorers — opt-in. Disable, restart, sync, and Blak stops wiring them in.

:BlakExtras enable lang.rust
:BlakExtras enable git.lazygit
:BlakExtras disable ai.copilot
safety

Rollback snapshots, always

:BlakUpdate snapshots the lockfile and config state before any change. :BlakRollback restores them in one step.

:BlakUpdate
:BlakRollback     " undo the last update
:BlakUpgrade      " migrations + bigger moves
keys

No hidden chords

Every keymap has a description and shows in :BlakKeys. The leader is <Space>.

<Space><Space>   find files
<Space>ff        files
<Space>fg        grep
<Space>e         explorer
picker

fff.nvim by default

Snappier than telescope for the common path. Swap providers in one line.

return {
  picker = { provider = 'fff' },
}
install

Isolated, never overwrites

Installer uses NVIM_APPNAME=blak. Your ~/.config/nvim is untouched.

curl -fsSL getblak.dev/install.sh | sh
# clones to ~/.config/blak
# launcher at ~/.local/bin/blak
// stack

The default kit.

Twelve core decisions, wired up and reversible. Anything beyond this set lives in an opt-in extra.

  • Package manager

    lazy.nvim

    rollback snapshots included

  • Default picker

    fff.nvim

    fast, native

  • Completion

    blink.cmp

  • LSP wiring

    vim.lsp.config()

    native, no wrapper

  • Formatter

    conform.nvim

  • Linter

    nvim-lint

  • Treesitter

    nvim-treesitter

  • Explorer

    oil.nvim

    neo-tree / snacks via extras

  • Git signs

    gitsigns.nvim

  • Keymap hints

    which-key.nvim

    every mapping described

  • Dashboard

    Snacks

    black-hole splash

  • Colorscheme

    blak

    monochrome with ember red

Who Blak is for

You’ll like Blak if:

  • You want a config you can read in an afternoon.
  • You want a distro that ships with sensible defaults but doesn’t trap you.
  • You want updates that won’t quietly swap your picker, completion engine, or LSP strategy.
  • You’d rather type :BlakExtras enable lang.rust than learn a config DSL.

What’s next