.

content/posts/getting-started-with-a-barebones-neovim-plugin-in-lua.md

@@ -0,0 +1,109 @@
+---
+title: so you want to write a neovim plugin with lua
+date: 2024-04-06
+tags:
+  - lua
+  - neovim
+draft: false
+---
+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](https://neovim.io/doc) 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.
+
+```bash
+├── lua
+│   └── note
+│       └── init.lua
+└── plugin
+    └── note.vim
+```
+
+The `plugin/note.vim` file will look like this.
+
+```vim
+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.
+
+```lua
+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.
+
+```lua
+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.
+
+```lua
+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.
+
+```lua
+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.
+
+```lua
+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](https://github.com/folke/lazy.nvim/).
+
+```lua
+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.