Kate

Using the esbonio language server from within Kate

Installation

Note

This guide was written using Kate v22.12.1

1. Open Kate’s settings through the Settings -> Configure Kate… menu, or with the Ctrl+Shift+, shortcut.

2. Select the Plugins section on the left hand side, find the LSP Client plugin and ensure that it’s checked.

   

   Kate’s Plugins settings.

3. With the LSP Client enabled, open the LSP Client configuration section and select the User Server Settings tab.

4. This should open up a text box where you can enter some JSON to tell Kate how and when to start the language server.

   {
     "servers": {
       "rst": {
         "command": ["python", "-m", "esbonio"],
         "initializationOptions": {
           "sphinx": { },
           "server": {
             "completion": {
               "preferredInsertBehavior": "insert"
             }
           }
         },
         "rootIndicationFileNames": ["conf.py"],
         "highlightingModeRegex": "^reStructuredText$"
       }
     }
   }
   

   For best results, we recommend you set server.completion.preferredInsertBehavior (string) to insert, see the section on Configuration for details on all the available options.

   For more details on Kate’s LSP client see the project’s documentation.

5. Once you’re happy with your configuration be sure to hit the Save button for it to take effect!

   

   Kate’s LSP Client settings with an example Esbonio config.

Configuration

The settings that go in the User Server Settings tab of the LSP Client configuration section will apply globally to all your projects. Settings that you want to only apply to a specific project can go in your project’s .kateproject file.

As an example, the following .kateproject file sets a custom start command to use a specific Python environment along with specifying the sphinx build dir.

{
  "name": "Esbonio",
  "files": [
    {
      "git": 1
    }
  ],
  "lspclient": {
    "servers": {
      "rst": {
        "command": ["/path/to/venv/bin/python", "-m", "esbonio"],
        "initializationOptions": {
          "sphinx": {
            "buildDir": "${confDir}/_build"
          },
          "server": {
            "logLevel": "debug"
          }
        }
      }
    }
  }
}

The values in the lspclient section will be merged with the values specified in User Server Settings.

See below for a list of all available configuration options.