vim-board

   ver 1.26.2

This plugin introduces a file type board which allows you to easily write quick notes and some shortcuts to files, directories and additional commands.

Feature

After setting up a custom Key, you can bring up the board using the following key sequence:

      Key Enter

and to return:

      Key Esc

Installation

You can use your preferred plugin manager using the string 'azabiong/vim-board'. For example:

vim-plug  .vim

 Plug 'azabiong/vim-board'

lazy.nvim  .lua

 {
   "azabiong/vim-board",
   init = function()
     -- settings
   end,
 },

  or,  Vim's built-in package feature:

Linux, Mac	Windows
~/.vim	~/vimfiles

in the terminal:

cd ~/.vim && git clone --depth=1 https://github.com/azabiong/vim-board.git pack/azabiong/start/vim-board
cd ~/.vim && vim -u NONE -c "helptags pack/azabiong/start/vim-board/doc" -c q

Configuration

The first item is to define the directory to store the board files. And next is to assign a convenient key to bring up the board with menu.  The plugin default shortcut is a single quote and space if available.

  .vim

    let BoardPath = '~/.config/boards'

    nmap '<Space> <Plug>(BoardMenu)

  .lua

    vim.g.BoardPath = '~/.config/boards'

    vim.keymap.set('n', "'<Space>", '<Plug>(BoardMenu)')

Now, save the changes and reload the plugin.

Syntax

The plugin has an easy syntax and uses .board and .bd as file extensions.
You can display each item differently by using indentation and some leading characters.

The plugin uses sections to categorize content. Each section starts at the beginning of a line, and can have different syntax depending on its type.

Menu

Pressing the BoardMenu key will bring up the most recently used board with the auto-expanding menu.

You can enter keys defined on the board, or switch between boards using the following keys:

keys

key	function
Enter	edit current board
Esc	return
;	return (optional)
Space	scroll down
↓	scroll down
↑	scroll up
CtrlSpace	scroll up
-	switch to previous board
=	switch to main board
+	add new board
:	command-line mode
/	search (optional)
<	load links
>	unload links

:Links Section

The plugin loads the shortcut links defined in this section. The following example defines two links:

:Links
       #key value
       \py  ~/Languages/Python/
        pn  ~/Languages/Python/notes.py

Each link is a simple space-separated key-value pair, and uses the same indentation as the TEXT field starting at column 6 or higher.   Modified links take effect immediately after saving.

Key

A key can consist of any combination of symbols, alphanumeric, and Unicode characters except those that start with some predefined characters.

Available leading characters:

    ~!@$%^&*_()[]{}'`";,.\/? 0-9 a-z A-Z and Unicode characters

Used in the menu and syntax:

    -  previous     #  comment 
    =  main         |  command 
    +  new
    <  load
    >  unload
    :  command

The same key can be defined differently on each board.

Long keys

Long keys can be activated by typing only the unique prefix portion of the key.   For example, if you define a link with a long key xylophone, and no other keys start with xy, you can open the link with xy Enter.

Path

To easily define a link to a file, the plugin supports copying the current file's path to a register when the menu key is pressed (by default the b register).

To paste the path stored in register b in insert mode:

      Ctrl+R b

🍏  Tip

When switching to another board stored in the BoardPath directory, you can omit the path and specify only the file name.  For example:

      'a  another.board

Switching boards using the defined keys will automatically load the links defined on the board.

Commands

Additional commands can be added using the | bar character.

For example, to browse files after changing the current working directory:

      \py  ~/Languages/Python/ | edit .

After opening the file, to go to the line 128:

       pn  ~/Languages/Python/notes.py | 128

More commands can be combined together:

      \d1 ~/Directory/ | NERDTreeCWD | wincmd p | edit README.md

Commands only

You can also define just a list of commands without specifying a file or directory.

For example, to define a command that copies frequently used commands or strings to the clipboard:

      s1  | let @+ = "copy this string to the clipboard"

To define a substitution command:

      ss  | %s/Foo/Bar/gc

To define a set of temporary key-maps:

      key | nn f0 <Cmd>echo 0<CR>
          | nn f9 <Cmd>echo 9<CR>

To define some input from the shell tool to the scratchpad, Board*:

      sh1 | Board* | r! echo "This is the scratchpad on the Board"
      sh2 | Board* | r! curl -sI example.com

Multi-line commands

Multi-line commands  can be set using the leading bar | character.

      c1  ~/directory/or_file
          | echo 'foo'
          | echo 'bar'

Link reference

You can refer to links using the '&' symbol instead of duplicates. For example:

      \d1 ~/directory1/ | &_N
      \d2 ~/directory2/ | &_N

      _N  | NERDTreeCWD | wincmd =

Command-line mode

When using the | bar character as a shell pipe or other meaning, you can switch to command-line mode input by adding a colon : after the bar.

      sh3 | Board* |: r! ls | wc
      sh4 | Board* |: r! cat ~/.ssh/known_hosts | awk '$1 ~ /[0-9]/ { print $1; exit }'

Stop command

To stop a long list of commands while processing, press the menu key and input Ctrl+C or an undefined key.

Help tags

For more information about options, please see:

 :h Board-Options

Customizing Colors

The plugin provides two default color sets that can be automatically loaded depending on the current background mode. You can use the native hi command to customize colors starting with Board, and save them to the configuration file or color scheme.

 BoardHelp  BoardSection  BoardGroup  BoardSpecial  BoardMarker  BoardLink  BoardLed...

Example

 :hi BoardSpecial ctermfg=208 guifg=#ff8700

Issues

If you have any issues that need fixing, comments or new features you would like to add, please feel free to open an issue.