Customizing the actions taken when clicking on links¶
kitty has support for terminal hyperlinks. These
are generated by many terminal programs, such as ls, gcc, systemd,
mdcat, etc. You can customize exactly what happens when clicking on these hyperlinks
in kitty.
You can tell kitty to take arbitrarily many, complex actions
when a link is clicked. Let us illustrate with some examples, first. Create
the file ~/.config/kitty/open-actions.conf with the following:
# Open any image in the full kitty window by clicking on it
protocol file
mime image/*
action launch --type=overlay kitty +kitten icat --hold ${FILE_PATH}
Now, run ls --hyperlink=auto in kitty and click on the filename of an
image, holding down ctrl+shift. It will be opened over the current
window. Press any key to close it.
Each entry in open-actions.conf consists of one or more
Matching criteria, such as protocol and mime and one or more
action entries. In the example above kitty uses the launch
action which can be used to run external programs. Entries are separated by
blank lines.
Actions are very powerful, anything that you can map to a key combination in kitty.conf can be used as an action. You can specify more than one action per entry if you like, for example:
# Tail a log file (*.log) in a new OS Window and reduce its font size
protocol file
ext log
action launch --title ${FILE} --type=os-window tail -f ${FILE_PATH}
action change_font_size current -2
In the action specification you can expand environment variables, as shown in the examples above. In addition to regular environment variables, there are some special variables, documented below:
URLThe full URL being opened
FILE_PATHThe path portion of the URL (unquoted)
FILEThe file portion of the path of the URL (unquoted)
FRAGMENTThe fragment (unquoted), if any of the URL or the empty string.
Matching criteria¶
An entry in open-actions.conf must have one or more matching criteria.
URLs that match all criteria for an entry will trigger that entry's actions.
Processing stops at the first matching entry, so put more specific matching
criteria at the start of the list. Entries in the file are separated by blank
lines. The various available criteria are:
protocolA comma separated list of protocols, for example:
http, https. If absent, there is no constraint on protocolurlA regular expression that must match against the entire (unquoted) URL
fragment_matchesA regular expression that must match against the fragment (part after #) in the URL
mimeA comma separated list of MIME types, for example:
text/*, image/*, application/pdf. You can add MIME types to kitty by creating themime.typesin the kitty configuration directory. Useful if your system MIME database does not have definitions you need. This file is in the standard format of one definition per line, like:text/plain rst md.extA comma separated list of file extensions, for example:
jpeg, tar.gzfileA shell glob pattern that must match the filename, for example:
image-??.png