nvim-origami 🐦📄

A collection of quality-of-life features related to folding.

Features

• Use the LSP to provide folds, with Treesitter as fallback if the LSP does not provide folding information (and indent-based folding as fallback if neither is available).
• Fold-text decorations: Displays the number of lines, diagnostics, and changes in the fold, while preserving the syntax highlighting of the line (displaying git changes requires gitsigns.nvim).
• Overload h, l, and $ as fold keymaps:
  • h will fold a line when used on the first non-blank character (or before), and behaves as regular h otherwise.
  • l unfolds the cursorline when used on a folded line, and behaves as regular l otherwise.
  • $ unfolds the cursorline recursively when used on a folded line, and behaves as regular $ otherwise
  • This allows you to ditch zc, zo, za and zO, since you only need h, l, and $.
• Auto-fold: Automatically fold comments and/or imports when opening a file (requires an LSP that provides that information).
• Pause folds while searching, and restore folds when done with searching. (Normally, folds are opened when you search for text inside them and stay open afterward.)

All features are independent, so you can choose to only enable some of them.

nvim-origami replaces most features of nvim-ufo in a much more lightweight manner and adds some features that nvim-ufo does not provide.

Table of Content

• Breaking changes in v2.0
• Installation
• Configuration
• FAQ
  • Error when opening or reloading a file
  • Folds are opened after running a formatter
  • Debug folding issues
• Credits
• About the developer

Breaking changes in v2.0

• nvim 0.11 is now required.
• nvim-ufo is *no longer compatible* with this plugin (most of its features are now offered by nvim-origami in a more lightweight way).
• Saving folds across sessions is no longer supported.
• If you do not like the changes, you can pin nvim-origami to the tag v1.9.

Installation

Requirements - nvim 0.11+ - not using nvim-ufo, since nvim-origami is incompatible with it

```lua -- lazy.nvim { "chrisgrieser/nvim-origami", event = "VeryLazy", opts = {}, -- needed even when using default config

-- recommended: disable vim's auto-folding
init = function()
    vim.opt.foldlevel = 99
    vim.opt.foldlevelstart = 99
end,

}, ```

Configuration

lua -- default settings require("origami").setup { useLspFoldsWithTreesitterFallback = true, pauseFoldsOnSearch = true, foldtext = { enabled = true, padding = 3, lineCount = { template = "%d lines", -- `%d` is replaced with the number of folded lines hlgroup = "Comment", }, diagnosticsCount = true, -- uses hlgroups and icons from `vim.diagnostic.config().signs` gitsignsCount = true, -- requires `gitsigns.nvim` }, autoFold = { enabled = true, kinds = { "comment", "imports" }, ---@type lsp.FoldingRangeKind[] }, foldKeymaps = { setup = true, -- modifies `h`, `l`, and `$` hOnlyOpensOnFirstColumn = false, }, }

If you use other keys than h, l, and $ for vertical movement, set opts.foldKeymaps.setup = false and map the keys yourself:

lua vim.keymap.set("n", "<Left>", function() require("origami").h() end) vim.keymap.set("n", "<Right>", function() require("origami").l() end) vim.keymap.set("n", "<End>", function() require("origami").dollar() end)

FAQ

Error when opening or reloading a file

txt Error executing vim.schedule lua callback: ...0.11.2/share/nvim/runtime/lua/vim/lsp/_folding_range.lua:311: attempt to index a nil value

This error occasionally occurs with autoFold enabled. It is, however, not caused by nvim-origami but by a bug with vim.lsp.foldclose() in nvim core. A future version of nvim will hopefully fix this.

Folds are opened after running a formatter

This is a known issue of many formatting plugins and not related to nvim-origami.

The only two tools I am aware of that are able to preserve folds are the efm-language-server and conform.nvim.

Debug folding issues

Debug issues with folds provided by the LSP:

lua require("origami").inspectLspFolds("special") -- comment & import only require("origami").inspectLspFolds("all")

Credits

• u/marjrohn for the decorator approach to styling foldtext.

About the developer

In my day job, I am a sociologist studying the social mechanisms underlying the digital economy. For my PhD project, I investigate the governance of the app economy and how software ecosystems manage the tension between innovation and compatibility. If you are interested in this subject, feel free to get in touch.

• Website
• Mastodon
• ResearchGate
• LinkedIn