A Neovim Plugin Template

A template repository used to create Neovim plugins.

Features

• Follows nvim-best-practices
• Fast start-up (~1 ms)
• Auto-release to luarocks & GitHub
• Automated user documentation (using panvimdoc)
• Automated API documentation (using mini.doc)
• Automated HTML documentation + self-publishing using emmylua_doc_cli & mkdocs-material
  • Yes, this repository has a website! Check it out at nvim-best-practices-plugin-template!
• Vimtags generation
• Built-in Vim commands
• A high quality command mode parser
• Auto-completes your commands at any cursor position
• No external dependencies*
• LuaCATS annotations and type-hints, everywhere
• RSS feed support
• Built-in logging to stdout / files
• Unittests use the full power of native busted
  • Supports LuaCov for coverage reports!
• Automated testing matrix supports 12 Neovim/OS combinations
  • neovim: [v0.11.0, v0.12.0, stable, nightly]
  • os: [ubuntu-latest, macos-latest, windows-latest]
• 100% Lua
• Uses Semantic Versioning
• Integrations
  • lualine.nvim
  • telescope.nvim
  • :checkhealth
• Github actions for:
  • StyLua - Auto-formats Lua code
  • llscheck - Checks for Lua type mismatches
  • luacheck - Checks for Lua code issues
  • luarocks auto-release (LUAROCKS_API_KEY secret configuration required)
  • GitHub auto-release (PERSONAL_ACCESS_TOKEN secret configuration required)
  • mdformat - Auto-formats project Markdown files
  • mini.doc - API documentation auto-generator
  • panvimdoc - User documentation auto-generator
  • emmylua_doc_cli & mkdocs-material - Generate HTML from Lua files automatically
  • urlchecker - Checks for broken URL links
  • PR reviews - Reminds users to update doc/news.txt

Using This Template

1. Follow the Wiki instructions
2. Run make download-dependencies so all the Lua LSP features work as expected.
3. Once you're done, remove this section (the rest of this README.md file should be kept / customized to your needs)

Installation

• lazy.nvim

{
    "ColinKennedy/nvim-best-practices-plugin-template",
    dependencies = { "ColinKennedy/mega.cmdparse", "ColinKennedy/mega.logging" },
    -- TODO: (you) - Make sure your first release matches v1.0.0 so it auto-releases!
    version = "v1.*",
}

Configuration

(These are default values)

• lazy.nvim

{
    "ColinKennedy/nvim-best-practices-plugin-template",
    config = function()
        vim.g.plugin_template_configuration = {
            commands = {
                goodnight_moon = { read = { phrase = "A good book" } },
                hello_world = {
                    say = { ["repeat"] = 1, style = "lowercase" },
                },
            },
            logging = {
                level = "info",
                use_console = false,
                use_file = false,
            },
            tools = {
                lualine = {
                    arbitrary_thing = {
                        color = "Visual",
                        text = " Arbitrary Thing",
                    },
                    copy_logs = {
                        color = "Comment",
                        text = "󰈔 Copy Logs",
                    },
                    goodnight_moon = {
                        color = "Question",
                        text = " Goodnight moon",
                    },
                    hello_world = {
                        color = "Title",
                        text = " Hello, World!",
                    },
                },
                telescope = {
                    goodnight_moon = {
                        { "Foo Book", "Author A" },
                        { "Bar Book Title", "John Doe" },
                        { "Fizz Drink", "Some Name" },
                        { "Buzz Bee", "Cool Person" },
                    },
                    hello_world = { "Hi there!", "Hello, Sailor!", "What's up, doc?" },
                },
            },
        }
    end
}

Lualine

Note: You can customize lualine colors here or using vim.g.plugin_template_configuration.

lualine.nvim

require("lualine").setup {
    sections = {
        lualine_y = {
            -- ... Your other configuration ...
            {
                "plugin_template",
                -- NOTE: These will override default values
                -- display = {
                --     goodnight_moon = {color={fg="#FFFFFF"}, text="Custom message 1"}},
                --     hello_world = {color={fg="#333333"}, text="Custom message 2"},
                -- },
            },
        }
    }
}

Telescope

Note: You can customize telescope colors here or using vim.g.plugin_template_configuration.

telescope.nvim

{
    "nvim-telescope/telescope.nvim",
    cmd = "Telescope",
    config = function()
        -- ... Your other configuration ...
        require("telescope").load_extension("plugin_template")
    end,
    dependencies = {
        "ColinKennedy/nvim-best-practices-plugin-template",
        "nvim-lua/plenary.nvim",
    },
    version = "0.1.*",
},

Colors

This plugin provides two default highlights

• PluginTemplateTelescopeEntry
• PluginTemplateTelescopeSecondary

Both come with default colors that should look nice. If you want to change them, here's how:

vim.api.nvim_set_hl(0, "PluginTemplateTelescopeEntry", {link="Statement"})
vim.api.nvim_set_hl(0, "PluginTemplateTelescopeSecondary", {link="Question"})

Commands

Here are some example commands:

" A typical subcommand
:PluginTemplate hello-world say phrase "Hello, World!" " How are you?"
:PluginTemplate hello-world say phrase "Hello, World!" --repeat=2 --style=lowercase

" An example of a flag this repeatable and 3 flags, -a, -b, -c, as one dash
:PluginTemplate arbitrary-thing -vvv -abc -f

" Separate commands with completely separate, flexible APIs
:PluginTemplate goodnight-moon count-sheep 42
:PluginTemplate goodnight-moon read "a book"
:PluginTemplate goodnight-moon sleep -z -z -z

Tests

Initialization

Run this line once before calling any busted command

eval $(luarocks path --lua-version 5.1 --bin)

Running

Run all tests

# Using the package manager
luarocks test --test-type busted
# Or manually
busted .
# Or with Make
make test

Run test based on tags

busted . --tags=simple

Coverage

Making sure that your plugin is well tested is important. nvim-best-practices-plugin-template can generate a per-line breakdown of exactly where your code is lacking tests using LuaCov.

Setup

Make sure to install all dependencies for the unittests + coverage reporter if you have not installed them already.

luarocks install busted --local
luarocks install luacov --local
luarocks install luacov-multiple --local

Running

make coverage-html

This will generate a luacov.stats.out & luacov_html/ directory.

Viewing

(cd luacov_html && python -m http.server)

If it worked, you should see a message like "Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000) ..." Open http://0.0.0.0:8000 in a browser like Firefox and you should see a view like this:

Just navigate down a few folders until you get to a .lua file and you'll see a breakdown of your line coverage like this:

Tracking Updates

See doc/news.txt for updates.

You can watch this plugin for changes by adding this URL to your RSS feed:

https://github.com/ColinKennedy/nvim-best-practices-plugin-template/commits/main/doc/news.txt.atom

Other Plugins

This template is full of various features. But if your plugin is only meant to be a simple plugin and you don't want the bells and whistles that this template provides, consider instead using nvim-plugin-template