BOXdash – A simple dashboard for Neovim

If you want to use a dashboard but you want to keep it simple because you just want an easy way to perform certain actions when starting Neovim without a file or directory?

Try BOXdash! It intentionally does not use colors, nor icons, nor fancy highlighting. Just a customizable menu with a classic look (you can even enable ASCII mode).

Install BOXdash

Even if BOXdash is not available on GitHub but on a selfhosted Forgejo instance, you can still use it with your favorite plugin manager

-- Use lazy.nvim, for example:
  require('lazy').setup({
    -- [more plugins here]
    { url = 'https://git.0x7be.net/dirk/boxdash', opts = setup_table }
  })

-- or use Packer:
require('packer').startup(function(use)
    use 'https://git.0x7be.net/dirk/boxdash.git'
end

If you’re really oldschool just grab the files directly and place them wherever you want. Just make sure they can be loaded by Neovim.

Configuration

Use whatever method is needed in order to configure a plugin with your plugin manager. You can also manually require the plugin and run the setup command.

require('neovim-boxdash').setup({
    title = 'Neovim',  -- box title (set to '' to hide)
    align = {
        horizontal = 0,  -- horizontal box alignment
        vertical = 0,    -- vertical box alignment
    },
    style = 1,   -- One of the available styles (see below)
    entries = {  -- Menu entries
        { 'i', 'Switch to insert mode', 'insert_mode'  },
        { 'e', 'Get an empty buffer',   'empty_buffer' },
        '----------------------------------------------',
        { 'q', 'Quit Neovim',           'quit_neovim'  },
    }
})

For lazy.nvim simply use the table provided to the setup() function as the opts table. You don’t need to manually run the setup function there.

Design

For the align entries the following definitions are possible.

1. 0 center/middle
2. +N from left/top
3. -N from right/bottom

For style the following styles are available. Just use the corresponding number. If you use -1 one of the available styles is used randomly on each startup.

    1          2          3          4          5
┏━━━┯━━━┓  +---+---+  ╔═══╤═══╗  ┌───┬───┐  ╭───┬───╮
┃   │   ┃  |   |   |  ║   │   ║  │   ┆   │  │   │   │
┠───┼───┨  +---+---+  ╟───┼───╢  ├╌╌╌┼╌╌╌┤  ├───┼───┤
┃   │   ┃  |   |   |  ║   │   ║  │   ┆   │  │   │   │
┗━━━┷━━━┛  +---+---+  ╚═══╧═══╝  └───┴───┘  ╰───┴───╯

The entries table is where the fun begins … Each table line represents an entry in the menu. To define an entry, 3 bits of information are needed.

1. The key to execute the action. If the key is already defined, it gets overwritten for the current buffer.
2. A short description of what action is performed.
3. The action definition, this can either be a predefined keyword or a function doing anything you want.

You’re also not limited to single key keymaps. You can do whatever you want here (see “Definition limitations” for details).

If you want to show a separator line in the menu, add a string starting with one of the following characters top the entries table.

    -          #          |

┠───┼───┨  ┗━━━┷━━━┛  ┃   │   ┃
           ┏━━━┯━━━┓

The entry doesn’t need to be formatted like in the example. As long as the string starts with the character everything is fine, but for aligning the configuration you can use as many of the characters or any other character you want.

Definition limitations

Even if the title, the keys, and the descriptions can be whatever you want, they have to match all of the following rules.

1. The title must be at least 1 character longer than the longest key definition.
2. The title must be at least 1 character shorter than the longest key definition plus the longest description of a key.
3. There is no line wrapping, lines too long will run outside the buffer.

Predefined keywords

BOXdash provides you with – currently – 4 predefined action keywords.

1. insert_mode – deletes the dash buffer and opens insert mode in a new one
2. empty_buffer – deletes the dash buffer and creates a new one without any special modes
3. quit_neovim – Nicely asks Neovim to quit. If there are some things that prevent Neovim from quitting, it will complain (i.e. no handling of any quitting-related actions is done by BOXdash)
4. lazy_sync – Synchronize/update plugins handled with lazy.nvim.
5. packer_sync – Synchronize/update plugins handled with Packer.

Example for a custom action

Please note that custom actions always delete buffer BOXdash is shown in. Also, this buffer is locked down. It is not modifiable and set to readonly, so it can’t be used for something anyways.

entries = {
    { 'n', 'Start netrw', function () vim.api.nvim_command('Explore') end }
}

This gives you a pretty sad little menu (and when you press n, netrw will be started).

But you can use whatever you want in the call. And yes, you might be able to break BOXdash :)