Neovim Plugin Template

A template for creating Neovim plugins with best practices and standardized structure

Features • Requirements • Installation • Usage • Configuration • Development • Contributing • License • Discussions

Overview

This repository provides a template for creating Neovim plugins with a standardized structure and best practices. It includes:

• Complete plugin structure with entry points
• Documentation templates
• Test framework setup
• Code quality tools integration
• GitHub workflows for CI/CD
• Community health files

Features

• 📋 Complete Structure - All necessary files and directories for a Neovim plugin
• 📚 Documentation - Templates for help docs and README
• 🧪 Testing - Plenary-based test setup with minimal configuration
• ✨ Code Quality - StyLua and Luacheck configuration
• 🔄 CI/CD - GitHub Actions workflows for testing, linting and releases
• 👥 Community - Templates for issues, PRs, and contributing guidelines

Requirements

• Neovim >= 0.8.0
• Git for version control
• (Optional) StyLua for code formatting
• (Optional) Luacheck for static analysis

Installation

Creating a New Plugin

1. Use this template to create a new repository:

   git clone https://github.com/greggh/neovim-plugin-template.git my-awesome-plugin
   cd my-awesome-plugin

2. Run the setup script to customize the template:

   ./scripts/setup.sh

3. Update the documentation files with your plugin-specific information

Installing the Plugin (For Users)

Using lazy.nvim:

{
  "greggh/plugin-name",
  dependencies = {
    -- Add dependencies here
  },
  config = function()
    require("plugin-name").setup({
      -- Your configuration
    })
  end
}

Using packer.nvim:

use {
  'greggh/plugin-name',
  requires = {
    -- Add dependencies here
  },
  config = function()
    require('plugin-name').setup({
      -- Your configuration
    })
  end
}

Using vim-plug:

Plug 'greggh/plugin-name'

" In your init.vim after plug#end():
lua require('plugin-name').setup({})

Usage

After installation, you can use the plugin with the following commands:

:PluginNameCommand    " Execute the plugin's main function
:PluginNameToggle     " Toggle the plugin on/off

Key mappings (if using which-key):

• <leader>pf - Execute the plugin's main function
• <leader>pt - Toggle the plugin on/off

Configuration

Default configuration:

require("plugin-name").setup({
  enabled = true,
  debug = false,
  -- Add other options here
})

Option	Type	Default	Description
enabled	boolean	true	Enable/disable plugin
debug	boolean	false	Enable debug logging

Development

Setting Up Development Environment

1. Clone the repository:

   git clone https://github.com/username/plugin-name.git
   cd plugin-name

2. Install development dependencies:

   • Neovim 0.8+
   • Luacheck for linting
   • StyLua for formatting

3. Set up pre-commit hooks (important first step!):

   ./scripts/setup-hooks.sh

   This will enable automatic formatting, linting, and testing before each commit. Make sure to run this before making any changes to ensure code quality.

Directory Structure

.
├── lua/
│   └── plugin-name/      # Plugin code
│       └── init.lua      # Main entry point
├── plugin/
│   └── plugin-name.lua   # Plugin load script
├── doc/
│   └── plugin-name.txt   # Help documentation
├── tests/
│   ├── minimal-init.lua  # Minimal config for testing
│   └── spec/             # Test specifications
│       └── plugin_spec.lua
├── .github/              # GitHub specific files
├── .githooks/            # Git hooks for development
├── scripts/              # Development scripts
├── .stylua.toml          # StyLua configuration
├── .luacheckrc           # Luacheck configuration
└── README.md             # This file

Testing

Before making changes, ensure your development environment is set up with pre-commit hooks:

./scripts/setup-hooks.sh

Run tests with:

make test

Or manually:

nvim --headless -u tests/minimal-init.lua -c "lua require('plenary.test_harness').test_directory('tests/spec')"

Code Quality

Format code with StyLua:

stylua .

Lint code with Luacheck:

luacheck .

Both tools are integrated with the pre-commit hooks when using hooks-util.

Contributing

Contributions are welcome! Here's how to contribute to this template:

1. Fork the repository
2. Create a feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request

Please make sure to:

• Follow the coding style (run StyLua)
• Add tests for new features
• Update documentation as needed

License

This template is released under the MIT License. See the LICENSE file for details.

Acknowledgements

• Neovim - The core editor
• lazy.nvim - Plugin manager
• plenary.nvim - Testing framework
• StyLua - Lua formatter
• Luacheck - Lua linter
• hooks-util - Git hooks framework

Discussions

Have questions or ideas? Join the conversation in GitHub Discussions.

• Questions: For help with using or developing the plugin
• Ideas: Suggest new features or improvements
• Show and Tell: Share how you're using this plugin
• General: For any other topics related to this plugin

---

Made with ❤️ by greggh