Language Server Protocol (LSP)

A modern approach to code intelligence

The Language Server Protocol (LSP) is a standardized communication protocol developed by Microsoft^™ to enable real-time language analysis and intelligent code editing across different editors and IDE (Integrated Development Environment).

By decoupling language-specific logic from the editor itself, LSP allows developers to use advanced features such as autocompletion, diagnostics, code navigation and refactoring, regardless of the programming language or toolchain.

This protocol has revolutionized the way developers interact with code, making it possible to offer consistent, high-quality language support in any editor that implements LSP.

LSP in Neovim

Neovim includes a built-in LSP client that integrates with language servers to give IDE features. The implementation maintains Neovim's performance and extensibility while delivering code completion, diagnostics and symbol navigation.
This native support ensures a consistent experience across languages and workflows.

LSP in Rocksmarker

Rocksmarker leverages Neovim's native LSP client to enhance editing for code-intensive documentation and multi-language projects. The integration uses mason.nvim, nvim-lspconfig, and mason-lspconfig.nvim to streamline language server management.

This setup provides:

Simplified installation and configuration of LSP servers

Consistent access to code intelligence, diagnostics, and refactoring tools

Maintained editor responsiveness during language server operations

The result is a unified workflow for coding, debugging, and technical writing within the same environment.

LSP client capabilities

The get_lsp_capabilities function configures and returns a table of Language Server Protocol (LSP) client capabilities, optimized for Markdown rendering and enhanced completion functionality.

This function is essential for integrating Neovim with LSP servers, ensuring that features such as rich documentation formatting, snippet support, and interactive completion are fully utilized.

3
4
5

--- Get LSP capabilities with support for Markdown and other features.
---@return table The LSP client capabilities.
local function get_lsp_capabilities()

The function initializes the LSP client capabilities and extends them to support:

• Markdown formatting in documentation and completion items.
• Advanced completion features such as snippets, pre-selection, and tag support.

7

local capabilities = vim.lsp.protocol.make_client_capabilities()

• Creates a table of default LSP client capabilities using Neovim's built-in make_client_capabilities function.

 9
10
11
12
13
14
15
16

-- Try to extend capabilities with blink.cmp
local blink_cmp_ok, blink_cmp = pcall(require, "blink.cmp")
if blink_cmp_ok then
  ---@diagnostic disable-next-line: need-check-nil
  capabilities = blink_cmp.get_lsp_capabilities(capabilities)
else
  vim.notify("blink.cmp not found. Using default capabilities.", vim.log.levels.WARN)
end

• Attempts to load the blink.cmp module.
• If successful, extends the capabilities using blink.cmp.get_lsp_capabilities.
• If blink.cmp is not available, logs a warning and proceeds with default capabilities.

19
20
21

capabilities.textDocument = capabilities.textDocument or {}
capabilities.textDocument.completion = capabilities.textDocument.completion or {}
capabilities.textDocument.completion.completionItem = capabilities.textDocument.completion.completionItem or {}

• Ensures the nested structure for textDocument.completion.completionItem exists to avoid nil errors.

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

  local new_capabilities = {
   documentationFormat = { "markdown", "plaintext" },
   snippetSupport = true,
   preselectSupport = true,
   insertReplaceSupport = true,
   labelDetailsSupport = true,
   deprecatedSupport = true,
   commitCharactersSupport = true,
   tagSupport = { valueSet = { 1 } },
   resolveSupport = {
   properties = {
      "documentation",
      "detail",
      "additionalTextEdits",
    },
  },
}

• Defines a table of additional capabilities:

43
44
45

for key, value in pairs(new_capabilities) do
  capabilities.textDocument.completion.completionItem[key] = value
end

• Iterates over new_capabilities and merges each key-value pair into the existing capabilities table.

47

return capabilities

• Returns the extended capabilities table.

Setting up with error handling

The setup_lsp_server function configures and initializes an LSP server by using provided settings. It implements error handling and extends server capabilities during setup.

51
52
53

-- Setup language servers using vim.lsp.config (Neovim 0.11+).
-- Helper function to setup an LSP server with error handling.
local function setup_lsp_server(server_name, config)

The function sets up an LSP server with the following features:

• Validates Neovim version compatibility.
• Merges default capabilities with user-provided configuration.
• Handles set up errors gracefully.

55
56
57
58

if not vim.lsp.config then
  vim.notify("vim.lsp.config not available. Ensure you are using Neovim 0.11+.", vim.log.levels.ERROR)
  return
end

• Checks for vim.lsp.config, a requirement in Neovim 0.11 and later.
• If unavailable, logs an error and exits the function.

