#+TITLE: Neovim installation on WSL2 Debian Sid under Windows 11
#+SUBTITLE:
#+DESCRIPTION:
#+AUTHOR: Tuomas Pyyhtiä
#+EMAIL:
#+DATE:
#+KEYWORDS:
# Export underscore as underscore instead of highlight in HTML:
#+OPTIONS: ^:nil
# Include usable macros from https://github.com/fniessen/org-macros:
#+INCLUDE: ../org-mode/macros/org-macros.setup
#+BEGIN_COMMENT
#+INFOJS_OPT: view:showall ltoc:nil path:https://iki.fi/~pyyhttu/debian/org-mode/js/org-info.js
#+END_COMMENT
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="../org-mode/css/org.css"/>

* Philosophy

I've been using Vim since ~2008, but Neovim has meanwhile gathered a very vibrant plugin community for writing, note taking and task management, which is my main Vim use case.
These are my notes how to set up Neovim to support that.

* Installation

Neovim is [[https://packages.debian.org/search?keywords=neovim][in Debian]] but its latest stable lags several major versions behind
the [[https://github.com/neovim/neovim/releases/tag/stable][upstream
stable]], so installing with [[https://github.com/MordechaiHadad/bob][bob]].

Install dependencies for ~bob~:

~$ sudo aptitude install rustup~

~$ cd ~/sources~

~$ wget https://github.com/MordechaiHadad/bob/releases/download/v2.8.3/bob-linux-x86_64.zip~

~$ unzip bob-linux-x86_64.zip~

~$ cd bob-linux-x86_64/~

~$ chmod +x bob~

~$ ./bob use stable~

Nvim is now installed. Check the release installed:

#+begin_src bash
$ ./bob list
┌────────────────────┬─────────────┐
│  Version           │  Status     │
├────────────────────┼─────────────┤
│  v0.9.5            │  Used       │
└────────────────────┴─────────────┘
#+end_src

And what that release version consists of:

~$ nvim -V1 -v~

#+begin_src bash
NVIM v0.9.5-dev-2947+ge1ca7a7bf
Build type: RelWithDebInfo
LuaJIT 2.1.1710088188
Compilation: /usr/bin/gcc-10 -O2 -g -Og -g -flto=auto -fno-fat-lto-objects -Wall -Wextra -pedantic -Wno-unused-parameter -Wstrict-prototypes -std=gnu99 -Wshadow -Wconversion -Wvla -Wdouble-promotion -Wmissing-noreturn -Wmissing-format-attribute -Wmissing-prototypes -fsigned-char -fstack-protector-strong -Wno-conversion -fno-common -Wno-unused-result -Wimplicit-fallthrough -fdiagnostics-color=always  -DUNIT_TESTING -DHAVE_UNIBILIUM -D_GNU_SOURCE -DINCLUDE_GENERATED_DECLARATIONS -I/home/runner/work/neovim/neovim/.deps/usr/include/luajit-2.1 -I/home/runner/work/neovim/neovim/.deps/usr/include -I/home/runner/work/neovim/neovim/build/src/nvim/auto -I/home/runner/work/neovim/neovim/build/include -I/home/runner/work/neovim/neovim/build/cmake.config -I/home/runner/work/neovim/neovim/src -I/usr/include

   system vimrc file: "$VIM/sysinit.vim"
  fall-back for $VIM: "/usr/local/share/nvim"
#+end_src

Run =:checkhealth= in nvim for more info.
#+begin_note
=:checkhealth= will show warnings, but unless a certain config requires them as dependencies, warnings can be ignored.
#+end_note

Then keep your installation up-to-date:

~$ ./bob update |nightly|stable|--all|~

#+BEGIN_COMMENT
OR install using the latest binary:

,#+BEGIN_SRC bash
$ curl -L -O https://github.com/neovim/neovim/releases/download/stable/nvim-linux64.tar.gz

$ rm -rf "$HOME/sources/neovim"

$ mkdir "$HOME/sources/neovim"

$ tar xzvf nvim-linux64.tar.gz -C "$HOME/sources/neovim"

$ sudo ln -sf "$HOME/sources/neovim/nvim-linux64/bin/nvim" "/usr/bin/nvim"

$ rm "$HOME/sources/neovim/nvim-linux64.tar.gz"
,#+END_SRC
#+END_COMMENT

* Post-installation tasks

** DONE Symlink ~nvim~

So that [[https://github.com/MordechaiHadad/bob?tab=readme-ov-file#%EF%B8%8F-troubleshooting][sudo nvim works]] with bob-installed nvim.

Otherwise ~$ sudo nvim~ gives:
#+begin_src bash
sudo: nvim: command not found
#+end_src


~$ sudo ln -s /home/pyyhttu/.local/share/bob/nvim-bin/nvim /usr/bin/nvim~

** DONE Install a sane config

Here's one to start with:\\

~$ git clone https://github.com/meuter/nvim ~/.config/nvim~

After this you have relatively understandable config under =$XDG_CONFIG_HOME/nvim/lua= you can start tweak further. I've modified it mostly to disable plugins I don't need, and ones I need under =plugins/=:

#+begin_src bash
~/.config/nvim/lua$ tree
.
├── disabled
│   ├── aosp-vim-syntax.lua
│   ├── bufdelete.lua
│   ├── clangd_extensions.lua
│   ├── cmake-tools.lua
│   ├── crates.lua
│   ├── dap-ui.lua
│   ├── dap-virtual-text.lua
│   ├── diffview.lua
│   ├── dressing.lua
│   ├── gitsigns.lua
│   ├── indent-blankline.lua
│   ├── inlay-hints.lua
│   ├── lsp-config.lua
│   ├── lsp-format.lua
│   ├── lsp-zero.lua
│   ├── mason-lspconfig.lua
│   ├── mason.lua
│   ├── mason-nvim-dap.lua
│   ├── mason-tool-installer.lua
│   ├── neodev.lua
│   ├── nibbler.lua
│   ├── rust-tools.lua
│   ├── schemastore.lua
│   ├── toggleterm.lua
│   ├── trouble.lua
│   └── venv-selector.lua
├── plugins
│   ├── catppuccin.lua
│   ├── cmp.lua
│   ├── colorizer.lua
│   ├── lastplace.lua
│   ├── lualine.lua
│   ├── orgmode.lua
│   └── telescope.lua
#+end_src

Here's my =~/.config/nvim/init.lua=.

First install [[https://github.com/folke/lazy.nvim][folke/lazy.nvim]] as your plugin manager.

Then get the plugins and place them at =~/.config/nvim/lua/plugins/=

#+BEGIN_COMMENT
,*** DONE Install kickstart.nvim

First install dependencies:

~$ sudo aptitude install build-essential gcc unzip git make ripgrep fd-find~

Otherwise you will get various [[https://github.com/nvim-treesitter/nvim-treesitter/issues/2811#issuecomment-1583652972][errors]] when nvim sources kickstart's =init.lua= such as: =No C compiler found! "cc", "gcc", "clang", "cl", "zig" are not executable.=

After installing the dependencies, install =kickstart.nvim= by getting its =init.lua=:

~$ git clone https://github.com/nvim-lua/kickstart.nvim.git "${XDG_CONFIG_HOME:-$HOME/.config}"/nvim~

,*** DONE Uninstall kickstart.nvim

If you screw up and want to start over, as per [[https://github.com/folke/lazy.nvim#-uninstalling][instructions]], delete:

    data: ~sudo rm -r ~/.local/share/nvim~ \\
    state: ~rm -r ~/.local/state/nvim~ \\
    lockfile: ~sudo rm -r ~/.config/nvim~ \\
#+END_COMMENT

** DONE Install manual

In order to do ~$ man nvim~:

As neovim binary was installed with ~bob~, the manual [[https://github.com/MordechaiHadad/bob/issues/168][isn't copied]], so remember to [[https://www.baeldung.com/linux/man-pages-manual-install#installing-man-pages-globally][copy the manual]] to its place:

~$ sudo cp ~/.local/share/bob/v0.10.2/share/man/man1/nvim.1 /usr/local/share/man/man1/~

** DONE Install [[https://neovim.io/doc/user/provider.html#clipboard-tool][clipboard support]]

So that copying / pasting into / to nvim works under WSL2 works. There are two ways.

Install first ~xclip~ so that in =:checkhealth= clipboard support is satisfied (OK).

*** win32yank
Easiest way (tested) to do this is with [[https://learn.microsoft.com/en-us/windows/package-manager/winget/][Winget]] and =win32yank=.

Launch =cmd.exe= and issue:

~winget install win32yank~

Then restart Expolorer/computer for {{{kbd(win)}}} -> win32yank is registered as an executable.

After this also mouse right click menu with its copy/paste works, as will {{{kbd("*y)}}}-yanking in visual selection.


See
[[https://www.reddit.com/r/neovim/comments/1e1rtct/comment/lcxp5qu/][this reddit thread]] for more info.

*** clipboard-osc52

*[2024-12-31 Tue]*: Copy to/from WSL neovim also works after added to by =init.lua=:

#+begin_src lua
vim.g.cliboard = {
  name = 'OSC 52',
  copy = {
    ['+'] = require('vim.ui.clipboard.osc52').copy('+'),
    ['*'] = require('vim.ui.clipboard.osc52').copy('*'),
  },
  paste = {
    ['+'] = require('vim.ui.clipboard.osc52').paste('+'),
    ['*'] = require('vim.ui.clipboard.osc52').paste('*'),
  },
}p
#+end_src

#+begin_note
*Note:* This will make copy paste operations [[https://github.com/neovim/neovim/issues/28611][dreadfully slow]], even with workaround, don't implement.
#+end_note


#+BEGIN_COMMENT
,** Plugins

=.config/nvim/lua/plugins/orgmode.lua=:

,#+BEGIN_SRC lua
return {
      "nvim-orgmode/orgmode",
  event = "BufRead", -- replace VeryLazy, otherwise syntax highlighting won't work
  config = function()
    -- Setup orgmode
    require("orgmode").setup({
--    org_agenda_files = "~/orgfiles/**/*",
      org_agenda_files = "~/orgfiles/*",
      org_default_notes_file = "~/orgfiles/refile.org",
    })

    -- NOTE: If you are using nvim-treesitter with `ensure_installed = "all"` option
    -- add `org` to ignore_install
    -- require('nvim-treesitter.configs').setup({
    --   ensure_installed = 'all',
    --   ignore_install = { 'org' },
    -- })
  end,
}
,#+END_SRC

#+END_COMMENT

** DONE Install LuaRocks support for Lazy.nvim

Not strictly needed, but if I have [[https://github.com/folke/lazy.nvim/issues/37][plugins]] that need it.

* Tips

Getting started with Neovim: =:h vimtutor=, vim-adventures.com, =:h usr_toc.txt=.

A good [[https://vim.rtorr.com/][cheatsheet]] for keys.

{{{kbd(Ctrl-c)}}} exits the insert mode, easier than pressing {{{kbd(esc)}}}.

** Command-line usage
As mentioned [[https://www.reddit.com/r/neovim/comments/16bvtr4/what_is_that_command_line_mode_where_i_see_the/][here]]. Invoked with =q:= and by pressing {{{kbd(Ctrl-f)}}}

** Motions for editing
{{{kbd(ca)}}} and {{{kbd(ci)}}} are game-changing. E.g. {{{kbd(ca[)}}} (“change around [”) or {{{kbd(ci()}}} (“change inside (”). They even work when you’re currently inside or outside the bracket/parenthesis/quote/whatever on the same line.


* Troubleshooting

Basically, it's always either your config =~/.config/nvim/init.lua= or plugins =~/.config/nvim/plugins/= causing problems. Problems can be various. Usually it's

- your keymaps not working.

First run nvim without config:\\
~nvim -u NONE~

The plugins are still loaded. If the issue persist, then it is some of your plugins. Disable by bisecting plugins until you find the plugin overriding the keymap.

If you have =whichkey.nvim= installed, you can also do in nvim:

=:checkhealth which-key= and/or if {{{kbd(q)}}} for example does not work (recording does not work) then you can do =:lua print(vim.inspect(vim.api.nvim_get_keymap('q')))= and inspect output and =:messages=.


* Future direction

** DONE =init.vim= vs. =init.lua=

Both config files are [[https://herrbischoff.com/2022/07/neovim-using-init-vim-and-init-lua-concurrently/][not supported]] at the same time, but I can [[https://www.reddit.com/r/neovim/comments/zfimqo/is_it_possible_to_use_initvim_and_initlua_together/]["nest"]] =init.vim= config into =init.lua=, so write config to =init.lua= with that option in mind.

Here's a helpful [[https://neovim.io/doc/user/lua-guide.html][lua-guide]] to get started. There's also [[https://github.com/nvim-lua/kickstart.nvim][kickstart.nvim]] which goes through the config. Here's vhyrro's video on understanding [[https://www.reddit.com/r/neovim/comments/1bh9d3y/vhyrros_understanding_neovim_by_far_the_best/][Neovim]].

** NEXT Go through the old =vimrc= and migrate config to =init.lua=
Pay attention to differences between vim and nvim when going through =.vimrc=. You can see differences by doing =:h vim_diff-txt=.

** NEXT Config: Try relative vs. absolute line numbers
Whether in [[https://www.reddit.com/r/neovim/comments/1euc8mk/how_to_show_relative_line_numbers_in_normal_mode/][insert mode vs. normal mode]].

** NEXT Config: Setup [[https://www.reddit.com/r/neovim/comments/1dhgzw7/how_to_configure_undo_in_neovim/?rdt=48380][persistent undo]]

** NEXT Plugins to experiment
- State "NEXT"       from ""           [2025-03-10 Mon 20:59]
*** DONE nvim-orgmode/orgmode
   CLOSED: [2025-03-16 Sun 17:33]

Syntax highlighting doesn't work until you have org grammar installed. Install with:

=:lua require('orgmode.config'):reinstall_grammar()=

After install run =:checkhealth orgmode= to check everything is working:

#+ATTR_HTML: :width:100%; height:auto;
[[file:images/1.png]]


**** NEXT Troubleshoot slowness with org-mode

Use ~$ nvim --startuptime file notes.org~ and analyze the results. Also run with clean. Document repro steps and open issue to neovim org-mode. Also repeat steps by placing the files to wsl filesystem instead of running them from host file system.

*** WAIT [[https://github.com/nvim-orgmode/orgmode/discussions/810][Telescope-orgmode.nvim]]

*** NEXT [[https://www.reddit.com/r/neovim/comments/1crwprz/orgroamnvim_org_roam_clone_written_in_lua_on_top/][Org-roam.nvim]]

*** DONE [[https://github.com/hamidi-dev/org-list.nvim][org-list.nvim]]

*** NEXT RLDX.nvim
https://github.com/michhernand/RLDX.nvim

*** NEXT csvview.nvim
https://www.reddit.com/r/neovim/comments/1iqaghp/csvviewnvim_is_amazing/?rdt=46637

*** NEXT [[https://www.reddit.com/r/neovim/comments/1elhsxb/been_writing_a_better_grammar_checker_for_neovim/][Harper.nvim]]
[[https://www.reddit.com/r/neovim/comments/1jbbh6e/meet_harper_a_grammarly_alternative_for_neovim/][Introductional video]].

*** NEXT [[https://lobste.rs/s/7idig8/writing_like_pro_with_vale_neovim][Vale]]
For better writing.
*** NEXT [[https://github.com/MiragianCycle/OVIWrite][OVIWrite]]
As this is a whole writing environment, install this on separate bob version.

*** NEXT [[https://www.reddit.com/r/neovim/comments/1hhiidm/a_few_nice_fzflua_configurations_now_that_lazyvim/][fzf-lua]]
Consider using fzf-lua instead of Telescope.

*** NEXT [[https://opensource.com/article/17/2/vim-plugins-writers][Plugins for writers]]

*** NEXT [[https://www.reddit.com/r/neovim/comments/1k2qic0/recordkeynvim_release_v120/][record-key.nvim]]
*** NEXT Plugin and =init.lua= configurations by others

In case you want to search by plugins, or configurations, what others have set up their neovim, head to https://dotfyle.com/
Also https://neovimcraft.com/?search=tag%3Anote-taking and https://github.com/rockerBOO/awesome-neovim?tab=readme-ov-file#note-taking have list of plugins to inspect.

** DONE Try Neovide
#+begin_note
*Note:* Run version 0.12.2 until https://github.com/neovide/neovide/issues/2689 is fixed. Otherwise UNC-paths are not working correctly. Evident e.g. by doing ~$ neovide.exe --wsl ~.bashrc~ and file is opened blank.
#+end_note

Install 0.12.2 neovide.msi from here: https://github.com/neovide/neovide/releases

Then run in wsl ~$ neovide.exe --wsl .bashrc~ to see it works.

In =neovide= doing =:!export= sees my =bob= in =$PATH=.

*[2025-03-15 Sat]*: Neovide is not yet production ready. At least the following issues below needs to be DONE:

*** ONGO setup clipboard support

Mouse right click does work.

[2025-08-04 Mon]: What works from version onwards:
- [X] On windows host select text, {{{kbd(ctrl-c)}}} then inside wsl nvide guest in insert mode: right click and paste works.
- [X] Inside nvide guest in WSL in insert mode select text with mouse and press {{{kbd(y)}}} then right click and paste works. Also pastes to Windows host.
- [] Inserting link after {{{kbd(\oli)}}} does not yet work.

*** NEXT setup link support for mouse

Ctrl + mouse click does not follow links. Test link: https://pyyhttu.kapsi.fi/debian/neovim
[[https://pyyhttu.kapsi.fi/debian/neovim/][Concealed link]].
[2025-08-04 Mon]: Supported but [[https://github.com/neovide/neovide/issues/2649#issuecomment-2162392312][requires configuration]].

*** NEXT setup =config.toml=

For smaller font sizes etc. See what is supported with 0.12.2 config.

Tried with =config.toml= from https://github.com/linkarzu/dotfiles-latest/blob/main/neovide/config.toml placed at =c:\Users\TPyyhtia\AppData\Roaming\neovide\= with =wsl = true= but this configuration file was never read by neovide.
https://www.reddit.com/r/neovim/comments/1anku9o/neovide_app_from_brew_and_nvim_from_bob_in_macos

https://github.com/neovide/neovide/issues/2193#issuecomment-1866729923

*** NEXT Evaluate if neovide is usable
Because I need to revert in =/etc/wsl.conf=:

#+begin_src bash
[interop]
appendWindowsPath = false
#+end_src

Otherwise =$ nvide= in wsl won't work.