diff --git a/.config/nvim/lua/config/autocmds.lua b/.config/nvim/lua/config/autocmds.lua index 8266a1d..036c9d5 100644 --- a/.config/nvim/lua/config/autocmds.lua +++ b/.config/nvim/lua/config/autocmds.lua @@ -95,6 +95,10 @@ vim.api.nvim_create_autocmd("FileType", { end, { desc = "Toggle render-markdown on an RMarkdown file" } ) + vim.keymap.set({ + "n", + "i", + }, "`", "i```{r}```O", { desc = "New fenced RMarkdown code block" }) end, }) diff --git a/.config/nvim/lua/config/keymaps.lua b/.config/nvim/lua/config/keymaps.lua index d74743e..26dfa07 100644 --- a/.config/nvim/lua/config/keymaps.lua +++ b/.config/nvim/lua/config/keymaps.lua @@ -16,7 +16,6 @@ vim.keymap.set("t", "", "") -- Fix in terminal buffer vim.keymap.set("n", "H", ":set hlsearch!", { desc = "Toggle search highlight" }) vim.keymap.set("n", "W", ":%s/\\s\\+$//:let @/=''", { desc = "Clean trailing whitespace" }) vim.keymap.set({ "n", "i" }, "R", ":syntax sync fromstart", { desc = "Refresh syntax highlighting" }) -vim.keymap.set({ "n", "i" }, "`", "i```{r}```O", { desc = "New fenced RMarkdown code block" }) vim.keymap.set( { "n", "i" }, "ts", diff --git a/.config/nvim/lua/config/options.lua b/.config/nvim/lua/config/options.lua index 5fbaf95..1da1c17 100644 --- a/.config/nvim/lua/config/options.lua +++ b/.config/nvim/lua/config/options.lua @@ -38,11 +38,11 @@ vim.opt.wildmenu = true -- Make tab completion for files/buffers act like bash vim.opt.wildmode="list:full" -- Show a list when pressing tab; complete first full match vim.opt.wildignore:append("*.swp,*.bak,*.pyc,*.class") -- Ignore these when autocompleting vim.opt.cursorline = true -- Highlight line where the cursor is -vim.opt.fillchars:append { diff = "╱" } -- in diffs, show deleted lines with slashes rather than dashes +vim.opt.fillchars:append { diff = "·" } -- in diffs, show deleted lines with dots rather than dashes vim.opt.signcolumn = "yes" -- always show the signcolumn to minimize distraction of appearing and disappearing --- vim.cmd(":autocmd InsertEnter * set cul") -- Color the current line in upon entering insert mode --- vim.cmd(":autocmd InsertLeave * set nocul") -- Remove color upon existing insert mode +-- vim.cmd(":autocmd InsertEnter * set nocul") -- Remove color when entering insert mode +-- vim.cmd(":autocmd InsertLeave * set cul") -- Turn color back on when exiting insert mode -- vim.cmd("set guicursor=i:block") -- Always use block cursor. In some terminals and fonts (like iTerm), it can be hard to see the cursor when it changes to a line. -- Copy all yanked/deleted lines to the "+" buffer. Useful when you want to use diff --git a/.config/nvim/lua/plugins/beacon.lua b/.config/nvim/lua/plugins/beacon.lua index 274ebee..0383e6a 100644 --- a/.config/nvim/lua/plugins/beacon.lua +++ b/.config/nvim/lua/plugins/beacon.lua @@ -15,7 +15,6 @@ return { end, keys = { - { "", ":Beacon", desc = "Flash beacon" }, { "N", "N:Beacon", desc = "Prev search hit and flash beacon" }, { "n", "n:Beacon", desc = "Next search hit and flash beacon" }, { "%", "%:Beacon", desc = "Go to matching bracket and flash beacon" }, diff --git a/.config/nvim/lua/plugins/blink.lua b/.config/nvim/lua/plugins/blink.lua new file mode 100644 index 0000000..3f702a7 --- /dev/null +++ b/.config/nvim/lua/plugins/blink.lua @@ -0,0 +1,76 @@ +-- blink.cmp provides autocompletion + +-- Used below to detect if we're in a word or not +local has_words_before = function() + local col = vim.api.nvim_win_get_cursor(0)[2] + if col == 0 then + return false + end + local line = vim.api.nvim_get_current_line() + return line:sub(col, col):match("%s") == nil +end +return { + "saghen/blink.cmp", + dependencies = { + "rafamadriz/friendly-snippets", + 'Kaiser-Yang/blink-cmp-dictionary', + dependencies = { 'nvim-lua/plenary.nvim' } + }, + + -- using a release tag downloads pre-built binaries + version = "v1.*", + + opts = { + keymap = { + -- At any time, to show menu, arrows to select, Enter to accept. + preset = 'default', + + -- Additionally, this configures tab-completion to mimic what happens in bash: + -- * Tab shows selections if cursor is in or immediately after a word, and immediately fills in the first item + -- * Enter to select. + -- * Tab scrolls thru suggestions (or Shift-Tab to go back) + -- + [''] = { + function(cmp) + if has_words_before() then + return cmp.show_and_insert() + end + end, + 'snippet_forward', + 'select_next', + 'fallback', + }, + -- Navigate to the previous suggestion or cancel completion if currently on the first one. + [''] = { 'snippet_backward', 'insert_prev' }, + [''] = { 'accept', 'fallback' }, + }, + sources = { + default = function() + local result = { 'lsp', 'path', 'snippets', 'buffer' } + + -- turn on dictionary completion in non-code files + if vim.tbl_contains({ 'markdown', 'text', 'rst' }, vim.bo.filetype) then + table.insert(result, 'dictionary') + end + return result + end, + providers = { + dictionary = { + module = 'blink-cmp-dictionary', + name = 'Dict', + min_keyword_length = 3, + opts = { + -- This is the location of the word list on macOS and many Linux distributions + dictionary_files = { '/usr/share/dict/words' } + } + } + }, + }, + fuzzy = { implementation = "prefer_rust_with_warning" }, + completion = { + menu = { auto_show = false }, + trigger = { show_in_snippet = false }, + }, + }, + opts_extend = { "sources.default" }, +} diff --git a/.config/nvim/lua/plugins/browsher.lua b/.config/nvim/lua/plugins/browsher.lua index e8afba2..b1d287d 100644 --- a/.config/nvim/lua/plugins/browsher.lua +++ b/.config/nvim/lua/plugins/browsher.lua @@ -1,3 +1,4 @@ +-- browsher will copy a link to github/gitlab based on where you are in the code return { 'claydugo/browsher.nvim', event = "VeryLazy", diff --git a/.config/nvim/lua/plugins/zenburn.lua b/.config/nvim/lua/plugins/colorschemes.lua similarity index 87% rename from .config/nvim/lua/plugins/zenburn.lua rename to .config/nvim/lua/plugins/colorschemes.lua index 06bf1d2..e0f15d4 100644 --- a/.config/nvim/lua/plugins/zenburn.lua +++ b/.config/nvim/lua/plugins/colorschemes.lua @@ -24,4 +24,5 @@ return { lazy = false, priority = 1000, }, + { "daler/zenfade", dependencies = { "rktjmp/lush.nvim" }, lazy = false, priority = 1000 }, } diff --git a/.config/nvim/lua/plugins/conform.lua b/.config/nvim/lua/plugins/conform.lua index 2073f46..c40223c 100644 --- a/.config/nvim/lua/plugins/conform.lua +++ b/.config/nvim/lua/plugins/conform.lua @@ -18,9 +18,8 @@ return { formatters_by_ft = { lua = { "stylua" }, python = { "isort", "black" }, - javascript = { { "prettierd", "prettier" } }, - bash = { { "shfmt" } }, - sh = { { "shfmt" } }, + bash = { "shfmt" }, + sh = { "shfmt" }, }, formatters = { shfmt = { diff --git a/.config/nvim/lua/plugins/indent-o-matic.lua b/.config/nvim/lua/plugins/indent-o-matic.lua new file mode 100644 index 0000000..680167d --- /dev/null +++ b/.config/nvim/lua/plugins/indent-o-matic.lua @@ -0,0 +1,4 @@ +-- indent-o-matic provides automatic detection of indentation settings +return { + 'Darazaki/indent-o-matic' +} diff --git a/.config/nvim/lua/plugins/lush.lua b/.config/nvim/lua/plugins/lush.lua new file mode 100644 index 0000000..d46be4a --- /dev/null +++ b/.config/nvim/lua/plugins/lush.lua @@ -0,0 +1,6 @@ +-- lush is used for colormaps and designing/modifying colormaps +return { + priority=1000, + lazy=false, + "rktjmp/lush.nvim", +} diff --git a/.config/nvim/lua/plugins/nightfox.lua b/.config/nvim/lua/plugins/nightfox.lua deleted file mode 100644 index 6a9eae9..0000000 --- a/.config/nvim/lua/plugins/nightfox.lua +++ /dev/null @@ -1,11 +0,0 @@ --- nightfox is a family of colorschemes (nightfox, dawnfox, terrafox, etc) -return { - { - "EdenEast/nightfox.nvim", - lazy = false, - priority = 1000, - opts = { - styles = { comments = "italic" }, - }, - }, -} diff --git a/.config/nvim/lua/plugins/nvim-cmp.lua b/.config/nvim/lua/plugins/nvim-cmp.lua deleted file mode 100644 index 567ecf7..0000000 --- a/.config/nvim/lua/plugins/nvim-cmp.lua +++ /dev/null @@ -1,70 +0,0 @@ --- nvim-cmp provides tab completion for many things -return { - { - "hrsh7th/nvim-cmp", - dependencies = { - "hrsh7th/cmp-nvim-lsp", - "hrsh7th/cmp-buffer", - "hrsh7th/cmp-path", - "saadparwaiz1/cmp_luasnip", - "L3MON4D3/LuaSnip", - }, - event = "InsertEnter", - opts = function() - local has_words_before = function() - unpack = unpack or table.unpack - local line, col = unpack(vim.api.nvim_win_get_cursor(0)) - return col ~= 0 and vim.api.nvim_buf_get_lines(0, line - 1, line, true)[1]:sub(col, col):match("%s") == nil - end - - local cmp = require("cmp") - local defaults = require("cmp.config.default")() - local luasnip = require("luasnip") - return { - completion = { autocomplete = false }, - snippet = { - expand = function(args) - require("luasnip").lsp_expand(args.body) - end, - }, - mapping = cmp.mapping.preset.insert({ - [""] = cmp.mapping.abort(), - [""] = cmp.mapping.confirm({ select = false }), - [""] = cmp.mapping(function(fallback) - if cmp.visible() then - cmp.select_next_item() - elseif luasnip.jumpable(1) then - luasnip.jump(1) - elseif has_words_before() then - cmp.complete() - else - fallback() - end - end, { "i", "s" }), - [""] = cmp.mapping(function(fallback) - if cmp.visible() then - cmp.select_prev_item() - elseif luasnip.jumpable(-1) then - luasnip.jump(-1) - else - fallback() - end - end, { "i", "s" }), - }), - sources = cmp.config.sources({ - { name = "nvim_lsp" }, - { name = "luasnip" }, - { name = "buffer" }, - { name = "path" }, - { name = "mkdnflow" }, - }), - experimental = { - ghost_text = { - hl_group = "CmpGhostText", - }, - }, - sorting = defaults.sorting, - } - end, - }, -} diff --git a/.config/nvim/lua/plugins/render-markdown.lua b/.config/nvim/lua/plugins/render-markdown.lua index 958497d..f2494d7 100644 --- a/.config/nvim/lua/plugins/render-markdown.lua +++ b/.config/nvim/lua/plugins/render-markdown.lua @@ -30,6 +30,9 @@ return { internal = { pattern = ".*", icon = "⛬ ", highlight = "RenderMarkdownLink" }, }, }, + checkbox = { + checked = { icon = "✓" } + } }, }, } diff --git a/.config/nvim/lua/plugins/treesj.lua b/.config/nvim/lua/plugins/treesj.lua new file mode 100644 index 0000000..ec2a720 --- /dev/null +++ b/.config/nvim/lua/plugins/treesj.lua @@ -0,0 +1,12 @@ +-- treesj splits and joins nodes +return { + 'Wansmer/treesj', + lazy = false, + dependencies = { 'nvim-treesitter/nvim-treesitter' }, + config = function() + require('treesj').setup({ + use_default_keymaps = false, + }) + vim.keymap.set('n', 'j', require('treesj').toggle, { desc = "Toggle split/join nodes" }) + end, +} diff --git a/.config/nvim/lua/plugins/vim-sleuth.lua b/.config/nvim/lua/plugins/vim-sleuth.lua deleted file mode 100644 index 4ee48c5..0000000 --- a/.config/nvim/lua/plugins/vim-sleuth.lua +++ /dev/null @@ -1,4 +0,0 @@ --- vim-sleuth autodetects indentation settings -return { - { "tpope/vim-sleuth" }, -} diff --git a/Dockerfile b/Dockerfile index a177ab5..9c5ba2f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -96,13 +96,13 @@ RUN ./setup.sh --install-npm # Additional for this container: asciinema for screen casts RUN source ~/.bashrc \ && ca \ - && mamba create -y -n asciinema asciinema \ + && conda create -y -n asciinema asciinema \ && ln -s $(conda info --base)/envs/asciinema/bin/asciinema ~/opt/bin # imagemagick for converting gifs RUN source ~/.bashrc \ && ca \ - && mamba create -y -n imagemagick imagemagick \ + && conda create -y -n imagemagick imagemagick \ && ln -s $(conda info --base)/envs/imagemagick/bin/convert ~/opt/bin # Install fonts for use by agg diff --git a/docs/_static/plugin_metadata.css b/docs/_static/plugin_metadata.css new file mode 100644 index 0000000..bd965b7 --- /dev/null +++ b/docs/_static/plugin_metadata.css @@ -0,0 +1,50 @@ +/* Styling for plugin metadata */ +.plugin-metadata { + background-color: #f5f5f5; + border-left: 3px solid #ccc; + padding: 10px; + margin-bottom: 15px; + font-size: 0.9em; +} + +/* Style for commit hashes */ +.plugin-metadata code, .plugin-metadata tt { + background-color: #f0f0f0; + border: 1px solid #ddd; + padding: 0 3px; + font-size: 0.9em; + border-radius: 3px; + color: #666; + font-weight: bold; +} + +/* Style for commit messages */ +.plugin-metadata em { + font-style: italic; + color: #444; +} + +/* Style for the changes list */ +.plugin-metadata ul { + margin-left: 20px; + padding-left: 0; +} + +.plugin-metadata li { + margin-bottom: 4px; +} + +/* Style for definition lists */ +.plugin-metadata dl { + margin-bottom: 10px; +} + +.plugin-metadata dt { + font-weight: bold; + color: #666; +} + +.plugin-metadata dd { + margin-left: 20px; + margin-bottom: 5px; +} diff --git a/docs/changelog.rst b/docs/changelog.rst index 3492bce..846b994 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,6 +1,44 @@ Changelog ========= +2025-08-14 +---------- + +**vim** + +- Replace vim-sleuth with indent-o-matic for better indentation detection +- Replace nvim-cmp with blink.cmp for autocompletion (about the same features but with simplified config) +- Update checkbox rendering in markdown files +- Add zenfade colorscheme (not enabled by default) +- Nicer diff deletion symbol +- Add lush plugin +- Add treesj plugin +- Bump installed nvim version to 0.10.4 + +**setup** + +- conda installation dir can be configured via env var ``CONDA_INSTALLATION_DIR`` +- dockerfile uses conda rather than mamba for testing + +**docs** + +Nvim documentation overhaul. This now includes a new sphinx extension which +inspects the git history to create a changelog of a plugin. This looks for the +plugin name in filenames, commit messages, and changed text in an attempt to be +more transparent about changes over time. + +The updates also include splitting the vim plugins from the main vim docs and +rewriting some supporting docs for vim. + +2025-05-16 +---------- + +**setup** + +``--dotfiles`` now properly handles backups of existing files, using a manual +copy approach rather than rsync (thanks @mitraak) + + 2025-05-07 ---------- @@ -15,8 +53,8 @@ Changelog - The previous changes (2024-11-19) for better Python code pasting did not work on all systems. IPython would sometimes have a lag using ``%cpaste``. So this - time, we use `bracketed paste - `__ when pasting into a running terminal. This seems to have better behavior + time, we use `bracketed paste `__ + when pasting into a running terminal. This seems to have better behavior in general (including R) by reducing the noise of pasted lines. - new plugin, `browsher`, to construct a URL for github/gitlab that highlights diff --git a/docs/conf.py b/docs/conf.py index d8e39fd..658a7fd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,7 +31,8 @@ sys.path.insert(0, ".") extensions = [ "sphinx.ext.autosectionlabel", - "details_ext" + "details_ext", + "plugin_metadata_ext" ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/index.rst b/docs/index.rst index 8b24d8d..84d9ecb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,6 +43,7 @@ Ready? :ref:`starthere`! tools bash vim + nvim-plugins tmux conda post diff --git a/docs/nvim-lua.rst b/docs/nvim-lua.rst index 51d1960..18843e3 100644 --- a/docs/nvim-lua.rst +++ b/docs/nvim-lua.rst @@ -24,37 +24,18 @@ config you don't know what's going on! **TL;DR: to try out the new version** -First, back up your existing config. - -.. code-block:: bash - - # Back up old files - mv ~/.config/nvim ~/.config/nvim-backup - mv ~/.vimrc ~/.vimrc-backup - mv ~/.vim ~/.vim-backup - -Then manually copy the relevant files from this repo (that is, don't use the -``--dotfiles`` argument to :file:`setup.sh` since that will copy over more than -just these): - .. code-block:: bash - # here we refer to the dotfiles repo dir; - # modify accordingly for where you put it. - cp -r dotfiles/.config/nvim ~/.config/nvim - cp dotfiles/.vimrc ~/.vimrc - -Then open up nvim, and wait for the installations to complete. You should be -good to go. + ./setup.sh --nvim-test-drive Here are some initial things to try: -- :kbd:`` (by default, :kbd:`,`) and then wait a second. You'll get - a menu that pops up, showing you the currently-configured key mappings that - follow . Hitting a listed key will execute the command. Sometimes - you'll see ``-> +prefix`` in the menu, which means you can hit that key to see - a menu of the things you can type after that. If you go too far, use - :kbd:`` to go back a step. +- Press :kbd:`` (by default, :kbd:`,`) . . . and then wait a second. You'll get + a menu that pops up at the bottom of the window, showing you the + currently-configured key mappings that follow . Hitting a listed key + will execute the command. Sometimes you'll see ``-> +prefix`` in the menu, + which means you can hit that key to see a menu of the things you can type + after that. If you go too far, use :kbd:`` to go back a step. In fact, you can hit backspace a few times to get to the base vim commands. It can be helpful to look through to see if there's any you've forgotten about! @@ -64,58 +45,24 @@ Here are some initial things to try: - :kbd:`z=` over a word to get a pop-up for spelling suggestions -- Saner tab completion (hit tab until you like what you see). Snippets are - enabled, so if you're in a Python file for example, type ``def`` and then hit - :kbd:``. One of the options will be a snippet to create a Python - function. There are also other "flavors" of snippets, for example whether you - want to return from the function, o if you're writing method. Use - :kbd:`` to jump between the placeholders, and immediately start typing - to replace them. - -- :kbd:`KJ` (so, hold down shift and type ``kj``) to flash a beacon - where the cursor is. This also works when jumping between search hits. +- Saner tab completion (hit tab until you like what you see). - :kbd:`ff` to open a file selector within this directory - :kbd:`fg` to live-grep within the directory (hit enter on the search result to open the file at that location). Great for exploring new codebases. -- Open a file in a git repo with some changes. Then use :kbd:`]c` to go to the +- Open a file in a git repo with some changes. Then use :kbd:`]h` to go to the next change (hunk) and :kbd:`hp` to preview hunks. -- Open a file browser with :kbd:`fbo`, hit Enter to select, or :kbd:`-` +- Open a file browser with :kbd:`fb`, hit Enter to select, or :kbd:`` to go up a level - Open a Python file with lots of classes/functions, or a markdown or RMarkdown file. Use :kbd:`a` to open a panel for navigation within the file. - -Don't like it? Do this to revert: - -.. code-block:: - - # aaaaah! revert! revert! - mv ~/.config/nvim ~/.config/nvim-lua - mv ~/.config/nvim-backup ~/.config/nvim - rm ~/.vimrc - mv ~/.vimrc-backup ~/.vimrc - mv ~/.vim-backup ~/.vim - The rest of this page gives some more context so you can make your own changes. -Structure ---------- - -First, there's no more ``init.vim``. It's ``init.lua`` instead. - -There is an additional :file:`lua/plugins/init.lua` which holds plugin configuration. - -I had initially completely modularized things into separate settings, -autocommands, mappings, colorscheme, and plugins files. But after living with -that a bit, I decided to go back to a single main config with settings, -mappings, autocommands, and colorscheme, and only having a separate plugins -file. - Lua --- More info on Lua: @@ -126,7 +73,7 @@ More info on Lua: But for a quick intro, here are some of my notes: -- Any vim commands can be trivially converted to Lua by wrapping them in +- **Any vim commands can be trivially converted to Lua** by wrapping them in ``vim.cmd()``. See the `nvim docs on running Vim commands with Lua `_ for more info. @@ -190,6 +137,8 @@ things to load as well as the ability to update or clean up plugins. This is similar to ``:PlugInstall`` and ``:PlugClean`` from the previous versions of these dotfiles. +.. _creatingkeymappings: + Creating keymappings -------------------- @@ -226,9 +175,9 @@ needs to be in a table. When setting in a plugin config, it's not in a table. How to add/configure plugins ---------------------------- -Edit :file:`lua/plugins.lua`. - -Follow the existing plugin files for a guide, but basically you're aiming for +Follow the existing plugin files for a guide, but if you're adding a new +plugin, create a new file in :file:`lua/plugins` named after the plugin, and +follow the plugin author's instructions. Typically the new file will look something like this: .. code-block:: lua diff --git a/docs/nvim-plugins.rst b/docs/nvim-plugins.rst new file mode 100644 index 0000000..d5f92d7 --- /dev/null +++ b/docs/nvim-plugins.rst @@ -0,0 +1,1561 @@ +.. _plugins: + +Nvim plugins +============ + +Plugins are configured in :file:`lua/plugins/*.lua`. + +Plugins are configured using `lazy.nvim `_. +This supports lazy-loading of plugins to keep a snappy startup time, and only +load plugins when they're needed. See :ref:`nvim-lua` for my rationale on that. + +.. details:: Quick-reference on lazy.nvim + + Each plugin spec in :file:`lua/plugins/*.lua` is a table. The first property is + the name of the plugin. Other properties: + + * ``lazy``: only load when requested by something else. Saves on initial load + time, but use this with care since it can get confusing. + + * ``ft``: only load the plugin when editing this filetype. Implies lazy=true. + + * ``cmd``: only load the plugin when first running this command. Implies lazy=true. + + * ``keys``: only load the plugin when using these keymappings. Implies lazy=true. + + * ``config``: run this stuff after the plugin loads. If config = true, just run + the default setup for the plugin. + + * ``init``: similar to config, but used for pure-vim plugins + + If keys are specified, this is the only place they need to be mapped, and they + will make their way into the which-key menu even if they trigger a lazy-loaded + plugin. Use the ``desc`` argument to give which-key a description to use. + + .. note:: + + Don't like a plugin? Find it in :file:`lua/plugins/*.lua` and add ``enabled + = false`` next to where the plugin is named. For example: + + .. code-block:: lua + + { "user/plugin-name", enabled = false }, + + Or delete the file completely. + +.. details:: screencast of lazy.nvim setting up plugins + + .. image:: gifs/lazy_annotated.gif + +Because of how frequently nvim changes, each plugin section below has +a changelog. Since I have reorganized files over the years, the changelogs show +the *mention* of a plugin in a commit message, in a filename, or as part of the +changeset of a commit in an attempt to catch all of the changes. This may be +a little overzealous (for example the ``trouble`` plugin picks up commits +related to troubleshooting) but I've opted to err on the side of completeness. + +Plugin list +----------- + +I've organized the plugins into broad categories: + +.. contents:: Plugin list + :local: + :depth: 3 + +Git-related ++++++++++++ + +.. contents:: + :local: + +The following commands are built-in vim commands when in diff mode, but +are used heavily when working with git, so here is a reminder: + +.. _working-with-diffs: + + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`]c` + - Go to the next diff + + * - :kbd:`[c` + - Go to the previous diff + + * - :kbd:`do` + - Use the [o]ther file's contents for the current diff + + * - :kbd:`dp` + - [P]ut the contents of this diff into the other file + +.. _vimfugitive_ref: + +``vim-fugitive`` +~~~~~~~~~~~~~~~~ + +`vim-fugitive `_ provides a git interface in vim. + +Fugitive is wonderful for making incremental commits from within vim. This +makes it a terminal-only version of GUIs like git-cola, gitkraken, or GitHub +Desktop. + +I use it so much that I have a bash alias for starting this directly from the +command line: ``gsv`` (mnemonic: git status viewer). + + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - ``:Git`` + - Opens the main screen for fugitive (hint: use `vim -c ":Git"` from the + command line to jump right into it) + + * - ``:tab Git`` + - Opens the main screen for fugitive in a new tab, for fullscreen usage; + :kbd:`:q` to get back to what you were editing on before running it. + + * - :kbd:`=` + - Toggle visibility of changes + + * - :kbd:`-` (when over a filename) + - Stage or unstage the file + + * - :kbd:`-` (when in a chunk after using ``=``) + - Stage or unstage the chunk + + * - :kbd:`-` (in visual select mode (``V``)) + - Stage or unstage **just the selected lines**. Perfect for making + incremental commits. + + * - :kbd:`cc` + - Commit, opening up a separate buffer in which to write the commit + message + + * - :kbd:`dd` (when over a file) + - Open the file in diff mode (to better see intraline diffs) + +.. plugin-metadata:: + :name: vim-fugitive + +.. _diffview_ref: + +``diffview.nvim`` +~~~~~~~~~~~~~~~~~ + +`diffview.nvim `_ supports viewing +diffs across multiple files. It also has a nice interface for browsing previous +commits. I find this to be nicer for browsing git history when there are +multiple files per commit. + +I have a bash alias for starting this directly from the command line: ``glv`` +(mnemonic: git log viewer). + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - ``:DiffviewOpen`` + - Opens the viewer + + * - ``:DiffviewFileHistory`` + - View diffs for this file throughout git history + + +.. plugin-metadata:: + :name: diffview + + +.. _gitsigns_ref: + +``gitsigns`` +~~~~~~~~~~~~ + +`gitsigns `_ shows a "gutter" along +the left side of the line numbers, indicating where there were changes in +a file. Only works in git repos. + +Since you can stage and make commits with this plugin, it is in a way redundant +with vim-fugitive. I find fugitive to be more useful when making commits across +multiple files, and gitsigns to be more useful in showing what's changed while +still editing a file. + +Most commands require being in a hunk. Keymappings start with ``h``, mnemonic +is "hunk" (the term for a block of changes). + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`[h` + - Previous change + + * - :kbd:`]h` + - Next change + + * - :kbd:`hp` + - Preview hunk (shows floating window of the change, only works in a change) + + * - :kbd:`hs` + - Stage hunk (or stage lines in visual mode) + + * - :kbd:`hr` + - Reset hunk (or reset lines in visual mode) + + * - :kbd:`hu` + - Undo stage hunk + + * - :kbd:`hS` + - Stage buffer + + * - :kbd:`hR` + - Reset buffer + + * - :kbd:`hb` + - Blame line in floating window + + * - :kbd:`hd` + - Diff this file (opens diff mode) + + +Additionally, this supports hunks as text objects using ``ih`` (inside hunk). +E.g., select a hunk with :kbd:`vih`, or delete a hunk with :kbd:`dih`. + +.. plugin-metadata:: + :name: gitsigns + +.. _gv_ref: + +``gv`` +~~~~~~ + +`vim.gv `_ provides an interface to easily +view and browse git history. + +It's simpler than :ref:`diffview_ref` which can be helpful sometimes. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`:GV` in visual mode + - View commits affecting selection + + * - :kbd:`GV` + - Open a commit browser, hit :kbd:`Enter` on a commit to view + +.. plugin-metadata:: + :name: gv + + +.. _mergetool_ref: + +``vim-mergetool`` +~~~~~~~~~~~~~~~~~ + +`vim-mergetool `_ makes 3-way merge +conflicts much easier to deal with by only focusing on what needs to be +manually edited. + +This makes it MUCH easier to work with 3-way diffs (like what happens in merge +conflicts), while at the same time allowing enough flexibility in configuration +to be able to reproduce default behaviors. + +.. note:: + + You'll need to set the following in your .gitconfig:: + + [merge] + conflictStyle = diff3 + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`:MergetoolStart` + - Starts the tool + + * - :kbd:`:diffget` + - Pulls "theirs" (that is, assume the remote is correct) + + * - :kbd:`do`, :kbd:`dp` + - Used as in vim diff mode + +Save and quit, or use :kbd:`:MergetoolStop`. + +.. plugin-metadata:: + :name: vim-mergetool + + +LSP-related ++++++++++++ + +The Language Server Protocol lets an editor like neovim communicate with +a language server. A language server is installed per language (e.g. Python, +Bash, etc), which knows a LOT about the language, and supports things like: + +- advanced autocomplete +- advanced highlighting +- going to definitiions or references (e.g., find where a function is + originally defined, or where it is used) +- identifying syntax errors directly in the editor + + +`Microsoft's overview +`__ of LSP has more +information. + +You install an LSP server for each language you want to use it with (see +:ref:`mason_ref` for installing these). Then you enable the LSP server for +a buffer, and you get code-aware hints, warnings, etc. + +Not all features are implemented in every LSP server. For example, the Python +LSP is quite feature-rich. In contrast, the R LSP is a bit weak. + +The Python LSP may be quite verbose if you enable it on existing code, though +in my experience addressing everything it's complaining about will improve your +code. You may find you need to add type annotations in some cases. + +Because the experience can be hit-or-miss depending on the language you're +using, and the language servers need to be installed, LSP is disabled by +default; start it with :kbd:`cl`. + +.. warning:: + + nvim 0.11 changed the way LSPs are handled, making them more natively + integrated. However, this breaks the existing plugin configuration. + + These dotfiles **currently only support nvim <0.11**. + + I experimented with supporting both versions simultaneously. But the files + got complex, and it was a pain to keep switching versions to test everything + on both. So I'm opting to require nvim 0.10 for now. After a little while, + I'll move everything to 0.11+ and require nvim 0.11+. + +.. contents:: + :local: + +.. _nvimlspconfig_ref: + +``nvim-lspconfig`` +~~~~~~~~~~~~~~~~~~ + +`nvim-lspconfig `_ provides access to +nvim's Language Server Protocol (LSP). + +.. note:: + + You'll probably need to install NodeJS to install language servers with ``:Mason`` (see :ref:`mason_ref`): + + .. code-block:: bash + + ./setup.sh --install-npm # install nodejs into conda env + +These keymaps start with :kbd:`c` (mnemonic: "code"). You need to start the +language server with :kbd:`cl` to have access to any of the other keymaps. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + * - :kbd:`cl` + - Start the LSP server for this buffer + * - :kbd:`ce` + - Open diagnostic details + * - :kbd:`[d` + - Prev diagnostic + * - :kbd:`]d` + - Next diagnostic + * - :kbd:`cgd` + - Goto definition (e.g., when cursor is over a function) + * - :kbd:`cK` + - Hover help + * - :kbd:`crn` + - Rename all instances of this symbol + * - :kbd:`cr` + - Goto references + * - :kbd:`ca` + - Code action (opens a menu if implemented) + +.. plugin-metadata:: + :name: nvim-lspconfig + +.. _mason_ref: + +``mason.nvim`` +~~~~~~~~~~~~~~ + +`mason.nvim `_ easily installs +Language Server Protocols, debuggers, linters, and formatters. Use ``:Mason`` +to open the interface, and hit :kbd:`i` on what you want to install, or +:kbd:`g?` for more help. + +.. note:: + + Many language servers use the npm (javascript package manager) to install. + This is the case for ``pyright``, for example. You can use ``./setup.sh + --install-npm`` to easily create a conda env with npm and add its bin dir to + your ``$PATH``. + +For Python, try ``pyright``. + +For Lua (working on your nvim configs), use ``lua-language-server`` +(nvim-lspconfig calls this ``lua-ls``). + +For Bash, ``bash-language-server``. + +For R, you can try ``r-languageserver``, but this needs to be installed within +the environment you're using R (and R itself must be available). It's not +that useful if you want to use it in multiple conda environments. It doesn't +have that many features yet, either. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + * - ``:Mason`` + - Open the mason interface + + * - :kbd:`i` on an item + - Install + + +.. plugin-metadata:: + :name: mason + +.. _trouble_ref: + +``trouble.nvim`` +~~~~~~~~~~~~~~~~ + +`trouble.nvim `_ organizes all the LSP +diagnostics into a single window. You can use that to navigate the issues found +in your code. + +This only works if you've started the LSP for the buffer with :kbd:`cl` (see :ref:`nvimlspconfig_ref`). + +The alternative is using :kbd:`[d` and :kbd:`]d` to move between diagnostics +(see :ref:`nvimlspconfig_ref`) but it's nice to get an overview with this +plugin. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + * - :kbd:`ct` + - Toggle trouble.nvim window + +.. plugin-metadata:: + :name: trouble + +.. _conform_ref: + +``conform`` +~~~~~~~~~~~ + +`conform `__ runs style formatters on +the current buffer. + +For example, if ``black`` is avaiable it will run that on the code, but in +a way that the changes can be undone (in contrast to running ``black`` +manually on the file, which overwrites it). + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`cf` + - Run configured formatter on buffer (mnemonic: [c]ode [f]ormat) + +You can install formatters via :ref:`mason_ref`. + +For example, for Python I have ``isort`` and ``black``; for Lua, ``stylua``; for +bash, ``shfmt``. See the config file for how to set this up. + +.. plugin-metadata:: + :name: conform + +.. _lspprogress_ref: + +``lsp-progress.nvim`` +~~~~~~~~~~~~~~~~~~~~~ + +`lsp-progress.nvim `__ adds +a status/progress indicator to the lualine (at the bottom of a window) so you +know when it's running. + +No additional commands configured. + +.. plugin-metadata:: + :name: lsp-progress + + +Interfaces +++++++++++ + +These plugins add different interfaces unrelated to git (interfaces related to +git are described above). + +.. contents:: + :local: + +.. _telescope_ref: + +``telescope`` +~~~~~~~~~~~~~ + +`Telescope `_ provides +a floating window with fuzzy-search selection. + +Searching and selecting what, you ask? Pretty much anything you hook it up to. + +Type in the text box to filter the list. Hit enter to select (and open the +selected file in a new buffer). Hit Esc twice to exit. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`ff` + - Find files under this directory. Handy alternative to ``:e`` + + * - :kbd:`fg` + - Search directory for string. This is like using ripgrep, but in vim. + Selecting entry takes you right to the line. + + * - :kbd:`/` + - Fuzzy find within buffer + + * - :kbd:`fc` + - Find code object + + +Other useful things you can do with Telescope: + +- ``:Telescope highlights`` to see the currently set highlights for the + colorscheme. + +- ``:Telescope builtin`` to see a picker of all the built-in pickers. + Selecting one opens that picker. Very meta. But also very interesting for + poking around to see what's configured. + +- ``:Telescope planets`` to use a telescope + +- ``:Telescope autocommands``, ``:Telescope commands``, ``:Telescope + vim_options``, ``:Telescope man_pages`` are some other built-in pickers that + are interesting to browse through. + +.. plugin-metadata:: + :name: telescope + +.. _nvimtree_ref: + +``nvim-tree`` +~~~~~~~~~~~~~ + +`nvim-tree `__ provides a filesystem tree for browsing. + +.. list-table:: + :header-rows: 1 + + * - command + - description + + * - :kbd:`fb` + - Toggle file browser + + * - :kbd:`-` (within browser) + - Go up a directory. + + * - :kbd:`Enter` (within browser) + - Open file or directory, or close directory + +The window-switching shortcuts :kbd:`w` and :kbd:`q` (move to +windows left and right respectively; see :ref:`toggleterm_ref`) also work. + +.. plugin-metadata:: + :name: nvim-tree + +.. _whichkey_ref: + +``which-key`` +~~~~~~~~~~~~~ + +`which-key `_ displays a popup with +possible key bindings of the command you started typing. This is wonderful for +discovering commands you didn't know about, or have forgotten. + +The window will appear 1 second after pressing a key. For example, try pressing +the leader key (:kbd:`,`) and waiting a second to see all the keys you can +press after the leader and what the behavior will be. + +The length of this delay is configured with ``vim.o.timeoutlen``, e.g. +``vim.o.timeoutlen=500`` for half a sectond). There is no timeout though for +registers (``"``) or marks (``'``) or spelling (``z=`` over a word). + +You can hit a displayed key to execute the command, or if it's a multi-key +command (typically indicated with a ``+prefix`` to show there's more), then +that will take you to the next menu. + +Use :kbd:`` to back out a menu. In fact, pressing any key, waiting +for the menu, and then hitting backspace will give a list of all the default +mapped keys in vim. + +There is currently no extra configuration. Instead, when a key is mapped +(either in :file:`lua/mappings.lua` or :file:`lua/plugins/*.lua`), an +additional parameter ``desc = "description of mapping"`` is included. This +allows which-key to show a description. Mappings with no descriptions will +still be shown. + +.. code-block:: lua + + -- example mapping using vim.keymap.set, with description + vim.keymap.set('n', '1', ':bfirst', + { desc = "First buffer" }) + + -- example mapping when inside a plugin spec + { "plugin/plugin-name", + keys = { + { "1", ":bfirst", desc = "First buffer" }, + } + } + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - any + - after 1 second, shows a popup menu + + * - :kbd:`` + - Goes back a menu + + * - :kbd:`z=` (over a word) + - Show popup with spelling suggestions, use indicated character to select + + * - :kbd:`'` + - Show popup with list of marks + + * - :kbd:`"` + - Show popup with list of registers + +.. plugin-metadata:: + :name: which-key + + +.. _aerial_ref: + +``aerial`` +~~~~~~~~~~ + +`aerial `_ provides a navigation +sidebar for quickly moving around code (for example, jumping to functions or +classes or methods). For markdown or ReStructured Text, it acts like a table of +contents. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`a` + - Toggle aerial sidebar + + * - :kbd:`{` and :kbd:`}` + - Jump to prev or next item (function, snakemake rule, markdown section) + +For navigating complex codebases, there are other keys that are automatically +mapped, which you can read about in the `README for aerial +`_. + +.. plugin-metadata:: + :name: aerial + +Visuals ++++++++ + +These plugins add various visual enhancements to nvim. + +.. _bufferline_ref: + +``bufferline`` +~~~~~~~~~~~~~~ + +`bufferline.nvim `_ provides the +tabs along the top. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + * - :kbd:`b`, then type highlighted letter in tab + - Switch to buffer + +.. plugin-metadata:: + :name: bufferline + +.. _beacon_ref: + +``beacon`` +~~~~~~~~~~ + +`Beacon `_ provides an animated +marker to show where the cursor is. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`n` or :kbd:`N` after search + - Flash beacon at search hit + +.. plugin-metadata:: + :name: beacon + +.. _lualine_ref: + +``lualine`` +~~~~~~~~~~~ + +`lualine `_ provides the status line along the bottom. + +No additional commands configured, but see the homepage for all the things you +can add to it. + +.. plugin-metadata:: + :name: lualine + +.. _indentblankline_ref: + +``indent-blankline`` +~~~~~~~~~~~~~~~~~~~~ + +`indent-blankline `_ +shows vertical lines where there is indentation, and highlights one of these +vertical lines to indicate the current `scope +`_. + +No additional commands configured. However, depending on the font you use, you +may want to play around with the symbol used. + +.. plugin-metadata:: + :name: indent-blankline + +.. _rendermarkdown_ref: + +``render-markdown`` +~~~~~~~~~~~~~~~~~~~ + +`render-markdown +`__ provides +a nicer reading experience for markdown files. This includes bulleted list and +checkbox icons, fancy table rendering, colored background for code blocks, and +more. + +In my testing I found it to be more configurable and performant than the +``obsidian.nvim`` equivalent functionality, and in ``daler/zenburn.nvim`` I've +added highlight groups for this plugin. + +.. details:: Some notes about its behavior: + + - It uses "conceal" functionality to replace things like ``-`` (for bulleted + lists) with the unicode ``•``. It hides URLs and only shows the link text + (like a website does) + - It's configured to differentiate between a web link (http) and an internal + link (no http) and show an icon for an internal link. + - It has functionality for parsing headlines and making them stand out more in + a document. The actual styling of headlines is configured in the colorscheme. + - Code blocks have an icon indicating their language, and the background of + code blocks is different from surrounding text. + - Tables are rendered nicely + +This plugin is **specifically disabled for RMarkdown files**, which are +typically heavy on the source code, and the background of code chunks can get +distracting when entering and exiting insert mode. However, this plugin can be +useful when reviewing a long RMarkdown file to focus on the narrative text. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`rm` + - Toggle [r]ender[m]arkdown on an [r][m]arkdown file + +.. plugin-metadata:: + :name: render-markdown + +.. _nvimcolorizer_ref: + +``nvim-colorizer`` +~~~~~~~~~~~~~~~~~~ + +`nvim-colorizer `__ is +a high-performance color highlighter. It converts hex codes to their actual +colors. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - ``ColorizerToggle`` + - Toggle colorizing of hex codes + +.. plugin-metadata:: + :name: nvim-colorizer + +.. _lush_ref: + +``lush`` +~~~~~~~~ + +`lush `__ is a helper for adjusting colors in a colorscheme. + +Open up a color scheme file, run ``:Lushify``, and you can use :kbd:`` and +:kbd:`` to increase/decrease values. This gives you live feedback as +you're working. See the homepage linked above for a demo, and `zenfade +`__ for a colorscheme that used lush (and +so supports it well). + +.. plugin-metadata:: + :name: lush + + +Everything else ++++++++++++++++ + +These plugins don't have a clear categorization. That doesn't mean they're not +super helpful though! + +.. contents:: + :local: + +.. _vimcommentary_ref: + +``vim-commentary`` +~~~~~~~~~~~~~~~~~~ + +`vim-commentary `_ lets you easily +toggle comments on lines or blocks of code. + + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`gc` on a visual selection + - toggle comment + + * - :kbd:`gcc` on a single line + - toggle comment + +.. plugin-metadata:: + :name: vim-commentary + + +.. _acceleratedjk_ref: + +``accelerated-jk`` +~~~~~~~~~~~~~~~~~~ + +`accelerated-jk `_ speeds up j and +k movements: longer presses will jump more and more lines. + +In particular, you might want to tune the acceleration curve depending on your +system's keyboard repeat rate settings -- see the config file for an explanation of +how to tweak. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`j`, :kbd:`k` + - Keep holding for increasing vertical scroll speed + +.. plugin-metadata:: + :name: accelerated-jk + +.. _blink_ref: + +``blink`` +~~~~~~~~~ + +`blink `__ offers autocomplete. + + +In this config, I've chosen to mimic the bash style of completion, +the commands documented here reflect that. I've also disabled the menu popping +up all the time. There are a lot of ways you can customize this yourself though +-- see the `blink docs `__. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`` + - Open completion menu + + * - :kbd:`` (when typing and the cursor is in a word) + - Open completion menu + + * - :kbd:``, :kbd:`` (in menu) + - Next, previous entry + + * - :kbd:`Enter` (when menu visible) + - Select entry + + * - up/down arrow (in menu) + - Next, previous entry + +.. plugin-metadata:: + :name: blink + +.. _treesitter_ref: + +``treesitter`` +~~~~~~~~~~~~~~ + +`treesitter `__ is a parsing +library that underpins many other plugins. + +You install a parser for a language, and it figures out which tokens +are functions, classes, variables, modules, etc. Then it's up to other plugins +to do something with that. For example, colorschemes can use that information, +or you can select text based on its semantic meaning within the programming +language (like easily select an entire function, or the body of a for-loop). + +Treesitter is configured to ensure the parsers listed in the config are +installed. These will be attempted to be installed automatically, but they do +require a C compiler to be available. + +- On a Mac, this may need XCode Command Line Tools to be installed. +- A fresh Ubuntu installation will need ``sudo apt install build-essential`` +- RHEL/Fedora will need ``sudo dnf install 'Development Tools'`` (and may need + the `EPEL repo `__ enabled). +- Alternatively, if you don't have root access, you can install `compiler + packages via conda + `_, + +Alternatively, comment out the entire ``ensure_installed`` block in +:file:`~/.config/nvim/lua/plugins/treesitter.lua`; this means you will not have +treesitter-enabled syntax highlighting though. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`cs` + - Start incremental selection + + * - :kbd:`` (in incremental selection) + - Increase selection by node + + * - :kbd:`` (in incremental selection) + - Decrease selection by node + +.. plugin-metadata:: + :name: treesitter + +.. _toggleterm_ref: + +``toggleterm`` +~~~~~~~~~~~~~~ + +`ToggleTerm `_ lets you easily +interact with a terminal within vim. + +The greatest benefit of this is that you can send text from a text buffer +(Python script, RMarkdown file, etc) over to a terminal. This lets you +reproduce an IDE-like environment purely from the terminal. The following +commands are custom mappings set in :file:`.config/nvim/init.vim` that affect +the terminal use. + +.. note:: + + The terminal will jump to insert mode when you switch to it (either using + keyboard shortcuts or mouse), but **clicking the mouse a second time will + enter visual mode**, just like in a text buffer. This can get confusing if + you're not expecting it. + + You can either click to the text buffer and immediately back in the + terminal, or use :kbd:`a` or :kbd:`i` in the terminal to get back to insert + mode. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`t` + - Open terminal to the right. + + * - :kbd:`w` + - Move to the right window (assumes it's terminal), and enter insert mode + + * - :kbd:`q` + - Move to the text buffer to the left, and enter normal mode + + * - :kbd:`cd` + - Send the current RMarkdown code chunk to the terminal, and jump to the + next chunk + + * - :kbd:`gxx` + - Send the current *line* to the terminal buffer + + * - :kbd:`gx` + - Send the current *selection* to the terminal buffer + + * - :kbd:`k` + - Render the current RMarkdown file to HTML using `knitr::render()`. + Assumes you have knitr installed and you're running R in the terminal + buffer. + + * - :kbd:`k` + - Run the current Python script in IPython. Assumes you're running + IPython in the terminal buffer. + +.. plugin-metadata:: + :name: toggleterm + + +.. _vimdiffenhanced: + +``vim-diff-enhanced`` +~~~~~~~~~~~~~~~~~~~~~ + +`vim-diff-enhanced `_ provides +additional diff algorithms that work better on certain kinds of files. If your +diffs are not looking right, try changing the algorithm with this plugin: + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`:EnhancedDiff ` + - Configure the diff algorithm to use, see below table + +The following algorithms are available: + +.. list-table:: + :header-rows: 1 + :align: left + + * - algorithm + - description + + * - myers + - Default diff algorithm + + * - default + - alias for `myers` + + * - minimal + - Like myers, but tries harder to minimize the resulting diff + + * - patience + - Patience diff algorithm + + * - histogram + - Histogram is similar to patience but slightly faster + +.. plugin-metadata:: + :name: vim-diff-enhanced + +.. _vimtablemode_ref: + +``vim-table-mode`` +~~~~~~~~~~~~~~~~~~ + +`vim-table-mode `_ provides +easy formatting of tables in Markdown and Restructured Text + +Nice Markdown and ReStructured Text tables are a pain to format. This plugin +makes it easy, by auto-padding table cells and adding the header lines as +needed. + +* With table mode enabled, :kbd:`||` on a new line to start the header. +* Type the header, with column names separated by :kbd:`|`. +* On a new line, use :kbd:`||` to fill in the header underline. +* On subsequent rows, delimit fields by :kbd:`|` (including a leading and trailing :kbd:`|`) +* Complete the table with :kbd:`||` on a new line. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`:TableModeEnable` + - Enables table mode, which makes on-the-fly adjustments to table cells + as they're edited + + * - :kbd:`:TableModeDisable` + - Disables table mode + + * - :kbd:`:Tableize` + - Creates a markdown or restructured text table based on TSV or CSV text + + * - :kbd:`TableModeRealign` + - Realigns an existing table, adding padding as necessary + +.. plugin-metadata:: + :name: vim-table-mode + +.. _flash_ref: + +``flash`` +~~~~~~~~~ + +`flash `__ lets you jump around in +a buffer with low mental effort. + +The trick is to *keep your eyes on the destination*. Hit :kbd:`s`, and type the +first 2 letters of where you're trying to go. This plugin will dim the rest of +the buffer, only highlighting instances where those 2 letters occur. It will +also add a *third* letter after it. If you type that third letter, the cursor will +jump to that location. + +Alternatively, if a treesitter parser is installed for this filetype, you can +use :kbd:`S` and suffix letters will be shown at different levels of the syntax +tree. For example inside a for-loop (i.e. don't include the `for`); outside +a for-loop (including the `for`), an entire function, entire Rmd code chunk, +etc. In this mode, which is just for selection, you don't type the two +characters you're looking for. Instead you just type the letter coresponding to +level of code that you want to select. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`s` in normal mode + - jump to match (see details) + + * - :kbd:`S` in normal mode + - select this treesitter node (see details) + + * - :kbd:`Ctrl-s` when searching + - Toggle flash during search + +.. plugin-metadata:: + :name: flash + +.. _vimsurround: + +``vim-surround`` +~~~~~~~~~~~~~~~~ + +`vim-surround `_ lets you easily change +surrounding characters. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`cs"'` + - change surrounding ``"`` to ``'`` + + * - :kbd:`csw}` + - add ``{`` and ``}`` surrounding word + + * - :kbd:`csw{` + - same, but include a space + +.. plugin-metadata:: + :name: vim-surround + +.. _vis_ref: + +``vis`` +~~~~~~~ + +`vis `_ provides better behavior on visual +blocks. + +By default in vim and neovim, when selecting things in visual +block mode, operations (substitutions, sorting) operate on the entire line -- +not just the block, as you might expect. However sometimes you want to edit +just the visual block selection, for example when editing TSV files. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + * - :kbd:``, then use :kbd:`:B` instead of :kbd:`:` + - Operates on visual block selection only + +.. plugin-metadata:: + :name: vis + +.. _stickybuf_ref: + +``stickybuf.nvim`` +~~~~~~~~~~~~~~~~~~ + +`stickybuf.nvim `__ prevents text +buffers from opening up inside a terminal buffer. + +Otherwise, you run nvim inside of nvim, and it gets hard to control which +instance of nvim is supposed to be interpreting your keystrokes. + +No additional commands configured. + +.. plugin-metadata:: + :name: stickybuf + + +.. _obsidian_ref: + +``obsidian.nvim`` +~~~~~~~~~~~~~~~~~ + +`obsidian.nvim `__ is a plugin +originally written for working with `Obsidian `__ which is a GUI +notetaking app (that uses markdown and has vim keybindings). If you're an +Obsidian user, this plugin makes the experience with nvim quite nice. + +However, after using it for a bit I really like it for markdown files in +general, in combination with the :ref:`rendermarkdown_ref` plugin. + +I've been using it to take daily notes. + + +The mapped commands below use :kbd:`o` ([o]bsidian) as a a prefix. + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`Enter` on any link + - Open the link in a browser (if http) or open the file in a new buffer + + * - :kbd:`od` + - [o]bsidian [d]ailies: choose or create a daily note + + * - :kbd:`os` + - [o]bsidian [s]search for notes with ripgrep + + * - :kbd:`ot` + - [o]bsidian [t]ags finds occurrences of ``#tagname`` across files in directory + + * - :kbd:`on` + - [o]bsidian [n]ew link with a word selected will make a link to that new file + +.. plugin-metadata:: + :name: obsidian + + +.. _browsher_ref: + +``browsher.nvim`` +~~~~~~~~~~~~~~~~~ + +`browsher.nvim `_ constructs a URL +for GitHub or GitLab that includes line highlighting, based on your visual +selection. + +Run ``:Browsher`` on a line of code, and a URL to that line of code in the +upstream repo (GitHub, GitLab) will be copied to your clipboard. + +It is currently configured to store the URL on your OS clipboard, which makes +it useful for working on remote systems. However, you can comment out the +``open_cmd`` config option if you want it to automatically open a browser tab +for working on a local machine. + +It is also currently configured to optionally read from a file stored outside +of a dotfiles repo. This is to support the construction of URLs for private +GitHub/GitLab instances. See the config file +:file:`.config/nvim/lua/plugins/browsher.lua` for details. + + +.. code-block:: lua + + -- Add the following to ~/.browsher.lua, using your own instance URL + return { + ["gitlab.private.com"] = { + url_template = "%s/-/blob/%s/%s", + single_line_format = "#L%d", + multi_line_format = "#L%d-%d", + }, + } + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - ``Browsher`` + - Store URL on OS clipboard + +.. plugin-metadata:: + :name: browsher + +.. _indentomatic_ref: + +``indent-o-matic`` +~~~~~~~~~~~~~~~~~~ +`indent-o-matic `__ is "dumb +automatic fast indentation detection". + +To quote more from the home page, "Instead of trying to be smart about +detecting an indentation using statistics, it will find the first thing that +looks like a standard indentation (tab or 8/4/2 spaces) and assume that's what +the file's indentation is. This has the advantage of being fast and very often +correct while being simple enough that most people will understand what it will +do predictably" + +When starting a blank file, if it's not doing what you want when you hit +:kbd:`` then give it a hint: manually use the tab spacing you want and then +run ``:IndentOMatic`` to re-check. + +No additional commands configured. + +.. plugin-metadata:: + :name: indent-o-matic + + +.. _treesj_ref: + +``TreeSJ`` +~~~~~~~~~~ + +`TreeSJ `__ uses treesitter to split and +join nodes. This is one of those things that is a lot easier to show than +explain. It converts back and forth between this: + +.. code-block:: python + + def f(a, b=True, c='default'): + pass + +and this: + +.. code-block:: python + + def f( + a, + b=True, + c='default', + ): + pass + + +.. list-table:: + :header-rows: 1 + :align: left + + * - command + - description + + * - :kbd:`j` + - Toggle split/join + +.. plugin-metadata:: + :name: treesj + +Colorschemes +------------ + +**If colors look broken** then you may be using a terminal like the default +Terminal.app on macOS that does not support true color. See +:ref:`mac-terminal-colors` for how to fix. + +For years I've been using the venerable *zenburn* colorscheme. However, now +with additional plugins and highlighting mechansims (especially treesitter), it +became important to be able to configure more than what that colorscheme supported. + +`zenburn.nvim `_ is a reboot of +this colorscheme, but there were some parts of it that I wanted to change, or +at least have more control over. + +`My fork of the repo `__ is used here. +If you're interested in tweaking your own colorschemes, I've hopefully +documented that fork enough to give you an idea of how to modify on your own. + + +`zenfade `__ is what I've been working on +recently. It's a warmer and more faded version of zenburn and I like it quite +a bit. However, since zenburn has been the default for a while and other people +are using it (and are probably used to it), I'm not setting zenfade to be the +default, at least not yet. + +Changelog for ``zenburn``: + +.. plugin-metadata:: + :name: zenburn + :file: ../.config/nvim/lua/plugins/colorschemes.lua + +Changelog for ``zenfade``: + +.. plugin-metadata:: + :name: zenfade + +Changelog for ``colorscheme``: + +.. plugin-metadata:: + :name: colorscheme + +Deprecations +------------ + +Sometimes there are better plugins for a particular functionality. I've kept +the documentation here in case you're using an old version. + +Deprecated plugins +++++++++++++++++++ + +``vim-rmarkdown`` +~~~~~~~~~~~~~~~~~ + +.. plugin-metadata:: + :name: vim-rmarkdown + :deprecation: Removed in favor of treesitter + +``vim-pandoc`` +~~~~~~~~~~~~~~ + +.. plugin-metadata:: + :name: vim-pandoc + :deprecation: Removed in favor of treesitter + +``vim-pandoc-syntax`` +~~~~~~~~~~~~~~~~~~~~~ + +.. plugin-metadata:: + :name: vim-pandoc-syntax + :deprecation: Removed in favor of treesitter + +``vim-tmux-clipboard`` +~~~~~~~~~~~~~~~~~~~~~~ + +.. plugin-metadata:: + :name: vim-tmux-clipboard + :deprecation: Removed because OSC 52 support in modern terminals/tmux/nvim makes things much easier for handling copy/paste. + +``leap.nvim`` +~~~~~~~~~~~~~ + +.. plugin-metadata:: + :name: leap + :deprecation: Removed in favor of the :ref:`flash_ref` plugin, which behaves similarly but also supports treesitter selections + +``nvim-cmp`` +~~~~~~~~~~~~ + +.. plugin-metadata:: + :name: nvim-cmp + :deprecation: Deprecated in favor of :ref:`blink_ref`, which has similar configurability but does not *require* it. blink also seems to play nicer with LSP. + + +``vim-sleuth`` +~~~~~~~~~~~~~~ + +.. plugin-metadata:: + :name: vim-sleuth + :deprecation: vim-sleuth would often get things wrong. indent-o-matic's simpler algorithm seems to work better. + +Notes on tried plugins +---------------------- + +- nvim-aider, when paired with neo-tree, was nice to use for adding files to the context. But now: + + - nvim-aider supports nvim-tree too now + - aider has gotten better at tab-completion, making it easy to add even deeply-nested files + - nvim-tree's :kbd:`-` to go up a directory was confusing with neo-tree's "remove from aider context" + - It's a better experience to just keep aider running in a different tmux pane/window . . . no need to consume nnvim screen real estate. + +- vim-matchup was nice to have (esp for Python) but it caused errors when + trying to edit a buffer where a treesitter parser wasn't installed. + + +- ``jakewvincent/mkdnflow.nvim`` was nice for hitting :kbd:`` to open + a linked file and then :kbd:`` to go back. But I realized I needed to + keep the context in my head of where I came from. I prefer having separate + buffers open so I can keep track of that (and buffer navigation helps move + between them). This plugin is also pretty nice for collapsing sections into + fancy headers. But I didn't consider it sufficiently useful to warrant + including and configuring it. +- ``lukas-reineke/headlines.nvim`` had nice section headers, and it had + backgrounds for code blocks. However that ended up having too much visual + noise for my taste. +- ``nvim-telekasten/telekasten.nvim`` has nice pickers for tags and files and + making links, but it was too opinionated for forcing the "telekasten" style + of note-taking. diff --git a/docs/plugin_metadata_ext.py b/docs/plugin_metadata_ext.py new file mode 100644 index 0000000..536323e --- /dev/null +++ b/docs/plugin_metadata_ext.py @@ -0,0 +1,393 @@ +""" +A Sphinx extension that provides a directive to display plugin metadata +extracted from git history. + +Usage: + .. plugin-metadata:: + :name: plugin-name + :file: optional-filename-if-different + +This will automatically extract: +- Date added (first commit with this plugin) +- Date updated (most recent commit modifying this plugin) +- Date removed (if applicable) + +The data is extracted from git history at build time. +""" + +import subprocess +import docutils.nodes +from docutils import nodes +import docutils.statemachine +import sphinx.util.nodes +from docutils.parsers.rst import Directive, directives +from datetime import datetime +import json +import pathlib +import os + + +class NestedParseNodes: + """Helper class for nested parsing of reStructuredText. From + https://www.drmoron.org/posts/sphinx-nested-parse-extensions/""" + + def __init__(self): + self.source = docutils.statemachine.ViewList() + + def add_line(self, sourceline, filename, linenumber): + self.source.append(sourceline, filename, linenumber) + + def get_nodes(self, directive): + node = docutils.nodes.section() + node.document = directive.state.document + + sphinx.util.nodes.nested_parse_with_titles(directive.state, self.source, node) + return node.children + + +class plugin_metadata(nodes.Element, nodes.General): + pass + + +class PluginMetadataDirective(Directive): + has_content = False + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = { + # Used to fill in config file; more convenient than providing full + # config filename in most cases. + "name": directives.unchanged_required, + # Explicitly provide config file + "file": directives.unchanged, + # Optional explanation of why deprecated, though should be filled in if + # the file was removed. + "deprecation": directives.unchanged, + } + + def run(self): + plugin_name = self.options.get("name") + if not plugin_name: + raise self.error("Plugin name must be provided") + + file_name = self.options.get("file", None) + if file_name is None: + file_name = f"../.config/nvim/lua/plugins/{plugin_name}.lua" + deprecation = self.options.get("deprecation", "") + + history = get_git_history(plugin_name, file_name) + + # We'll build up the node bit by bit, using ReST format, which will + # then get parsed into HTML. + parse = NestedParseNodes() + current_source = self.state.document.current_source + current_line = self.lineno + + # Helper functions + _hash_link = ( + lambda hash: f"`{hash} `__ " + ) + + def _add_line(text, newline=True): + parse.add_line(text, current_source, current_line) + if newline: + parse.add_line("", current_source, current_line) + + # For later CSS styling + _add_line(".. container:: plugin-metadata") + + if history["added"]: + _add_line(f" :Added:") + _add_line( + f" * {history['added']['date']} " + f"{_hash_link(history['added']['hash'])} " + f"*{history['added']['message']}*" + ) + + if history["changes"]: + _add_line(" :Changes:") + for change in history["changes"]: + _add_line( + f" * {change['date']} " + f"{_hash_link(change['hash'])}" + f"*{change['message']}*" + ) + + # if history["removed"]["date"] != "N/A": + # _add_line(" .. warning::") + # _add_line(" :Removed:") + # _add_line( + # f" {history['removed']['date']} " + # f"{_hash_link(history['removed']['hash'])} " + # f"*{history['removed']['message']}*", + # ) + if deprecation: + _add_line(" .. warning::") + _add_line(" :DEPRECATED: " + deprecation) + + # This is where the nested parsing is useful: we can use the details + # extension and it'll be parsed correctly + if os.path.exists(file_name): + file_label = file_name.replace("../", "") + _add_line(" .. details:: Config") + _add_line( + f" This can be found in :file:`{file_label}`:", + ) + _add_line(f" .. literalinclude:: {file_name}", False) + _add_line(" :language: lua") + else: + print(f"{file_name} does not exist") + + # Return the parsed nodes + return parse.get_nodes(self) + + +def get_git_history(plugin_name, file_name=None): + """Extract git history for a plugin file. + Cache results for quicker turnaround time when developing docs. + """ + + global _git_history_cache + + cache_key = f"{plugin_name}:{file_name}" + if cache_key in _git_history_cache: + print(f"Using cached git history for {plugin_name}") + return _git_history_cache[cache_key] + + print(f"Fetching git history for {plugin_name}") + + # Look for: + # - plugin name mentioned in commit messages + # - plugin name in .lua file contents (to catch them when they were in + # a giant init.lua file) + # - plugin name in filename + # + # In each case, we keep track of results in strings of the form + # "YYYY-MM-DD|hash|message" + try: + # Commit messages + cmd_changes_commit_messages = [ + "git", + "log", + "--format=%ad|%h|%s", + "--date=short", + "-i", # Case insensitive + f"--grep={plugin_name}", # Search in commit messages + ] + changes_commit_messages = ( + subprocess.check_output(cmd_changes_commit_messages, text=True) + .strip() + .split("\n") + ) + + # Changed file contents + cmd_changes_file_contents = [ + "git", + "log", + "--format=%ad|%h|%s", + "--date=short", + "-i", # Case insensitive + "-p", # Show patches + f"-S{plugin_name}", # Search for string in file contents + "--", # Separator between options and file paths + "*.lua", # Only search in .lua files + ] + changes_file_contents = ( + subprocess.check_output(cmd_changes_file_contents, text=True) + .strip() + .split("\n") + ) + + # Changed filenames containing the plugin name + cmd_changes_filenames = [ + "git", + "log", + "--format=%ad|%h|%s", + "--date=short", + "-i", # Case insensitive + "--name-only", # Show filenames + "--", # Separator between options and file paths + f"*{plugin_name}*.lua", # Files containing plugin name + ] + try: + changes_filenames = ( + subprocess.check_output(cmd_changes_filenames, text=True) + .strip() + .split("\n") + ) + changes_filenames = [ + r for r in changes_filenames if r and r.startswith("20") + ] # Keep only date lines + except subprocess.CalledProcessError: + changes_filenames = [] + + # Actual file changes. If had originally split files (and was always + # rigorous about git commits), this would have been all we needed. + cmd_file_changes = [ + "git", + "log", + "--format=%ad|%h|%s", + "--date=short", + "--", + file_name, + ] + try: + file_changes = ( + subprocess.check_output(cmd_file_changes, text=True).strip().split("\n") + ) + except subprocess.CalledProcessError: + file_changes = [] + + # Sorted list of unique changes without empty lines or non-date lines + all_changes = set( + changes_commit_messages + + changes_file_contents + + changes_filenames + + file_changes + ) + all_changes = [r for r in all_changes if r and r.startswith("20")] + changes_info = sorted(list(all_changes)) + + # Remove the first commit (which is the "added" commit) from changes if it exists + if changes_info: + added_info = changes_info.pop(0) + else: + added_info = "Unknown||" + added_hash = added_info.split("|")[1] if len(added_info.split("|")) > 1 else "" + changes_info = [ + change + for change in changes_info + if change + and ( + not added_hash + or len(change.split("|")) < 2 + or change.split("|")[1] != added_hash + ) + ] + + cmd_removed = [ + "git", + "log", + "--diff-filter=D", + "--format=%ad|%h|%s", + "--date=short", + "--", + file_name, + ] + removed_info = subprocess.check_output(cmd_removed, text=True).strip() + + # Parse changes + changes = [] + for change in changes_info: + if change: + parts = change.split("|", 2) + hash = parts[1] + + # I guess we could have "|" in messages + assert len(parts) >= 3 + + changes.append({"date": parts[0], "hash": hash, "message": parts[2]}) + + added_parts = added_info.split("|", 2) if added_info else ["Unknown", "", ""] + removed_parts = removed_info.split("|", 2) if removed_info else ["N/A", "", ""] + + result = { + "added": { + "date": added_parts[0], + "hash": added_parts[1] if len(added_parts) > 1 else "", + "message": added_parts[2] if len(added_parts) > 2 else "", + }, + "changes": sorted(changes, key=lambda x: x["date"]), + "removed": { + "date": removed_parts[0], + "hash": removed_parts[1] if len(removed_parts) > 1 else "", + "message": removed_parts[2] if len(removed_parts) > 2 else "", + }, + } + + # Store in cache + _git_history_cache[cache_key] = result + + return result + except subprocess.CalledProcessError: + result = { + "added": {"date": "Unknown", "hash": "", "message": ""}, + "changes": [], + "removed": {"date": "N/A", "hash": "", "message": ""}, + } + + # Store in cache + _git_history_cache[cache_key] = result + + return result + + +# Global cache for git history +_git_history_cache = {} +_cache_file = pathlib.Path(".git_history_cache.json") +_cache_max_age_days = 7 # Only regenerate cache if older than this many days + + +def load_cache(): + """Load the git history cache from disk if it exists and is recent enough.""" + global _git_history_cache + + if not _cache_file.exists(): + print("No cache file found, will create new cache") + _git_history_cache = {} + return + + # Check if cache file is recent enough + cache_age = datetime.now() - datetime.fromtimestamp(_cache_file.stat().st_mtime) + if cache_age.days > _cache_max_age_days: + print( + f"Cache is {cache_age.days} days old (older than {_cache_max_age_days} days), will regenerate" + ) + _git_history_cache = {} + return + + # Cache exists and is recent enough, load it + try: + with open(_cache_file, "r") as f: + _git_history_cache = json.load(f) + print( + f"Loaded git history cache with {len(_git_history_cache)} entries (age: {cache_age.days} days)" + ) + except (json.JSONDecodeError, IOError) as e: + print(f"Error loading git history cache: {e}") + _git_history_cache = {} + + +def save_cache(): + """Save the git history cache to disk if it has been modified.""" + if not _git_history_cache: + print("No cache entries to save") + return + + _cache_file.parent.mkdir(exist_ok=True) + try: + with open(_cache_file, "w") as f: + json.dump(_git_history_cache, f) + print(f"Saved git history cache with {len(_git_history_cache)} entries") + except IOError as e: + print(f"Error saving git history cache: {e}") + + +def setup(app): + app.add_node(plugin_metadata) + app.add_directive("plugin-metadata", PluginMetadataDirective) + + # Add some CSS for styling + app.add_css_file("plugin_metadata.css") + + # Load the cache when the extension is set up + load_cache() + + # Save the cache when the build is finished, but only if we've added new entries + app.connect("build-finished", lambda app, exc: save_cache()) + + return { + "version": "0.4", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/vim.rst b/docs/vim.rst index 6376c95..6066c19 100644 --- a/docs/vim.rst +++ b/docs/vim.rst @@ -6,9 +6,8 @@ Vim (neovim) configuration See :ref:`why` for why nvim (short for `Neovim `__) instead of vim. -This page documents my nvim configuration. Because the nvim community -(specifically, the plugin community) moves so quickly, this config and these -accompanying docs change more often than any other configs in this repo. +The nvim community moves quickly, and this config and these accompanying docs +change more often than any other configs in this repo. **You can take these new changes for a test drive** by running @@ -16,36 +15,25 @@ accompanying docs change more often than any other configs in this repo. ./setup.sh --nvim-test-drive -to move existing nvim config and plugins to backup directories. -This does not affect any other config (like bash). You can always roll back to -what you had before. The commands to roll back are printed at the end of the +This will move existing nvim config and plugins to backup directories. This +does not affect any other config (like bash). You can always roll back to what +you had before. The commands to roll back are printed at the end of the command. -.. note:: +Config file location +-------------------- - See :ref:`nvim-lua` and :ref:`Why Lua ` if you're coming here from - using older versions of these dotfiles that used vimscript instead of Lua. +The nvim configuration is split over multiple files. -Files ------ +This makes it easier to see what changed, and decide if you want those changes +or not. It also enables us to import the config files into this documentation +to easily view them (look for the "**Config:**" dropdowns). -.. versionchanged:: 2024-09-01 - - Updated nvim installation version to 0.10.1 for macOS - -.. versionchanged:: 2024-09-20 - - Modularized configuration: split up config files according to `structured - setup `__ recommendations from - lazy.nvim. +This is just a starting point, **you should adjust the config to +your liking!** -The nvim configuration is split over multiple files. This keeps any changes -more tightly confined to individual files, which makes it easier to see what -changed, and decide if you want it or not. It also enables us to import the -files into this documentation to easily view them on an individual plugin -basis. Hopefully this better makes the connection between the description and -the config, encouraging better understanding. Unfold each file below to see the -details. +Here is a description of the different pieces of the nvim config. Paths are +relative to :file:`~/.config/nvim`: .. details:: init.lua @@ -96,57 +84,27 @@ details. Each plugin is described in more detail below in its own section. Each has its own file in the :file:`.config/nvim/lua/plugins` directory. -Screencasts ------------ - -.. versionadded:: 2024-03-31 - -Sometimes it's much easier to see what's going on than to read about it... - -.. details:: screencast of lazy.nvim setting up plugins - - See :ref:`plugins_` for more details. - .. image:: gifs/lazy_annotated.gif +Leader key +---------- -.. details:: screencast of switching buffers +The leader key is remapped to :kbd:`,`. This is configured in :file:`.config/nvim/init.lua`. - See :ref:`buffers` for more; this uses :ref:`bufferline` for the tabs, - :ref:`nvimtree` for the file tree, and :ref:`telescope_ref` for the - fuzzy-finder. - - .. image:: gifs/buffers_annotated.gif - -Non-printing characters ------------------------ -Non-printing characters (tab characters and trailing spaces) are displayed. -Differentiating between tabs and spaces is extremely helpful in tricky -debugging situations. - -:file:`~/.config/nvim/lua/config/autocmds.lua` has these lines: - -.. code-block:: lua - - vim.cmd(":autocmd InsertEnter * set listchars=tab:>•") - vim.cmd(":autocmd InsertLeave * set listchars=tab:>•,trail:∙,nbsp:•,extends:⟩,precedes:⟨") +.. list-table:: + :header-rows: 1 + :align: left -With these settings characters look like ``>••••``. Trailing spaces show up -as dots like ``∙∙∙∙∙``. + * - command + - description -The autocmds here mean that we only show the trailing spaces when we're outside -of insert mode, so that every space typed doesn't show up as trailing. When -wrap is off, the characters for "extends" and "precedes" indicate that there's -text offscreen. + * - :kbd:`,` + - Remapped leader. Below, when you see :kbd:`` it means :kbd:`,`. .. _buffers: -Switching buffers ------------------ - -.. versionadded:: 2023-11-01 - :kbd:`b` using bufferline plugin -Three main ways of **opening** file in a new buffer: +Opening multiple files +---------------------- .. list-table:: :header-rows: 1 @@ -162,11 +120,11 @@ Three main ways of **opening** file in a new buffer: - Search for file in directory to open in new buffer (Telescope) * - :kbd:`fb` - - Toggle file browser, hit Enter on file (nvim-tree) + - Toggle file browser, hit Enter on file (see :ref:`neotree` for more) -See :ref:`nvimtree` for more on navigating the file tree shown by :kbd:`fb`. -Once you have multiple buffers, you can **switch** between them in these ways: +Switching between open files +---------------------------- .. list-table:: :header-rows: 1 @@ -174,96 +132,50 @@ Once you have multiple buffers, you can **switch** between them in these ways: * - command - description + - configured in * - :kbd:`[b`, :kbd:`]b` - Prev and next buffers + - :file:`lua/config/keymaps.lua` * - :kbd:`H`, :kbd:`L` - Prev buffer, next buffer + - :file:`lua/config/keymaps.lua` * - :kbd:`1`, :kbd:`2` - First buffer, last buffer + - :file:`lua/config/keymaps.lua` * - :kbd:`b` then type highlighted letter in tab - Switch buffer + - :file:`lua/plugins/bufferline.lua` -The display of the bufferline is configured in -:file:`lua/plugins/bufferline.lua`, as part of the bufferline plugin. It is -additionally styled using the :ref:`zenburn` plugin/colorscheme. - -Format options explanation --------------------------- - -The following options change the behavior of various formatting; see ``:h formatoptions``: - -.. code-block:: lua - - vim.opt.formatoptions = "qrn1coj" - -Explanation of these options: - -- q: gq also formats comments -- r: insert comment leader after in insert mode -- n: recognize numbered lists -- 1: don't break a line after a 1-letter word -- c: autoformat comments -- o: automatically insert comment leader afer 'o' or 'O' in Normal mode. -- Use Ctrl-u to quickly delete it if you didn't want it. -- j: where it makes sense, remove a comment leader when joining lines - -Spell check ------------ - -In case you're not aware, vim has built-in spellcheck. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description +.. details:: Don't like this? - * - ``:set spell`` - - Enable spell check + See the config for the :ref:`bufferline` plugin to change; the bufferline is + additionally styled using the :ref:`zenburn` plugin/colorscheme. - * - :kbd:`]s` - - Next spelling error +.. details:: Screencast of switching buffers - * - :kbd:`[s` - - Previous spelling error + This example uses an older version of the bufferline plugin and so the + styling is a little different, but the shortcuts demonstrated are the same. - * - :kbd:`z=` - - Show spelling suggestions + .. image:: gifs/buffers_annotated.gif Shortcuts --------- -.. versionchanged:: 2024-01-21 - - Added :kbd:`p` for pasting formatted Markdown/ReST links - -.. versionchanged:: 2024-03-31 - - Added :kbd:`cp` for a convenient "copy mode" - -.. versionchanged:: 2024-09-01 - - :kbd:`cp` is more complete (toggles render-markdown and sign columns, too) - +Here are the shortcuts configured in the main config. See :ref:`plugins` for +all the plugin-specific shortcuts. -Here are some general shortcuts that are defined in the included config. With -the ``which-key`` plugin, many of these are also discoverable by hitting the -first key and then waiting a second for the menu to pop up. +You can browse around to see if there's anything you think might be useful, but +there's no need for you to know all these! I happen to use them, and since I've +included them in this config you get them for free. -.. note:: +The :ref:`whichkey` plugin will pop up a window showing what keys you can +press, so you can use that for exploration as well. - **Mappings that use a plugin** are configured in the plugin's respective file - in :file:`lua/plugins/` and are described below under the respective plugin's - section. - -If you're defining your own keymappings, add a ``desc`` argument so that -which-key will provide a description for it. .. list-table:: :header-rows: 1 @@ -271,53 +183,47 @@ which-key will provide a description for it. * - command - description - - * - :kbd:`,` - - Remapped leader. Below, when you see :kbd:`` it means :kbd:`,`. - - * - :kbd:`r` - - Toggle relative line numbering (makes it easier to jump around lines - with motion operators). + - configured in * - :kbd:`H` - Toggle highlighted search. Sometimes it's distracting to have all the highlights stick around. + - :file:`lua/config/keymaps.lua` * - :kbd:`W` - Remove all trailing spaces in the file. Useful when cleaning up code to commit. + - :file:`lua/config/keymaps.lua` * - :kbd:`R` - Refresh syntax highlighting. Useful when syntax highlighting gets wonky. + - :file:`lua/config/keymaps.lua` * - :kbd:`@l` - Macro to surround the line with quotes and add a trailing comma. Useful for making Python or R lists out of pasted text + - :file:`lua/config/keymaps.lua` * - :kbd:`-` - Fills in the rest of the line with "-", out to column 80. Useful for making section separators. + - :file:`lua/config/keymaps.lua` * - :kbd:`` - Useful for working with TSVs. Starts the command ``:set nowrap tabstop=`` but then leaves the cursor at the vim command bar so you can fill in a reasonble tabstop for the file you're looking at. + - :file:`lua/config/keymaps.lua` * - :kbd:`\`` - (that's a backtick) Adds a new RMarkdown chunk and places the cursor inside it - - * - :kbd:`ry` - - Used for RMarkdown; writes commonly-used YAML front matter (mnemonic: - rmarkdown yaml) - - * - :kbd:`ko` - - Used for RMarkdown; writes an RMarkdown chunk with commonly-used knitr - global options (mnemonic: knitr options) + - :file:`lua/config/autocmds.lua` * - :kbd:`d` - Insert the current date as a ReST or Markdown-formatted title, depending on the file type. Useful when writing logs. + - :file:`lua/config/autocmds.lua` * - :kbd:`p` - Paste the contents of the OS clipboard into a formatted link as @@ -325,1873 +231,102 @@ which-key will provide a description for it. and puts the cursor in the link description. Note that this will *not* work to paste to vim on a remote server, unless you do tricky things with X forwarding, so consider it local-only. + - :file:`lua/config/autocmds.lua` * - :kbd:`cp` - Toggle a sort of "copy mode". Turns off line numbers, the vertical indentation lines from indent-blankline, any sign columns, and render-markdown (if enabled) so you can more easily copy text into another app. + - :file:`lua/config/keymaps.lua` -.. _plugins_: - -Plugins -------- - -The plugins configured in :file:`lua/plugins/*.lua` have lots and lots of -options. Here I’m only highlighting the options I use the most, but definitely -check out each homepage to see all the other weird and wonderful ways they can -be used. - -**Plugins are now configured using** `lazy.nvim -`_. This supports lazy-loading of plugins -to keep a snappy startup time, and only load plugins when they're needed. See -:ref:`nvim-lua` for my rationale on that. - -Each plugin spec in :file:`lua/plugins/*.lua` is a table. The first property is -the name of the plugin. Other properties: - -* ``lazy``: only load when requested by something else. Saves on initial load - time, but use this with care since it can get confusing. - -* ``ft``: only load the plugin when editing this filetype. Implies lazy=true. - -* ``cmd``: only load the plugin when first running this command. Implies lazy=true. - -* ``keys``: only load the plugin when using these keymappings. Implies lazy=true. - -* ``config``: run this stuff after the plugin loads. If config = true, just run - the default setup for the plugin. - -* ``init``: similar to config, but used for pure-vim plugins - -If keys are specified, this is the only place they need to be mapped, and they -will make their way into the which-key menu even if they trigger a lazy-loaded -plugin. Use the ``desc`` argument to give which-key a description to use. - -Here, plugins are sorted roughly so that the ones that provide additional -commands come first. - -.. note:: - - Don't like a plugin? Find it in :file:`lua/plugins.lua` and add ``enabled - = false`` next to where the plugin is named. For example: - - .. code-block:: lua - - -- ... other stuff - { "user/plugin-name", enabled = false }, - -- ... more stuff - - Or delete it, or comment it out. - - -The vim config has changed over the years. Depending on when you last updated, -there may be plugins added or removed or changed in some way. This table keeps -track of what has changed recently. - -.. list-table:: - :header-rows: 1 - :align: left - - * - plugin - - date added - - date changed - - description - - * - :ref:`vimtmuxclipboard` - - 2016 - - 2024-10-24 (removed) - - makes tmux play nicer with vim clipboard - - * - :ref:`vimpythonpep8indent` - - 2017 - - - - nice indentation for python - - * - :ref:`vimfugitive` - - 2018-09-26 - - - - a wonderful and powerful interface for git, in vim - - * - :ref:`vimdiffenhanced` - - 2019-02-27 - - - - additional diff algorithms - - * - :ref:`vimtablemode` - - 2019-03-27 - - - - makes markdown and restructured text tables easy - - * - :ref:`vis_ref` - - 2019-09-30 - - - - replace text in visual selections - - * - :ref:`vimgv` - - 2021-02-14 - - - - git log viewer - - * - :ref:`vimmergetool` - - 2021-02-14 - - - - sane approach to handling merge conflicts in git - - * - :ref:`toggleterm_ref` - - 2022-12-27 - - 2024-03-31 - - open a terminal inside vim and send text to it - - * - :ref:`vimsurround` - - 2022-12-27 - - - - add and change surrounding characters easily - - * - :ref:`nvimtree` - - 2023-10-10 - - - - provides a file browser window in vim - - * - :ref:`diffview` - - 2023-10-11 - - - - a wonderful tool for exploring git history - - * - :ref:`acceleratedjk` - - 2023-10-15 - - - - speeds up vertical navigation - - * - :ref:`beacon_ref` - - 2023-10-15 - - 2023-09-01 - - flash a beacon where the cursor is - - * - :ref:`gitsigns_ref` - - 2023-10-15 - - - - unobtrusively indicate git changes within a file - - * - :ref:`indentblankline` - - 2023-10-15 - - - - show vertical lines at tab stops - - * - :ref:`nvimcmp` - - 2023-10-15 - - - - autocomplete - - * - :ref:`telescope_ref` - - 2023-10-15 - - - - a menu tool for picking (selecting files, etc) - - * - :ref:`vimcommentary` - - 2023-10-15 - - - - easily comment/uncomment - - * - :ref:`whichkey` - - 2023-10-15 - - 2024-09-01 - - automated help for keymappings - - * - :ref:`aerial_ref` - - 2023-10-15 - - - - optional navigational menu for navigating large files - - * - :ref:`treesitter` - - 2023-10-15 - - - - provides parsers for advanced syntax and manipulation - - * - :ref:`bufferline` - - 2023-11-01 - - 2024-09-01 - - ergonomic buffer management - - * - :ref:`lualine_ref` - - 2023-11-01 - - - - statusline - - * - :ref:`mason` - - 2023-11-01 - - - - tool for easily installing LSPs, linters, and other tools - - * - :ref:`nvimlspconfig` - - 2023-11-01 - - 2024-03-31 - - handles the configuration of LSP servers - - * - :ref:`trouble` - - 2023-11-01 - - - - provides a separate window for diagnostics from LSPs - - * - :ref:`zenburn` - - 2023-11-01 - - - - colorscheme - - * - :ref:`conform` - - 2024-03-31 - - - - run linters and code formatters - - * - :ref:`flash` - - 2024-03-31 - - - - rapidly jump to places in code without counting lines - - * - :ref:`lspprogress` - - 2024-04-27 - - - - indicator that LSP is running - - * - :ref:`stickybuf_ref` - - 2024-04-27 - - - - prevents buffers from opening within a terminal - - * - :ref:`obsidian` - - 2024-09-01 - - - - provides nice editing and navigation tools for markdown - - * - :ref:`rendermarkdown` - - 2024-09-01 - - - - fancy rendering of markdown files - - -Sometimes there are better plugins for a particular functionality. I've kept -the documentation, but noted when they've been deprecated here and in the -linked description. - -.. list-table:: - :header-rows: 1 - :align: left - - * - plugin - - date added - - deprecated - - * - :ref:`leap` - - 2022-12-27 - - deprecated 2024-03-31 in favor of :ref:`flash` - - * - :ref:`vimrmarkdown` - - 2019-02-27 - - deprecated 2023-11-14 in favor of treesitter - - * - :ref:`vimpandoc` - - 2019-02-2 - - deprecated 2023-11-14 in favor of treesitter - - * - :ref:`vimpandocsyntax` - - 2019-02-27 - - deprecated 2023-11-14 in favor of treesitter - -.. _vimcommentary: - -``vim-commentary`` -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2023-10-15 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/vim-commentary.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/vim-commentary.lua - :language: lua - -`vim-commentary `_ lets you easily -toggle comments on lines or blocks of code. - - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`gc` on a visual selection - - toggle comment - - * - :kbd:`gcc` on a single line - - toggle comment - -.. _beacon_ref: - -``beacon`` -~~~~~~~~~~ - -.. versionadded:: 2023-10-15 - -.. versionchanged:: 2023-11-07 - - Only commands below will trigger the beacon - -.. versionchanged:: 2024-09-01 - - Pinned version to latest prior to Lua rewrite (which is making configuration more difficult) - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/beacon.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/beacon.lua - :language: lua - -`Beacon `_ provides an animated -marker to show where the cursor is. - - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`KJ` (hold shift and tap kj) - - Flash beacon - - * - :kbd:`n` or :kbd:`N` after search - - Flash beacon at search hit - - -.. _telescope_ref: - -``telescope`` -~~~~~~~~~~~~~ - -.. versionadded:: 2023-10-15 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/telescope.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/telescope.lua - :language: lua - -`Telescope `_ opens -a floating window with fuzzy-search selection. - -Type in the text box to filter the list. Hit enter to select (and open the -selected file in a new buffer). Hit Esc twice to exit. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`ff` - - Find files under this directory. Handy alternative to ``:e`` - - * - :kbd:`fg` - - Search directory for string. This is like using ripgrep, but in vim. - Selecting entry takes you right to the line. - - * - :kbd:`/` - - Fuzzy find within buffer - - * - :kbd:`fc` - - Find code object - - * - :kbd:`fo` - - Find recently-opened files - - -Other useful things you can do with Telescope: - -- ``:Telescope highlights`` to see the currently set highlights for the - colorscheme. - -- ``:Telescope builtin`` to see a picker of all the built-in pickers. - Selecting one opens that picker. Very meta. But also very interesting for - poking around to see what's configured. - -- ``:Telescope planets`` to use a telescope - -- ``:Telescope autocommands``, ``:Telescope commands``, ``:Telescope - vim_options``, ``:Telescope man_pages`` are some other built-in pickers that - are interesting to browse through. - - -.. _nvimtree: + * - :kbd:`ts` + - Insert a timestamp of the form ``YYYY-MM-DD HH:MM`` + - :file:`lua/config/keymaps.lua` -``nvim-tree`` -~~~~~~~~~~~~~ - -.. versionadded:: 2023-10-10 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/nvim-tree.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/nvim-tree.lua - :language: lua - -`nvim-tree `_ is a file browser. - -.. list-table:: - :header-rows: 1 - - * - command - - description - - * - :kbd:`fb` - - Toggle file browser - - * - :kbd:`-` (within browser) - - Go up a directory - - * - :kbd:`Enter` (within browser) - - Open file or directory, or close directory - -The window-switching shortcuts :kbd:`w` and :kbd:`q` (move to -windows left and right respectively) also work +.. versionchanged:: 2024-01-21 -.. _whichkey: + Added :kbd:`p` for pasting formatted Markdown/ReST links -``which-key`` -~~~~~~~~~~~~~ +.. versionchanged:: 2024-03-31 -.. versionadded:: 2023-10-15 + Added :kbd:`cp` for a convenient "copy mode" .. versionchanged:: 2024-09-01 - Pinned version; later versions are raising warnings that still need to be addressed - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/which-key.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/which-key.lua - :language: lua - -`which-key `_ displays a popup with -possible key bindings of the command you started typing. This is wonderful for -discovering commands you didn't know about, or have forgotten. - -The window will appear 1 second after pressing a key (this is configured with -``vim.o.timeoutlen``, e.g. ``vim.o.timeoutlen=500`` for half a sectond). There -is no timeout though for registers (``"``) or marks (``'``) or spelling (``z=`` -over a word). - -You can hit a displayed key to execute the command, or if it's a multi-key -command (typically indicated with a ``+prefix`` to show there's more), then -that will take you to the next menu. - -Use :kbd:`` to back out a menu. In fact, pressing any key, waiting -for the menu, and then hitting backspace will give a list of all the default -mapped keys in vim. - -There is currently no extra configuration. Instead, when a key is mapped -(either in :file:`lua/mappings.lua` or :file:`lua/plugins.lua`), an -additional parameter ``desc = "description of mapping"`` is included. This -allows which-key to show a description. Mappings with no descriptions will -still be shown. - -.. code-block:: lua - - -- example mapping using vim.keymap.set, with description - vim.keymap.set('n', '1', ':bfirst', - { desc = "First buffer" }) - - -- example mapping when inside a plugin spec - { "plugin/plugin-name", - keys = { - { "1", ":bfirst", desc = "First buffer" }, - } - } - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - any - - after 1 second, shows a popup menu - - * - :kbd:`` - - Goes back a menu - - * - :kbd:`z=` (over a word) - - Show popup with spelling suggestions, use indicated character to select - - * - :kbd:`'` - - Show popup with list of marks - - * - :kbd:`"` - - Show popup with list of registers - -.. _acceleratedjk: - -``accelerated-jk`` -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2023-10-15 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/accelerated-jk.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/accelerated-jk.lua - :language: lua - -`accelerated-jk `_ speeds up j and -k movements: longer presses will jump more and more lines. - -Configured in :file:`lua/plugins.lua`. In particular, you might want to tune -the acceleration curve depending on your system's keyboard repeat rate settings --- see that file for an explanation of how to tweak. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`j`, :kbd:`k` - - Keep holding for increasing vertical scroll speed - -.. _nvimcmp: - -``nvim-cmp`` -~~~~~~~~~~~~ - -.. versionadded:: 2023-10-15 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/nvim-cmp.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/nvim-cmp.lua - :language: lua - -`nvim-cmp `_ provides tab-completion. - -By default, this would show a tab completion window on every keypress, which to -me is annoying and distracting. So this is configured to only show up when -I hit :kbd:``. - -Hit :kbd:`` to initiate. Hit :kbd:`` until you like what you see. -Then hit Enter. Arrow keys work to select, too. - -Snippets are configured as well. If you hit Enter to complete a snippet, you -can then use :kbd:`` and :kbd:`` to move between the placeholders -to fill them in. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`` - - Tab completion - -.. _aerial_ref: - -``aerial`` -~~~~~~~~~~ - -.. versionadded:: 2023-10-15 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/aerial.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/aerial.lua - :language: lua - -`aerial `_ provides a navigation -sidebar for quickly moving around code (for example, jumping to functions or -classes or methods). For markdown or ReStructured Text, it acts like a table of -contents. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description + :kbd:`cp` is more complete (toggles render-markdown and sign columns, too) - * - :kbd:`a` - - Toggle aerial sidebar +Other behaviors +--------------- - * - :kbd:`{` and :kbd:`}` - - Jump to prev or next item (function, snakemake rule, markdown section) +Here are some other behaviors that are configured in :file:`.config/nvim/lua/config/options.lua`; expand for details. -For navigating complex codebases, there are other keys that are automatically -mapped, which you can read about in the `README for aerial -`_. +.. details:: Non-printing characters + characters look like ``>••••``. Trailing spaces show up as dots like + ``∙∙∙∙∙``. Differentiating between tabs and spaces is extremely helpful in + tricky debugging situations. -.. _treesitter: + :file:`~/.config/nvim/lua/config/autocmds.lua` has these lines: -``treesitter`` -~~~~~~~~~~~~~~ + .. code-block:: lua -.. versionadded:: 2023-10-15 + vim.cmd(":autocmd InsertEnter * set listchars=tab:>•") + vim.cmd(":autocmd InsertLeave * set listchars=tab:>•,trail:∙,nbsp:•,extends:⟩,precedes:⟨") -.. details:: Config + The autocmds here mean that we only show the trailing spaces when we're outside + of insert mode, so that every space typed doesn't show up as trailing. When + wrap is off, the characters for "extends" and "precedes" indicate that there's + text offscreen. - This can be found in :file:`.config/nvim/lua/plugins/treesitter.lua`: - .. literalinclude:: ../.config/nvim/lua/plugins/treesitter.lua - :language: lua +.. details:: Formatting text -`treesitter `__ is a parsing -library. You install a parser for a language, and it figures out which tokens -are functions, classes, variables, modules, etc. Then it's up to other plugins -to do something with that. For example, colorschemes can use that information, -or you can select text based on its semantic meaning within the programming -language. + The following options change the behavior of various formatting; see ``:h formatoptions``: -In :file:`~/.config/lua/plugins.lua`, treesitter is configured to ensure the -listed parsers are installed. These will be attempted to be installed -automatically, but they do require a C compiler to be installed. + .. code-block:: lua + vim.opt.formatoptions = "qrn1coj" -- On a Mac, this may need XCode Command Line Tools to be installed. -- A fresh Ubuntu installation will need ``sudo apt install build-essential`` -- RHEL/Fedora will need ``sudo dnf install 'Development Tools'`` (and may need - the `EPEL repo `__ enabled). -- Alternatively, if you don't have root access, you can install `compiler - packages via conda - `_, + Explanation of these options: -Alternatively, comment out the entire ``ensure_installed`` block in -:file:`~/.config/lua/plugins.lua`; this means you will not have -treesitter-enabled syntax highlighting though. + - q: gq also formats comments + - r: insert comment leader after in insert mode + - n: recognize numbered lists + - 1: don't break a line after a 1-letter word + - c: autoformat comments + - o: automatically insert comment leader afer 'o' or 'O' in Normal mode. + - Use Ctrl-u to quickly delete it if you didn't want it. + - j: where it makes sense, remove a comment leader when joining lines +.. details:: Spell check -.. list-table:: - :header-rows: 1 - :align: left + In case you're not aware, vim has built-in spellcheck. - * - command - - description + .. list-table:: + :header-rows: 1 + :align: left - * - :kbd:`cs` - - Start incremental selection + * - command + - description - * - :kbd:`` (in incremental selection) - - Increase selection by node + * - ``:set spell`` + - Enable spell check - * - :kbd:`` (in incremental selection) - - Decrease selection by node + * - :kbd:`]s` + - Next spelling error -.. _nvimlspconfig: + * - :kbd:`[s` + - Previous spelling error -``nvim-lspconfig`` -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2023-11-01 - -.. versionchanged:: 2024-03-31 - - Changed next diagnostic to :kbd:`]d` rather than :kbd:`]e` for better - mnemonic (and similar for :kbd:`[d`) - - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/nvim-lspconfig.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/nvim-lspconfig.lua - :language: lua - -`nvim-lspconfig `_ provides access to -nvim's Language Server Protocol (LSP). You install an LSP server for each -language you want to use it with (see :ref:`mason` for installing these). -Then you enable the LSP server for a buffer, and you get code-aware hints, -warnings, etc. - -Not all features are implemented in every LSP server. For example, the Python -LSP is quite feature-rich. In contrast, the R LSP is a bit weak. Install them -with :ref:`mason`. - -The Python LSP may be quite verbose if you enable it on existing code, though -in my experience addressing everything it's complaining about will improve your -code. You may find you need to add type annotations in some cases. - -Because the experience can be hit-or-miss depending on the language you're -using, LSP is disabled by default. The current exception is for Lua, but you -can configure this behavior in :file:`lua/plugins.lua`. Use :kbd:`cl` -to start the LSP for a buffer. See :ref:`trouble` for easily viewing all the -diagnostics. - -.. note:: - - You'll need to install NodeJS - - .. code-block:: bash - - ./setup.sh --install-npm # install nodejs into conda env - - - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - * - :kbd:`cl` - - Start the LSP server for this buffer - * - :kbd:`ce` - - Open diagnostic details - * - :kbd:`[d` - - Prev diagnostic - * - :kbd:`]d` - - Next diagnostic - * - :kbd:`cgd` - - Goto definition (e.g., when cursor is over a function) - * - :kbd:`cK` - - Hover help - * - :kbd:`crn` - - Rename all instances of this symbol - * - :kbd:`cr` - - Goto references - * - :kbd:`ca` - - Code action (opens a menu if implemented) - -.. _mason: - -``mason.nvim`` -~~~~~~~~~~~~~~ - -.. versionadded:: 2023-11-01 - - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/mason.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/mason.lua - :language: lua - -`mason.nvim `_ easily installs -Language Server Protocols, debuggers, linters, and formatters. Use ``:Mason`` -to open the interface, and hit :kbd:`i` on what you want to install, or -:kbd:`g?` for more help. - -.. note:: - - Many language servers use the npm (javascript package manager) to install. - This is the case for ``pyright``, for example. You can use ``./setup.sh - --install-npm`` to easily create a conda env with npm and add its bin dir to - your ``$PATH``. - -For Python, install ``pyright``. - -For Lua (working on your nvim configs), use ``lua-language-server`` -(nvim-lspconfig calls this ``lua-ls``). - -For R, you can try ``r-languageserver``, but this needs to be installed within -the environment you're using R (and R itself must be available). It's not -that useful if you want to use it in multiple conda environments. It doesn't -have that many features yet, either. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - * - ``:Mason`` - - Open the mason interface - -.. _trouble: - -``trouble.nvim`` -~~~~~~~~~~~~~~~~ - -.. versionadded:: 2023-11-01 - - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/trouble.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/trouble.lua - :language: lua - -`trouble.nvim `_ organizes all the LSP -diagnostics into a single window. You can use that to navigate the issues found -in your code. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - * - :kbd:`ct` - - Toggle trouble.nvim window - - -.. _gitsigns_ref: - -``gitsigns`` -~~~~~~~~~~~~ - -.. versionadded:: 2023-10-15 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/gitsigns.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/gitsigns.lua - :language: lua - -`gitsigns `_ shows a "gutter" along -the left side of the line numbers, indicating where there were changes in -a file. Only works in git repos. - -This plugin is in a way redundant with vim-fugitive. Fugitive is more useful -when making commits across multiple files; gitsigns is more useful when making -commits within a file while you're editing it. So they are complementary -plugins rather than competing. - -Most commands require being in a hunk. Keymappings start with ``h``, mnemonic -is "hunk" (the term for a block of changes). - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`[c` - - Previous change - - * - :kbd:`]c` - - Next change - - * - :kbd:`hp` - - Preview hunk (shows floating window of the change, only works in a change) - - * - :kbd:`hs` - - Stage hunk (or stage lines in visual mode) - - * - :kbd:`hr` - - Reset hunk (or reset lines in visual mode) - - * - :kbd:`hu` - - Undo stage hunk - - * - :kbd:`hS` - - Stage buffer - - * - :kbd:`hR` - - Reset buffer - - * - :kbd:`hb` - - Blame line in floating window - - * - :kbd:`tb` - - Toggle blame for line - - * - :kbd:`hd` - - Diff this file (opens diff mode) - - * - :kbd:`td` - - Toggle deleted visibility - -Additionally, this supports hunks as text objects using ``ih`` (inside hunk). -E.g., select a hunk with :kbd:`vih`, or delete a hunk with :kbd:`dih`. - -.. seealso:: - - :ref:`vimfugitive`, :ref:`gitsigns_ref`, :ref:`vimgv`, and :ref:`diffview` are other complementary plugins for working with Git. - -.. _toggleterm_ref: - -``toggleterm`` -~~~~~~~~~~~~~~ - -.. versionadded:: 2022-12-27 - -.. versionchanged:: 2024-03-31 - Version of toggleterm is pinned because later versions have issues with - sending multiple selected lines to the terminal. - -.. versionchanged:: 2024-11-19 - Added a custom command for sending Python code to IPython using IPython's - ``%cpaste`` magic command. - -.. versionchanged:: 2024-12-15 - Removed the ``%cpaste`` functionality added 2024-11-19 due to IPython lag on - some systems. Use the more general bracketed paste mechanism. - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/toggleterm.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/toggleterm.lua - :language: lua - -`ToggleTerm `_ lets you easily -interact with a terminal within vim. - -The greatest benefit of this is that you can send text from a text buffer -(Python script, RMarkdown file, etc) over to a terminal. This lets you -reproduce an IDE-like environment purely from the terminal. The following -commands are custom mappings set in :file:`.config/nvim/init.vim` that affect -the terminal use. - -.. note:: - - The terminal will jump to insert mode when you switch to it (either using - keyboard shortcuts or mouse), but **clicking the mouse a second time will - enter visual mode**, just like in a text buffer. This can get confusing if - you're not expecting it. - - You can either click to the text buffer and immediately back in the - terminal, or use :kbd:`a` or :kbd:`i` in the terminal to get back to insert - mode. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`t` - - Open terminal to the right. - - * - :kbd:`w` - - Move to the right window (assumes it's terminal), and enter insert mode - - * - :kbd:`q` - - Move to the text buffer to the left, and enter normal mode - - * - :kbd:`cd` - - Send the current RMarkdown code chunk to the terminal, and jump to the - next chunk - - * - :kbd:`gxx` - - Send the current *line* to the terminal buffer - - * - :kbd:`gx` - - Send the current *selection* to the terminal buffer - - * - :kbd:`k` - - Render the current RMarkdown file to HTML using `knitr::render()`. - Assumes you have knitr installed and you're running R in the terminal - buffer. - - * - :kbd:`k` - - Run the current Python script in IPython. Assumes you're running - IPython in the terminal buffer. - - -.. _vimfugitive: - -``vim-fugitive`` -~~~~~~~~~~~~~~~~ - -.. versionadded:: 2018-09-26 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/vim-fugitive.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/vim-fugitive.lua - :language: lua - -`vim-fugitive `_ provides a git interface in vim. - -This is wonderful for making incremental commits from within vim. This makes it -a terminal-only version of git-cola or an alternative to tig. Specifically: - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`:Git` - - Opens the main screen for fugitive (hint: use `vim -c ":Git"` from the - command line to jump right into it) - - * - :kbd:`=` - - Toggle visibility of changes - - * - :kbd:`-` (when over a filename) - - Stage or unstage the file - - * - :kbd:`-` (when in a chunk after using ``=``) - - Stage or unstage the chunk - - * - :kbd:`-` (in visual select mode (``V``)) - - Stage or unstage **just the selected lines**. Perfect for making - incremental commits. - - * - :kbd:`cc` - - Commit, opening up a separate buffer in which to write the commit - message - - * - :kbd:`dd` (when over a file) - - Open the file in diff mode - -The following commands are built-in vim commands when in diff mode, but -are used heavily when working with ``:Gdiff``, so here is a reminder: - -.. _working-with-diffs: - -Working with diffs -++++++++++++++++++ - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`]c` - - Go to the next diff - - * - :kbd:`[c` - - Go to the previous diff - - * - :kbd:`do` - - Use the [o]ther file's contents for the current diff - - * - :kbd:`dp` - - [P]ut the contents of this diff into the other file - -.. seealso:: - - :ref:`vimfugitive`, :ref:`gitsigns_ref`, :ref:`vimgv`, and :ref:`diffview` are other complementary plugins for working with Git. - -.. _vimgv: - -``gv`` -~~~~~~~~~~ - -.. versionadded:: 2021-02-14 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/gv.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/gv.lua - :language: lua - -`vim.gv `_ provides an interface to easily -view and browse git history. - - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`:GV` in visual mode - - View commits affecting selection - - * - :kbd:`GV` - - Open a commit browser, hit :kbd:`Enter` on a commit to view - -.. seealso:: - - :ref:`vimfugitive`, :ref:`gitsigns_ref`, :ref:`vimgv`, and :ref:`diffview` are other complementary plugins for working with Git. - - -.. _vimmergetool: - -``vim-mergetool`` -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2021-02-14 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/vim-mergetool.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/vim-mergetool.lua - :language: lua - -`vim-mergetool `_ makes 3-way merge -conflicts much easier to deal with by only focusing on what needs to be -manually edited. - -Makes it MUCH easier to work with 3-way diffs, while at the same time allowing -enough flexibility in configuration to be able to reproduce default behaviors. - -.. note:: - - You'll need to set the following in your .gitconfig:: - - [merge] - conflictStyle = diff3 - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`:MergetoolStart` - - Starts the tool - - * - :kbd:`:diffget` - - Pulls "theirs" (that is, assume the remote is correct) - - * - :kbd:`do`, :kbd:`dp` - - Used as in vim diff mode - -Save and quit, or use :kbd:`:MergetoolStop`. - -.. _vimdiffenhanced: - -``vim-diff-enhanced`` -~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2019-02-27 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/vim-diff-enhanced.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/vim-diff-enhanced.lua - :language: lua - -`vim-diff-enhanced `_ provides -additional diff algorithms that work better on certain kinds of files. If your -diffs are not looking right, try changing the algorithm with this plugin: - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`:EnhancedDiff ` - - Configure the diff algorithm to use, see below table - - -The following algorithms are available: - -.. list-table:: - :header-rows: 1 - :align: left - - * - algorithm - - description - - * - myers - - Default diff algorithm - - * - default - - alias for `myers` - - * - minimal - - Like myers, but tries harder to minimize the resulting diff - - * - patience - - Patience diff algorithm - - * - histogram - - Histogram is similar to patience but slightly faster - -.. _vimtablemode: - -``vim-table-mode`` -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2019-03-27 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/vim-table-mode.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/vim-table-mode.lua - :language: lua - -`vim-table-mode `_ provides -easy formatting of tables in Markdown and Restructured Text - -Nice Markdown tables are a pain to format. This plugin makes it easy, by -auto-padding table cells and adding the header lines as needed. - -* With table mode enabled, :kbd:`||` on a new line to start the header. -* Type the header, separated by :kbd:`|`. -* On a new line, use :kbd:`||` to fill in the header underline. -* On subsequent rows, delimit fields by :kbd:`|`. -* Complete the table with :kbd:`||` on a new line. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`:TableModeEnable` - - Enables table mode, which makes on-the-fly adjustments to table cells - as they're edited - - * - :kbd:`:TableModeDisable` - - Disables table mode - - * - :kbd:`:Tableize` - - Creates a markdown or restructured text table based on TSV or CSV text - - * - :kbd:`TableModeRealign` - - Realigns an existing table, adding padding as necessary - -See the homepage for, e.g., using ``||`` to auto-create header lines. - -.. _leap: - -``leap.nvim`` -~~~~~~~~~~~~~ - -.. versionadded:: 2022-12-27 -.. deprecated:: 2024-03-31 - Removed in favor of the :ref:`flash` plugin, which behaves similarly but - also supports treesitter selections - - -.. _flash: - -``flash`` -~~~~~~~~~ - -.. versionadded:: 2024-03-31 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/flash.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/flash.lua - :language: lua - -`flash `__ lets you jump around in a buffer with low mental effort. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`Ctrl-s` when searching - - Toggle flash during search - - * - :kbd:`s` in normal mode - - jump to match (see details) - - * - :kbd:`S` in normal mode - - select this treesitter node (see details) - -When searching with :kbd:`/` or :kbd:`?`, **an additional suffix letter will be -shown after each match**. Typing this additional letter lets you jump right to -that instance. - -Or just hit :kbd:`Enter` like normal to do a typical search. - -Either way, :kbd:`n` and :kbd:`N` for next/prev hit work as normal. - -With :kbd:`s`, this changes the syntax highlighting to hide everything but the -search hit and the suffix. - -With :kbd:`S`, if a treesitter parser is installed for this filetype, suffix -letters will be shown at different levels of the syntax tree. - -For example, :kbd:`S` within an R for-loop within an RMarkdown chunk will show -suffixes to type that will select the inner body of the for-loop, the entire -for-loop, or the entire body of the chunk. If you wanted to select the -backticks as well, you could use :kbd:`S` when on the backticks. - - -.. _vimsurround: - -``vim-surround`` -~~~~~~~~~~~~~~~~ - -.. versionadded:: 2022-12-27 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/vim-surround.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/vim-surround.lua - :language: lua - -`vim-surround `_ lets you easily change -surrounding characters. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - - * - :kbd:`cs"'` - - change surrounding ``"`` to ``'`` - - * - :kbd:`csw}` - - add ``{`` and ``}`` surrounding word - - * - :kbd:`csw{` - - same, but include a space - -.. _vis_ref: - -``vis`` -~~~~~~~ - -.. versionadded:: 2019-09-30 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/vis.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/vis.lua - :language: lua - -`vis `_ provides better behavior on visual -blocks. - -By default in vim and neovim, when selecting things in visual -block mode, operations (substitutions, sorting) operate on the entire line -- -not just the block, as you might expect. However sometimes you want to edit -just the visual block selection, for example when editing TSV files. - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - * - :kbd:``, then use :kbd:`:B` instead of :kbd:`:` - - Operates on visual block selection only - -.. _bufferline: - -``bufferline.nvim`` -~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2023-11-01 - -.. versionchanged:: 2024-09-01 - - Changing to default style since newer versions of nvim add additional, currently-unstyled elements - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/bufferline.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/bufferline.lua - :language: lua - -`bufferline.nvim `_ provides the -tabs along the top. - - -.. list-table:: - :header-rows: 1 - :align: left - - * - command - - description - * - :kbd:`b`, then type highlighted letter in tab - - Switch to buffer - -.. _diffview: - -``diffview.nvim`` -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2023-10-11 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/diffview.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/diffview.lua - :language: lua - -`diffview.nvim `_ supports viewing -diffs across multiple files. It also has a nice interface for browsing previous -commits. - -I'm still figuring out when it's better to use this, fugitive, or gitsigns. - -.. seealso:: - - :ref:`vimfugitive`, :ref:`gitsigns_ref`, :ref:`vimgv`, and :ref:`diffview` are other complementary plugins for working with Git. - -See the homepage for details. - -.. list-table:: - - * - command - - description - - * - ``:DiffviewOpen`` - - Opens the viewer - - * - ``:DiffviewFileHistory`` - - View diffs for this file throughout git history - -.. _conform: - -``conform`` -~~~~~~~~~~~ - -.. versionadded:: 2024-03-31 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/conform.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/conform.lua - :language: lua - -`conform `__ runs style formatters on -the current buffer. - -For example, if ``black`` is avaiable it will run that on the code, but in -a way that the changes can be undone (in contrast to running ``black`` -manually on the file, which overwrites it). - -.. list-table:: - - * - command - - description - - * - :kbd:`cf` - - Run configured formatter on buffer (mnemonic: [c]ode [f]ormat) - -You can install formatters via :ref:`mason`; search -:file:`.config/nvim/lua/plugins.lua` for ``conform.nvim`` to see the -configuration. - -For example, for Python I have ``isort`` and ``black``; for Lua, ``stylua``; for -bash, ``shfmt``. - -.. _lualine_ref: - - -``lualine`` -~~~~~~~~~~~ - -.. versionadded:: 2023-11-01 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/lualine.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/lualine.lua - :language: lua - -`lualine `_ provides the status line along the bottom. - -No additional commands configured. - -.. _indentblankline: - -``indent-blankline`` -~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2023-10-15 - -.. versionchanged:: 2024-09-01 - - Exclude entirely for markdown and ReStructured Text filetypes - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/indent-blankline.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/indent-blankline.lua - :language: lua - -`indent-blankline `_ -shows vertical lines where there is indentation, and highlights one of these -vertical lines to indicate the current `scope -`_. - -No additional commands configured. - -.. _vimpythonpep8indent: - -``vim-python-pep8-indent`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2017 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/vim-python-pep8-indent.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/vim-python-pep8-indent.lua - :language: lua - -`vim-python-pep8-indent `_ -auto-indents Python using pep8 recommendations. This happens as you’re typing, -or when you use :kbd:`gq` on a selection to wrap. - -No additional commands configured. - -.. _vimrmarkdown: - -``vim-rmarkdown`` -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2019-02-27 - -.. deprecated:: 2023-11-14 - Removed in favor of treesitter - -.. details:: Deprecation notes - - `vim-rmarkdown `_ provides syntax - highlighting for R within RMarkdown code chunks. Requires both ``vim-pandoc`` - and ``vim-pandoc-syntax``, described below. - - No additional commands configured. - -.. _vimpandoc: - -``vim-pandoc`` -~~~~~~~~~~~~~~ - -.. versionadded:: 2019-02-27 - -.. deprecated:: 2023-11-14 - Removed in favor of treesitter - -.. details:: Deprecation notes - - `vim-pandoc `_ Integration with - `pandoc `_. Uses vim-pandoc-syntax (see - below) for syntax highlighting. - - Includes folding and formatting. Lots of shortcuts are defined by this plugin, - see ``:help vim-pandoc`` for much more. - - No additional commands configured. - -.. _vimpandocsyntax: - -``vim-pandoc-syntax`` -~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2019-02-27 - -.. deprecated:: 2023-11-14 - Removed in favor of treesitter - -.. details:: Deprecation notes - - `vim-pandoc-syntax `_ is used - by vim-pandoc (above). It is a separate plugin because the authors found it - easier to track bugs separately. - - No additional commands configured. - -.. _vimtmuxclipboard: - -``vim-tmux-clipboard`` -~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2016 - -.. deprecated:: 2024-10-14 - Removed because OSC 52 support in modern terminals/tmux/nvim makes things - much easier for handling copy/paste. See :ref:`tmuxcopy`. - -.. details:: Deprecation notes - - Removed because OSC 52 support in modern terminals/tmux/nvim makes things - much easier for handling copy/paste. See :ref:`tmuxcopy`. - - `vim-tmux-clipboard `_ - automatically copies yanked text from vim into the tmux clipboard. Similarly, - anything copied in tmux makes it into the vim clipboard. - - See this `screencast `_ for - usage details. Note that this also requires the `vim-tmux-focus-events - `_ plugin. You'll need - to make sure ``set -g focus-events on`` is in your :file:`.tmux.conf`. - - No additional commands configured. - -.. _zenburn: - -``zenburn.nvim`` -~~~~~~~~~~~~~~~~ - -.. versionadded:: 2023-11-01 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/zenburn.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/zenburn.lua - :language: lua - -This uses my fork of https://github.com/phha/zenburn.nvim, which adds addtional -support for plugins and tweaks some of the existing colors to work better. - -No additional commands configured. - -.. _stickybuf_ref: - -``stickybuf.nvim`` -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2024-04-27 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/stickybuf.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/stickybuf.lua - :language: lua - -`stickybuf.nvim `__ prevents text -buffers from opening up inside a terminal buffer. - -No additional commands configured. - -.. _lspprogress: - -``lsp-progress.nvim`` -~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2024-04-27 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/lsp-progress.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/lsp-progress.lua - :language: lua - -`lsp-progress.nvim `__ adds -a status/progress indicator to the lualine (at the bottom of a window) so you -know when it's running. - -No additional commands configured. - -.. _obsidian: - -``obsidian.nvim`` -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2024-09-01 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/obsidian.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/obsidian.lua - :language: lua - -`obsidian.nvim `__ is a plugin -originally written for working with `Obsidian `__ which is a GUI -notetaking app (that uses markdown and has vim keybindings). If you're an -Obsidian user, this plugin makes the experience with nvim quite nice. - -However, after using it for a bit I really like it for markdown files in -general, in combination with the ``render-markdown`` plugin (described below). - -I've been using it to take daily notes. - -Notes on other plugins: - -- ``jakewvincent/mkdnflow.nvim`` was nice for hitting :kbd:`` to open - a linked file and then :kbd:`` to go back. But I realized I needed to - keep the context in my head of where I came from. I prefer having separate - buffers open so I can keep track of that (and buffer navigation helps move - between them). This plugin is also pretty nice for collapsing sections into - fancy headers. But I didn't consider it sufficiently useful to warrant - including and configuring it. -- ``lukas-reineke/headlines.nvim`` had nice section headers, and it had - backgrounds for code blocks. However that ended up having too much visual - noise for my taste. -- ``nvim-telekasten/telekasten.nvim`` has nice pickers for tags and files and - making links, but it was too opinionated for forcing the "telekasten" style - of note-taking. -- - -The mapped commands below use :kbd:`o` ([o]bsidian) as a a prefix. - -.. list-table:: - - * - command - - description - - * - :kbd:`Enter` on any link - - Open the link in a browser (if http) or open the file in a new buffer - - * - :kbd:`od` - - [o]bsidian [d]ailies: choose or create a daily note - - * - :kbd:`os` - - [o]bsidian [s]search for notes with ripgrep - - * - :kbd:`ot` - - [o]bsidian [t]ags finds occurrences of ``#tagname`` across files in directory - - * - :kbd:`on` - - [o]bsidian [n]ew link with a word selected will make a link to that new file - - -.. _rendermarkdown: - -``render-markdown`` -~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2024-09-01 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/render-markdown.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/render-markdown.lua - :language: lua - -`render-markdown -`__ provides -a nicer reading experience for markdown files. This includes bulleted list and -checkbox icons, fancy table rendering, colored background for code blocks, and -more. - -In my testing I found it to be more configurable and performant than the -``obsidian.nvim`` equivalent functionality, and in ``daler/zenburn.nvim`` I've -added highlight groups for this plugin. - -Some notes about its behavior: - -- It uses "conceal" functionality to replace things like ``-`` (for bulleted - lists) with the unicode ``•``. It hides URLs and only shows the link text - (like a website does) -- It's configured to differentiate between a web link (http) and an internal - link (no http) and show an icon for an internal link. -- It has functionality for parsing headlines and making them stand out more in - a document. The actual styling of headlines is configured in the colorscheme. -- Code blocks have an icon indicating their language, and the background of - code blocks is different from surrounding text. -- Tables are rendered nicely - -This plugin is **specifically disabled for RMarkdown files**, which are -typically heavy on the source code, and the background of code chunks can get -distracting when entering and exiting insert mode. However, this plugin can be -useful when reviewing a long RMarkdown file to focus on the narrative text. - -.. list-table:: - - * - command - - description - - * - :kbd:`rm` - - Toggle [r]ender[m]arkdown on an [r][m]arkdown file - - - -``nvim-colorizer`` -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2024-09-01 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/nvim-colorizer.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/nvim-colorizer.lua - :language: lua - -`nvim-colorizer `__ is -a high-performance color highlighter. It converts hex codes to their actual -colors. - - -.. list-table:: - - * - command - - description - - * - ``ColorizerToggle`` - - Toggle colorizing of hex codes - - -``browsher.nvim`` -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2024-12-15 - -.. details:: Config - - This can be found in :file:`.config/nvim/lua/plugins/browsher.lua`: - - .. literalinclude:: ../.config/nvim/lua/plugins/browsher.lua - :language: lua - -`browsher.nvim `_ constructs a URL -for GitHub or GitLab that includes line highlighting, based on your visual -selection. - -It is currently configured to store the URL on your OS clipboard, which makes -it useful for working on remote systems. However, you can comment out the -``open_cmd`` config option if you want it to automatically open a browser tab. - -It is also currently configured to optionally read from a file stored outside -of a dotfiles repo, for example to support the construction of URLs for private -GitHub/GitLab instances. See the config file -:file:`.config/nvim/lua/plugins/browsher.lua` for details. - -.. list-table:: - - * - command - - description + * - :kbd:`z=` + - Show spelling suggestions - * - ``Browsher`` - - Store URL on OS clipboard +.. details:: Line coloring and cursor -Colorschemes ------------- + See :file:`.config/nvim/lua/config/options.lua` for the ``set cul`` and ``set nocul`` options and set to your liking -For years I've been using the venerable *zenburn* colorscheme. However, now -with additional plugins and highlighting mechansims (especially treesitter), it -became important to be able to configure more than what that colorscheme supported. +Plugin documentation +-------------------- -The `zenburn.nvim `_ repo was a reboot of -this colorscheme, but there were some parts of it that I wanted to change, or -at least have more control over. Hence `my fork of the repo -`_, which is used here. If you're -interested in tweaking your own colorschemes, I've hopefully documented that -fork enough to give you an idea of how to modify on your own. +See the separate section :ref:`plugins` for documentation. diff --git a/setup.sh b/setup.sh index 68029d2..e712bba 100755 --- a/setup.sh +++ b/setup.sh @@ -22,7 +22,7 @@ set -eo pipefail # Change tool versions here VISIDATA_VERSION=2.11 HUB_VERSION=2.14.2 -NVIM_VERSION=0.10.1 +NVIM_VERSION=0.10.4 RG_VERSION=13.0.0 BAT_VERSION=0.19.0 JQ_VERSION=1.6 @@ -84,9 +84,11 @@ function showHelp() { printf "${YELLOW}Usage:${UNSET}\n\n" echo " $0 [ARGUMENT]" echo - echo " - Options are intended to be run one-at-a-time." - echo " - Each command will prompt if you want to continue." - echo " - Set the env var DOTFILES_FORCE=true if you want always say yes." + echo " Options are intended to be run one-at-a-time." + echo " Each command will prompt if you want to continue." + echo " Environment variables:" + echo " - DOTFILES_FORCE=true to all confirmation prompts" + echo " - CONDA_INSTALLATION_DIR=/path/to/dir: Custom installation location for conda" echo printf " ${BLUE}Documentation: https://daler.github.io/dotfiles/${UNSET}\n" echo @@ -451,25 +453,19 @@ elif [ $task == "--install-docker" ]; then echo "Please log out and then log back in again to be able to use docker as $USER instead of root" elif [ $task == "--install-conda" ]; then - ok "Installs conda using the Miniforge installation" + MINIFORGE_DIR=${CONDA_INSTALLATION_DIR:-"$HOME/miniforge"} + ok "Installs conda using the Miniforge installation to $MINIFORGE_DIR. Set CONDA_INSTALLATION_DIR to change." + printf "${YELLOW}Installing Miniforge to: ${MINIFORGE_DIR}${UNSET}\n" - # On Biowulf/Helix, if we install into $HOME then the installation might - # larger than the quota for the home directory. Instead, install to user's - # data directory which has much more space. - # Also, .path needs to reflect this change. - MINIFORGE_DIR=$HOME/miniforge - if [[ $HOSTNAME == "helix.nih.gov" || $HOSTNAME == "biowulf.nih.gov" ]]; then - MINIFORGE_DIR=/data/$USER/miniforge + mkdir -p $(dirname $MINIFORGE_DIR) - # Newer versions of the installer cannot run from a noexec directory - # which may be the case on some hosts. See discussion at - # https://github.com/ContinuumIO/anaconda-issues/issues/11154#issuecomment-535571313 - export TMPDIR=/data/$USER/miniforge + download "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" miniforge.sh - fi + # Newer versions of the installer cannot run from a noexec directory + # which may be the case on some hosts. See discussion at + # https://github.com/ContinuumIO/anaconda-issues/issues/11154#issuecomment-535571313 + TMPDIR=$MINIFORGE_DIR bash miniforge.sh -b -p $MINIFORGE_DIR - download "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" miniforge.sh - bash miniforge.sh -b -p $MINIFORGE_DIR rm miniforge.sh echo "export PATH=\$PATH:$MINIFORGE_DIR/condabin" >> ~/.path printf "${YELLOW}conda installed at ${MINIFORGE_DIR}/condabin. This has been added to your ~/.path file, but you should double-check to make sure it gets on your path. You may need to close and then reopen your terminal.${UNSET}\n" @@ -523,10 +519,10 @@ elif [ $task == "--install-neovim" ]; then mkdir -p "$HOME/opt/bin" mv nvim-macos-*64 "$HOME/opt/neovim" else - download https://github.com/neovim/neovim/releases/download/v${NVIM_VERSION}/nvim-linux64.tar.gz nvim-linux64.tar.gz - tar -xzf nvim-linux64.tar.gz - mv nvim-linux64 "$HOME/opt/neovim" - rm nvim-linux64.tar.gz + download https://github.com/neovim/neovim/releases/download/v${NVIM_VERSION}/nvim-linux-x86_64.tar.gz nvim-linux-x86_64.tar.gz + tar -xzf nvim-linux-x86_64.tar.gz + mv nvim-linux-x86_64 "$HOME/opt/neovim" + rm nvim-linux-x86_64.tar.gz fi ln -sf ~/opt/neovim/bin/nvim ~/opt/bin/nvim printf "${YELLOW}- installed neovim to $HOME/opt/neovim${UNSET}\n"