Customizing Neovim

User commands

I think implementing them as user commands makes sense—I’ll forget them if I create I keybinding for them. (I know, I tried.)

I setup user commands in blog/commands.lua:

local cmd = require("util").create_cmd
local files = require("blog.files")

-- Create a new draft, promote it to a post, or revert it back to a draft.
cmd("BlogNewDraft", files.new_draft)
cmd("BlogPromoteDraft", files.promote_curr_draft)
cmd("BlogDemotePost", files.demote_curr_post)

In Neovim you can use vim.api.nvim_create_user_command to create a user command. Because it takes three arguments, with the third options argument only being empty, I use the helper create_cmd to make it optional:

-- A module file in lua by convention use an `M` table,
-- allowing us to call`require("util").create_cmd(...)`.
local M = {}

M.create_cmd = function(command, f, opts)
  opts = opts or {}
  vim.api.nvim_create_user_command(command, f, opts)
end

return M

New draft

Creating a draft should do two things:

1. Create a file at drafts/some_title.dj under the blog directory.
2. Open it and fill in some placeholder data.

Creating a file and opening it can be done using vim.cmd to send the :edit command.

Inserting text from lua was harder to figure out, I tried to search Neovim’s help with :Telescope help_tags but came up short. In the end I found vim.api.nvim_buf_set_lines via Google that can be used to insert lines.

This is the solution I came up with:

local path = require("blog.path")
local nio = require("nio")

local M = {}

M.new_draft = function()
  nio.run(function()
    -- Prompt for the title of the new draft.
    local title = nio.ui.input({ prompt = "Draft title: " })

    -- Create and open the draft for edit (without checking if it exists...)
    -- `path.blog_path` expands to the path to my blog and `slugify` converts
    -- a title to a slug by replacing spaces with underscores and removing symbols.
    local file_path = path.blog_path .. "drafts/" .. M.slugify(title) .. ".dj"
    vim.cmd(":e " .. file_path)

    -- The text the draft will start with.
    local template = {
      "---toml",
      'title = "' .. title .. '"',
      'tags = ["Some tag"]',
      "---",
    }
    -- Insert the text into the current buffer (0) at row 0 (to 0).
    vim.api.nvim_buf_set_lines(0, 0, 0, true, template)
  end)
end

-- Convert a title to a "slug" used in the post path and url.
-- for example, converts `My title` to `my_title`.
M.slugify = function(title)
  title = title:lower()
  -- Remove disallowed characters.
  title = title:gsub("[^ a-zA-Z0-9_-]+", "")
  -- Convert spaces and multiple `_` to a single `_`.
  title = title:gsub("[ _]+", "_")
  -- Remove dashes and underscores from the beginning and end.
  title = title:gsub("^[ _-]+", "")
  title = title:gsub("[ _-]+$", "")
  return title
end

return M

I hope it’s clear what the above code is doing, but I want to call out the usage of nvim-nio. It’s a great library that makes asynchronous programming simple in Neovim.

To start an async task you use nio.run:

nio.run(function()
  -- Code here is run async
end)

For this example of creating a new draft async is overkill. Async is required for some other situations and it’s easy to add so I use it liberally, even when not strictly needed.

Moving files

In my blogging setup I store posts under posts/ with the release date in the path, and drafts under drafts/. So promoting and demoting is accomplished by moving the file:

• Promote a draft to a post by moving it from drafts/post_title.dj to posts/2024-04-14-post_title.dj.
• Demote a post by moving it from posts/2024-04-14-post_title.dj to drafts/post_title.dj.

Instead of pasting a big chunk of code, let’s go through the most important implementation details:

1. I want to use the title from the metadata because I’ll often change the title and I want the slug to be updated.

   We can extract the title from the post by shelling out to ripgrep that matches against a title = "My title" line.

   nvim-nio provides process.run to run a shell command:

   local proc = nio.process.run(args)
   proc.stdout.read()
   

   We can use process.run to run ripgrep to search for the title by passing this table as args:

   {
     cmd = "rg",
     args = {
        "-INo",
        "^title = (.+)$",
       path,
     },
   }
   

   Because we might get multiple matches (such as in this post), we can extract it using Lua:

   return output:match('title = "([^%"]+)"')
   

   Not the prettiest solution I’ve come up with.

2. Create the destination path.

   For example a post path is created like this:

   path.blog_path
     .. "posts/"
     .. os.date("%Y-%m-%d")
     .. "-"
     .. M.slugify(title)
     .. ".dj"
   

3. Move the file.

   I don’t know what the idiomatic way to rename a file is, or even how to do it in Neovim using Lua. But I do know that with :! you can call an external program… Like mv!

   So here’s one way to rename a file, that works for me on Linux:

   vim.cmd(":!mv " .. from .. " " .. to)
   vim.cmd(":e " .. to)
   

   Because everything is done in an async context (inside nio.run) we run into a problem: we can’t call the Neovim API. We’ll get an error like this:

   ...e/tree/.local/share/nvim/lazy/nvim-nio/lua/nio/tasks.lua:95: Async task failed without callback: The co
   routine failed with this message:
   vim/_editor.lua:0: E5560: nvim_exec2 must not be called in a lua loop callback
   stack traceback:
           [C]: in function 'nvim_exec2'
           vim/_editor.lua: in function 'cmd'
           /home/tree/.config/nvim/lua/blog/files.lua:82: in function '_rename'
           /home/tree/.config/nvim/lua/blog/files.lua:116: in function 
   s.lua:106>
   

   The error to look out for is nvim_exec2 must not be called in a lua loop callback, which I assume means that nio uses the lower level lua loop API for its async system.

   What we need to do is yield to the Neovim scheduler before calling vim.cmd to rename the file, which can be done with nio.scheduler():

   nio.scheduler()
   -- Now we can call `vim.cmd` and `vim.fn`.