From bfb18c603cdfbb7fe0c84090df47d498ba9ff564 Mon Sep 17 00:00:00 2001
From: Leo Ji <nuglifeleoji@github.com>
Date: Wed, 25 Mar 2026 21:59:54 +0000
Subject: [PATCH 1/3] docs: add Neovim configuration guide

Add comprehensive Neovim setup instructions to the editor integration
documentation. Covers:

- lazy.nvim configuration (modern standard)
- packer.nvim configuration
- Lua-based settings in init.lua
- Keymap examples
- Troubleshooting for Python provider issues

Resolves #3960
---
 docs/integrations/editors.md | 80 ++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 3f5a99933a6..55ecd2f0255 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -411,6 +411,86 @@ Sublime Text, Visual Studio Code and many more), you can use the
 
 Use the [Spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle) plugin.
 
+## Neovim
+
+_Black_ works with Neovim using the same official plugin as Vim. The plugin automatically
+detects Neovim and uses `~/.local/share/nvim/black` as the default virtualenv location.
+
+### Using lazy.nvim
+
+For Neovim 0.8+ with [lazy.nvim](https://github.com/folke/lazy.nvim):
+
+```lua
+{
+  'psf/black',
+  branch = 'stable',
+  ft = 'python',
+  config = function()
+    -- Configure Black settings
+    vim.g.black_fast = 0
+    vim.g.black_linelength = 88
+
+    -- Format on save
+    vim.api.nvim_create_autocmd('BufWritePre', {
+      pattern = '*.py',
+      callback = function()
+        vim.cmd('Black')
+      end,
+    })
+  end,
+}
+```
+
+### Using packer.nvim
+
+```lua
+use {
+  'psf/black',
+  branch = 'stable',
+  ft = 'python',
+  config = function()
+    -- Format on save
+    vim.cmd([[ augroup black_on_save
+      autocmd!
+      autocmd BufWritePre *.py Black
+    augroup end ]])
+  end,
+}
+```
+
+### Lua Configuration
+
+For `init.lua` users:
+
+```lua
+-- All g:black_* settings
+vim.g.black_fast = 0
+vim.g.black_linelength = 88
+vim.g.black_use_virtualenv = 1
+vim.g.black_virtualenv = '~/.local/share/nvim/black'
+
+-- Commands
+vim.keymap.set('n', '<F9>', ':Black<CR>', { silent = true })
+```
+
+### Troubleshooting
+
+**Error: Python provider not found**
+
+Ensure Neovim has Python 3 support:
+
+```vim
+:checkhealth provider
+```
+
+Install if missing:
+
+```console
+$ pip install pynvim
+```
+
+_See [Vim section](#vim) for more configuration options._
+
 ## Kakoune
 
 Add the following hook to your kakrc, then run _Black_ with `:format`.

From fbd3fcbf8ea7539c9e81c58e11159140b73cbc68 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 25 Mar 2026 22:01:13 +0000
Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 docs/integrations/editors.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 55ecd2f0255..c0b52001fef 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -413,8 +413,9 @@ Use the [Spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle)
 
 ## Neovim
 
-_Black_ works with Neovim using the same official plugin as Vim. The plugin automatically
-detects Neovim and uses `~/.local/share/nvim/black` as the default virtualenv location.
+_Black_ works with Neovim using the same official plugin as Vim. The plugin
+automatically detects Neovim and uses `~/.local/share/nvim/black` as the default
+virtualenv location.
 
 ### Using lazy.nvim
 

From 52a401b454cab4eca767fe187e924a9913b37268 Mon Sep 17 00:00:00 2001
From: Leo Ji <nuglifeleoji@gmail.com>
Date: Sun, 29 Mar 2026 22:38:33 +0000
Subject: [PATCH 3/3] Add changelog entry and fix Lua highlighting in
 packer.nvim example

- Add CHANGES.md entry for #5064 to pass changelog CI check
- Replace vim.cmd([[...autocmd!...]]) with nvim_create_autocmd to avoid
  Pygments Lua lexer error on '!' token (Sphinx -W treats it as error)

Made-with: Cursor
---
 CHANGES.md                   |  3 +++
 docs/integrations/editors.md | 10 ++++++----
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index b326a0139d1..3c0accaffc1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -53,6 +53,9 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+- Add Neovim configuration guide to editor integration docs, covering lazy.nvim,
+  packer.nvim, Lua configuration, and troubleshooting (#5064)
+
 ## 26.3.1
 
 ### Stable style
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index c0b52001fef..3e1ff0e9840 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -451,10 +451,12 @@ use {
   ft = 'python',
   config = function()
     -- Format on save
-    vim.cmd([[ augroup black_on_save
-      autocmd!
-      autocmd BufWritePre *.py Black
-    augroup end ]])
+    vim.api.nvim_create_autocmd('BufWritePre', {
+      pattern = '*.py',
+      callback = function()
+        vim.cmd('Black')
+      end,
+    })
   end,
 }
 ```