diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 32b8f7c1c..c0979d9a7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -76,7 +76,7 @@ jobs: python-version: 3.8 - name: Install build-only deps - run: pip install flake8 mypy types-requests types-docutils sphinx + run: pip install -r docs/requirements.txt flake8 mypy types-requests types-docutils - name: Run pyflakes run: python -m flake8 --count . diff --git a/Makefile b/Makefile index 1db9b9ba7..a82f987af 100644 --- a/Makefile +++ b/Makefile @@ -44,3 +44,7 @@ website: ./publish.py --only website docs: man html + + +develop-docs: + $(MAKE) -C docs develop-docs diff --git a/docs/Makefile b/docs/Makefile index 5f857fa19..f47d6b089 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -18,3 +18,7 @@ help: # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +develop-docs: + sphinx-autobuild --ignore "/home/kovid/work/kitty/docs/generated/*" --watch ../kitty --watch ../kittens -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index d1678db8e..95c4150e2 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -5,118 +5,11 @@ * Distributed under terms of the MIT license. */ -.float-left-img { - float: left; - margin-right: 1em; - margin-bottom: 1em; -} - -.float-right-img { float: right; margin-left: 1em; margin-bottom: 1em } - -.half-with-img { max-width: 50% } - -.fit-img { max-width: 95% } - -div.body { - min-width: 200px; -} - -pre { - white-space: pre-wrap; -} - -pre.pre { - white-space: pre; -} - -a[href], input[type="submit"] { cursor: pointer; } - -img[style] { - /* Used for :scale: images to have them render properly but still popup when clicked */ - width: auto !important; - height: auto !important; -} - -a { - text-decoration: none !important; - border-bottom: none !important; -} - -body div.document { - margin-top: 1ex; +.sidebar-logo { + max-height: 128px; } .major-features li { - margin-top: 0.75ex; margin-bottom: 0.75ex; -} - -.support-form input[type=submit] { - border-radius: 6px; - box-shadow: rgb(255, 246, 175) 0px 1px 0px 0px; - background: linear-gradient(rgb(255, 236, 100) 5%, rgb(255, 171, 35) 100%) rgb(255, 236, 100); - border: 1px solid rgb(255, 170, 34); - display: inline-block; - color: rgb(51, 51, 51); - font-family: Arial; - font-size: 15px; - font-weight: bold; - padding: 6px 24px; - text-decoration: none; - text-shadow: rgb(255, 238, 102) 0px 1px 0px; -} - -.support-form input[type=submit]:hover { - background: linear-gradient(rgb(255, 171, 35) 5%, rgb(255, 236, 100) 100%) rgb(255, 171, 35); -} - -.support-form input[type=submit]:focus { - outline: 0; -} - - -div.sphinxsidebar { - font-size: inherit; - line-height: inherit; - max-height: 100%; - overflow-y: auto; -} - -#sidebartoc li { margin-top: 0.75ex; - margin-bottom: 0.75ex; -} - -#sidebartoc ul { - list-style: none !important; -} - -#sidebartoc a[href]:hover { - color: red; -} - - -.green { - color: green; -} - -.cyan { - color: blue; -} - -.env { - font-style: italic; -} - -.italic { - font-style: italic; -} - -.bold { - font-weight: bold; -} - -.title { - font-size: larger; - font-weight: bold } diff --git a/docs/_templates/base.html b/docs/_templates/base.html new file mode 100644 index 000000000..b9ca3170f --- /dev/null +++ b/docs/_templates/base.html @@ -0,0 +1,19 @@ +{% extends "!base.html" %} +{% block extrahead %} + {{ super() }} + {%- if analytics_id %} + + {% endif -%} +{% endblock %} diff --git a/docs/_templates/localtoc.html b/docs/_templates/localtoc.html deleted file mode 100644 index 655bdb7c4..000000000 --- a/docs/_templates/localtoc.html +++ /dev/null @@ -1,6 +0,0 @@ -{%- if display_toc %} -
 