61
62
63

local success, err = pcall(function()
  vim.lsp.config(server_name, vim.tbl_deep_extend("force", { capabilities = get_lsp_capabilities() }, config or {}))
end)

• Uses pcall to try server setup within a protected call.
• Merges the default capabilities (from get_lsp_capabilities) with the user-provided config table using vim.tbl_deep_extend.
• The force option ensures the default capabilities are not overridden by nil values in the user configuration.

65
66
67

if not success then
  vim.notify("Failed to setup LSP server: " .. server_name .. ". Error: " .. err, vim.log.levels.ERROR)
end

• If the setup fails, logs an error message including the server name and the specific error.

-- Configure Taplo language server for TOML file support in Neovim.
setup_lsp_server("taplo", {
  -- Settings specific to Taplo LSP.
  settings = {
    -- Formatting configuration: enable or disable automatic formatting.
    format = {
      enable = true,
    },
  ....
  ....
  -- Specify the filetypes for which Taplo should be activated.
  filetypes = { "toml" },
})

• Calls setup_lsp_server with the server name and a configuration table.
• The setup process merges the configuration table with the default capabilities.

Completion engine

blink.cmp is a high-performance completion engine for Neovim, designed to offer fast, customizable, and context-aware code completion.

Built as a plugin, it integrates seamlessly with Neovim's native Language Server Protocol (LSP) and other completion sources, offering a unified interface for autocompletion across programming languages and file types.

254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270

blink_cmp.setup({
  -- Keymap configuration for completion behavior.
  keymap = {
    preset = "super-tab",
    ["<ESC>"] = { "cancel", "fallback" },
  },
  -- Command-line mode completion settings.
  cmdline = {
    keymap = {
      preset = "default",
    },
  },
  -- Fuzzy matching settings for completion results.
  fuzzy = {
    implementation = "lua",
  },
})

The plugin emphasizes efficiency, leveraging Lua for both core logic and fuzzy matching to minimize latency and external dependencies.

blink.cmp settings

The blink.cmp plugin configuration defines keymaps, command-line mode behavior, and fuzzy matching settings for Neovim's code completion system.

keymap = {
  preset = "super-tab",
  ["<ESC>"] = { "cancel", "fallback" },
}

preset

Uses the super-tab preset, enabling Tab and Shift+Tab for navigating completion suggestions.
["<ESC>"]: Maps the Esc key to cancel the completion menu and fall back to default behavior.

Command-line mode settings

cmdline = {
  keymap = {
   preset = "default",
  },
}

preset

Applies the default keymaps preset for command-line mode completion.
Configures completion behavior in Neovim's command-line mode (e.g., /, :, >).

Fuzzy matching settings

fuzzy = {
  implementation = "lua",
}

implementation

Specifies the algorithm for fuzzy matching in completion results.
Uses the Lua-based fuzzy matching algorithm for filtering completion results.

Summary

These configurations give a streamlined setup for LSP and completion in Neovim:

• Capabilities: Extend LSP features with Markdown and advanced completion support.
• Server Setup: Initialize LSP servers with error handling and merged configurations.
• Completion: Configure blink.cmp for intuitive keymaps, command-line support, and fuzzy matching.

This setup ensures efficient, customizable, and reliable code completion.

Plugin details

nvim-lspconfig

nvim-lspconfig provides server-specific configurations for LSP servers and integrates with Neovim's built-in LSP client using vim.lsp.config (Neovim 0.11+), which replaces the deprecated require('lspconfig') API.
For server installation and management, which nvim-lspconfig does not handle, Rocksmarker uses mason.nvim. This approach simplifies setup for autocompletion, diagnostics, code navigation, and refactoring while supporting full customization of server settings and capabilities.

Key features

Settings

With the transition to Neovim 0.11+ and the adoption of vim.lsp.config, nvim-lspconfig no longer requires explicit plugin settings for basic functionality. The new implementation automatically detects and loads server configurations. This eliminates the need for manual setup of the plugin itself, as Neovim's native LSP client handles core integration.

mason.nvim

mason.nvim is a portable and intuitive plugin designed to simplify the management of external editor tools, including LSP servers, linters, formatters, and debuggers.
It provides a unified and user-friendly interface within Neovim, allowing you to discover, install, update, and manage essential development tools without leaving your editor.

Key features

Settings

This code initializes Mason for managing LSP servers and related tools in Neovim.

179
180
181
182
183
184
185
186
187

-- Setup Mason for managing LSP servers and related tools.
local mason_ok, mason = pcall(require, "mason")
if not mason_ok then
  vim.notify("mason.nvim not installed.", vim.log.levels.ERROR)
  return
end

---@diagnostic disable-next-line: need-check-nil
mason.setup({}) -- Initialize Mason with default settings.

• First, it checks if mason.nvim is available using pcall. If the plugin is not installed, it logs an error notification and exits.
• If mason.nvim is available, it initializes Mason with default settings using mason.setup({}).

This minimal setup ensures Mason is ready to install and manage LSP servers and other development tools, but does not configure any servers or tools directly.

mason-lspconfig.nvim

mason-lspconfig.nvim serves as a critical bridge between mason.nvim and nvim-lspconfig, automating the registration and configuration of language servers installed through mason.nvim.

This plugin ensures that your LSP servers are properly set up and ready to use, eliminating the need for manual configuration and reducing setup time.

Key features

Setting

This code establishes a bridge between the tool manager and a language server configuration system, automating both installation and setup of language servers.

189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218

-- Setup Mason-LSPConfig to bridge Mason and nvim-lspconfig.
local mason_lspconfig_ok, mason_lspconfig = pcall(require, "mason-lspconfig")
if not mason_lspconfig_ok then
vim.notify("mason-lspconfig not installed.", vim.log.levels.ERROR)
return
end

---@diagnostic disable-next-line: need-check-nil
mason_lspconfig.setup({
  -- List of LSP servers to automatically install.
  ensure_installed = {
    "emmylua_ls",
    "html",
    "cssls",
    "rumdl",
    "harper_ls",
    "yamlls",
    "bashls",
    "taplo",
    "jsonls",
    "vimls",
    "vale_ls",
  },
  -- Handler to automatically set up each installed LSP server.
  handlers = {
    function(server_name)
      setup_lsp_server(server_name, {})
    end,
  },
})

The code starts by attempting to load mason-lspconfig by using pcall.

• If the plugin is not found, it displays an error notification and terminates execution.
• If successful, it calls mason_lspconfig.setup() with two key configurations:

This code combines both configurations to remove manual setup steps, so all listed language servers install and register automatically with Neovim's LSP client. The approach minimizes configuration requirements, using the server list and handler function to manage the process.

mason-tool-installer.nvim

mason-tool-installer.nvim automates the installation and management of development tools, including LSP servers, linters, formatters, and other utilities required for project-specific workflows.

By accepting a declarative list of tools as input, the plugin ensures the development environment has all specified dependencies without manual intervention. It integrates with package managers to fetch, install, and update tools automatically, reducing configuration overhead and eliminating discrepancies between environments. This approach standardizes tool availability, accelerates environment setup, and maintains consistency across development workflows. The plugin supports both project-level and user-level configurations, allowing flexible tool management for different use cases.

Key features

Settings

This code configures mason-tool-installer.nvim to automate the installation of formatting, linting, and utility tools managed by mason.nvim.

220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244

-- Mason tool installer for additional formatting, linting, and utility tools.
local mason_tool_installer_ok, mason_tool_installer = pcall(require, "mason-tool-installer")
if not mason_tool_installer_ok then
  vim.notify("mason-tool-installer not installed.", vim.log.levels.ERROR)
  return
end

---@diagnostic disable-next-line: need-check-nil
mason_tool_installer.setup({
  -- List of tools to automatically install for formatting, linting, and validation.
  ensure_installed = {
    "rumdl",
    "vale",
    "stylua",
    "shfmt",
    "yamlfmt",
    "shellcheck",
    "prettier",
    "yamllint",
    "jsonlint",
    "vint",
  },
  auto_update = true,
  run_on_start = true,
})

• It starts by checking the availability of mason-tool-installer using pcall. If the plugin is not installed, it logs an error notification and exits.
• If available, it initializes the plugin with a list of tools (ensure_installed) that Mason will install automatically. The specified tools (e.g., rumdl, vale, stylua, prettier) cover a range of use cases, including Markdown linting, prose validation, Lua formatting, and JSON validation.

The configuration enables auto_update to keep up-to-date tools and sets run_on_start to true, which installs or updates tools automatically at Neovim start. This approach eliminates manual tool installation and updates, delivering a seamless development workflow setup.

Integrated LSP management

These plugins combine to create a unified ecosystem for Language Server Protocol (LSP) tools. They automate server configuration, dependency management, and client communication, removing the need for manual setup.
The system manages initialization, error handling, and performance tuning automatically.

This allows developers and technical writers to focus on coding, documentation, and productivity without distractions from underlying infrastructure. The outcome is a responsive, reliable, and maintenance-free environment for advanced language features.