How to get OSC 8 hyperlinks to work in nvim terminal

[Batkow]

I saw that this commit #27109 (comment) added support for OSC8 hyperlinks and I was wondering how to set up nvim to render them properly like in the demo example showed in the attached link. I was directed to post a question here instead of posting my question directly on the commit.

It seems that I have to set a extmark property for the URL i want to click, but I'm not 100% sure how to do that.

Furthermore, I'm mostly interested in getting commands of the form printf '\e]8;;https://neovim.io\e\\A link to Neovim\e]8;;\e\\\n' to render a clickable link while inside nvim.

[Batkow]

Hi @gpanders! Sorry for tagging you, but since you wrote the commit, would you mind guiding me in the right direction?

[gpanders]

The function you want is nvim_buf_set_extmark() (see :h nvim_buf_set_extmark() for more info).

Assuming you have a buffer in Nvim open with the contents:

A link to Neovim

You can create an OSC 8 hyperlink with the following Lua script:

local ns = vim.api.nvim_create_namespace("my_namespace")
vim.api.nvim_buf_set_extmark(0, ns, 0, 0, { end_col = 16, url = 'https://neovim.io' })

To set an extmark you must first create a namespace (the first line in the script). The arguments to nvim_buf_set_extmark are (1) the buffer number (0 for the current buffer), (2) the namespace to add the extmark to, (3) start row (0 is the first row), (4) start column (0 is the first column), and (4) an options table. In the options table we set end_col to 16 (the length of the line) and teh url property to the URL you want to use.

Note this requires that your terminal supports OSC 8 (not all do). And you will almost certainly need to press or hold some modifier key to have your terminal make the hyperlink clickable (Nvim intercepts mouse events, so you have to use the modifier to tell your terminal to bypass Nvim and click the hyperlink directly). For instance, on iTerm2 I have to hold the Cmd key.

[Batkow]

Hi, thanks for the explanation. I think that I understand the idea behind it better now! Also, yes, I've made sure that my terminal (alacritty) supports the hyperlinks, e.g., when I run printf '\e]8;;https://neovim.io\e\\A link to Neovim\e]8;;\e\\\n' in the terminal, I see that I get a clickable hyperlink!

However, when I add the Lua snippet in my init.vim it throws the following error: E5108: Error executing lua [string ":lua"]:3: Invalid 'end_col': out of range. Setting any end_col!=0 gives the same error.

I am on a fresh build of nvim with tag: nightly, i.e., commit hash: 17c89ea. I've tried also selecting the commit where you first introduced the OSC 8 commit, but I got the same error. Any idea what the reason can be?

I used the following example init.vim

nnoremap <SPACE> <Nop>
let mapleader="\<Space>"

syntax on
set number relativenumber
set noswapfile
set hlsearch
set ignorecase
set incsearch
set tabstop=4
set shiftwidth=4
set softtabstop=4
set expandtab
set noautochdir
set termguicolors

" Copy to clipboard
vnoremap <leader>y "+y

" Source the current file quickly
nnoremap <silent> <leader>src :w<CR>:so %<CR>
nnoremap <silent> <leader>vimrc :e $MYVIMRC<CR>
nnoremap <C-h> <C-w>h
nnoremap <C-l> <C-w>l
nnoremap <C-j> <C-w>j
nnoremap <C-k> <C-w>k
nnoremap <silent> <leader>hl :let @/='\<'.expand('<cword>').'\>'\|set hlsearch<C-M>
vnoremap <silent> <leader>hl y:let @/='<C-R>"'\|set hlsearch<CR>
nnoremap <leader>c :let @+=expand('%')<CR>

" Plugins
call plug#begin('~/.local/share/nvim/site/plugged')
Plug 'voldikss/vim-floaterm'
Plug 'preservim/nerdtree'
Plug 'morhetz/gruvbox'
call plug#end()

colorscheme gruvbox
hi link markdownError colorscheme

" NERDTree settings
let g:NERDTreeShowHidden=1
let g:NERDTreeChDirMode=0
nnoremap <leader><TAB> :NERDTreeToggle<CR>
nnoremap <leader>r :NERDTreeFind<CR>

" Floaterm
function! ToggleFloaterm(insert_mode)
    let g:floaterm_autoinsert=a:insert_mode
    :FloatermToggle
endfunction
nnoremap <silent> <leader>t :call ToggleFloaterm(v:false)<CR>
tnoremap <silent> <C-t> <C-\><C-n>:FloatermToggle<CR>
nnoremap <silent> <C-t> :call ToggleFloaterm(v:true)<CR>
let g:floaterm_width = 0.8

augroup floaterm
    au!
    autocmd FileType floaterm nnoremap <silent> <buffer> gf :call <SID>openInNormalWindow()<CR>
    autocmd FileType floaterm nnoremap <buffer> <silent> gF :call <SID>openInNormalWindowGoToLine()<CR>
augroup END

lua << EOF

local ns = vim.api.nvim_create_namespace("my_namespace")
vim.api.nvim_buf_set_extmark(0, ns, 0, 0, { end_col = 16, url = 'https://neovim.io' })

EOF

Finally, from the example you posted, any OSC8 hyperlink that has "http://neovim.io" will be clickable with this setup. Would it be possible to add regex expressions for the urls, e.g., 'https://example.com/\d\d' to match the url with double digits?

[zeertzjq]

The snippet only works if the first line of the buffer has at least 16 characters, and it makes the first 16 characters of the first line a clickable link to https://neovim.io. It doesn't make anything else clickable.

[bluss]

Here's an easily stated feature request, solving this would solve your issue. (Edit: Or at least I thought so, because you mentioned the cli command printf! But not sure.)

In a regular terminal, if I run this: ls -l --hyperlink=always I get clickable hyperlinks to each file in the listing. (Not ancient GNU coreutils ls supports this).

What is needed to have this work in the terminal emulator in neovim?

In neovim do the following:

:term
i # insert mode
ls -l --hyperlink=always

What we want: clickable hyperlinks in ls output just like in a regular terminal.

[gpanders]

Enabling OSC 8 hyperlinks in the embedded terminal is not yet possible (or at least, not easy). There is a TermRequest autocommand that a plugin could use to handle OSC 8 escape sequences from the embedded terminal, and use nvim_buf_set_extmark to add the URL attribute, but there is no (easy) way to get the position of the text in the terminal buffer from the TermRequest autocommmand.

This would probably need to be done by Nvim itself in core. Feel free to open an issue to track the feature request.

[bluss]

Thanks for chiming in on that! Issue filed at #28789