Esbonio v1.0 Released!

[alcarney]

After over 2 years of development v1.0 of the Esbonio language server is finally available! 🎉

What's new?

MyST Support

Esbonio now equally supports projects written using MyST Markdown or reStructuredText syntax.

Synchronised Scrolling

The v1.0 release includes support for synchronising the scroll state between your editor and the preview pane.

Note

This relies on custom messages beyond the Language Server Protocol specification and therefore requires additional support from your language client to enable.
See the documentation for more details.

Better architecture

The previous version of Esbonio hosted Sphinx builds directly in the server process, this limited the server to only supporting single-root, single project workspaces. Now in v1.0 Sphinx builds are hosted in separate background processes, bringing with it support for multi-root workspaces and multiple Sphinx projects in a single workspace root!

Flexible Configuration

Initialization options are no longer the only means by which you can configure the server. v1.0 includes support for setting configuration values via workspace/configuration requests and pyproject.toml files e.g

[tool.esbonio.sphinx]
pythonCommand = ["uv", "run", "--group", "docs", "python"]
buildCommand = ["sphinx-build", "-M", "html", "docs/source", "${defaultBuildDir}"]

See the configuration reference in the documentation for more details

Reactive Configuration

With the additional configuration sources you are no longer forced to restart the server in order to change configuration settings. Options set via workspace/configuration requests and pyproject.toml files will reload automatically when changed.

Graceful Degradation

When running in an environment that is missing some dependencies, Esbonio will try disabling missing extensions and using a fallback theme in an attempt to offer partial support for your documentation project.

LSP Features

While the focus of this release wasn't really on expanding support for LSP features (in fact, some features are currently missing! 😅 - see below), v1.0 adds support for pull-model diagnostics and workspace symbols.

Keeping up with the times

This release brings support for

• Python v3.13, v3.14
• Sphinx v7, v8
• pygls v2

What's Changed?

The biggest changes compared to the 0.x release are how you install and configure the server, see the migration guide for details.

You may also find the guides on configuring your Sphinx build command and environment useful.

What's missing?

Legacy version support

This release drops support for

• Python v3.8, v3.9
• Sphinx v4, v5
• pygls v1

LSP Features

Unfortunately, some features from the 0.x version of the server were not migrated in time for the release. This includes

• Completion suggestions for directive options
• Documentation hovers for roles and directives
• Goto Implementation support for roles/directives

These are being tracked in #901

What's Next?

Aside from re-implementing those missing features, I hope to finally start realising my long term goal of enabling Sphinx extensions to "teach" Esbonio about the extra features they provide.

Any maybe, someday, being able to provide a WASM version of the server that can be run in the browser!

[drvinceknight]

Congrats on 1.0!

[marcel-22]

Nice! Thank you for all your hard work!