Actions

init.lua registers one or more actions with waydir.register. Waydir stores the contribution metadata, then calls the matching action's run(ctx) function when the user invokes it.

Register an action

waydir.register({
  id = "to_webp",
  title = "Convert to WebP",
  menu = "context",
  icon = "file-image",
  when = { extensions = { "png", "jpg", "jpeg" }, min = 1 },
  shortcut = "ctrl+shift+w",
  run = function(ctx)
    for _, path in ipairs(ctx.paths) do
      waydir.run_task({
        title = "Convert " .. path,
        cmd = "cwebp",
        args = { path, "-o", path:gsub("%.%w+$", ".webp") },
      })
    end
  end,
})

Contribution fields

Field	Meaning
id	Action id inside this plugin. The full host id becomes plugin:<plugin-id>:<action-id>.
title	Label shown in menus, toolbar tooltip, and keybindings.
menu	context by default, or menubar, or toolbar.
where	For context actions: { "selection" }, { "background" }, or both.
group	Context submenu label. Actions sharing a group are nested together.
icon	Bundled .svg/.png path or a named builtin icon.
shortcut	Chord such as ctrl+alt+n, alt+f5, or shift+?.
settings	Optional user-editable settings schema.
when	Optional selection filter.
run	Function called when the action is invoked.

Invocation context

Field	Meaning
ctx.paths	Selected paths. Empty on background and toolbar actions.
ctx.count	Number of selected paths.
ctx.dir	Current folder.
ctx.plugin_dir	The plugin folder, useful for bundled scripts or assets.
ctx.settings	Schema defaults overlaid with saved user values.
ctx.form	Dialog results after a waydir.dialog round-trip.

when filters

Selection context actions are visible only when every supplied condition matches.

when = {
  types = { "file" },
  extensions = { "png", "jpg" },
  min = 1,
  max = 10,
  in_archive = false,
}

Field	Meaning
types	{ "file" }, { "folder" }, or both.
extensions	File extensions without a dot. Matching is lowercase. Folders do not match extension filters.
min	Minimum selected item count. Defaults to 1.
max	Maximum selected item count.
in_archive	Use false to hide inside archives or true to show only inside archives.

Omit when entirely to show the action for any non-empty selection.

Shortcut parsing

Supported modifier names:

• ctrl, control, cmd, command, meta, super
• shift
• alt, option

Supported keys include letters, digits, f1 through f12, arrows, space, enter, tab, escape, backspace, delete, home, end, pageup, pagedown, comma, period, and slash.

Waydir ignores plugin shortcuts that cannot be parsed, conflict with a built-in shortcut, or conflict with an earlier plugin shortcut.