How To Integrate Esbonio with Neovim¶

This guide covers how to setup esbonio with Neovim’s built-in language client.

Installation¶

Note

The esbonio Python package does not need to be installed into the same environment as your project dependencies. A single, global installation is all that is required.

It’s recommended to install the language server using a tool like uv:

uv tool install esbonio

or pipx:

pipx install esbonio

Alternatively, you can use pip to install esbonio into a virtual environment of your choosing. However you decide to install the server, the esbonio command must be available on your PATH:

$ esbonio --help
usage: esbonio [-h] [--version] {server} ...

The Esbonio language server

options:
  -h, --help  show this help message and exit
  --version   print the current version and exit.

commands:
  {server}
    server    launch the esbonio language server

Configuration¶

Every Neovim configuration is unique, so we provide just a minimal example configuration that uses the vim.lsp.config() mechanism introduced in Neovim v0.11. See the Tips and Tricks section below for examples on how you might want to extend your configuration once you have the basics setup.

The following configuration should be all you need to instruct Neovim to launch the esbonio language server within your Sphinx projects.

vim.lsp.config('esbonio', {
  cmd = {'esbonio', 'server'},
  filetypes = { 'rst' }, -- or 'markdown' if you use MyST
  root_markers = { '.git', 'conf.py' },
})
vim.lsp.enable('esbonio')

However, to be useful you will also need to ensure that the esbonio.sphinx.pythonCommand and esbonio.sphinx.buildCommand options are configured for your project. The recommended way to do this is via your project’s pyproject.toml file, for example

[tool.esbonio.sphinx]
buildArguments = ["-M", "dirhtml", ".", "${defaultBuildDir}"]
pythonCommand = ["hatch", "-e", "docs", "run", "python"]

Tip

See How To Configure the Sphinx Build Environment and How To Configure the Sphinx Build guides for more examples of these settings.

If you don’t have a pyproject.toml file, or would prefer to set these options directly in neovim you can include a settings table

vim.lsp.config('esbonio', {
  cmd = {'esbonio'},
  filetypes = { 'rst' }, -- or 'markdown' if you use MyST
  root_markers = { '.git', 'conf.py' },
  settings = {
    esbonio = {
      sphinx = {
        buildCommand = {'sphinx-build', '-M', 'dirhtml', '.', '${defaultBuildDir}'},
        pythonCommand = {'hatch', '-e', 'docs', 'run', 'python'},
      }
    },
  },
})
vim.lsp.enable('esbonio')

The settings table can be used to set any configuration value supported by the server. See the Configuration Reference for details on all available options.

Example¶

See the init.lua file below for a complete, minimal example configuration. If you want to try it out, you can download it here and load it by running the command nvim -u init.lua.

-- Basic options
vim.opt.number = true
vim.opt.shiftwidth = 3

-- Diagnostics
vim.diagnostic.config({
  virtual_lines = { current_line = true },
})

-- LSP Config
vim.lsp.config('esbonio', {
  cmd = { 'esbonio', 'server' },
  filetypes = { 'rst' },
  root_markers = { '.git' },
  settings = {
    esbonio = {
      -- sphinx = {
      --   See: See: https://docs.esbon.io/en/latest/lsp/howto/configure-the-sphinx-build-cmd.html
      --   buildCommand = { 'sphinx-build', '-M', 'dirhtml', '.', './_build' },
      --
      --   See: https://docs.esbon.io/en/latest/lsp/howto/configure-the-sphinx-build-env.html
      --   pythonCommand = { 'hatch', '-e', 'docs', 'run', 'python' },
      -- },
      -- logging = {
      --   level = 'debug',
      --   filepath = 'esbonio.log'
      -- },
    },
  },
})
vim.lsp.enable('esbonio')
-- vim.lsp.set_log_level('DEBUG')

Tips and Tricks¶

This section contains examples on how you might build on the minimal examples included above

Log to a File¶

By default, esbonio will log to stderr which can be viewed in neovim’s lsp.log file. However, it’s not necessarily the easiest file to read so you might prefer configuring esbonio to log to a file instead.

vim.lsp.config('esbonio', {
  ...,
  settings = {
    esbonio = {
      logging = {
        level = 'debug',
        filename = 'esbonio.log',
        stderr = false,
      }
    },
  },
})
vim.lsp.enable('esbonio')

Provide a Default Build Environment¶

If you have ever used the Esbonio VSCode extension, you may have noticed that it provides a fallback build environment for use with projects that do not provide their own esbonio config.

To replicate the same functionality with neovim, you can provide the esbonio.sphinx.pythonCommand setting under the init_options key.

vim.lsp.config('esbonio', {
  ...,
  init_options = {
    esbonio = {
      sphinx = {
        pythonCommand = {'/path/to/fallback/venv/bin/python'},
      }
    },
  },
})
vim.lsp.enable('esbonio')

This value will be overidden by any project-local instances of this option.

Sphinx Build Progress Notifications¶

esbonio uses the window/workDoneProgress/create mechanism to report the progress of background Sphinx builds. You can use a plugin like fidget to provide a UI for these.

Troubleshooting¶

The :checkhealth vim.lsp command will show you details about your current configuration