mirrors/kitty
1
0
Fork 0
mirror of https://github.com/kovidgoyal/kitty synced 2026-07-24 01:08:10 +02:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Improve the documentation for kittens

Browse Source 
Add more text roles and links.
Add an example that broadcasts only to other windows in the current tab.
Initial capitalization of the key names in the kbd text role.
Add Python type hints for custom kittens.
Note about hyperlink support for ls on macOS.
Add description text for show_key.
This commit is contained in:
pagedown
2022-04-27 15:58:20 +08:00
parent 627c79ffbb
commit 510022c3c1
29 changed files with 374 additions and 336 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/open_actions.rst
View File

@@ -1,15 +1,14 @@
Scripting the mouse click
======================================================
|kitty| has support for `terminal hyperlinks
<https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_. These
are generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on these
hyperlinks in |kitty|.
|kitty| has support for :term:`terminal hyperlinks <hyperlinks>`. These are
generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
:ref:`tool_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:
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
@@ -22,6 +21,13 @@ 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.
.. note::
The :program:`ls` comes with macOS does not support hyperlink, you need to
install `GNU Coreutils <https://www.gnu.org/software/coreutils/>`__. If you
install it via `Homebrew <https://formulae.brew.sh/formula/coreutils>`__, it
will be :program:`gls`.
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 <launch>`
@@ -29,8 +35,8 @@ 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:
:file:`kitty.conf` can be used as an action. You can specify more than one
action per entry if you like, for example:
.. code:: conf
@@ -60,7 +66,7 @@ some special variables, documented below:
.. note::
You can use the :opt:`action_alias` option just as in kitty.conf to
You can use the :opt:`action_alias` option just as in :file:`kitty.conf` to
define aliases for frequently used actions.
@@ -77,7 +83,7 @@ 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
absent, there is no constraint on protocol.
``url``
A regular expression that must match against the entire (unquoted) URL
@@ -88,11 +94,12 @@ lines. The various available criteria are:
``mime``
A comma separated list of MIME types, for example: ``text/*, image/*,
application/pdf``. You can add MIME types to kitty by creating the
:file:`mime.types` in 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``. Note that the MIME type for directories is ``inode/directory``.
application/pdf``. You can add MIME types to kitty by creating a file named
:file:`mime.types` in the :ref:`kitty configuration directory <confloc>`.
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``. Note that the MIME type for directories is
``inode/directory``.
``ext``
A comma separated list of file extensions, for example: ``jpeg, tar.gz``
@@ -116,9 +123,10 @@ URLs onto the kitty dock icon to open them with kitty. The default actions are:
These actions can also be executed from the command line by running::
open -a kitty.app file_or_url ... (on macOS only)
or
kitty +open file_or_url ...
kitty +open file_or_url another_url ...
# macOS only
open -a kitty.app file_or_url another_url ...
Since macOS lacks an official interface to set default URL scheme handlers,
kitty has a command you can use for it. The first argument for is the URL
@@ -133,8 +141,8 @@ defaults to kitty, if not specified. For example:
kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' xyz someapp.bundle.identifier
You can customize these actions by creating a :file:`launch-actions.conf` file
in the kitty config directory, just like
the :file:`open-actions.conf` file above. For example:
in the :ref:`kitty config directory <confloc>`, just like the
:file:`open-actions.conf` file above. For example:
.. code:: conf