🔌 Neovim plugin boilerplate

Plug and play Neovim plugin boilerplate with pre-configured CI, CD, linter, docs and tests.

⚡️ Features

• interactive setup script
• README.md template
• Perfect for open-source:
  • CODEOWNERS file for PR auto-assign
  • Issues and PR templates
• CD leveraging release-please-action
• CI:
  • Test running on multiple Neovim version
  • Lint check
  • Documentation generation check
  • Minimal run time, ideal for free plans
• Docs with mini.nvim doc plugin
• Tests with mini.nvim test plugin
  • Versioned testing with bob
• Linting with Stylua
• LuaLS checks on CI (inspired by lukas-reineke/ci-template.nvim)

📋 Installation

Note: This section is only required if you wish to use the linter provided by the template.

• Install Stylua linter
• Install bob neovim version manager

☄ Getting started

The following checklist is all your need to do to start writing your first plugin.

1 - Clone the template repository

via HTTPs

git clone https://github.com/shortcuts/neovim-plugin-boilerplate.git ~/my-awesome-plugin.nvim

via SSH

git clone [email protected]:shortcuts/neovim-plugin-boilerplate.git ~/my-awesome-plugin.nvim

via GH

gh repo create my-awesome-plugin --template shortcuts/neovim-plugin-boilerplate --public --clone

2 - Replace placeholder names with your plugin name

✨ Automatically

The setup script will rename files and placeholder names for you. Once done, you can remove anything setup related if you want to.

# interactive
make setup

# automated
USERNAME=my-github-username PLUGIN_NAME=my-awesome-plugin REPOSITORY_NAME=my-awesome-plugin.nvim make setup

✍️ Manually

Note: The placeholder names are purposely written with different casing. Make sure to keep it.

File names

rm -rf doc
mv plugin/your-plugin-name.lua plugin/my-awesome-plugin.lua
mv lua/your-plugin-name lua/my-awesome-plugin
mv README_TEMPLATE.md README.md 

Search and replace placeholder occurrences:

:vimgrep /YourPluginName/ **/*
:cfdo %s/YourPluginName/MyAwesomePlugin/g | update

:vimgrep /your-plugin-name/ **/* .github/**
:cfdo %s/your-plugin-name/my-awesome-plugin/g | update

:vimgrep /YOUR_GITHUB_USERNAME/ .github/** **/*.md
:cfdo %s/YOUR_GITHUB_USERNAME/shortcuts/g | update

:vimgrep /YOUR_REPOSITORY_NAME/ **/*.md
:cfdo %s/YOUR_REPOSITORY_NAME/my-awesome-plugin.nvim/g | update

3 - Code

You can now start writing your plugin, make sure the following commands work:

1. make deps to install docs/tests dependencies
2. make lint to format the code
3. make documentation to generate the documentation
4. make test to run the tests

Enjoy!

⌨ Contributing

PRs and issues are always welcome. Make sure to provide as much context as possible when opening one.