How To Use Esbonio in Emacs#

There are two main language client implementations available in Emacs

eglot a mimialistic implementation, relies on built-in functionality where possible. Built into Emacs since v29.1
lsp-mode integrates well with third party packages like treemacs and helm.

Installation#

Install the language server using pipx

$ pipx install esbonio

eglot

Add esbonio to the eglot-server-programs list and enable eglot in rst-mode buffers

(require 'eglot)
(add-to-list 'eglot-server-programs '(rst-mode . ("esbonio")))
(add-hook 'rst-mode-hook 'eglot-ensure)

Configuration#

It’s recommended to store as many project-specific options as possible in your pyproject.toml file

[tool.esbonio.sphinx]
buildCommand = [
  "sphinx-build", "-M", "html", "docs", "docs/_build"
]

eglot

However, for options that are only applicable to your setup e.g. python environment these can be stored in a .dir-locals.el file in the root of your workspace.

((rst-mode
  . ((eglot-workspace-configuration
      . ((esbonio
         . ((sphinx
             . ((pythonCommand . ["/path/to/venv/bin/python"]))
           ))
        ))
    ))
))