neovim + offpunk amusement

tl; dr: I made a neovim plugin that calls offpunk to render page content in the current buffer. For the time being I’ve named the project neopunk as it was the obvious portmanteau of neovim and offpunk. But I don’t know that I’ll be keeping the name if I do keep the plugin. For now it’s an amusement, but it has some interesting potential.

the backstory

There was a thread going on in the offpunk devel list about using cat as the pager (as an option instead of less). A new user thought it would be a nice option, and coincidentally it was actually the very first change I made to my local checkout of offpunk. Except their solution was quite a bit cleaner than mine, as mine was an ugly hack to just replace the call to less.

My motivation for it was that I wanted the entire page content dumped to the screen at all times and I would use a pager after the fact. I’d just hit the tmux keybinding to enter copy-mode. This worked pretty well, and I used it for a few days. But then I started finding more capsules and wouldn’t you know it, some of them were long. There are one or two that are thousands of links in a page long. Using copy mode started to lose the allure while browsing these. But I still kind of liked it for a lot of places.

Anyway, I stopped using it because I couldn’t think of an elegant way to keep it and I really wanted to try out some other features, so I just smashed it when I merged something else later.

a little more backstory

That change plus using tmux got me closer to one of the ways I like to take notes. But it wasn’t quite all the way there. Copy-mode in tmux is nice, but it’s a bit clunky to move between that and neovim. Yes, I can run neovim on one side and a gemini browser on the other, but then there’s the awkwardness of lining up the content and dealing with paging… it’s nicer to just slurp a target page into neovim and then trim it down from that.

So I tried calling things like bollux, gmni, and offpunk straight from within neovim. And this actually wasn’t as awkward as it might sound. While gmni and bollux both produce nice looking renderings of gemini pages, and they could be used just as easily, offpunk coincidentally indents things at exactly the level needed for it to be considered markdown pre-formatted text. And I take all my notes in markdown. So for a while, I manually invoked offpunk to slurp up pages from within neovim where I could then reference them later or just start hacking them up and inserting content in the middle of them.

But that was still a tiny bit awkward. So I didn’t use it very much. (Offpunk recently got the option to send the entire page content to the tmux clipboard, which is pretty nice, too, but it’s the source and not the rendered version. – I’ve just been informed that it can do that, too, with copy raw.)

before the mailing list

So, I still didn’t use the feature too much. I had multiple paths to get stuff from gemini into a note, either copying from offpunk or invoking offpunk from neovim, but it was kind of awkward. I did kind of write my own gemini client and not really tell anyone about it, which would pretty much render visited pages in their markdown equivalent format with reference links and ansi-escaped color, and I kind of started using that from within neovim. How crazy is that? Offpunk can dump links at the end of a page to provide the urls for navigating to other content, but I didn’t happen to know the option off the top of my head and I needed a space to try out features before I tried to port them into offpunk, so I had made my own client and I used it for this, too.

But it was still a little awkward to run, it didn’t reduce the friction between having a link and being able to navigate to it, all while in neovim, without having to enter some extra syntactical nonsense.

then the mailing list

So the when the cat topic came up on the mailing list and I stopped lurking and shared a tiny piece of how I used offpunk, I revisited my approach. Ploum pointed out that openk might make a better thing to invoke, and pointed out the option for dropping the links as references at the end, so I gave that a try. And that worked well. Nice colors, nice formatting, and the links were dumped at the end so I could easily jump to them in case I waned to navigate further or just so I had them preserved in my notes.

after that, it was only a matter of time

Then I thought maybe some other crazy person might want to be able to call offpunk from within neovim. Maybe they might be able to appreciate the aesthetic beauty of ansi escaped renderings in their favorite editor. And if not, it would at least get me more familiar with neovim plugin creation. Ideally such a thing would make it easy to:

quickly grab a gemini page without goofy syntactic hurdles of :read !
lend itself to ansi colors via ansi.nvim
dump rendered content into preformatted blocks for unmolested ansi color
leverage markdown for headings and other editor features (like automatic table of contents)

So that is what I made.

Why Markdown?

My gemini client produced markdown-looking output with markdown style reference links and it seemed appropriate. Then it kind of justified itself after the fact because everything that looks like markdown folds into my markdown note taking stuff so well.

Fetching a page makes a new H1 heading with the title that was associated with the link. Outline.nvim gives me an automatic table of contents, so I can fetch a link while reading a page’s content and then I can jump to it from the outline. This lined up really well with what offpunk was doing, so I plugged in offpunk for similar results.

The rendered content is indented so that it wont be further interpreted or otherwise messed with. This makes it ideal for slicing it up in any way to insert annotations between lines or in the margins. Or I can leave it as it is and if it uses ansi colors, they wont be ripped out by an egregious linter/formatter.

What’s this talk of your own gemini client?

Ignore that. I’m using offpunk in this addon and it works just fine. In fact, <Leader>. can be used on the first occurrence of a link in the context of the rendered document, and the addon will seek out the dumped list of links at the end of the document, extract the link address, and use the title from the link to name a new H1 section in the document and put the content there. I specifically target the way offpunk styles the output. And you can also jump from the link at the end of the document, too.

Also, it’s using openk and that can deal with more file types than my barely functional gemini client can. Remember, my client only existed to toy with features so that I could then add them to offpunk later.

What else can it do?

It can fetch pages from raw links, markdown reference links, or via a :Go command. The page will be fetched and appended to the current document. I had experimented with making it jump immediately to the new section, but I ended up not wanting that behavior. It worked better to have it shove that content at the bottom of the page so I could fetch a bunch of pages and then go review them. For each page it fetches, if it did it from a context that it had a title for that page, then the page title goes into an H1. If there is no title, it will just produce the link.

But doesn’t that defeat the purpose of a tour?

I’m not suggesting anyone try to use neovim for their complete browsing experience. Offpunk’s tour feature is really cool and offpunk caches everything, you can actually use this addon to render your cache which you’ve just synced based on what’s in your tour. It’s really just a convenient scratch space for holding on to a collection of renders from offpunk. Hm, maybe I should have made a way to add something to the tour from within neovim.

Where is it?

It can be cloned from here:

https://git.thatit.be/neopunk.nvim.git

But I prefer loading things with Lazy, so this can go into a spec in the lazy plugins:

{
    "https://git.thatit.be/neopunk.nvim.git",
    ft = "markdown",
},

Note that I set the filetype to Markdown because my notes are in markdown and that’s where I typically call it. It does do a few markdownish things (though it’s gemini compatible, they’re just headers.)

Or if you want a different keybinding than <Leader>. or you want to use a different program than openk:

{
  "https://git.thatit.be/neopunk.nvim.git",
  config = function()
    require("neopunk").setup({
      key = "<Leader>.",
      execute_command = "openk.py --linkmode=end %s", -- %s receives the link
    })
  end
}

I also have ansi.nvim so I can render the escape sequences according to the offpunk theme, again, using lazy:

{
    "0xferrous/ansi.nvim",
    config = function()
        require("ansi").setup({
            theme = "gruvbox",
            auto_enable = true,
            filetypes = { "log", "ansi" },
        })
    end,
},

I generally toggle it on with :AnsiEnable depending on my mood or purpose.

I also use Outline.nvim which I can toggle for a convenient table of contents.

Tags: index, neovim, offpunk