Neovim Telescope for links

tl;dr: I found a nifty plugin that makes it possible to use Telescope to insert file paths. It does it by way of Telescope actions and I couldn’t figure out how the hell to actually invoke the damn thing. Eventually I got it, and I prefer it now for making links in Markdown or just grabbing file paths.

Background

I have two Neovim plugins that enhance the markdown experience. Whether that enhancement is positive or negative depends on my mood. One of them is obsidian.nvim – I don’t have anything to for making back links in my setup and obsidian.nvim provides that (among many, many, many other features). But that’s the feature I’ve been keeping it around for.

I made a bunch of script edits to my Python processing script for my capsule not too long ago. I made it generate symlinks with tags and titles (my usual file names are date and time based) to my notes and I now run it on document save. This lets me browse a somewhat shallow file hierarchy if I want to explore my notes by tag or title from the file system. Or I can pop open a neo-tree file viewer to the side and browse notes by tag or title. But I don’t have a convenient way to display back links. That’s the biggest reason I keep the obsidian.nvim plugin around, so I can easily pop up a list of back links in case I want to explore notes that link to the note I’m viewing.

The other plugin is MeanderingProgrammer’s markdown plugin for which I documented a frustration with the conceallevel settings where I was using the wrong value, but that wasn’t public (before now). That vaguely mentions the markdown plugin. Documenting frustrations seems pretty popular with me, the obsidian.nvim note is also an instance where I wanted the obsidian plugin to not do formatting to my YAML headers. So I ended up writing a note on how I configured it so I wouldn’t forget (or could look it up) later.

obsidian.nvim

MeanderingProgrammer’s markdown plugin

Using It

Anyway, where was I? The plugin is on Github, kiyoon/telescope-insert-path.nvim and it provides some simple actions that can be fired of to insert paths in visual or normal mode, using partial relative paths, or absolute paths, in front of the cursor, or the line, or after the cursor or after the line…

But I couldn’t figure out how to do it. It was really frustrating. Everyone that had ever used Telescope just understood the parlance of actions and knew that you could fire actions with keystrokes once you had made some selections in Telescope. It took me a while to figure this out.

Installing

I put this in my plugins (take a peek at my [lazy setup] for context):

{
    "kiyoon/telescope-insert-path.nvim",
    config = function()
        local path_actions = require("telescope_insert_path")
        require("telescope").setup({
            defaults = {
                mappings = {
                    n = {
                        -- E.g. Type `[i`, `[I`, `[a`, `[A`, `[o`, `[O` to insert relative path and select the path in visual mode.
                        -- Other mappings work the same way with a different prefix.
                        ["["] = path_actions.insert_reltobufpath_visual,
                        ["]"] = path_actions.insert_abspath_visual,
                        ["{"] = path_actions.insert_reltobufpath_insert,
                        ["}"] = path_actions.insert_abspath_insert,
                        ["-"] = path_actions.insert_reltobufpath_normal,
                        ["="] = path_actions.insert_abspath_normal,
                    },
                },
            },
        })
    end,
},

lazy setup

Process

And then this is how I use it:

1. Fire up any Telescope picker (for example, :Telescope live_grep)

2. Drill down to a choice

3. Hit escape 3.1. (optional) select multiple files with tab

4. Enter one of the bindings – like {a – while still in Telescope

And at step number four, the hilighted file name gets appended to wherever the cursor was in the document.

Additional Uses

The plugin makes it possible to use Telescope to provide a file name or multiple file names and insert them into the current document. Whether this is links in markup or file names in scripts, it’s fairly general purpose.

And it works for any Telescope plugin that drills down to file names. There’s a minor drawback: it doesn’t remove duplicates. If the live grep were being used in Telescope, and it matched more than one file, and you select multiple instances of that file, they will all be dropped into the document. Arguably it should and if that’s not desired, just select the range in visual mode and run :sort -u on it. (Which would look like :'<,'>sort -u because of the selection.)

Speaking of Multiple Selections

I allude to this above in the process, but you can use Telescope to select more than a single file. You hit escape so you can use j and k to move up or down the file list, then hit tab to toggle the selection for whatever is currently under the cursor. When you’re finished, you typically hit enter to do something to all those files, or hit one of the key strokes that fires an action to do something with the list.

Advantage over Obsidian.nvim

The obsidian.nvim plugin kindof/sortof makes it possible to easily link to other documents. It’s very easy to use if you have path completion turned on, and it’s almost identical to using Obsidian. You can double left-bracket and start typing and it will pop up helpful potential targets. Except - the targets aren’t real. They tend to link to headers or key words and those become the link target instead of the target file. If I were only using Obsidian and Neovim to browse my notes, this would be mostly okay. I could still jump to those notes, mostly. If the tag or heading has a collision, Telescope will pop up to allow resolving the collision. That’s okayish – it will keep colliding and keep popping up whenever the link is used. But they’re useless broken links when I generate my Gemini capsule because there are no files to back them.

Tags: telescope, nvim, index

Navigation

index