xplr/docs/en/src/writing-plugins.md

Writing Plugins

Anyone who can write Lua code, can write xplr plugins.

Just follow the instructions and best practices:

Naming

xplr plugins are named using hiphen (-) separated words that may also include integers. They will be plugged using the require() function in Lua.

Structure

A minimal plugin should confirm to the following structure:

.
├── README.md
└── init.lua

You can also use this template.

README.md

This is where you document what the plugin does, how to use it, etc.

init.lua

This file is executed to load the plugin. It should expose a setup() function, which will be used by the users to setup the plugin.

Example:

local function setup(args)
  local xplr = xplr
  -- do stuff with xplr
end

return { setup = setup }

Publishing

When publishing plugins on GitHub or other repositories, it's a best practice to append .xplr to the name to make them distinguishable. Similar to the *.nvim naming convention for Neovim plugins.

Finally, after publishing, don't hesitate to let us know.

Examples

Visit Awesome Plugins for xplr plugin examples.

Also See

• Tip: A list of hacks yet to make it as Lua plugins
• Tip: Some UI and themeing tips
• Tip: A list of handy utility functions
• Tip: Share tips and tricks working with Lua
• Tutorial: Adding a New Mode
• Example: Using Environment Variables and Pipes
• Example: Using Lua Function Calls
• Example: Defining Custom Layout
• Example: Customizing Table Renderer
• Example: Render a custom dynamic table