Skip to content

Using This Template

Jump to bottom
Colin Kennedy edited this page Dec 23, 2024 · 11 revisions

To use this template to write a Neovim plugin, in short, you clone this template, remove what you don't want, set the GitHub repository settings to enable what you do want, and then you're ready to extend the template for your needs.

Clone This Template

Press Clone this template (Or use gh repo create nvim-best-practices-plugin-template -p ColinKennedy/nvim-best-practices-plugin-template)

Remove Unwanted Features

In general that means

  • Make sure the plugin/ directory implements the command(s) and mappings that you need
  • Remove plugin integrations if you don't want them:

Removing lualine.nvim

If you don't want a lualine.nvim status bar, run this:

git rm -rf lua/lualine
git rm spec/plugin_template/configuration_tools_lualine_spec.lua
git rm spec/plugin_template/lualine_spec.lua

Removing telescope.nvim

If you don't want telescope.nvim commands, run this:

git rm -rf lua/telescope
git rm spec/plugin_template/configuration_tools_telescope_spec.lua
git rm spec/plugin_template/telescope_spec.lua

Removing Renovate

Renovate is a useful GitHub opt-in feature for bumping your dependencies. It requires some extra setup (see Managing Dependencies ‐ Using Renovate). If you don't want it at all though, run this:

git rm renovate.json

Removing Built-In Commands

This plugin comes with example commands that you probably won't want, make sure to remove them.

git rm -rf lua/plugin_template/_commands

Removing Miscellaneous

The nvim-best-practices-plugin-template repository has its own CHANGELOG.md that are useful for communicating changes but you won't actually want. in your new repository. Remove it with the command below:

git rm CHANGELOG.md

Customize Your GitHub Repository

Some features require API keys for third-party services or repository write permission. For example:

Replace PluginTemplate With YourPlugin

There are several files that are named after this plugin and file contents that you'll want to change. The scripts can automate the process:

# Rename all files
git mv lua/plugin_template lua/your_plugin
git mv lua/telescope/_extensions/plugin_template lua/telescope/_extensions/your_plugin
git mv spec/plugin_template spec/your_plugin
find $PWD -type f | grep -v .git/ | grep -v .dependencies/ | xargs -I{} sh -c "rename --filename 's/nvim-best-practices-plugin-template/your-plugin.nvim/g ; s/plugin-template/your-plugin/ ; s/PluginTemplate/YourPlugin/ ; s/plugin_template/your_plugin/ ; s/ColinKennedy/YourUsername/' {}"

# Rename all file contents
find . -type f | grep -v .git/ | grep -v .dependencies/ | xargs sed -i 's/nvim-best-practices-plugin-template/your-plugin.nvim/g ; s/plugin-template/your-plugin/ ; s/PluginTemplate/YourPlugin/ ; s/plugin_template/your_plugin/ ; s/ColinKennedy/YourUsername/'

Replace TODO notes

We've left a number of TODO notes labeled TODO: (you) that you'll want to address.

The command below will auto-find all of these TODO notes and show them in Neovim's quickfix so you can quickly cycle through them all.

grep --recursive --line-number --word-regexp 'TODO: (you)' | nvim -q - -c "copen"

Extend Your New Plugin

At this point, you've completely made this template your own plugin. Congratulations! Now go forth and add new Vim commands, mappings, configuration, unittests, or whatever else you'd like to create.

Appendix

Releases

Releases - GitHub

To enable automatic uploads to GitHub, you must:

  1. Go to your repository's Settings page

  2. Go to Security -> Secrets and variables -> Actions

  1. Press the New repository secret button. Call it PERSONAL_ACCESS_TOKEN (in the screenshot below this has already been done)

To complete this last step, you need a Personal Access Token to paste into here

Generating A Personal Access Token

  1. Go to https://github.com/settings/profile
  2. Go all the way to the bottom of the left side bar where it says Developer settings
  1. Go to the left sidebar where it says Personal access tokens -> Tokens (classic
  1. Press Generate new token [menu] -> Generate new token (classic)
  1. Add "repo" scopes
  1. Press Generate token at the bottom and then copy the created token string. Paste it into your repository's personal access token secrets.

And you're done

Releases - LuaRocks

To enable automatic uploads to LuaRocks, you must:

  1. Create a LuaRocks API key
  2. Add the secret API key to your GitHub actions (see below) image
  3. Add a new git tag and push the tag to the default (main) branch.

Example:

git checkout main
git tag -a v1.2.3 -m "Added an important bug fix"
git push --tags

release.yml will then make a release for you.

Documentation

This template can auto-generate its own documentation and Vimtags. This is controlled by the documentation.yml file.

For this feature to work, the GitHub workflow must have write access to the repository. To enable it:

  • Click the Settings tab
  • (Under the "Code and automation" section) Press "Actions" > "General"
  • (In the new page) (Under "Workflow permissions") Press "Read and write permissions"

image

You can also disable this feature by removing documentation.yml.

Clone this wiki locally