yutkat / sidebar.nvim

A generic and modular lua sidebar for Neovim

sidebar.nvim

A generic and modular lua sidebar inspired by lualine

Development status: Alpha - bugs are expected

Quick start

local sidebar = require("sidebar-nvim")
local opts = {open = true}
sidebar.setup(opts)

See options for a full list of setup options

TODOs (Need help)

• Better section icons
• Improve docs + write vim help files
• See repo issues, any contribution is really appreciated

Options

Sidebar setup options.

Defaults:

require("sidebar-nvim").setup({
    disable_default_keybindings = 0,
    bindings = nil,
    open = false,
    side = "left",
    initial_width = 35,
    update_interval = 1000,
    sections = { "datetime", "git-status", "lsp-diagnostics" },
    section_separator = "-----"
})

disable_default_keybindings

Default: 0

Enable/disable the default keybindings

bindings

Default: nil

Attach custom bindings to the sidebar buffer.

Example:

require("sidebar-nvim").setup({
    bindings = { ["q"] = function() require("sidebar-nvim").close() end }
})

Note sections can override these bindings, please see Section Bindings

side

Default: left

initial_width

Default: 50

update_interval

Default: 1000

Update frequency in milliseconds

sections

Default: { "datetime", "git-status", "diagnostics" }

Which sections should the sidebar render

See Bultin Sections and Custom Sections

section_separator

Default: -----

Can be a string or a function with like the following:

function section_separator(section)
    return "-----"
end

section is the section definition. See Custom Sections for more info

Builtin Sections

datetime

Prints the current date and time using vim.fn.strftime("%c")

git-status

Prints the status of the repo as returned by git status --porcelain

keybindings

key	when	action
e	hovering filename	open file in the previous window

lsp-diagnostics

Prints the current status of the builtin lsp grouper by file. It shows only loaded buffers

keybindings

key	when	action
e	hovering diagnostic message	open file in the previous window at the diagnostic position
t	hovering filename	toggle collapse on the group

todos

Shows the TODOs in source. Provided by todo-comments

There are some small issues using this section see folke/todo-comments.nvim#63 So you might want to consider using my fork instead https://github.com/GustavoKatel/todo-comments.nvim

keybindings

key	when	action
e	hovering todo location	open file in the previous window at the todo position
t	hovering the group	toggle collapse on the group

containers

Shows the system docker containers. Collected from docker ps -a --format='{{json .}}'

config

require("sidebar-nvim").setup({
    ...
    docker = {
        use_podman = false,
        attach_shell = "/bin/sh",
        show_all = true, -- whether to run `docker ps` or `docker ps -a`
    }
    ...
})

keybindings

key	when	action
e	hovering a container location	open a new terminal and attach to the container with docker exec -it <container id> ${config.docker.attach_shell}

Custom Sections

sidebar.nvim accepts user defined sections. The minimal section definition is a table with a draw function that returns the string ready to render in the sidebar and a title. See below the list of available properties

local section = {
    title = "Section Title",
    icon = "->",
    setup = function()
        -- called only once and if the section is being used
    end,
    draw = function(ctx)
        return "> string here\n> multiline"
    end,
    highlights = {
        groups = { MyHighlightGroup = { gui="#C792EA", fg="#ff0000", bg="#00ff00" } },
        links = { MyHighlightGroupLink = "Keyword" }
    }
}

setup

This function is called only once and only if the section is being used You can use this function to create timers, background jobs etc

draw

The function accepts a single parameter ctx containing the current width of the sidebar:

{ width = 90 }

The draw function may appear in three forms:

• Returning a string
• Returning a table of strings
• Returning a table like { lines = "", hl = {} }

The later is used to specify the highlight groups related to the lines returned

Example:

local section = {
    title = "test",
    draw = function()
        return {
            lines = {"> item1", "> item2"},
            hl = {
                -- { <group name>, <line index relative to the returned lines>, <column start>, <column end, -1 means end of the line> }
                { "SectionMarker", 0, 0, 1 },
            }
        }
    end
}

highlights

Specify the highlight groups associated with this section. This table contains two properties: groups and links

• groups define new highlight groups
• links link highlight groups to another

Example:

local section = {
    title = "Custom Section",
    icon = "->",
    draw = function()
        return {
            lines = {"hello world"},
            hl = {
                -- more info see `:h nvim_buf_add_highlight()`
                { "CustomHighlightGroupHello", 0, 0, 5 }, -- adds `CustomHighlightGroupHello` to the word "hello"
                { "CustomHighlightGroupWorld", 0, 6, -1 }, -- adds `CustomHighlightGroupWorld` to the word "world"
            }, 
        }
    end,
    highlights = {
        groups = { CustomHighlightGroupHello = { gui="#ff0000", fg="#00ff00", bg="#0000ff" } },
        links = { CustomHighlightGroupWorld = "Keyword" }
    }
}

more info see: :h nvim_buf_add_highlight

bindings

Custom sections can define custom bindings. Bindings are dispatched to the section that the cursor is currently over.

This means that multiple sections can define the same bindings and SidebarNvim will dispatch to the correct section depending on the cursor position.

Example:

local lines = {"hello", "world"}
local section = {
    title = "Custom Section",
    icon = "->",
    draw = function()
        return lines
    end,
    bindings = {
        ["e"] = function(line, col)
            print("current word: "..lines[line])
        end,
    },
}

Builtin components

Builtin components abstract ui elements that can be reused within sections.

Loclist

Create a location list with collapsable groups.

Sections using it: git-status, lsp-diagnostics and todos

Example:

local Loclist = require("sidebar-nvim.components.loclist")
local loclist = Loclist:new()
loclist:add_item({ group = "my_group", lnum = 1, col = 2, text = "my cool location", icon = { text = "#", hl = "MyCustomHighlightGroup" } })

-- inside the section draw function
local lines, hl = {}, {}

table.insert(lines, "Here's the location list you asked:")

loclist:draw(ctx, lines, hl)

return { lines = lines, hl = hl }

Colors

Highlight Group	Defaults To
SidebarNvimSectionTitle	Directory
SidebarNvimSectionSeparator	Comment
SidebarNvimGitStatusState	Keyword
SidebarNvimGitStatusFileName	Normal
SidebarNvimLspDiagnosticsError	LspDiagnosticsDefaultError
SidebarNvimLspDiagnosticsWarn	LspDiagnosticsDefaultWarning
SidebarNvimLspDiagnosticsInfo	LspDiagnosticsDefaultInformation
SidebarNvimLspDiagnosticsHint	LspDiagnosticsDefaultHint
SidebarNvimLspDiagnosticsLineNumber	LineNr
SidebarNvimLspDiagnosticsColNumber	LineNr
SidebarNvimLspDiagnosticsFilename	Label
SidebarNvimLspDiagnosticsTotalNumber	LspTroubleCount
SidebarNvimLspDiagnosticsMessage	Normal
SidebarNvimTodoTag	Label
SidebarNvimTodoTotalNumber	Normal
SidebarNvimTodoFilename	Normal
SidebarNvimTodoLineNumber	LineNr
SidebarNvimTodoColNumber	LineNr
SidebarNvimDockerContainerStatusRunning	LspDiagnosticsDefaultInformation
SidebarNvimDockerContainerStatusExited	LspDiagnosticsDefaultError
SidebarNvimDockerContainerName	Normal

References

We based most of the code from the awesome work of @kyazdani42 in nvim-tree

Contributors

@GustavoKatel @davysson