{"id":14981709,"url":"https://github.com/colinkennedy/nvim-best-practices-plugin-template","last_synced_at":"2025-10-25T14:42:33.026Z","repository":{"id":255600489,"uuid":"840584996","full_name":"ColinKennedy/nvim-best-practices-plugin-template","owner":"ColinKennedy","description":"A no-nonsense template for making high-quality Neovim plugins. It has all the best opinions, pinky promise","archived":false,"fork":false,"pushed_at":"2025-03-21T22:00:16.000Z","size":1885,"stargazers_count":105,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T11:11:59.784Z","etag":null,"topics":["neovim","neovim-plugin","nvim","nvim-plugin","plugin-template"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ColinKennedy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-10T04:47:22.000Z","updated_at":"2025-03-26T06:05:55.000Z","dependencies_parsed_at":"2024-09-06T08:33:04.965Z","dependency_job_id":"00226f1b-0f4d-4ce8-9334-c1fb0e58c53a","html_url":"https://github.com/ColinKennedy/nvim-best-practices-plugin-template","commit_stats":{"total_commits":8,"total_committers":1,"mean_commits":8.0,"dds":0.0,"last_synced_commit":"3085fcedf4a0a1f38bad0643c10bdae318fdad0f"},"previous_names":["colinkennedy/nvim-best-practices-plugin-template"],"tags_count":21,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinKennedy%2Fnvim-best-practices-plugin-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinKennedy%2Fnvim-best-practices-plugin-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinKennedy%2Fnvim-best-practices-plugin-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinKennedy%2Fnvim-best-practices-plugin-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ColinKennedy","download_url":"https://codeload.github.com/ColinKennedy/nvim-best-practices-plugin-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247485287,"owners_count":20946398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["neovim","neovim-plugin","nvim","nvim-plugin","plugin-template"],"created_at":"2024-09-24T14:04:05.988Z","updated_at":"2025-10-25T14:42:33.021Z","avatar_url":"https://github.com/ColinKennedy.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A Neovim Plugin Template\n\nA template repository used to create Neovim plugins.\n\n| \u003c!-- --\u003e | \u003c!-- --\u003e |\n|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Build Status | [![unittests](https://img.shields.io/github/actions/workflow/status/ColinKennedy/nvim-best-practices-plugin-template/test.yml?branch=main\u0026style=for-the-badge\u0026label=Unittests)](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/actions/workflows/test.yml) [![documentation](https://img.shields.io/github/actions/workflow/status/ColinKennedy/nvim-best-practices-plugin-template/documentation.yml?branch=main\u0026style=for-the-badge\u0026label=Documentation)](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/actions/workflows/documentation.yml) [![luacheck](https://img.shields.io/github/actions/workflow/status/ColinKennedy/nvim-best-practices-plugin-template/luacheck.yml?branch=main\u0026style=for-the-badge\u0026label=Luacheck)](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/actions/workflows/luacheck.yml) [![llscheck](https://img.shields.io/github/actions/workflow/status/ColinKennedy/nvim-best-practices-plugin-template/llscheck.yml?branch=main\u0026style=for-the-badge\u0026label=llscheck)](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/actions/workflows/llscheck.yml) [![checkhealth](https://img.shields.io/github/actions/workflow/status/ColinKennedy/nvim-best-practices-plugin-template/checkhealth.yml?branch=main\u0026style=for-the-badge\u0026label=checkhealth)](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/actions/workflows/checkhealth.yml) [![stylua](https://img.shields.io/github/actions/workflow/status/ColinKennedy/nvim-best-practices-plugin-template/stylua.yml?branch=main\u0026style=for-the-badge\u0026label=Stylua)](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/actions/workflows/stylua.yml) [![urlchecker](https://img.shields.io/github/actions/workflow/status/ColinKennedy/nvim-best-practices-plugin-template/urlchecker.yml?branch=main\u0026style=for-the-badge\u0026label=URLChecker)](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/actions/workflows/urlchecker.yml) [![mdformat](https://img.shields.io/github/actions/workflow/status/ColinKennedy/nvim-best-practices-plugin-template/mdformat.yml?branch=main\u0026style=for-the-badge\u0026label=mdformat)](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/actions/workflows/mdformat.yml) |\n| License | [![License-MIT](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/blob/main/LICENSE) |\n| Social | [![RSS](https://img.shields.io/badge/rss-F88900?style=for-the-badge\u0026logo=rss\u0026logoColor=white)](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/commits/main/doc/news.txt.atom) |\n\n# Features\n\n- Follows [nvim-best-practices](https://github.com/nvim-neorocks/nvim-best-practices)\n- Fast start-up (~1 ms)\n- Auto-release to [luarocks](https://luarocks.org) \u0026 [GitHub](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/releases)\n- Automated user documentation (using [panvimdoc](https://github.com/kdheepak/panvimdoc))\n- Automated API documentation (using [mini.doc](https://github.com/echasnovski/mini.doc))\n- Automated HTML documentation + self-publishing using [emmylua_doc_cli](https://github.com/CppCXY/emmylua-analyzer-rust/tree/main/crates/emmylua_doc_cli) \u0026 [mkdocs-material](https://github.com/squidfunk/mkdocs-material)\n  - Yes, this repository has a website! Check it out at [nvim-best-practices-plugin-template](https://colinkennedy.github.io/nvim-best-practices-plugin-template)!\n- Vimtags generation\n- Built-in Vim commands\n- A high quality command mode parser\n- Auto-completes your commands at any cursor position\n- No external dependencies[\\*](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/wiki/External-Dependencies-Disclaimer)\n- [LuaCATS](https://luals.github.io/wiki/annotations/) annotations and type-hints, everywhere\n- [RSS feed support](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/commits/main/doc/news.txt.atom)\n- Built-in logging to stdout / files\n- Unittests use the full power of native [busted](https://github.com/lunarmodules/busted)\n  - Supports [LuaCov](https://luarocks.org/modules/mpeterv/luacov) for coverage reports!\n- Automated testing matrix supports 12 Neovim/OS combinations\n  - neovim: `[v0.10.0, v0.11.0, stable, nightly]`\n  - os: `[ubuntu-latest, macos-latest, windows-latest]`\n- 100% Lua\n- Uses [Semantic Versioning](https://semver.org)\n- Integrations\n  - [lualine.nvim](https://github.com/nvim-lualine/lualine.nvim)\n  - [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)\n  - [`:checkhealth`](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/actions/workflows/checkhealth.yml)\n- Github actions for:\n  - [StyLua](https://github.com/JohnnyMorganz/StyLua) - Auto-formats Lua code\n  - [llscheck](https://github.com/jeffzi/llscheck) - Checks for Lua type mismatches\n  - [luacheck](https://github.com/mpeterv/luacheck) - Checks for Lua code issues\n  - [luarocks](https://luarocks.org) auto-release ([LUAROCKS_API_KEY secret](https://github.com/nvim-neorocks/sample-luarocks-plugin?tab=readme-ov-file#publishing-to-luarocks) configuration required)\n  - [GitHub](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/releases) auto-release ([PERSONAL_ACCESS_TOKEN secret](https://github.com/nvim-neorocks/sample-luarocks-plugin?tab=readme-ov-file#installing-release-please-recommended) configuration required)\n  - [mdformat](https://github.com/hukkin/mdformat) - Auto-formats project Markdown files\n  - [mini.doc](https://github.com/echasnovski/mini.doc) - API documentation auto-generator\n  - [panvimdoc](https://github.com/kdheepak/panvimdoc) - User documentation auto-generator\n  - [emmylua_doc_cli](https://github.com/CppCXY/emmylua-analyzer-rust/tree/main/crates/emmylua_doc_cli) \u0026 [mkdocs-material](https://github.com/squidfunk/mkdocs-material) - Generate HTML from Lua files automatically\n  - [urlchecker](https://github.com/urlstechie/urlchecker-action) - Checks for broken URL links\n  - PR reviews - Reminds users to update `doc/news.txt`\n\n# Using This Template\n\n1. Follow the [Wiki instructions](https://github.com/ColinKennedy/nvim-best-practices-plugin-template/wiki/Using-This-Template)\n1. Run `make download-dependencies` so all the Lua LSP features work as expected.\n1. Once you're done, remove this section (the rest of this README.md file should be kept / customized to your needs)\n\n# Installation\n\n\u003c!-- TODO: (you) - Adjust and add your dependencies as needed here --\u003e\n\n- [lazy.nvim](https://github.com/folke/lazy.nvim)\n\n```lua\n{\n    \"ColinKennedy/nvim-best-practices-plugin-template\",\n    dependencies = { \"ColinKennedy/mega.cmdparse\", \"ColinKennedy/mega.logging\" },\n    -- TODO: (you) - Make sure your first release matches v1.0.0 so it auto-releases!\n    version = \"v1.*\",\n}\n```\n\n# Configuration\n\n(These are default values)\n\n\u003c!-- TODO: (you) - Remove / Add / Adjust your configuration here --\u003e\n\n- [lazy.nvim](https://github.com/folke/lazy.nvim)\n\n```lua\n{\n    \"ColinKennedy/nvim-best-practices-plugin-template\",\n    config = function()\n        vim.g.plugin_template_configuration = {\n            commands = {\n                goodnight_moon = { read = { phrase = \"A good book\" } },\n                hello_world = {\n                    say = { [\"repeat\"] = 1, style = \"lowercase\" },\n                },\n            },\n            logging = {\n                level = \"info\",\n                use_console = false,\n                use_file = false,\n            },\n            tools = {\n                lualine = {\n                    arbitrary_thing = {\n                        color = \"Visual\",\n                        text = \" Arbitrary Thing\",\n                    },\n                    copy_logs = {\n                        color = \"Comment\",\n                        text = \"󰈔 Copy Logs\",\n                    },\n                    goodnight_moon = {\n                        color = \"Question\",\n                        text = \" Goodnight moon\",\n                    },\n                    hello_world = {\n                        color = \"Title\",\n                        text = \" Hello, World!\",\n                    },\n                },\n                telescope = {\n                    goodnight_moon = {\n                        { \"Foo Book\", \"Author A\" },\n                        { \"Bar Book Title\", \"John Doe\" },\n                        { \"Fizz Drink\", \"Some Name\" },\n                        { \"Buzz Bee\", \"Cool Person\" },\n                    },\n                    hello_world = { \"Hi there!\", \"Hello, Sailor!\", \"What's up, doc?\" },\n                },\n            },\n        }\n    end\n}\n```\n\n## Lualine\n\n\u003c!-- TODO: (you) - Remove this is you do not want lualine --\u003e\n\n\u003e Note: You can customize lualine colors here or using\n\u003e `vim.g.plugin_template_configuration`.\n\n[lualine.nvim](https://github.com/nvim-lualine/lualine.nvim)\n\n```lua\nrequire(\"lualine\").setup {\n    sections = {\n        lualine_y = {\n            -- ... Your other configuration ...\n            {\n                \"plugin_template\",\n                -- NOTE: These will override default values\n                -- display = {\n                --     goodnight_moon = {color={fg=\"#FFFFFF\"}, text=\"Custom message 1\"}},\n                --     hello_world = {color={fg=\"#333333\"}, text=\"Custom message 2\"},\n                -- },\n            },\n        }\n    }\n}\n```\n\n## Telescope\n\n\u003c!-- TODO: (you) - Remove this is you do not want telescope --\u003e\n\n\u003e Note: You can customize telescope colors here or using\n\u003e `vim.g.plugin_template_configuration`.\n\n[telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)\n\n```lua\n{\n    \"nvim-telescope/telescope.nvim\",\n    cmd = \"Telescope\",\n    config = function()\n        -- ... Your other configuration ...\n        require(\"telescope\").load_extension(\"plugin_template\")\n    end,\n    dependencies = {\n        \"ColinKennedy/nvim-best-practices-plugin-template\",\n        \"nvim-lua/plenary.nvim\",\n    },\n    version = \"0.1.*\",\n},\n```\n\n### Colors\n\nThis plugin provides two default highlights\n\n- `PluginTemplateTelescopeEntry`\n- `PluginTemplateTelescopeSecondary`\n\nBoth come with default colors that should look nice. If you want to change them, here's how:\n\n```lua\nvim.api.nvim_set_hl(0, \"PluginTemplateTelescopeEntry\", {link=\"Statement\"})\nvim.api.nvim_set_hl(0, \"PluginTemplateTelescopeSecondary\", {link=\"Question\"})\n```\n\n# Commands\n\nHere are some example commands:\n\n\u003c!-- TODO: (you) - You'll probably want to change all this or remove it. See --\u003e\n\n\u003c!-- plugin/plugin_template.lua for details. --\u003e\n\n```vim\n\" A typical subcommand\n:PluginTemplate hello-world say phrase \"Hello, World!\" \" How are you?\"\n:PluginTemplate hello-world say phrase \"Hello, World!\" --repeat=2 --style=lowercase\n\n\" An example of a flag this repeatable and 3 flags, -a, -b, -c, as one dash\n:PluginTemplate arbitrary-thing -vvv -abc -f\n\n\" Separate commands with completely separate, flexible APIs\n:PluginTemplate goodnight-moon count-sheep 42\n:PluginTemplate goodnight-moon read \"a book\"\n:PluginTemplate goodnight-moon sleep -z -z -z\n```\n\n# Tests\n\n## Initialization\n\nRun this line once before calling any `busted` command\n\n```sh\neval $(luarocks path --lua-version 5.1 --bin)\n```\n\n## Running\n\nRun all tests\n\n```sh\n# Using the package manager\nluarocks test --test-type busted\n# Or manually\nbusted .\n# Or with Make\nmake test\n```\n\nRun test based on tags\n\n```sh\nbusted . --tags=simple\n```\n\n# Coverage\n\nMaking sure that your plugin is well tested is important.\n`nvim-best-practices-plugin-template` can generate a per-line breakdown of exactly where\nyour code is lacking tests using [LuaCov](https://luarocks.org/modules/mpeterv/luacov).\n\n## Setup\n\nMake sure to install all dependencies for the unittests + coverage reporter if\nyou have not installed them already.\n\n```sh\nluarocks install busted --local\nluarocks install luacov --local\nluarocks install luacov-multiple --local\n```\n\n## Running\n\n```sh\nmake coverage-html\n```\n\nThis will generate a `luacov.stats.out` \u0026 `luacov_html/` directory.\n\n## Viewing\n\n```sh\n(cd luacov_html \u0026\u0026 python -m http.server)\n```\n\nIf it worked, you should see a message like\n`\"Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000) ...\"`\nOpen `http://0.0.0.0:8000` in a browser like\n[Firefox](https://www.mozilla.org/en-US/firefox) and you should see a view like this:\n\n![Image](https://github.com/user-attachments/assets/e5b30df8-036a-4886-81b9-affbf5c9e32a)\n\nJust navigate down a few folders until you get to a .lua file and you'll see a breakdown\nof your line coverage like this:\n\n![Image](https://github.com/user-attachments/assets/c5420b16-4be7-4177-92c7-01af0b418816)\n\n# Tracking Updates\n\nSee [doc/news.txt](doc/news.txt) for updates.\n\nYou can watch this plugin for changes by adding this URL to your RSS feed:\n\n```\nhttps://github.com/ColinKennedy/nvim-best-practices-plugin-template/commits/main/doc/news.txt.atom\n```\n\n# Other Plugins\n\nThis template is full of various features. But if your plugin is only meant to\nbe a simple plugin and you don't want the bells and whistles that this template\nprovides, consider instead using\n[nvim-plugin-template](https://github.com/ellisonleao/nvim-plugin-template)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolinkennedy%2Fnvim-best-practices-plugin-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolinkennedy%2Fnvim-best-practices-plugin-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolinkennedy%2Fnvim-best-practices-plugin-template/lists"}