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 info.
• 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 and l as fold keymaps: Overloads the h key which will fold a line when used on the first non-blank character of (or before). And overloads the l key, which will unfold a line when used on a folded line. This allows you to ditch zc, zo, and za; h and l are all you need.
• 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.)

Every feature is 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 possess.

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 by this plugin.
• 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

-- 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

-- default settings
require("origami").setup {
    useLspFoldsWithTreesitterFallback = true, -- required for `autoFold`
    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` and `l`
        hOnlyOpensOnFirstColumn = false,
    },
}

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

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

FAQ

Error when opening or reloading a file

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 this plugin but by a bug with vim.lsp.foldclose() in nvim core. Unfortunately, there is little origami can do about it. A future update version of nvim core should fix it.

Folds are opened after running a formatter

This is a known issue of many formatting plugins and actually 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

-- Folds provided by the LSP
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