-
- {{ toc }} -
-{%- endif %} diff --git a/docs/_templates/searchbox.html b/docs/_templates/searchbox.html deleted file mode 100644 index c707c04c5..000000000 --- a/docs/_templates/searchbox.html +++ /dev/null @@ -1,22 +0,0 @@ -{# - basic/searchbox.html - ~~~~~~~~~~~~~~~~~~~~ - - Sphinx sidebar template: quick search box. - - :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. - :license: BSD, see LICENSE for details. -#} -{%- if pagename != "search" and builder != "singlehtml" %} - - -{%- endif %} diff --git a/docs/_templates/support.html b/docs/_templates/support.html deleted file mode 100644 index 43338c62c..000000000 --- a/docs/_templates/support.html +++ /dev/null @@ -1,7 +0,0 @@ -{% if pagename != "support" %} -
-
- -
-
-{% endif %} diff --git a/docs/actions.rst b/docs/actions.rst index 3430296c9..98e476824 100644 --- a/docs/actions.rst +++ b/docs/actions.rst @@ -1,15 +1,9 @@ -:tocdepth: 2 - Mappable actions -=================== +================== .. highlight:: conf The actions described below can be mapped to any key press or mouse action using the ``map`` and ``mouse_map`` directives in :file:`kitty.conf`. -.. contents:: - :local: - :depth: 1 - .. include:: /generated/actions.rst diff --git a/docs/binary.rst b/docs/binary.rst index 723c37de8..49b60a405 100644 --- a/docs/binary.rst +++ b/docs/binary.rst @@ -1,6 +1,9 @@ -kitty - Binary install +Install kitty ======================== +Binary install +---------------- + .. |ins| replace:: curl -L :literal:`https://sw.kovidgoyal.net/kitty/installer.sh` | sh /dev/stdin .. highlight:: sh diff --git a/docs/build.rst b/docs/build.rst index 93e7ad175..85afb96f8 100644 --- a/docs/build.rst +++ b/docs/build.rst @@ -1,5 +1,5 @@ -Building kitty from source -============================== +Build from source +================== .. image:: https://github.com/kovidgoyal/kitty/workflows/CI/badge.svg :alt: Build status @@ -78,8 +78,8 @@ you might have to rebuild the app. .. note:: The released :file:`kitty.dmg` includes all dependencies, unlike the :file:`kitty.app` built above and is built automatically by using the - `_ however, that is designed to - run on Linux and is not for the faint of heart. + `bypy framework `_ however, that is + designed to run on Linux and is not for the faint of heart. .. note:: diff --git a/docs/changelog.rst b/docs/changelog.rst index 21bb21e65..7d5539b7e 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -37,6 +37,8 @@ To update |kitty|, :doc:`follow the instructions `. - Wayland: Fix :opt:`initial_window_width/height ` specified in cells not working on High DPI screens (:iss:`3834`) +- A new theme for the kitty website with support for dark mode. + 0.21.2 [2021-06-28] ---------------------- @@ -1716,8 +1718,7 @@ To update |kitty|, :doc:`follow the instructions `. using standard keyboards) via `IBus `_ (:iss:`469`) -- Implement completion for the kitty command in bash and zsh. See - :ref:`completion`. +- Implement completion for the kitty command in bash and zsh - Render the text under the cursor in a fixed color, configurable via the option :opt:`cursor_text_color` (:iss:`126`) diff --git a/docs/clipboard.rst b/docs/clipboard.rst new file mode 100644 index 000000000..1396f55d4 --- /dev/null +++ b/docs/clipboard.rst @@ -0,0 +1,29 @@ +Pasting to clipboard +======================= + +|kitty| implements the OSC 52 escape code protocol to get/set the clipboard +contents (controlled via the :opt:`clipboard_control` setting). There is one +difference in kitty's implementation compared to some other terminal emulators. +|kitty| allows sending arbitrary amounts of text to the clipboard. It does so +by modifying the protocol slightly. Successive OSC 52 escape codes to set the +clipboard will concatenate, so:: + + ]52;c;\ + ]52;c;\ + +will result in the clipboard having the contents ``payload1 + payload2``. To +send a new string to the clipboard send an OSC 52 sequence with an invalid payload +first, for example:: + + ]52;c;!\ + +Here ``!`` is not valid base64 encoded text, so it clears the clipboard. +Further, since it is invalid, it should be ignored by terminal emulators +that do not support this extension, thereby making it safe to use, simply +always send it before starting a new OSC 52 paste, even if you aren't chunking +up large pastes, that way kitty won't concatenate your paste, and it will have +no ill-effects in other terminal emulators. + +In case you're using software that can't be easily adapted to this +protocol extension, it can be disabled by specifying ``no-append`` to the +:opt:`clipboard_control` setting. diff --git a/docs/color-stack.rst b/docs/color-stack.rst new file mode 100644 index 000000000..c3f8f7fa1 --- /dev/null +++ b/docs/color-stack.rst @@ -0,0 +1,26 @@ +Saving and restoring colors +============================== + +It is often useful for a full screen application with its own color themes to +set the default foreground, background, selection and cursor colors and the +ANSI color table. This allows for various performance optimizations when +drawing the screen. The problem is that if the user previously used the escape +codes to change these colors herself, then running the full screen application +will lose her changes even after it exits. To avoid this, kitty introduces a +new pair of *OSC* escape codes to push and pop the current color values from a +stack:: + + ]30001\ # push onto stack + ]30101\ # pop from stack + +These escape codes save/restore the colors, default +background, default foreground, selection background, selection foreground and +cursor color and the 256 colors of the ANSI color table. + +.. note:: In July 2020, after several years, XTerm copied this protocol + extension, without acknowledgement, and using incompatible escape codes + (XTPUSHCOLORS, XTPOPCOLORS, XTREPORTCOLORS). And they decided to save not + just the dynamic colors but the entire ANSI color table. In the interests of + promoting interoperability, kitty added support for XTerm's escape codes as + well, and changed this extension to also save/restore the entire ANSI color + table. diff --git a/docs/conf.py b/docs/conf.py index 916469027..9dd7a2f95 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,6 @@ from pygments.token import ( # type: ignore Comment, Keyword, Literal, Name, Number, String, Whitespace ) from sphinx import addnodes, version_info # type: ignore -from sphinx.environment.adapters.toctree import TocTree # type: ignore from sphinx.util.logging import getLogger # type: ignore kitty_src = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) @@ -60,8 +59,14 @@ extensions = [ 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', + 'sphinx_copybutton', + 'sphinx_inline_tabs', + "sphinxext.opengraph", ] +# URL for OpenGraph tags +ogp_site_url = 'https://sw.kovidgoyal.net/kitty/' + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -85,13 +90,10 @@ language: Optional[str] = None # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path . exclude_patterns = [ - '_build', 'Thumbs.db', '.DS_Store', + '_build', 'Thumbs.db', '.DS_Store', 'basic.rst', 'generated/cli-*.rst', 'generated/conf-*.rst', 'generated/actions.rst' ] -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - rst_prolog = ''' .. |kitty| replace:: *kitty* .. |version| replace:: VERSION @@ -111,32 +113,23 @@ rst_prolog = ''' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = 'furo' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # -html_theme_options = { - 'logo': 'kitty.png', - 'show_powered_by': False, - 'fixed_sidebar': True, - 'sidebar_collapse': True, - 'github_button': False, - 'github_banner': True, - 'github_user': 'kovidgoyal', - 'github_repo': 'kitty', - # increase contrast of link color with text color - 'link': '#00587d', - 'link_hover': 'green', +html_theme_options: Dict[str, Any] = { + 'sidebar_hide_name': True, + 'navigation_with_keys': True, } # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static', '../logo/kitty.png'] -html_favicon = '../logo/kitty.png' +html_static_path = ['_static'] +html_favicon = html_logo = '../logo/kitty.svg' # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -146,16 +139,8 @@ html_favicon = '../logo/kitty.png' # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', # 'searchbox.html']``. # -html_sidebars = { - '**': [ - 'about.html', - 'support.html', - 'searchbox.html', - 'localtoc.html', - 'relations.html', - ] -} html_show_sourcelink = False +html_show_sphinx = False # -- Options for manual page output ------------------------------------------ @@ -220,28 +205,6 @@ def commit_role(name: str, rawtext: str, text: str, lineno: int, inliner: Any, o # }}} -# Sidebar ToC {{{ -def create_toc(app: Any, pagename: str) -> Optional[Any]: - tt = TocTree(app.env) - toctree = tt.get_toc_for(pagename, app.builder) - if toctree is not None: - subtree = toctree[toctree.first_child_matching_class(nodes.list_item)] - bl = subtree.first_child_matching_class(nodes.bullet_list) - if bl is None: - return None # Empty ToC - subtree = subtree[bl] - # for li in subtree.traverse(nodes.list_item): - # modify_li(li) - # subtree['ids'] = [ID] - return app.builder.render_partial(subtree)['fragment'] - - -def add_html_context(app: Any, pagename: str, templatename: str, context: Any, *args: Any) -> None: - if 'toc' in context: - context['toc'] = create_toc(app, pagename) or context['toc'] -# }}} - - # CLI docs {{{ def write_cli_docs(all_kitten_names: Iterable[str]) -> None: from kitty.cli import option_spec_as_rst @@ -519,6 +482,10 @@ def write_conf_docs(app: Any, all_kitten_names: Iterable[str]) -> None: # }}} +def add_html_context(app: Any, pagename: str, templatename: str, context: Any, *args: Any) -> None: + context['analytics_id'] = app.config.analytics_id + + def setup(app: Any) -> None: os.makedirs('generated/conf', exist_ok=True) from kittens.runner import all_kitten_names @@ -526,10 +493,11 @@ def setup(app: Any) -> None: write_cli_docs(kn) write_remote_control_protocol_docs() write_conf_docs(app, kn) + app.add_config_value('analytics_id', '', 'env') + app.connect('html-page-context', add_html_context) app.add_css_file('custom.css') app.add_lexer('session', SessionLexer() if version_info[0] < 3 else SessionLexer) app.add_role('link', link_role) app.add_role('iss', partial(num_role, 'issues')) app.add_role('pull', partial(num_role, 'pull')) app.add_role('commit', commit_role) - app.connect('html-page-context', add_html_context) diff --git a/docs/conf.rst b/docs/conf.rst index 6dfb3cd6f..17fce5922 100644 --- a/docs/conf.rst +++ b/docs/conf.rst @@ -1,6 +1,4 @@ -:tocdepth: 2 - -Configuring kitty +Configure kitty =============================== .. highlight:: conf @@ -42,7 +40,7 @@ expanded, so :code:`${USER}.conf` becomes :file:`name.conf` if Sample kitty.conf -^^^^^^^^^^^^^^^^^^^^^ +-------------------- .. only:: html @@ -57,3 +55,14 @@ Sample kitty.conf file with full documentation and all settings commented out. If you have a pre-existing kitty.conf, then that will be used instead, delete it to see the sample file. + + +All mappable actions +------------------------ + +See the :doc:`list of all the things you can make kitty can do `. + +.. toctree:: + :hidden: + + actions diff --git a/docs/deccara.rst b/docs/deccara.rst new file mode 100644 index 000000000..04da22958 --- /dev/null +++ b/docs/deccara.rst @@ -0,0 +1,21 @@ +Setting text styles/colors in arbitrary regions of the screen +------------------------------------------------------------------ + +There already exists an escape code to set *some* text attributes in arbitrary +regions of the screen, `DECCARA +`_. However, it is limited to +only a few attributes. |kitty| extends this to work with *all* SGR attributes. +So, for example, this can be used to set the background color in an arbitrary +region of the screen. + +The motivation for this extension is the various problems with the existing +solution for erasing to background color, namely the *background color erase +(bce)* capability. See +`this discussion `_ +and `this FAQ `_ +for a summary of problems with *bce*. + +For example, to set the background color to blue in a +rectangular region of the screen from (3, 4) to (10, 11), you use:: + + [2*x[4;3;11;10;44$r[*x diff --git a/docs/desktop-notifications.rst b/docs/desktop-notifications.rst new file mode 100644 index 000000000..4eb3f7fa3 --- /dev/null +++ b/docs/desktop-notifications.rst @@ -0,0 +1,122 @@ +.. _desktop_notifications: + + +Desktop notifications +======================= + +|kitty| implements an extensible escape code (OSC 99) to show desktop +notifications. It is easy to use from shell scripts and fully extensible to +show title and body. Clicking on the notification can optionally focus the +window it came from, and/or send an escape code back to the application running +in that window. + +The design of the escape code is partially based on the discussion in +the defunct +`terminal-wg `_ + +The escape code has the form:: + + 99 ; metadata ; payload + +Here ```` is :code:`]` and ```` is +:code:``. The metadata is a section of colon separated +:code:`key=value` pairs. Every key must be a single character from the set +:code:`a-zA-Z` and every value must be a word consisting of characters from +the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The payload must be +interpreted based on the metadata section. The two semi-colons *must* always be +present even when no metadata is present. + +Before going into details, lets see how one can display a simple, single line +notification from a shell script:: + + printf '\x1b]99;;Hello world\x1b\\' + +To show a message with a title and a body:: + + printf '\x1b]99;i=1:d=0;Hello world\x1b\\' + printf '\x1b]99;i=1:d=1:p=body;This is cool\x1b\\' + +The most important key in the metadata is the ``p`` key, it controls how the +payload is interpreted. A value of ``title`` means the payload is setting the +title for the notification. A value of ``body`` means it is setting the body, +and so on, see the table below for full details. + +The design of the escape code is fundamentally chunked, this is because +different terminal emulators have different limits on how large a single escape +code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i`` +key is the *notification id* which can be any string containing the characters +``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and +can only take the values ``0`` and ``1``. A value of ``0`` means the +notification is not yet done and the terminal emulator should hold off +displaying it. A value of ``1`` means the notification is done, and should be +displayed. You can specify the title or body multiple times and the terminal +emulator will concatenate them, thereby allowing arbitrarily long text +(terminal emulators are free to impose a sensible limit to avoid +Denial-of-Service attacks). + +Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain +text with no embedded escape codes, or UTF-8 text that is base64 encoded, in +which case there must be an ``e=1`` key in the metadata to indicate the payload +is base64 encoded. + +When the user clicks the notification, a couple of things can happen, the +terminal emulator can focus the window from which the notification came, and/or +it can send back an escape code to the application indicating the notification +was activated. This is controlled by the ``a`` key which takes a comma +separated set of values, ``report`` and ``focus``. The value ``focus`` means +focus the window from which the notification was issued and is the default. +``report`` means send an escape code back to the application. The format of the +returned escape code is:: + + 99 ; i=identifier ; + +The value of ``identifier`` comes from the ``i`` key in the escape code sent by +the application. If the application sends no identifier, then the terminal +*must* use ``i=0``. Actions can be preceded by a negative sign to turn them +off, so for example if you do not want any action, turn off the default +``focus`` action with:: + + a=-focus + +Complete specification of all the metadata keys is in the table below. If a +terminal emulator encounters a key in the metadata it does not understand, +the key *must* be ignored, to allow for future extensibility of this escape +code. Similarly if values for known keys are unknown, the terminal emulator +*should* either ignore the entire escape code or perform a best guess effort +to display it based on what it does understand. + +.. note:: + It is possible to extend this escape code to allow specifying an icon for + the notification, however, given that some platforms, such as macOS, dont + allow displaying custom icons on a notification, at all, it was decided to + leave it out of the spec for the time being. + + Similarly, features such as scheduled notifications could be added in future + revisions. + + +======= ==================== ========= ================= +Key Value Default Description +======= ==================== ========= ================= +``a`` Comma separated list ``focus`` What action to perform when the + of ``report``, notification is clicked + ``focus``, with + optional leading + ``-`` + +``d`` ``0`` or ``1`` ``1`` Indicates if the notification is + complete or not. + +``e`` ``0`` or ``1`` ``0`` If set to ``1`` means the payload is base64 encoded UTF-8, + otherwise it is plain UTF-8 text with no C0 control codes in it + +``i`` ``[a-zA-Z0-9-_+.]`` ``0`` Identifier for the notification + +``p`` One of ``title`` or ``title`` Whether the payload is the notification title or body. If a + ``body``. notification has no title, the body will be used as title. +======= ==================== ========= ================= + + +.. note:: + |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for + desktop notifications. diff --git a/docs/faq.rst b/docs/faq.rst index 3f2ee90ec..0fb09a902 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -3,9 +3,6 @@ Frequently Asked Questions .. highlight:: sh -.. contents:: - :local: - Some special symbols are rendered small/truncated in kitty? ----------------------------------------------------------- @@ -36,7 +33,7 @@ it by adding the following to your vimrc:: let &t_ut='' -See :ref:`here ` for why |kitty| does not support background color erase. +See :doc:`here ` for why |kitty| does not support background color erase. I get errors about the terminal being unknown or opening the terminal failing when SSHing into a different computer? @@ -54,8 +51,6 @@ type it each time:: alias ssh="kitty +kitten ssh" -Remember to also setup :ref:`completion`. - If for some reason that does not work (typically because the server is using a non POSIX compliant shell as ``/bin/sh``), you can try using it with ``python`` instead:: diff --git a/docs/glossary.rst b/docs/glossary.rst index 5961aecc1..0b7c76ecd 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1,3 +1,5 @@ +:orphan: + Glossary ========= diff --git a/docs/graphics-protocol.rst b/docs/graphics-protocol.rst index 444eacc5e..211d21d55 100644 --- a/docs/graphics-protocol.rst +++ b/docs/graphics-protocol.rst @@ -1,18 +1,16 @@ -:tocdepth: 3 - The terminal graphics protocol -================================== +================================= The goal of this specification is to create a flexible and performant protocol that allows the program running in the terminal, hereafter called the *client*, to render arbitrary pixel (raster) graphics to the screen of the terminal -emulator. The major design goals are +emulator. The major design goals are: - * Should not require terminal emulators to understand image formats. - * Should allow specifying graphics to be drawn at individual pixel positions. - * The graphics should integrate with the text, in particular it should be possible to draw graphics - below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically. - * Should use optimizations when the client is running on the same computer as the terminal emulator. +* Should not require terminal emulators to understand image formats. +* Should allow specifying graphics to be drawn at individual pixel positions. +* The graphics should integrate with the text, in particular it should be possible to draw graphics + below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically. +* Should use optimizations when the client is running on the same computer as the terminal emulator. For some discussion regarding the design choices, see `#33 `_. @@ -30,23 +28,19 @@ alpha-blending and text over graphics. Some programs and libraries that use the kitty graphics protocol: - * `termpdf.py `_ - a terminal PDF/DJVU/CBR viewer - * `ranger `_ - a terminal file manager, with - image previews, see this `PR `_ - * :doc:`kitty-diff ` - a side-by-side terminal diff program with support for images - * `pixcat `_ - a third party CLI and python library that wraps the graphics protocol - * `neofetch `_ - A command line system - information tool - * `viu `_ - a terminal image viewer - * `glkitty `_ - C library to draw OpenGL shaders in the terminal with a glgears demo - * `ctx.graphics `_ - Library for drawing graphics - * `timg `_ - a terminal image and video viewer - * `notcurses `_ - C library for terminal graphics with bindings for C++, Rust and Python - * `rasterm `_ - Go library to display images in the the terminal - - -.. contents:: - :local: +* `termpdf.py `_ - a terminal PDF/DJVU/CBR viewer +* `ranger `_ - a terminal file manager, with + image previews, see this `PR `_ +* :doc:`kitty-diff ` - a side-by-side terminal diff program with support for images +* `pixcat `_ - a third party CLI and python library that wraps the graphics protocol +* `neofetch `_ - A command line system + information tool +* `viu `_ - a terminal image viewer +* `glkitty `_ - C library to draw OpenGL shaders in the terminal with a glgears demo +* `ctx.graphics `_ - Library for drawing graphics +* `timg `_ - a terminal image and video viewer +* `notcurses `_ - C library for terminal graphics with bindings for C++, Rust and Python +* `rasterm `_ - Go library to display images in the the terminal Getting the window size diff --git a/docs/index.rst b/docs/index.rst index 50bd9e69e..de977cd80 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,426 +1,66 @@ -:tocdepth: 2 - -========================================================== -kitty - the fast, featureful, GPU based terminal emulator +kitty ========================================================== -.. container:: major-features +*The fast, feature-rich, GPU based terminal emulator* - * Offloads rendering to the GPU for :doc:`lower system load ` and - buttery smooth scrolling. Uses threaded rendering to minimize input latency. +.. toctree:: + :hidden: - * Supports all modern terminal features: :doc:`graphics (images) - `, unicode, `true-color - `_, - OpenType ligatures, mouse protocol, :doc:`hyperlinks `, - focus tracking, `bracketed paste `_ - and several :doc:`new terminal protocol extensions - `. + quickstart + overview + faq + support + performance + changelog + integrations + protocol-extensions - * Supports tiling multiple terminal :term:`windows ` side by side in different - :ref:`layouts ` without needing to use an extra program like tmux - * Can be :doc:`controlled from scripts or the shell prompt `, - even over SSH. +.. tab:: Fast - * Has a framework for :ref:`kittens`, small terminal programs that can be used to - extend |kitty|'s functionality. For example, they are used for - :doc:`Unicode input `, :doc:`Hints ` and - :doc:`Side-by-side diff `. + * Offloads rendering to the GPU for :doc:`lower system load ` + * Uses threaded rendering for absolutely minimal latency + * Performance tradeoffs can be :ref:`tuned ` - * Supports :ref:`startup sessions ` which allow you to specify - the :term:`window`/:term:`tab` layout, working directories and programs to run on startup. +.. tab:: Capable - * Cross-platform: |kitty| works on Linux and macOS, but because it uses only - OpenGL for rendering, it should be trivial to port to other Unix-like platforms. + * Graphics, with :doc:`images and animations ` + * Ligatures and emoji, with :opt:`per glyph font substitution ` + * Hyperlinks, with :doc:`configurable actions ` - * Allows you to open :ref:`the scrollback buffer ` in a - separate :term:`overlay window ` using arbitrary programs of - your choice. This is useful for browsing the history comfortably in a - pager or editor. +.. tab:: Scriptable - * Has :ref:`multiple copy/paste buffers `, like vim. + * Control from :doc:`scripts or the shell ` + * Extend with :ref:`kittens ` using the Python language + * Use :ref:`startup sessions ` to specify working environments + +.. tab:: Composable + + * Programmble tabs, :ref:`splits ` and multiple :doc:`layouts ` to manage windows + * Browse the :ref:`entire history ` or the output from the last command comfortably in pagers and editors + * Edit or download :doc:`remote files ` in an existin SSH session + +.. tab:: Cross-platform + + * Linux + * macOS + * Various BSDs + +.. tab:: Innovative + + Pioneered various extensions to move the entire terminal ecosystem forward + + * :doc:`graphics-protocol` + * :doc:`keyboard-protocol` + * Lots more in :doc:`protocol-extensions` .. figure:: screenshots/screenshot.png :alt: Screenshot, showing three programs in the 'Tall' layout :align: center - :scale: 100% + :width: 100% Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout - -.. contents:: - :local: - :depth: 1 - - -.. _quickstart: - -Quickstart --------------- - -Pre-built binaries of |kitty| are available for both macOS and Linux. -See the :doc:`binary install instructions `. You can also -:doc:`build from source `. - -Additionally, you can use your favorite package manager to install the |kitty| -package, but note that some Linux distribution packages are woefully outdated. -|kitty| is available in a vast number of package repositories for macOS -and Linux. - -.. image:: https://repology.org/badge/tiny-repos/kitty.svg - :target: https://repology.org/project/kitty/versions - :alt: Number of repositories kitty is available in - -See :doc:`Configuring kitty ` for help on configuring |kitty| and -:doc:`Invocation ` for the command line arguments |kitty| supports. - - -Design philosophy -------------------- - -|kitty| is designed for power keyboard users. To that end all its controls -work with the keyboard (although it fully supports mouse interactions as -well). Its configuration is a simple, human editable, single file for -easy reproducibility (I like to store configuration in source control). - -The code in |kitty| is designed to be simple, modular and hackable. It is -written in a mix of C (for performance sensitive parts) and Python (for -easy hackability of the UI). It does not depend on any large and complex -UI toolkit, using only OpenGL for rendering everything. - -Finally, |kitty| is designed from the ground up to support all modern -terminal features, such as unicode, true color, bold/italic fonts, text -formatting, etc. It even extends existing text formatting escape codes, -to add support for features not available elsewhere, such as colored and -styled (curly) underlines. One of the design goals of |kitty| is to be -easily extensible so that new features can be added in the future with -relatively little effort. - -.. include:: basic.rst - -.. _layouts: - -Layouts ----------- - -A :term:`layout` is an arrangement of multiple :term:`kitty windows ` -inside a top-level :term:`OS window `. You can create a new -:term:`window` using the :sc:`new_window` key combination. - -Currently, there are seven layouts available: - -* **Fat** -- One (or optionally more) windows are shown full width on the top, the rest of the windows are shown side-by-side on the bottom -* **Grid** -- All windows are shown in a grid -* **Horizontal** -- All windows are shown side-by-side -* **Splits** -- Windows arranged in arbitrary patterns created using horizontal and vertical splits -* **Stack** -- Only a single maximized window is shown at a time -* **Tall** -- One (or optionally more) windows are shown full height on the left, the rest of the windows are shown one below the other on the right -* **Vertical** -- All windows are shown one below the other - -By default, all layouts are enabled and you can switch between layouts using -the :sc:`next_layout` key combination. You can also create shortcuts to select -particular layouts, and choose which layouts you want to enable/disable, see -:ref:`conf-kitty-shortcuts.layout` for examples. The first layout listed in -:opt:`enabled_layouts` becomes the default layout. - -For more details on the layouts and how to use them see :doc:`layouts`. - -.. _kittens: - -Kittens ------------------- - -|kitty| has a framework for easily creating terminal programs that make use of -its advanced features. These programs are called kittens. They are used both -to add features to |kitty| itself and to create useful standalone programs. -Some prominent kittens: - -:doc:`icat ` - Display images in the terminal - - -:doc:`diff ` - A fast, side-by-side diff for the terminal with syntax highlighting and - images - - -:doc:`Unicode Input ` - Easily input arbitrary unicode characters in |kitty| by name or hex code. - - -:doc:`Hints ` - Select and open/paste/insert arbitrary text snippets such as URLs, - filenames, words, lines, etc. from the terminal screen. - - -:doc:`Remote file ` - Edit, open, or download remote files over SSH easily, by simply clicking on - the filename. - - -:doc:`Hyperlinked grep ` - Search your files using `ripgrep `_ - and open the results directly in your favorite editor in the terminal, - at the line containing the search result, simply by clicking on the result you want. - - -:doc:`Broadcast ` - Type in one :term:`kitty window ` and have it broadcast to all (or a subset) of - other :term:`kitty windows `. - - -:doc:`Panel ` - Draw a GPU accelerated dock panel on your desktop showing the output - from an arbitrary terminal program. - - -:doc:`Clipboard ` - Copy/paste to the clipboard from shell scripts, even over SSH. - -You can also :doc:`Learn to create your own kittens `. - - -Configuring kitty -------------------- - -|kitty| is highly configurable, everything from keyboard shortcuts to -painting frames-per-second. Press :sc:`edit_config_file` in kitty -to open its fully commented sample config file in your text editor. -For details see the :doc:`configuration docs `. - - -Remote control ------------------- - -|kitty| has a very powerful system that allows you to control it from the -:doc:`shell prompt, even over SSH `. You can change colors, -fonts, open new :term:`windows `, :term:`tabs `, set their titles, -change window layout, get text -from one window and send text to another, etc, etc. The possibilities are -endless. See the :doc:`tutorial ` to get started. - -.. _sessions: - -Startup Sessions ------------------- - -You can control the :term:`tabs `, `:term:`kitty window ` layout, -working directory, startup programs, -etc. by creating a "session" file and using the :option:`kitty --session` -command line flag or the :opt:`startup_session` option in :file:`kitty.conf`. -For example: - -.. code-block:: session - - # Set the layout for the current tab - layout tall - # Set the working directory for windows in the current tab - cd ~ - # Create a window and run the specified command in it - launch zsh - # Create a window with some environment variables set and run - # vim in it - launch --env FOO=BAR vim - # Set the title for the next window - launch --title "Chat with x" irssi --profile x - - # Create a new tab (the part after new_tab is the optional tab - # name which will be displayed in the tab bar, if omitted, the - # title of the active window will be used instead) - new_tab my tab - cd ~/somewhere - # Set the layouts allowed in this tab - enabled_layouts tall, stack - # Set the current layout - layout stack - launch zsh - - # Create a new OS window - new_os_window - # set new window size to 80x25 cells - os_window_size 80c 25c - # set the --class for the new OS window - os_window_class mywindow - launch sh - # Make the current window the active (focused) window - focus - launch emacs - -.. note:: - The :doc:`launch ` command when used in a session file - cannot create new OS windows, or tabs. - - -Mouse features -------------------- - -* You can click on a URL to open it in a browser. -* You can double click to select a word and then drag to select more words. -* You can triple click to select a line and then drag to select more lines. -* You can triple click while holding :kbd:`ctrl+alt` to select from clicked - point to end of line. -* You can right click to extend a previous selection. -* You can hold down :kbd:`ctrl+alt` and drag with the mouse to select in - columns. -* Selecting text automatically copies it to the primary clipboard (on - platforms with a primary clipboard). -* You can middle click to paste from the primary clipboard (on platforms - with a primary clipboard). -* You can select text with kitty even when a terminal program has grabbed - the mouse by holding down the :kbd:`shift` key. - -All these actions can be customized in :file:`kitty.conf` as described -:ref:`here `. - - -Font control ------------------ - -|kitty| has extremely flexible and powerful font selection features. You can -specify individual families for the regular, bold, italic and bold+italic -fonts. You can even specify specific font families for specific ranges of -unicode characters. This allows precise control over text rendering. It can -come in handy for applications like powerline, without the need to use patched -fonts. See the various font related configuration directives in -:ref:`conf-kitty-fonts`. - - -.. _scrollback: - -The scrollback buffer ------------------------ - -|kitty| supports scrolling back to view history, just like most terminals. You -can use either keyboard shortcuts or the mouse scroll wheel to do so. However, -|kitty| has an extra, neat feature. Sometimes you need to explore the -scrollback buffer in more detail, maybe search for some text or refer to it -side-by-side while typing in a follow-up command. |kitty| allows you to do this -by pressing the :sc:`show_scrollback` key-combination, which will open the -scrollback buffer in your favorite pager program (which is ``less`` by default). -Colors and text formatting are preserved. You can explore the scrollback buffer -comfortably within the pager. - -Additionally, you can pipe the contents of the scrollback buffer to an -arbitrary, command running in a new :term:`window`, :term:`tab` or :term:`overlay`, -for example:: - - map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting less +G -R - -Would open the scrollback buffer in a new :term:`window` when you press the :kbd:`F1` -key. See :sc:`show_scrollback` for details. - -If you want to use it with an editor such as vim to get more powerful features, -you can see tips for doing so, in -`this thread `_. - -If you wish to store very large amounts of scrollback to view using the piping or -:sc:`show_scrollback` features, you can use the :opt:`scrollback_pager_history_size` -option. - -.. _cpbuf: - -Multiple copy/paste buffers ------------------------------ - -In addition to being able to copy/paste from the system clipboard, in |kitty| you -can also setup an arbitrary number of copy paste buffers. To do so, simply add -something like the following to your :file:`kitty.conf`:: - - map f1 copy_to_buffer a - map f2 paste_from_buffer a - -This will allow you to press :kbd:`F1` to copy the current selection to an -internal buffer named ``a`` and :kbd:`F2` to paste from that buffer. The buffer -names are arbitrary strings, so you can define as many such buffers as you -need. - -Marks -------------- - -kitty has the ability to mark text on the screen based on regular expressions. -This can be useful to highlight words or phrases when browsing output from long -running programs or similar. To learn how this feature works, see :doc:`marks`. - - -Frequently Asked Questions ---------------------------------- - -The list of Frequently Asked Questions (*FAQ*) is :doc:`available here `. - - -Cool integrations for kitty with other CLI tools --------------------------------------------------- - -kitty provides extremely powerful interfaces such as :doc:`remote-control` and -:doc:`kittens/custom` and :doc:`kittens/icat` -that allow it to be integrated with other tools seamlessly. For a list of such -user created integrations, see: :doc:`integrations`. - -.. _completion: - -Completion for kitty ---------------------------------- - -|kitty| comes with completion for the ``kitty`` command for popular shells. - - -bash -~~~~~~~~ - -Add the following to your :file:`~/.bashrc` - -.. code-block:: sh - - source <(kitty + complete setup bash) - -Older versions of bash (for example, v3.2) do not support -process substitution with the source command, in which -case you can try an alternative: - -.. code-block:: sh - - source /dev/stdin <<<"$(kitty + complete setup bash)" - - -zsh -~~~~~~~~~ - -Add the following to your :file:`~/.zshrc` - -.. code-block:: sh - - autoload -Uz compinit - compinit - # Completion for kitty - kitty + complete setup zsh | source /dev/stdin - -The important thing above is to make sure the call to |kitty| to load the zsh -completions happens after the call to :file:`compinit`. - - -fish -~~~~~~~~ - -For versions of fish earlier than 3.0.0, add the following to your -:file:`~/.config/fish/config.fish`. Later versions source completions by default. - -.. code-block:: sh - - kitty + complete setup fish | source - - -Changelog ------------------- - -See :doc:`changelog`. - -.. toctree:: - :hidden: - :glob: - - * - kittens/* - generated/rc +To get started see :doc:`quickstart`. diff --git a/docs/invocation.rst b/docs/invocation.rst index bdb7da92d..cacbcf380 100644 --- a/docs/invocation.rst +++ b/docs/invocation.rst @@ -1,3 +1,5 @@ +:orphan: + The kitty command line interface ==================================== diff --git a/docs/keyboard-protocol.rst b/docs/keyboard-protocol.rst index 7aae1ba7a..e884fafea 100644 --- a/docs/keyboard-protocol.rst +++ b/docs/keyboard-protocol.rst @@ -1,5 +1,5 @@ -A protocol for comprehensive keyboard handling in terminals -================================================================= +Comprehensive keyboard handling in terminals +============================================== There are various problems with the current state of keyboard handling in terminals. They include: diff --git a/docs/kittens/diff.rst b/docs/kittens/diff.rst index 6356ba115..25a99dbc2 100644 --- a/docs/kittens/diff.rst +++ b/docs/kittens/diff.rst @@ -1,6 +1,8 @@ -kitty-diff - A fast side-by-side diff tool with syntax highlighting and images +kitty-diff ================================================================================ +*A fast side-by-side diff tool with syntax highlighting and images* + .. highlight:: sh Major Features @@ -21,13 +23,10 @@ Major Features .. figure:: ../screenshots/diff.png :alt: Screenshot, showing a sample diff :align: center - :scale: 100% + :width: 100% Screenshot, showing a sample diff -.. contents:: - :local: - Installation --------------- @@ -121,8 +120,8 @@ Why does this work only in kitty? The diff kitten makes use of various features that are :doc:`kitty only `, such as the :doc:`kitty graphics protocol -`, the :ref:`extended keyboard protocol -`, etc. It also leverages terminal program +`, the :doc:`extended keyboard protocol +`, etc. It also leverages terminal program infrastructure I created for all of kitty's other kittens to reduce the amount of code needed (the entire implementation is under 2000 lines of code). diff --git a/docs/kittens/hints.rst b/docs/kittens/hints.rst index 9b552ca89..6982bf679 100644 --- a/docs/kittens/hints.rst +++ b/docs/kittens/hints.rst @@ -9,7 +9,7 @@ browser. .. figure:: ../screenshots/hints_mode.png :alt: URL hints mode :align: center - :scale: 100% + :width: 100% URL hints mode diff --git a/docs/kittens/hyperlinked_grep.rst b/docs/kittens/hyperlinked_grep.rst index 16bfccb09..3ea78e670 100644 --- a/docs/kittens/hyperlinked_grep.rst +++ b/docs/kittens/hyperlinked_grep.rst @@ -58,7 +58,7 @@ Then, for example, for ZSH, add the following to :file:`.zshrc`:: compdef _rg hg To learn more about kitty's powerful framework for customizing URL click -actions, :doc:`see here <../open_actions>`. +actions, :doc:`see here `. Hopefully, someday this functionality will make it into some `upstream grep `_ diff --git a/docs/kittens/icat.rst b/docs/kittens/icat.rst index f14d708e9..3c2be662d 100644 --- a/docs/kittens/icat.rst +++ b/docs/kittens/icat.rst @@ -1,6 +1,8 @@ -icat - Display images in the terminal +icat ======================================== +*Display images in the terminal* + The ``icat`` kitten can be used to display arbitrary images in the |kitty| terminal. Using it is as simple as:: diff --git a/docs/kittens/panel.rst b/docs/kittens/panel.rst index 13e0d1084..af62affd3 100644 --- a/docs/kittens/panel.rst +++ b/docs/kittens/panel.rst @@ -14,7 +14,7 @@ using terminal programs instead of GUI toolkits. .. figure:: ../screenshots/panel.png :alt: Screenshot, showing a sample panel :align: center - :scale: 100% + :width: 100% Screenshot, showing a sample panel diff --git a/docs/kittens/remote_file.rst b/docs/kittens/remote_file.rst index 1cae3479e..3c661a3a6 100644 --- a/docs/kittens/remote_file.rst +++ b/docs/kittens/remote_file.rst @@ -11,7 +11,7 @@ Then hold down :kbd:`ctrl+shift` and click the name of the file. .. figure:: ../screenshots/remote_file.png :alt: Remote file actions :align: center - :scale: 100% + :width: 100% Remote file actions diff --git a/docs/kittens/unicode-input.rst b/docs/kittens/unicode-input.rst index 1a91b68b3..9195607e8 100644 --- a/docs/kittens/unicode-input.rst +++ b/docs/kittens/unicode-input.rst @@ -7,7 +7,7 @@ Press :sc:`input_unicode_character` to start the unicode input widget, shown bel .. figure:: ../screenshots/unicode.png :alt: A screenshot of the unicode input widget :align: center - :scale: 100% + :width: 100% A screenshot of the unicode input widget diff --git a/docs/kittens_intro.rst b/docs/kittens_intro.rst new file mode 100644 index 000000000..567a4700a --- /dev/null +++ b/docs/kittens_intro.rst @@ -0,0 +1,66 @@ +.. _kittens: + +Extend kitty +================ + +.. toctree:: + :hidden: + :glob: + + kittens/icat + kittens/diff + kittens/unicode-input + kittens/hints + kittens/remote_file + kittens/hyperlinked_grep + kittens/custom + kittens/* + +|kitty| has a framework for easily creating terminal programs that make use of +its advanced features. These programs are called kittens. They are used both +to add features to |kitty| itself and to create useful standalone programs. +Some prominent kittens: + +:doc:`icat ` + Display images in the terminal + + +:doc:`diff ` + A fast, side-by-side diff for the terminal with syntax highlighting and + images + + +:doc:`Unicode Input ` + Easily input arbitrary unicode characters in |kitty| by name or hex code. + + +:doc:`Hints ` + Select and open/paste/insert arbitrary text snippets such as URLs, + filenames, words, lines, etc. from the terminal screen. + + +:doc:`Remote file ` + Edit, open, or download remote files over SSH easily, by simply clicking on + the filename. + + +:doc:`Hyperlinked grep ` + Search your files using `ripgrep `_ + and open the results directly in your favorite editor in the terminal, + at the line containing the search result, simply by clicking on the result you want. + + +:doc:`Broadcast ` + Type in one :term:`kitty window ` and have it broadcast to all (or a subset) of + other :term:`kitty windows `. + + +:doc:`Panel ` + Draw a GPU accelerated dock panel on your desktop showing the output + from an arbitrary terminal program. + + +:doc:`Clipboard ` + Copy/paste to the clipboard from shell scripts, even over SSH. + +You can also :doc:`Learn to create your own kittens `. diff --git a/docs/launch.rst b/docs/launch.rst index f1a583d5a..6888407d6 100644 --- a/docs/launch.rst +++ b/docs/launch.rst @@ -1,4 +1,4 @@ -Launching programs in new windows/tabs +Launching new tabs/windows ======================================== .. program:: launch diff --git a/docs/layouts.rst b/docs/layouts.rst index aeb510407..dcd165d8b 100644 --- a/docs/layouts.rst +++ b/docs/layouts.rst @@ -1,5 +1,5 @@ -Layouts -============ +Arrange windows +=================== kitty has the ability to define its own windows that can be tiled next to each other in arbitrary arrangements, based on *Layouts*, see below for examples: @@ -8,7 +8,7 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples: .. figure:: screenshots/screenshot.png :alt: Screenshot, showing three programs in the 'Tall' layout :align: center - :scale: 100% + :width: 100% Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout @@ -16,7 +16,7 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples: .. figure:: screenshots/splits.png :alt: Screenshot, showing windows in the 'Splits' layout :align: center - :scale: 100% + :width: 100% Screenshot, showing windows with arbitrary arrangement in the 'Splits' layout diff --git a/docs/marks.rst b/docs/marks.rst index 15c75366e..4c699ce64 100644 --- a/docs/marks.rst +++ b/docs/marks.rst @@ -1,5 +1,5 @@ -Marks -================= +Mark text on screen +======================== kitty has the ability to mark text on the screen based on regular expressions. diff --git a/docs/open_actions.rst b/docs/open_actions.rst index 70b20588a..79a4f37f9 100644 --- a/docs/open_actions.rst +++ b/docs/open_actions.rst @@ -1,10 +1,11 @@ -Customizing the actions taken when clicking on links +Scripting the mouse click ====================================================== -|kitty| has support for `terminal hyperlinks `_. These +|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|. +``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 diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 000000000..de43d81ef --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,287 @@ +Overview +============== + +Design philosophy +------------------- + +|kitty| is designed for power keyboard users. To that end all its controls +work with the keyboard (although it fully supports mouse interactions as +well). Its configuration is a simple, human editable, single file for +easy reproducibility (I like to store configuration in source control). + +The code in |kitty| is designed to be simple, modular and hackable. It is +written in a mix of C (for performance sensitive parts) and Python (for +easy hackability of the UI). It does not depend on any large and complex +UI toolkit, using only OpenGL for rendering everything. + +Finally, |kitty| is designed from the ground up to support all modern +terminal features, such as unicode, true color, bold/italic fonts, text +formatting, etc. It even extends existing text formatting escape codes, +to add support for features not available elsewhere, such as colored and +styled (curly) underlines. One of the design goals of |kitty| is to be +easily extensible so that new features can be added in the future with +relatively little effort. + +.. include:: basic.rst + + +Configuring kitty +------------------- + +|kitty| is highly configurable, everything from keyboard shortcuts to +painting frames-per-second. Press :sc:`edit_config_file` in kitty +to open its fully commented sample config file in your text editor. +For details see the :doc:`configuration docs `. + +.. toctree:: + :hidden: + + conf + + +.. _layouts: + +Layouts +---------- + +A :term:`layout` is an arrangement of multiple :term:`kitty windows ` +inside a top-level :term:`OS window `. The layout manages all its +windows automatically, resizing and moving them as needed. You can create a new +:term:`window` using the :sc:`new_window` key combination. + +Currently, there are seven layouts available: + +* **Fat** -- One (or optionally more) windows are shown full width on the top, the rest of the windows are shown side-by-side on the bottom +* **Grid** -- All windows are shown in a grid +* **Horizontal** -- All windows are shown side-by-side +* **Splits** -- Windows arranged in arbitrary patterns created using horizontal and vertical splits +* **Stack** -- Only a single maximized window is shown at a time +* **Tall** -- One (or optionally more) windows are shown full height on the left, the rest of the windows are shown one below the other on the right +* **Vertical** -- All windows are shown one below the other + +By default, all layouts are enabled and you can switch between layouts using +the :sc:`next_layout` key combination. You can also create shortcuts to select +particular layouts, and choose which layouts you want to enable/disable, see +:ref:`conf-kitty-shortcuts.layout` for examples. The first layout listed in +:opt:`enabled_layouts` becomes the default layout. + +For more details on the layouts and how to use them see :doc:`the documentation +`. + +.. toctree:: + :hidden: + + layouts + +Extending kitty +------------------ + +kitty has a powerful framework for scripting. You can create small terminal +programs called :doc:`kittens `. These can used to add features +to kitty, for example, :doc:`editing remote files ` or +:doc:`inputting unicode characters `. They can also be +used to create programs that leverage kitty's powerful features, for example, +:doc:`viewing images ` or :doc:`diffing files with images +`. + +You can :doc:`create your own kittens to scratch your own itches +`. + +For a list of all the builtin kittens, :ref:`see here `. + +.. toctree:: + :hidden: + + kittens_intro + + +Remote control +------------------ + +|kitty| has a very powerful system that allows you to control it from the +:doc:`shell prompt, even over SSH `. You can change colors, +fonts, open new :term:`windows `, :term:`tabs `, set their titles, +change window layout, get text +from one window and send text to another, etc, etc. The possibilities are +endless. See the :doc:`tutorial ` to get started. + +.. toctree:: + :hidden: + + remote-control + + +.. _sessions: + +Startup Sessions +------------------ + +You can control the :term:`tabs `, `:term:`kitty window ` layout, +working directory, startup programs, +etc. by creating a "session" file and using the :option:`kitty --session` +command line flag or the :opt:`startup_session` option in :file:`kitty.conf`. +For example: + +.. code-block:: session + + # Set the layout for the current tab + layout tall + # Set the working directory for windows in the current tab + cd ~ + # Create a window and run the specified command in it + launch zsh + # Create a window with some environment variables set and run + # vim in it + launch --env FOO=BAR vim + # Set the title for the next window + launch --title "Chat with x" irssi --profile x + + # Create a new tab (the part after new_tab is the optional tab + # name which will be displayed in the tab bar, if omitted, the + # title of the active window will be used instead) + new_tab my tab + cd ~/somewhere + # Set the layouts allowed in this tab + enabled_layouts tall, stack + # Set the current layout + layout stack + launch zsh + + # Create a new OS window + new_os_window + # set new window size to 80x25 cells + os_window_size 80c 25c + # set the --class for the new OS window + os_window_class mywindow + launch sh + # Make the current window the active (focused) window + focus + launch emacs + +.. note:: + The :doc:`launch ` command when used in a session file + cannot create new OS windows, or tabs. + + +Launching new tabs/windows +------------------------------- + +kitty can be told to run arbitrary programs in new :term:`tabs `, +:term:`windows ` or :term:`overlays ` at a keypress. +To learn how to do this, see :doc:`here `. + +.. toctree:: + :hidden: + + launch + + +Mouse features +------------------- + +* You can click on a URL to open it in a browser. +* You can double click to select a word and then drag to select more words. +* You can triple click to select a line and then drag to select more lines. +* You can triple click while holding :kbd:`ctrl+alt` to select from clicked + point to end of line. +* You can right click to extend a previous selection. +* You can hold down :kbd:`ctrl+alt` and drag with the mouse to select in + columns. +* Selecting text automatically copies it to the primary clipboard (on + platforms with a primary clipboard). +* You can middle click to paste from the primary clipboard (on platforms + with a primary clipboard). +* You can select text with kitty even when a terminal program has grabbed + the mouse by holding down the :kbd:`shift` key. + +All these actions can be customized in :file:`kitty.conf` as described +:ref:`here `. + + +Scripting the mouse click +--------------------------- + +You can customize what happens when clicking on hyperlinks in kitty, +having it open files in your editor, download remote files, open things +in your browser, etc. + +For details, see :doc:`here `. + +.. toctree:: + :hidden: + + open_actions + +Font control +----------------- + +|kitty| has extremely flexible and powerful font selection features. You can +specify individual families for the regular, bold, italic and bold+italic +fonts. You can even specify specific font families for specific ranges of +unicode characters. This allows precise control over text rendering. It can +come in handy for applications like powerline, without the need to use patched +fonts. See the various font related configuration directives in +:ref:`conf-kitty-fonts`. + + +.. _scrollback: + +The scrollback buffer +----------------------- + +|kitty| supports scrolling back to view history, just like most terminals. You +can use either keyboard shortcuts or the mouse scroll wheel to do so. However, +|kitty| has an extra, neat feature. Sometimes you need to explore the +scrollback buffer in more detail, maybe search for some text or refer to it +side-by-side while typing in a follow-up command. |kitty| allows you to do this +by pressing the :sc:`show_scrollback` key-combination, which will open the +scrollback buffer in your favorite pager program (which is ``less`` by default). +Colors and text formatting are preserved. You can explore the scrollback buffer +comfortably within the pager. + +Additionally, you can pipe the contents of the scrollback buffer to an +arbitrary, command running in a new :term:`window`, :term:`tab` or :term:`overlay`, +for example:: + + map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting less +G -R + +Would open the scrollback buffer in a new :term:`window` when you press the :kbd:`F1` +key. See :sc:`show_scrollback` for details. + +If you want to use it with an editor such as vim to get more powerful features, +you can see tips for doing so, in +`this thread `_. + +If you wish to store very large amounts of scrollback to view using the piping or +:sc:`show_scrollback` features, you can use the :opt:`scrollback_pager_history_size` +option. + +.. _cpbuf: + +Multiple copy/paste buffers +----------------------------- + +In addition to being able to copy/paste from the system clipboard, in |kitty| you +can also setup an arbitrary number of copy paste buffers. To do so, simply add +something like the following to your :file:`kitty.conf`:: + + map f1 copy_to_buffer a + map f2 paste_from_buffer a + +This will allow you to press :kbd:`F1` to copy the current selection to an +internal buffer named ``a`` and :kbd:`F2` to paste from that buffer. The buffer +names are arbitrary strings, so you can define as many such buffers as you +need. + + +Marks +------------- + +kitty has the ability to mark text on the screen based on regular expressions. +This can be useful to highlight words or phrases when browsing output from long +running programs or similar. To learn how this feature works, see :doc:`marks`. + +.. toctree:: + :hidden: + + marks diff --git a/docs/performance.rst b/docs/performance.rst index 8516d369d..8d2e0d9eb 100644 --- a/docs/performance.rst +++ b/docs/performance.rst @@ -1,4 +1,4 @@ -|kitty| Performance +Performance =================== The main goals for |kitty| performance are user perceived latency while typing diff --git a/docs/pipe.rst b/docs/pipe.rst index 8f1289cd8..8afd47a97 100644 --- a/docs/pipe.rst +++ b/docs/pipe.rst @@ -1,3 +1,5 @@ +:orphan: + Working with the screen and history buffer contents ====================================================== diff --git a/docs/protocol-extensions.rst b/docs/protocol-extensions.rst index 2d4e477b5..bc5f2bfca 100644 --- a/docs/protocol-extensions.rst +++ b/docs/protocol-extensions.rst @@ -1,7 +1,7 @@ -Extensions to the xterm protocol +Terminal protocol extensions =================================== -|kitty| has a few extensions to the xterm protocol, to enable advanced features. +|kitty| has extensions to the legacy terminal protocol, to enable advanced features. These are typically in the form of new or re-purposed escape codes. While these extensions are currently |kitty| specific, it would be nice to get some of them adopted more broadly, to push the state of terminal emulators forward. @@ -19,301 +19,15 @@ If you wish to discuss these extensions, propose additions/changes to them please do so by opening issues in the `GitHub `_ bug tracker. -.. contents:: - :local: -Colored and styled underlines -------------------------------- - -|kitty| supports colored and styled (wavy) underlines. This is of particular -use in terminal editors such as vim and emacs to display red, wavy underlines -under mis-spelled words and/or syntax errors. This is done by re-purposing some -SGR escape codes that are not used in modern terminals (`CSI codes -`_) - -To set the underline style:: - - [4:0m # this is no underline - [4:1m # this is a straight underline - [4:2m # this is a double underline - [4:3m # this is a curly underline - [4:4m # this is a dotted underline (not implemented in kitty) - [4:5m # this is a dashed underline (not implemented in kitty) - [4m # this is a straight underline (for backwards compat) - [24m # this is no underline (for backwards compat) - -To set the underline color (this is reserved and as far as I can tell not actually used for anything):: - - [58...m - -This works exactly like the codes ``38, 48`` that are used to set foreground and -background color respectively. - -To reset the underline color (also previously reserved and unused):: - - [59m - -The underline color must remain the same under reverse video, if it has a -color, if not, it should follow the foreground color. - -To detect support for this feature in a terminal emulator, query the terminfo database -for the ``Su`` boolean capability. - -Graphics rendering ---------------------- - -See :doc:`/graphics-protocol` for a description -of this protocol to enable drawing of arbitrary raster images in the terminal. - - -.. _extended-key-protocol: - -Keyboard handling -------------------- - -kitty has a :doc:`keyboard protocol ` for reporting key -presses to terminal applications that solves all key handling issues in -terminal applications. - -.. _ext_styles: - -Setting text styles/colors in arbitrary regions of the screen ------------------------------------------------------------------- - -There already exists an escape code to set *some* text attributes in arbitrary -regions of the screen, `DECCARA -`_. However, it is limited to -only a few attributes. |kitty| extends this to work with *all* SGR attributes. -So, for example, this can be used to set the background color in an arbitrary -region of the screen. - -The motivation for this extension is the various problems with the existing -solution for erasing to background color, namely the *background color erase -(bce)* capability. See -`this discussion `_ -and `this FAQ `_ -for a summary of problems with *bce*. - -For example, to set the background color to blue in a -rectangular region of the screen from (3, 4) to (10, 11), you use:: - - [2*x[4;3;11;10;44$r[*x - - -Saving and restoring colors ---------------------------------------------------------------------------------- - -It is often useful for a full screen application with its own color themes to -set the default foreground, background, selection and cursor colors and the -ANSI color table. This allows for various performance optimizations when -drawing the screen. The problem is that if the user previously used the escape -codes to change these colors herself, then running the full screen application -will lose her changes even after it exits. To avoid this, kitty introduces a -new pair of *OSC* escape codes to push and pop the current color values from a -stack:: - - ]30001\ # push onto stack - ]30101\ # pop from stack - -These escape codes save/restore the colors, default -background, default foreground, selection background, selection foreground and -cursor color and the 256 colors of the ANSI color table. - -.. note:: In July 2020, after several years, XTerm copied this protocol - extension, without acknowledgement, and using incompatible escape codes - (XTPUSHCOLORS, XTPOPCOLORS, XTREPORTCOLORS). And they decided to save not - just the dynamic colors but the entire ANSI color table. In the interests of - promoting interoperability, kitty added support for XTerm's escape codes as - well, and changed this extension to also save/restore the entire ANSI color - table. - - -Pasting to clipboard ----------------------- - -|kitty| implements the OSC 52 escape code protocol to get/set the clipboard -contents (controlled via the :opt:`clipboard_control` setting). There is one -difference in kitty's implementation compared to some other terminal emulators. -|kitty| allows sending arbitrary amounts of text to the clipboard. It does so -by modifying the protocol slightly. Successive OSC 52 escape codes to set the -clipboard will concatenate, so:: - - ]52;c;\ - ]52;c;\ - -will result in the clipboard having the contents ``payload1 + payload2``. To -send a new string to the clipboard send an OSC 52 sequence with an invalid payload -first, for example:: - - ]52;c;!\ - -Here ``!`` is not valid base64 encoded text, so it clears the clipboard. -Further, since it is invalid, it should be ignored by terminal emulators -that do not support this extension, thereby making it safe to use, simply -always send it before starting a new OSC 52 paste, even if you aren't chunking -up large pastes, that way kitty won't concatenate your paste, and it will have -no ill-effects in other terminal emulators. - -In case you're using software that can't be easily adapted to this -protocol extension, it can be disabled by specifying ``no-append`` to the -:opt:`clipboard_control` setting. - - -.. _unscroll: - -Unscrolling the screen ------------------------ - -This is a small extension to the `SD (Pan up) escape code -`_ from the VT-420 terminal. The -``SD`` escape code normally causes the text on screen to scroll down by the -specified number of lines, with empty lines appearing at the top of the screen. -This extension allows the new lines to be filled in from the scrollback buffer -instead of being blank. - -The motivation for this is that many modern shells will show completions in a -block of lines under the cursor, this causes some of the on-screen text to be -lost even after the completion is completed, because it has scrolled off -screen. This escape code allows that text to be restored. - -If the scrollback buffer is empty or there is no scrollback buffer, such as for -the alternate screen, then the newly inserted lines must be empty, just as with -the original ``SD`` escape code. The maximum number of lines that can be -scrolled down is implementation defined, but must be at least one screen worth. - -The syntax of the escape code is identical to that of ``SD`` except that it has -a trailing ``+`` modifier. This is legal under the `ECMA 48 standard -`_ -and unused for any other purpose as far as I can tell. So for example, to -unscroll three lines, the escape code would be:: - - CSI 3 + T - -See `discussion here -`_. - -.. versionadded:: 0.20.2 - - -.. _desktop_notifications: - - -Desktop notifications ---------------------------------- - -|kitty| implements an extensible escape code (OSC 99) to show desktop -notifications. It is easy to use from shell scripts and fully extensible to -show title and body. Clicking on the notification can optionally focus the -window it came from, and/or send an escape code back to the application running -in that window. - -The design of the escape code is partially based on the discussion in -the defunct -`terminal-wg `_ - -The escape code has the form:: - - 99 ; metadata ; payload - -Here ```` is :code:`]` and ```` is -:code:``. The metadata is a section of colon separated -:code:`key=value` pairs. Every key must be a single character from the set -:code:`a-zA-Z` and every value must be a word consisting of characters from -the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The payload must be -interpreted based on the metadata section. The two semi-colons *must* always be -present even when no metadata is present. - -Before going into details, lets see how one can display a simple, single line -notification from a shell script:: - - printf '\x1b]99;;Hello world\x1b\\' - -To show a message with a title and a body:: - - printf '\x1b]99;i=1:d=0;Hello world\x1b\\' - printf '\x1b]99;i=1:d=1:p=body;This is cool\x1b\\' - -The most important key in the metadata is the ``p`` key, it controls how the -payload is interpreted. A value of ``title`` means the payload is setting the -title for the notification. A value of ``body`` means it is setting the body, -and so on, see the table below for full details. - -The design of the escape code is fundamentally chunked, this is because -different terminal emulators have different limits on how large a single escape -code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i`` -key is the *notification id* which can be any string containing the characters -``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and -can only take the values ``0`` and ``1``. A value of ``0`` means the -notification is not yet done and the terminal emulator should hold off -displaying it. A value of ``1`` means the notification is done, and should be -displayed. You can specify the title or body multiple times and the terminal -emulator will concatenate them, thereby allowing arbitrarily long text -(terminal emulators are free to impose a sensible limit to avoid -Denial-of-Service attacks). - -Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain -text with no embedded escape codes, or UTF-8 text that is base64 encoded, in -which case there must be an ``e=1`` key in the metadata to indicate the payload -is base64 encoded. - -When the user clicks the notification, a couple of things can happen, the -terminal emulator can focus the window from which the notification came, and/or -it can send back an escape code to the application indicating the notification -was activated. This is controlled by the ``a`` key which takes a comma -separated set of values, ``report`` and ``focus``. The value ``focus`` means -focus the window from which the notification was issued and is the default. -``report`` means send an escape code back to the application. The format of the -returned escape code is:: - - 99 ; i=identifier ; - -The value of ``identifier`` comes from the ``i`` key in the escape code sent by -the application. If the application sends no identifier, then the terminal -*must* use ``i=0``. Actions can be preceded by a negative sign to turn them -off, so for example if you do not want any action, turn off the default -``focus`` action with:: - - a=-focus - -Complete specification of all the metadata keys is in the table below. If a -terminal emulator encounters a key in the metadata it does not understand, -the key *must* be ignored, to allow for future extensibility of this escape -code. Similarly if values for known keys are unknown, the terminal emulator -*should* either ignore the entire escape code or perform a best guess effort -to display it based on what it does understand. - -.. note:: - It is possible to extend this escape code to allow specifying an icon for - the notification, however, given that some platforms, such as macOS, dont - allow displaying custom icons on a notification, at all, it was decided to - leave it out of the spec for the time being. - - Similarly, features such as scheduled notifications could be added in future - revisions. - - -======= ==================== ========= ================= -Key Value Default Description -======= ==================== ========= ================= -``a`` Comma separated list ``focus`` What action to perform when the - of ``report``, notification is clicked - ``focus``, with - optional leading - ``-`` - -``d`` ``0`` or ``1`` ``1`` Indicates if the notification is - complete or not. - -``e`` ``0`` or ``1`` ``0`` If set to ``1`` means the payload is base64 encoded UTF-8, - otherwise it is plain UTF-8 text with no C0 control codes in it - -``i`` ``[a-zA-Z0-9-_+.]`` ``0`` Identifier for the notification - -``p`` One of ``title`` or ``title`` Whether the payload is the notification title or body. If a - ``body``. notification has no title, the body will be used as title. -======= ==================== ========= ================= - - -.. note:: - |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for - desktop notifications. +.. toctree:: + :maxdepth: 1 + + underlines + graphics-protocol + keyboard-protocol + desktop-notifications + unscroll + clipboard + color-stack + deccara diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 000000000..7df450812 --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,28 @@ +.. _quickstart: + +Quickstart +=========== + +.. toctree:: + :hidden: + + binary + build + +Pre-built binaries of |kitty| are available for both macOS and Linux. +See the :doc:`binary install instructions `. You can also +:doc:`build from source `. + +Additionally, you can use your favorite package manager to install the |kitty| +package, but note that some Linux distribution packages are woefully outdated. +|kitty| is available in a vast number of package repositories for macOS +and Linux. + +.. image:: https://repology.org/badge/tiny-repos/kitty.svg + :target: https://repology.org/project/kitty/versions + :alt: Number of repositories kitty is available in + +See :doc:`Configuring kitty ` for help on configuring |kitty| and +:doc:`Invocation ` for the command line arguments |kitty| supports. + +For a tour of kitty's design and features, see the :doc:`/overview`. diff --git a/docs/rc_protocol.rst b/docs/rc_protocol.rst index ea34df4fb..95ad2b29e 100644 --- a/docs/rc_protocol.rst +++ b/docs/rc_protocol.rst @@ -1,5 +1,5 @@ -Documentation for the kitty remote control protocol -====================================================== +The kitty remote control protocol +================================== The kitty remote control protocol is a simple protocol that involves sending data to kitty in the form of JSON. Any individual command of kitty has the @@ -37,5 +37,4 @@ with the following command line:: echo -en '\eP@kitty-cmd{"cmd":"ls","version":[0,14,2]}\e\' | socat - unix:/tmp/test | awk '{ print substr($0, 13, length($0) - 14) }' | jq -c '.data | fromjson' | jq . - .. include:: generated/rc.rst diff --git a/docs/remote-control.rst b/docs/remote-control.rst index 81e57d213..cca38976c 100644 --- a/docs/remote-control.rst +++ b/docs/remote-control.rst @@ -1,6 +1,4 @@ -:tocdepth: 2 - -Controlling kitty from scripts or the shell +Control kitty from scripts ============================================== .. highlight:: sh @@ -174,10 +172,15 @@ Now press, F1 and start typing, what you type will be sent to all windows, live, as you type it. -Documentation for the remote control protocol +The remote control protocol ----------------------------------------------- If you wish to develop your own client to talk to |kitty|, you -can use the :doc:`rc_protocol`. +can use the :doc:`protocol specification `. + +.. toctree:: + :hidden: + + rc_protocol .. include:: generated/cli-kitty-at.rst diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..5a57e5492 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +sphinx +furo +sphinx-copybutton +sphinxext-opengraph +sphinx-inline-tabs diff --git a/docs/underlines.rst b/docs/underlines.rst new file mode 100644 index 000000000..de63eaae2 --- /dev/null +++ b/docs/underlines.rst @@ -0,0 +1,36 @@ +Colored and styled underlines +================================ + +|kitty| supports colored and styled (wavy) underlines. This is of particular +use in terminal editors such as vim and emacs to display red, wavy underlines +under mis-spelled words and/or syntax errors. This is done by re-purposing some +SGR escape codes that are not used in modern terminals (`CSI codes +`_) + +To set the underline style:: + + [4:0m # this is no underline + [4:1m # this is a straight underline + [4:2m # this is a double underline + [4:3m # this is a curly underline + [4:4m # this is a dotted underline (not implemented in kitty) + [4:5m # this is a dashed underline (not implemented in kitty) + [4m # this is a straight underline (for backwards compat) + [24m # this is no underline (for backwards compat) + +To set the underline color (this is reserved and as far as I can tell not actually used for anything):: + + [58...m + +This works exactly like the codes ``38, 48`` that are used to set foreground and +background color respectively. + +To reset the underline color (also previously reserved and unused):: + + [59m + +The underline color must remain the same under reverse video, if it has a +color, if not, it should follow the foreground color. + +To detect support for this feature in a terminal emulator, query the terminfo database +for the ``Su`` boolean capability. diff --git a/docs/unscroll.rst b/docs/unscroll.rst new file mode 100644 index 000000000..bd05071db --- /dev/null +++ b/docs/unscroll.rst @@ -0,0 +1,34 @@ +.. _unscroll: + +Unscrolling the screen +======================== + +This is a small extension to the `SD (Pan up) escape code +`_ from the VT-420 terminal. The +``SD`` escape code normally causes the text on screen to scroll down by the +specified number of lines, with empty lines appearing at the top of the screen. +This extension allows the new lines to be filled in from the scrollback buffer +instead of being blank. + +The motivation for this is that many modern shells will show completions in a +block of lines under the cursor, this causes some of the on-screen text to be +lost even after the completion is completed, because it has scrolled off +screen. This escape code allows that text to be restored. + +If the scrollback buffer is empty or there is no scrollback buffer, such as for +the alternate screen, then the newly inserted lines must be empty, just as with +the original ``SD`` escape code. The maximum number of lines that can be +scrolled down is implementation defined, but must be at least one screen worth. + +The syntax of the escape code is identical to that of ``SD`` except that it has +a trailing ``+`` modifier. This is legal under the `ECMA 48 standard +`_ +and unused for any other purpose as far as I can tell. So for example, to +unscroll three lines, the escape code would be:: + + CSI 3 + T + +See `discussion here +`_. + +.. versionadded:: 0.20.2 diff --git a/kitty/actions.py b/kitty/actions.py index 70289e1ba..374985063 100644 --- a/kitty/actions.py +++ b/kitty/actions.py @@ -91,17 +91,13 @@ def as_rst() -> str: a(title) a('-' * len(title)) a('') - a('.. contents::') - a(' :local:') - a(' :depth: 1') - a('') for action in allg[group]: a('') a(f'.. _action-{action.name}:') a('') a(action.name) - a('^' * len(action.name)) + a('+' * len(action.name)) a('') a(action.short_help) a('') diff --git a/kitty/conf/types.py b/kitty/conf/types.py index db7331ce5..60ee7f3c6 100644 --- a/kitty/conf/types.py +++ b/kitty/conf/types.py @@ -428,7 +428,7 @@ class Group: a(f'.. _conf-{conf_name}-{self.name}:') a('') a(self.title) - heading_level = '+' if level > 1 else '^' + heading_level = '+' if level > 1 else '-' a(heading_level * (len(self.title) + 20)) a('') if self.start_text: diff --git a/publish.py b/publish.py index 5dbd27a3c..6e07dc098 100755 --- a/publish.py +++ b/publish.py @@ -63,7 +63,7 @@ def run_man(args: Any) -> None: def run_html(args: Any) -> None: - call('make FAIL_WARN=-W "OPTS=-D html_theme_options.analytics_id=UA-20736318-2" dirhtml', cwd=docs_dir) + call('make FAIL_WARN=-W "OPTS=-D analytics_id=UA-20736318-2" dirhtml', cwd=docs_dir) add_old_redirects('docs/_build/dirhtml')