I’ve recently been messing around with writing neovim plugins. When I initially got going I found it a little tricky to know how to get started. There’s the official neovim docs which are great; but in my beginner experience exhaustive to the point of slight impenetrability. Beyond that, the thing I found most useful was simply reading the source of some popular plugins to get an idea of how things worked. I would recommend sticking to plugins with a smaller scope though.

As a demostrative MVP (minimal viable plugin) jumping-off-point, I’m going to make a very simple note-taking plugin. It will provide a command to neovim which when run opens a file titled with the date and time in a specific notes directory. Vamos.

This is what you will want your directory structure to look like.

├── lua
│   └── note
│       └── init.lua
└── plugin
    └── note.vim

The plugin/note.vim file will look like this.

command! Note lua require("note").main()

This creates a custom command Note which when run will call a lua function. Now on to where that function and the meat of the plugin logic will live: the lua/note/init.lua file. With more complex plugins this section will often be split into many files but we’ve just got one here as it’s so simple.

First things first we create a plugin object.

local note = {}

Then we will define some default options for the plugin in a table. These are variables you want the user to be able to change when they call the setup function.

local defaults = {
  note_directory = "~/notes/",
  date_format = "%Y-%m-%d %H:%M",
  file_extension = ".md",
}

Next we need the setup function. This takes the user’s options and merges them with our default options.

function note.setup(user_options)
  options = vim.tbl_deep_extend("force", defaults, user_options or {})
end

This is the main function where the magic happens.

function note.main()
  local dir = options.note_directory
  local name = os.date(options.date_format)
  local ext = options.file_extension
  local filename = string.format("%s%s%s", dir, name, ext)
  local command = string.format("edit %s", filename)
  vim.api.nvim_command(command)
end

Finally we return the plugin obect.

return note

At this point you should have a working plugin :) As a little coda, this is how you can use your fancy new plugin using lazy.nvim.

require("lazy").setup({
  {
    -- local
    dir = "~/neovim-note-plugin",

    -- github
    -- "me/neovim-note-plugin",

    -- alternative non github hosting
    -- url = "https://git.example.com/me/neovim note-plugin",

    config = fucntion()
      require("note").setup({
        file_extension = ".org",
      })
    end,

  }
})

Hope you’ve enjoyed.