Formatting

Blak uses stevearc/conform.nvim for formatting. It runs on BufWritePre (when format-on-save is enabled) and via the :BlakFormat command and the <leader>cf keymap.

Spec: lua/blak/plugins/formatting.lua.

Defaults

format = {
  enabled = true,
  timeout_ms = 1000,
  lsp_format = "fallback",
  formatters_by_ft = {
    lua = { "stylua" },
    sh = { "shfmt" },
    bash = { "shfmt" },
    zsh = { "shfmt" },
  },
}

Option	Meaning
enabled	Whether format-on-save runs at all.
timeout_ms	Per-buffer timeout before Conform gives up.
lsp_format	"never", "fallback", "prefer", or "first". Blak defaults to "fallback" — use LSP only when no Conform formatter is configured for the filetype.
formatters_by_ft	Filetype → ordered formatter list. Each formatter must be installable via Mason (or already on $PATH).

Language extras add to formatters_by_ft:

Extra	Adds
lang.typescript	prettierd (fallback prettier) for js/ts/jsx/tsx/json
lang.typescript-tsgo	prettierd (fallback prettier) for js/ts/jsx/tsx/json
lang.python	isort then black for python
lang.python-pro	ruff_organize_imports then ruff_format for python
lang.markdown	prettierd (fallback prettier) for markdown
lang.go	goimports, gofumpt for go
lang.rust	rustfmt, taplo with lsp_format = "fallback"

Toggling format-on-save

Action	How
Toggle for current buffer	<leader>uf or :BlakFormatToggle
Toggle globally	:BlakFormatToggle! (with bang)
Format current buffer once	:BlakFormat
Format inside an LSP-attached buffer	<leader>cf

The flags are simple booleans:

vim.b.blak_disable_autoformat = true   -- buffer-local
vim.g.blak_disable_autoformat = true   -- global

You can flip them in your user.lua, an autocmd, or interactively.

Adding a formatter

Either via user.lua:

return {
  format = {
    formatters_by_ft = {
      yaml = { "prettierd", "prettier", stop_after_first = true },
      sql  = { "sqlfluff" },
    },
  },
  mason = {
    ensure_installed = { "prettierd", "prettier", "sqlfluff" },
  },
}

Or as part of an extra so it’s reversible — see Writing an extra.

Customizing a formatter

Use plugins.specs in user.lua to pass Conform options, including custom formatter arguments:

return {
  plugins = {
    specs = {
      {
        "stevearc/conform.nvim",
        opts = {
          formatters = { shfmt = { prepend_args = { "-i", "2", "-ci" } } },
        },
      },
    },
  },
}

Reload uses the same merged plugin options as startup. Explicit options such as format_on_save = false stay in effect, and removed filetypes are removed from Conform’s formatter map.

Skip on save without a flag

If you just want to skip once:

:noautocmd write

Inspecting

:lua = require("conform").list_formatters_for_buffer()
:ConformInfo                  " full report on this buffer