Getting Started

This tutorial will guide you through the process of using the Esbonio language server with VSCode for the first time. Even if VSCode is not your editor of choice, it is still recommended that you read through this guide as the concepts covered here will apply to other editors.

To follow along you will need either

  • VSCode, Git and Python installed on your machine, or

  • A GitHub account with access to Codespaces

Initial Setup

This tutorial uses a demo project to illustrate the features provided by Esbonio, so before we can begin we need to get this project setup on your machine.

The setup steps will be different depending on how you intend to follow along

  • VSCode: Follow these steps if you are using a VSCode

  • VSCode + Dev Container: Follow these steps if you are using VSCode, but want to use a devcontainer for the project’s environment.

  • Codespaces: Follow these steps if you don’t have VSCode or would prefer to use your browser.

  1. Open a terminal and clone the demo repository:

    $ git clone https://github.com/swyddfa/esbonio-demo
    
  2. Open the demo repository in VSCode:

    $ cd esbonio-demo && code .
    
  3. Open the Extensions sidebar (Ctrl+Shift+X) and search for esbonio. You should see the “Esbonio” extension at the top of the list, with an icon matching the logo you see on this documentation site.

  4. Instead of clicking the Install button, click the down arrow to the right of the Install text and pick the Install Pre-Release button.

  1. Open a terminal and clone the demo repository:

    $ git clone https://github.com/swyddfa/esbonio-demo
    
  2. Open the demo repository in VSCode:

    $ cd esbonio-demo && code .
    
  3. Assuming that you already have the Dev Containers extension installed, you should be prompted to reopen the repository in a container. Alternatively, you can run the Dev Containers: Reopen in Container command through the command palette (Ctrl+Shift+P)

  4. VSCode will automatically install the Esbonio extension as part of the container setup process.

  1. Open the repository for the demo project in your browser

  2. Sign in to GitHub if you have not done so already

  3. Click the green <> Code button

  4. Select the Codespaces tab in the popup dialog and click the green Create codespace on main button.

Open a Preview

By this point you should have the demo project open and the Esbonio extension installed.

  1. Open the Explorer sidebar (Ctrl+Shift+E) and click the index.rst file.

  2. Open a preview of this file by either

    • Clicking the icon in header that looks like a book book-icon

    • Hitting the Ctrl+K V keyboard shortcut

    • Running the Esbonio: Preview Documentation in Split Window command through the command palette (Ctrl+Shift+P)

    After a few seconds the Esbonio extension will have built the documentation in the background and be showing the result in the new side window.

    If you are using Codespaces…

    Previews in Esbonio work by starting Python’s built-in http.server in your project’s build directory and are hosted on localhost:<port_number> - something that shouldn’t normally work in a Codespace. Thankfully, GitHub will automatically expose local ports via your Codespace’s URL e.g. https://codespace-name-q99gp466q62xwqw.github.dev:<port_number>/

    Unfortunately, the browser will initially block Esbonio’s preview pane from accessing this URL with a message like This content is blocked. Contact the site owner to fix the issue.

    To fix this, we first need to open these Codespace URLs in a new tab

    1. If VSCode’s bottom panel is not already open, open it with the Ctrl+J shortcut.

    2. Select the Ports tab, you should see two URLs listed in a table.

    3. Click on the globe icon globe-icon next to each of the links to open them in a new tab

      • One of the links will take you to the documentation preview

      • The other will be an error message like Failed to open a WebSocket connection. This is expected, you can ignore this

    4. Close both of the tabs and return to the Codespace

    5. Close the Esbonio Preview window and re-open it using one of the methods mentioned above.

  3. Go back to the index.rst file and replace the .. Write a message here comment with Hello, World!.

    Notice how after a few seconds the preview will update showing the result of the changes you made.

Fixing the Project Configuration

By this point you may have noticed that there are some issues with this project. Open VSCode’s Problems tab (Ctrl+Shift+M) and you will see a number of errors including

  • Could not import extension sphinx_design (exception: No module named ‘sphinx_design’)

  • No theme named ‘furo’ found (missing theme.toml?)

  • Unknown directive type “grid”

Also if you compare your current preview to the published version of the demo documentation site, you can clearly see that Esbonio is not using the right theme!

This is because Esbonio is currently using a fallback environment which does not have access to all of the dependencies necessary to build the demo project. While Esbonio is able to work around issues like this, it will work best when we are able to provide it access to a complete environment.

Let’s create a virtual environment containing the required dependencies.

  1. Open the Terminal (Ctrl+`) and create a new virtual environment:

    $ python -m venv env
    
  2. Activate the environment and install the demo project’s dependencies:

    $ source env/bin/activate
    (env) $ python -m pip install -r requirements.txt
    

With the environment created, we now need to tell Esbonio to use it

  1. Open the demo project’s pyproject.toml file and add the following pythonCommand to the configuration

      [tool.esbonio.sphinx]
      buildCommand = ["sphinx-build", "-M", "dirhtml", ".", "./_build"]
    + pythonCommand = ["${venv:env}"]
    
  2. Save the file, Esbonio will detect the configuration change and automatically restart its background Sphinx process within the newly created environment

  3. Remove the Hello, World! text you added in the previous section. The next time the preview refreshes you will see that Esbonio is now using the correct theme for this project and that the errors mentioned at the start of this section have been fixed!

Next Steps

That’s all you need to get started, you should now be able to make use of Esbonio in your own projects!

If you like, you can continue exploring the demo project to discover some of the other features Esbonio provides by clicking either

  • the reStructuredText Demo card, or

  • the MyST Demo card

in the preview pane. Esbonio will open the corresponding section where you will be taken on a tour through the supported features of your selected syntax.

See also

How To Use Esbonio With…

Esbonio is able to work with more than just virtual environments, this guide will show you how to integrate it with other environment managers like poetry.

Editor Integration

This section provides details on how to integrate Esbonio with other text editors