From 7b3e345a2a9f8430d0e764e9c5b213f8773427fd Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Fri, 18 Sep 2020 21:33:30 +0530 Subject: [PATCH] Document the framework for customizing URL open actions --- docs/changelog.rst | 2 + docs/index.rst | 3 +- docs/kittens/hyperlinked_grep.rst | 3 ++ docs/open_actions.rst | 90 +++++++++++++++++++++++++++++++ 4 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 docs/open_actions.rst diff --git a/docs/changelog.rst b/docs/changelog.rst index 6d1f42054..b6b2d27a9 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -17,6 +17,8 @@ To update |kitty|, :doc:`follow the instructions `. - A new :doc:`kittens/hyperlinked_grep` kitten to easily search files and open the results at the matched line by clicking on them. +- Allow customizing the :doc:`actions kitty takes ` when clicking on URLs + - Improve rendering of borders when using minimal borders. Use less space and do not display a box around active windows diff --git a/docs/index.rst b/docs/index.rst index 2e2eaaa6d..ea7c0fe41 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,8 +12,7 @@ kitty - the fast, featureful, GPU based terminal emulator * Supports all modern terminal features: :doc:`graphics (images) `, unicode, `true-color `_, - OpenType ligatures, mouse protocol, `hyperlinks - `_, + OpenType ligatures, mouse protocol, :doc:`hyperlinks `, focus tracking, `bracketed paste `_ and several :doc:`new terminal protocol extensions `. diff --git a/docs/kittens/hyperlinked_grep.rst b/docs/kittens/hyperlinked_grep.rst index 4a8bf0dd1..dd7428608 100644 --- a/docs/kittens/hyperlinked_grep.rst +++ b/docs/kittens/hyperlinked_grep.rst @@ -43,6 +43,9 @@ You can now run searches with:: hg some-search-term +To learn more about kitty's powerful framework for customizing URL click +actions, :doc:`see here <../open_actions>`. + Hopefully, someday this functionality will make it into some `upstream grep `_ program directly removing the need for this kitten. diff --git a/docs/open_actions.rst b/docs/open_actions.rst new file mode 100644 index 000000000..e79ecfcb4 --- /dev/null +++ b/docs/open_actions.rst @@ -0,0 +1,90 @@ +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 :file:`~/.config/kitty/open-actions.conf` with the following: + +.. code:: conf + + # 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 :kbd:`ctrl+shift`. It will be opened over the current +window. Press any key to close it. + +Each entry in :file:`open-actions.conf` consists of one or more +:ref:`matching_criteria`, such as ``protocol`` and ``mime`` and one or more +``action`` entries. In the example above kitty uses the :doc:`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: + + +.. code:: conf + + # 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: + +``URL`` + The full URL being opened + +``FILE_PATH`` + The path portion of the URL (unquoted) + +``FILE`` + The file portion of the path of the URL (unquoted) + +``FRAGMENT`` + The fragment (unquoted), if any of the URL or the empty string. + +.. _matching_criteria: + +Matching criteria +------------------ + +An entry in :file:`open-actions.conf` must have one or more matching criteria. +URLs that match all criteria for an entry will trigger that entries' 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: + +``protocol`` + A comma separated list of protocols, for example: ``http, https``. If + absent, there is no constraint on protocol + +``url`` + A regular expression that must match against the entire (unquoted) URL + +``has_fragment`` + A boolean (``yes/no``) on whether the URL has a fragment or not. + +``mime`` + A comma separated list of MIME types, for example: ``text/*, image/*, + application/pdf`` + +``ext`` + A comma separated list of file extensions, for example: ``jpeg, tar.gz`` + +``file`` + A shell glob pattern that must match the filename, for example: + ``image-??.png``