nvim-lua.kickstart.nvim/lua/custom/plugins/toggleterm_guide.md

ToggleTerm.nvim Guide: A Flexible Terminal Integration for Neovim

ToggleTerm is a highly customizable plugin for Neovim that provides enhanced terminal functionality, making it easy to toggle and use multiple terminals directly within your Neovim environment.

Features

• Multiple terminal instances with persistent state
• Different terminal layouts (floating, horizontal split, vertical split, tab)
• Custom terminal commands and automation
• Terminal toggling with a single keystroke
• Seamless integration with existing Neovim workflow
• Support for terminal-specific keymaps
• Custom commands for specific applications (like lazygit)

Quick Start Guide

Basic Usage

1. Toggle Default Terminal: Press <Ctrl-\> to show/hide the terminal
2. Exit Terminal Mode: Press <Esc> to switch from terminal mode to normal mode
3. Navigate Away: Use regular Neovim window commands (<Ctrl-w>h/j/k/l) when in normal mode

Terminal Layouts

Press these keys in normal mode:

• <leader>tf - Toggle floating terminal (appears in the center of your screen)
• <leader>th - Toggle horizontal terminal (split at bottom)
• <leader>tv - Toggle vertical terminal (split on right)
• <leader>tt - Toggle terminal in new tab

Multiple Terminal Instances

• <leader>t1 - Toggle terminal #1
• <leader>t2 - Toggle terminal #2
• <leader>t3 - Toggle terminal #3

You can have multiple terminal instances running different commands simultaneously.

Special Terminal Integrations

• <leader>lg - Toggle LazyGit in a floating window
• <leader>py - Toggle Python REPL in a horizontal split

Terminal Navigation and Control

When in a terminal buffer:

Keybinding	Action
<Esc>	Exit terminal mode and enter normal mode
<C-h>	Move focus to the window on the left
<C-j>	Move focus to the window below
<C-k>	Move focus to the window above
<C-l>	Move focus to the window on the right
<C-v>	Paste from clipboard in terminal mode

Advanced Usage

Creating Custom Terminal Commands

You can define custom terminals for specific commands in the configuration file. Here's an example:

-- Creating a custom terminal for a Node.js REPL
local node = Terminal:new({
  cmd = "node",
  direction = "horizontal",
  close_on_exit = false,
})

function _NODE_TOGGLE()
  node:toggle()
end

vim.keymap.set('n', '<leader>nd', '<cmd>lua _NODE_TOGGLE()<CR>', {noremap = true})

Running Commands in Terminal

You can run commands in a terminal directly from Neovim:

-- Example: Run npm commands
local npm_install = Terminal:new({
  cmd = "npm install",
  dir = "git_dir",
  direction = "float",
  close_on_exit = true,
  on_open = function(term)
    vim.cmd("startinsert!")
  end,
})

function _NPM_INSTALL()
  npm_install:toggle()
end

vim.keymap.set('n', '<leader>ni', '<cmd>lua _NPM_INSTALL()<CR>', {noremap = true})

Terminal-Specific Settings

For custom terminal settings:

local opts = {
  shell = '/bin/zsh', -- Set specific shell
  env = { ['VAR'] = 'VALUE' }, -- Set environment variables
  clear_env = false, -- Don't clear environment between terminals
}

require("toggleterm").setup(opts)

Troubleshooting Common Issues

Terminal Not Opening

• Ensure the keybinding (<Ctrl-\>) isn't overridden by another plugin
• Check if your terminal size settings are valid (they should be numbers or functions)

Terminal Looks Incorrect

• Try changing the border option in float_opts to another value
• Adjust the shading_factor if the terminal is too dark/light

Terminal Not Persisting History

• Check that persist_size is set to true
• Try setting close_on_exit = false to maintain session history

Customizing Your Terminal Experience

Changing The Default Terminal Layout

To change the default terminal appearance, modify the direction option:

direction = "horizontal", -- or "vertical", "float", "tab"

Customizing Terminal Appearance

float_opts = {
  border = "double", -- Try "single", "double", "curved", etc.
  width = 80, -- Fixed width for floating window
  height = 20, -- Fixed height for floating window
},

Customizing Terminal Behavior

start_in_insert = true, -- Start in insert mode
persist_mode = true, -- Remember if terminal was in insert mode
auto_scroll = true, -- Auto-scroll to bottom when entering terminal

Integration with Other Plugins

ToggleTerm works well with:

• lazygit: For Git operations (already configured in our setup)
• vim-test: Run tests in a terminal
• nnn: File manager in a terminal
• Any CLI tool: MySQL client, HTTP clients, etc.

Conclusion

With ToggleTerm.nvim, you can keep your workflow within Neovim while having powerful terminal functionality at your fingertips. The plugin is highly customizable, allowing you to tailor it precisely to your needs.

For more details and advanced configurations, visit the ToggleTerm GitHub page.