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.


Install the language server using pipx

$ pipx install esbonio

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)


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

buildCommand = [
  "sphinx-build", "-M", "html", "docs", "docs/_build"

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.

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

See also


For details on all available configuration options