Repository Structure

This page explains the directory / file structure of nvim-best-practices-plugin-template

Overview

• lua/lualine is lualine.nvim integration
• lua/plugin_template/_cli is for parsing :PluginTemplate ... and handles auto-complete
  • In the future this might get moved to a separate Lua package and "vendored" instead
• lua/plugin_template/_commands all command / subcommand logic goes here
• lua/plugin_template/_core is extra files for better code re-use
• lua/plugin_template/_vendors is third-party FOSS stuff that was added to aid plugin-template
• lua/plugin_template/health.lua integrates the :checkhealth command
• lua/telescope is telescope.nvim integration
• spec/minimal_init.lua is a helper file that sets up our unittests

Commands

This template provides a standard command, :PluginTemplate. It also has subcommands such as :PluginTemplate hello-world, :PluginTemplate goodnight-moon, :PluginTemplate copy-logs, etc.

All Vim commands / subcommands are defined in plugin/plugin_template.lua

When a subcommand runs, we need to:

1. parse the user's text input
2. find the subcommand that they want to call
3. run the Lua function that's linked to that subcommand

lua/plugin_template/_cli/runner.lua covers 2 and 3

Each subcommand has a standard directory like this:

• lua/_commands/{subcommand}/runner.lua
• lua/_commands/{subcommand}/command.lua
• lua/_commands/{subcommand}/complete.lua

or

• lua/_commands/{subcommand}/{sub-subcommand}/runner.lua
• lua/_commands/{subcommand}/{sub-subcommand}/command.lua
• lua/_commands/{subcommand}/{sub-subcommand}/complete.lua

command.lua converts raw user text arguments from Vim's COMMAND mode and converts it to data that the subcommand can understand. Once that is done, runner.lua is called. Not all subcommands have auto-complete enabled but if they do, we add a complete.lua for that.

Examples:

A subcommand with sub-subcommands. e.g. :PluginTemplate hello-world say phrase "Hi!"

• lua/plugin_template/_commands/hello_world/say/command.lua
• lua/plugin_template/_commands/hello_world/say/runner.lua

A subcommand with no sub-subcommands. e.g. :PluginTemplate copy-logs

• lua/plugin_template/_commands/copy_logs/command.lua
• lua/plugin_template/_commands/copy_logs/runner.lua