156 lines
6.1 KiB
Plaintext
156 lines
6.1 KiB
Plaintext
*slot.nvim.txt* Persistent Adaptive Terminal Dock
|
||
|
||
Author: newbie <https://github.com/newbie/slot.nvim>
|
||
License: MIT
|
||
|
||
|
||
==============================================================================
|
||
CONTENTS *slot-contents*
|
||
|
||
1. Introduction .............................. |slot-intro|
|
||
2. Installation .............................. |slot-install|
|
||
3. Configuration ............................. |slot-config|
|
||
4. Usage ..................................... |slot-usage|
|
||
5. API ....................................... |slot-api|
|
||
6. Layout Logic .............................. |slot-layout|
|
||
7. Keymaps ................................... |slot-keymaps|
|
||
|
||
==============================================================================
|
||
INTRODUCTION *slot-intro*
|
||
|
||
slot.nvim is a zero-dependency, persistent terminal dock for Neovim. It uses
|
||
Neovim's native `vim.fn.termopen()` — no external plugins required.
|
||
|
||
Think of it like expansion slots in a computer: each command (shell, reasonix,
|
||
lazygit, codex, btop, …) gets its own dedicated slot. Toggle a slot to bring
|
||
its terminal panel in/out of view; the process keeps running in the background.
|
||
|
||
Key features:
|
||
|
||
- **Persistent** — toggle hide/show, terminal process keeps running.
|
||
- **Adaptive split** — vertical vsplit on wide screens, horizontal split on
|
||
tall screens; based on the current window, not the tabpage.
|
||
- **Main window mode** — when no file is open, the terminal occupies the
|
||
current window directly instead of creating a split.
|
||
- **Dynamic commands** — add new tools with two lines of config; keymaps are
|
||
auto-registered from `commands` and `keymaps` tables.
|
||
- **Single file** — ~220 lines of Lua.
|
||
|
||
==============================================================================
|
||
INSTALLATION *slot-install*
|
||
|
||
Using lazy.nvim >~
|
||
{
|
||
'newbie/slot.nvim',
|
||
url = 'https://github.com/newbie/slot.nvim',
|
||
config = function()
|
||
require('slot').setup({})
|
||
end,
|
||
}
|
||
|
||
No dependencies required.
|
||
|
||
==============================================================================
|
||
CONFIGURATION *slot-config*
|
||
|
||
slot.setup({opts}) accepts the following options:
|
||
|
||
require('slot').setup({
|
||
size = {
|
||
horizontal = nil, -- terminal height in rows (nil = auto)
|
||
vertical = nil, -- terminal width in columns (nil = auto)
|
||
},
|
||
commands = {
|
||
reasonix = 'reasonix',
|
||
lazygit = 'lazygit',
|
||
-- key = command name, value = shell command or function
|
||
},
|
||
keymaps = {
|
||
shell = { 'n', '<c-t>' },
|
||
shell_i = { 'i', '<c-t>' },
|
||
reasonix = { 'n', '<C-i>' },
|
||
lazygit = { 'n', '<leader>gg' },
|
||
-- key = must match a key in `commands`, value = {mode, lhs}
|
||
},
|
||
debug = false, -- log layout decisions to :messages
|
||
})
|
||
|
||
`commands` values can be strings or functions (lazy evaluation).
|
||
|
||
If `keymaps` is empty or omitted, no keymaps are registered. You can bind
|
||
everything manually via the API.
|
||
|
||
==============================================================================
|
||
USAGE *slot-usage*
|
||
|
||
*slot.shell*
|
||
slot.shell()~
|
||
Open/close a persistent plain shell. Equivalent to `slot.open(nil)`.
|
||
|
||
*slot.open*
|
||
slot.open({cmd})~
|
||
Open/close a persistent terminal running the given command. Each unique
|
||
{cmd} gets its own cached terminal instance.
|
||
|
||
Examples: >
|
||
local S = require('slot')
|
||
S.shell()
|
||
S.open('reasonix')
|
||
S.open('lazygit')
|
||
S.open('btop')
|
||
S.open('yazi')
|
||
|
||
Inside any terminal, press <C-\><C-\> (Ctrl+\\ twice) to hide it.
|
||
The process keeps running in the background.
|
||
|
||
==============================================================================
|
||
API *slot-api*
|
||
|
||
slot.setup({opts}) *slot.setup*
|
||
Configure and register keymaps. Call once, typically in your plugin
|
||
manager's `config` function.
|
||
|
||
Parameters: ~
|
||
{opts} (table) Configuration table, see |slot-config|.
|
||
|
||
slot.shell() *slot.shell*
|
||
Toggle a plain shell terminal. Shortcut for `slot.open(nil)`.
|
||
|
||
slot.open({cmd}) *slot.open*
|
||
Toggle a persistent terminal for the given command.
|
||
|
||
Parameters: ~
|
||
{cmd} (string|nil) Shell command to run, or nil for default shell.
|
||
|
||
==============================================================================
|
||
LAYOUT LOGIC *slot-layout*
|
||
|
||
The layout is determined automatically based on the current window dimensions:
|
||
|
||
Condition Result
|
||
----------------------------------- -------------------------------
|
||
Empty unnamed buffer, not modified Main window (no split)
|
||
width ≥ 110 and width > height × 2 Right vsplit, 40% width
|
||
Otherwise Bottom split, 35% height (min 10)
|
||
|
||
Splits use `rightbelow`, meaning they open relative to the current window
|
||
without disrupting the rest of the tabpage layout.
|
||
|
||
Set `debug = true` to see layout decisions in `:messages`.
|
||
|
||
==============================================================================
|
||
KEYMAPS *slot-keymaps*
|
||
|
||
*slot-ctrl-backslash*
|
||
<C-\><C-\> (terminal mode)~
|
||
Hide the current terminal. Bound automatically in every slot terminal
|
||
buffer. Does not affect TUI programs that use Ctrl+\ for other purposes.
|
||
|
||
Custom keymaps are defined in the `keymaps` table passed to |slot.setup|.
|
||
Each entry is {mode, lhs}. Key names must match entries in `commands`.
|
||
|
||
The `shell` and `shell_i` keys are special and are not driven by `commands`.
|
||
|
||
==============================================================================
|
||
vim:tw=78:ts=8:ft=help:norl:
|