Poesie, the declarative configuration layer for Neovim

Poesie is a configuration layer built on top of Neovim made to be declarative. Declarative configuration can be pictured as a tree of (possibly nested) key-value pairs.

• Features
• Install procedure
  • With packer
  • Bootstrapping
• User guide
  • Neovim layer
  • LSP layer
    • "diagnostics"
    • "capabilities"
  • Treesitter layer
  • Plugin layer
  • Keybindings layer
• Why this approach vs. scripting

Features

• Set Vim / Neovim declaratively.
• Set LSP features declaratively.
• Set Treesitter features declaratively.
• Extend your editor by adding plugins and configuring them declaratively. Poesie will expose the configuration scoped by plugin. If a plugin doesn’t support the configuration interface, some local overrides might be implemented in poesie to still be able to configure those plugins in a declarative way.

Install procedure

Installing poesie is a bit specific as it requires bootstrapping. This will largely depend on the packager you use. Once poesie is installed, you can drop your packager configuration and use the plugin layer of poesie, as it will automatically handle that for you.

If at some point you want to manually install poesie without having to alter your configuration, you can also bootstrap it by using git.

With packer

use {
  'phaazon/poesie.nvim',
  as = 'poesie',
}

Bootstrapping

git clone --recurse-submodules https://github.com/phaazon/poesie.nvim <path to the plugin directory>

User guide

Poesie is organized into different layers. You can enable each layer by creating and filling the file associated with the corresponding layer:

Layer	Associated file	Notes
Neovim layer	$XDG_CONFIG_HOME/nvim/nvim.json	Configure Neovim options.
LSP layer	$XDG_CONFIG_HOME/nvim/lsp.json	Configure Neovim’s native LSP.
Treesitter layer	$XDG_CONFIG_HOME/nvim/treesitter.json	Configure Neovim’s native Treesitter.
Plugin layer	$XDG_CONFIG_HOME/nvim/plugins.json	Declare and configure plugins.
Keybindings layer	$XDG_CONFIG_HOME/nvim/keybindings.json	Global keybindings.

If a file is present, its corresponding layer is assumed active and its configuration will be loaded.

Neovim layer

The Neovim layer is a 2-level configuration object used to configure Vim / Neovim options. Those objects directly map to the lua-vim-options (:h lua-vim-options) configuration objects. For instance, switching the showmode off option is done with vim.o.showmode = false; in Lua, and is done this way with the Neovim layer:

{
  "o": {
    "showmode": false
  }
}

LSP layer

The LSP layer allows to configure the internal Lua LSP implementation. It is a rich configuration object that provides some candies if you have the right plugins installed. It is mean of several main top-objects:

{
  "diagnostics": …,
  "capabilities": …,
  "symbol-kind-labels": …,
  "keybindings": …,
  "servers": …
}

"diagnostics"

Key	Type	Default value	Note
"diagnostics.underline"	boolean	true	Should diagnostics use underline.
"diagnostics.virtual_text"	boolean	true	Should diagnostics be using virtual text.
"diagnostics.signs"	boolean	true	Should diagnostics be using signs.
"diagnostics.update_in_insert"	boolean	false	Should diagnostics be updated in insert mode.
"diagnostics.severity_sort"	boolean	false	Should diagnostics be sorted by severity.

"capabilities"

Key	Type	Default value	Note
"capabilities.snippet"	boolean	true	Should LSP provide snippets support.
"capabilities.resolve"	array	N/A	List of LSP properties to resolve. Possible values: documentation, detail, additional-text-edits.
"capabilities.lsp_status"	boolean	N/A	Provide LSP status support for statuslines.

Treesitter layer

Plugin layer

Keybindings layer

Why this approach vs. scripting

The typical way to configure an editor like Vim or Neovim is via scripting: you get access to a VimL / Lua API, and you use it to configure the editor. The problem with that approach is that scripting ≠ configuring: using a programming language to configure your software yields more problems than it solves and having more power doesn’t always mean having an easier and better life. Scripting languages will offer people the power to use conditional, loops, imports, object-oriented programming and other paradigms that have nothing to do with configuration. If those concepts exist, you can be sure that someone will use them, abuse them and/or misuse them. Reading the configuration of a software that is full of loops, conditionals and imports doesn’t help making the end-users live any easier.

On the other side, this plugin allows users to configure Neovim in a declarative language devoid of control flow, without conditional, loops, etc. It provides users with real configuration files, and not source code / scripting files. Plugin authors can support the declarative layer directly in their plugins so that they automatically benefit from the declarative interface of poesie.