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

Section titled “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

Section titled “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 disable and unload on restart. Plugin updates with config and lockfile snapshots.

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

Blak-registered keymaps have descriptions and show in :BlakKeys. The leader is <Space>.

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

fff.nvim by default

Rust-backed file and text search, with Snacks for broader picker actions. Alternative providers are available as extras.

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.

The main tools in the default kit. Language stacks and additional workflows are available as opt-in extras.

  • Package manager

    lazy.nvim

    rollback snapshots included

  • Default picker

    fff.nvim

    Rust-backed file search

  • 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

    discoverable Blak shortcuts

  • Dashboard

    Snacks

    black-hole splash

  • Colorscheme

    TokyoNight Night

    tokyonight-night

Who Blak is for

Section titled “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

Section titled “What’s next”