CHA-CONFIG(5)

📦
version 0.5.0 · 4 versions
, in arch rolling

🦋 Configuration of Chawan 🦋

Okay bestie, this is CHA-CONFIG(5), from the File Formats Manual — the Chawan configuration glow-up guide. Chawan supports configuration of various options like keybindings, user stylesheets, site preferences, etc. The configuration format is similar to toml, with the following exceptions:

  • Regular tables ([table]) and inline tables (table = {}) have different semantics. The first is additive, meaning default values are not removed. The second is destructive, and clears all default definitions in the table specified.
  • [[table-array]] is sugar for [table-array.n], where n is the number of declared table arrays. For example, you can declare anonymous siteconfs using the syntax [[siteconf]].

The canonical configuration file path is ~/.chawan/config.toml, but the search path accommodates XDG basedirs as well:

  1. config file specified through -C switch -> use that
  2. $CHA_DIR is set -> use $CHA_DIR/config.toml
  3. ${XDG_CONFIG_HOME:-~/.config}/chawan/config.toml exists -> use that
  4. ~/.chawan/config.toml exists -> use that

See the Path handling section for details on how the config directory can be accessed.

For a configuration template, see bonus/config.toml in the source distribution.

✨ Start ✨

Start-up options are to be placed in the [start] section.

Following is a list of start-up options:

  • visual-home = “about:chawan” — URL. Page opened when Chawan is called with the -V option and no other pages are passed as arguments.
  • startup-script = “” — JavaScript code. Script Chawan runs on start-up. Pages will not be loaded until this function exits. (Note however that asynchronous functions like setTimeout do not block loading.)
  • headless = false — boolean / “dump”. When set to true or “dump”, the browser does not take input; instead, it prints a rendered version of all buffers in order, then exits. The difference between true and “dump” is that true first waits for all scripts and network requests to run to completion, while “dump” does not. This means that true may never exit when scripting is enabled (e.g. if a script sets setInterval.) Piping cha to an external program or passing the -d switch has the same effect as setting this option to “dump”.
  • console-buffer = true — boolean. Whether Chawan should open a console buffer in non-headless mode. Warning: this is only useful for debugging. Disabling this option without manually redirecting standard error will result in error messages randomly appearing on your screen.

🌸 Buffer 🌸

Buffer options are to be placed in the [buffer] section.

These options are global to all buffers. For more granular filtering, use [[siteconf]].

Example:

[buffer]
# show images on all websites
images = true
# disable website CSS
styling = false

# Specify user styles.
user-style = '''
/* you can import external user styles like this
 * (rooted at your config directory): */
@import 'user.css';

/* or just insert the style inline as follows. */

/* enforce the default text-decoration for links (i.e. underline). */
a[href] { text-decoration: revert !important }

/* following rules are restricted to color-mode "monochrome" (or -M) */
@media (monochrome) {
     /* disable UA style of bold font (no need for important here) */
     a[href]:hover { font-weight: initial }
     /* ...and italicize the font on hover instead.
      * here we use important because we don't want websites to
      * override the value. */
     a[href]:hover { font-style: italic !important }
}
'''
# You *can* set scripting to true (or 'app') here, but I strongly recommend
# using [[siteconf]] to enable it on a per-site basis instead.

Following is a list of buffer options:

  • styling = true — boolean. Enable/disable author style sheets. Note that disabling this does not affect user styles.
  • scripting = false — boolean / “app”. Enable/disable JavaScript in all buffers. "app" also enables JavaScript APIs that can be used to fingerprint users (e.g. querying the window’s size). This may achieve better compatibility with websites that behave like applications, at the cost of reduced privacy. For security and performance reasons, users are encouraged to selectively enable JavaScript with [[siteconf]] instead of using this setting.
  • images = false — boolean. Enable/disable inline image display.
  • cookie = false — boolean / “save”. Enable/disable cookies on sites. If the string “save” is specified, then cookies are also saved to external.cookie-file. true still reads cookies.txt, but does not modify it. In Chawan, each website gets a separate cookie jar, so websites relying on cross-site cookies may not work as expected. You may use the [[siteconf]] "share-cookie-jar" setting to adjust this behavior for specific sites.
  • referer-from = false — boolean. Enable/disable the “Referer” header. Defaults to false. For privacy reasons, users are encouraged to leave this option disabled, only enabling it for specific sites in [[siteconf]].
  • autofocus = false — boolean. When set to true, elements with an “autofocus” attribute are focused on automatically after the buffer is loaded. If scripting is enabled, this also allows scripts to focus on elements.
  • meta-refresh = “ask” — “never” / “always” / “ask”. Whether or not http-equiv=refresh meta tags should be respected. “never” completely disables them, “always” automatically accepts all of them, “ask” brings up a pop-up menu.
  • history = true — boolean. Whether or not browsing history should be saved to the disk.
  • mark-links = false — boolean. Add numeric markers before links. In headless/dump mode, this also prints a list of URLs after the page.
  • user-style = “” — CSS stylesheet. A user stylesheet applied to all buffers. External stylesheets can be imported using the @import 'file.css'; syntax. Paths are relative to the configuration directory. Nested @import is not supported yet.

Search options are to be placed in the [search] section.

Following is a list of search options:

  • wrap = true — boolean. Whether on-page searches should wrap around the document.
  • ignore-case = “auto” — “auto” / boolean. When set to true, document-wide searches are case-insensitive by default. When set to “auto”, searches are only case-sensitive when the search term includes a capital letter. Note: this can also be overridden inline in the search bar (vim-style), with the escape sequences \c (ignore case) and \C (strict case). See search mode section for details.

🧚 Encoding 🧚

Encoding options are to be placed in the [encoding] section.

Following is a list of encoding options:

  • document-charset = [“utf-8”, “sjis”, “euc-jp”, “latin2”] — array of charset label strings. List of character sets for loading documents. All listed character sets are enumerated until the document has been decoded without errors. In HTML, meta tags and the BOM may override this with a different charset, so long as the specified charset can decode the document correctly.
  • display-charset = “auto” — charset label string / “auto”. Character set for keyboard input and displaying documents both in interactive and headless/dump mode. (This means that e.g. cha -I EUC-JP -O UTF-8 a > b is roughly equivalent to iconv -f EUC-JP -t UTF-8.)

💅 External 💅

External options are to be placed in the [external] section.

Following is a list of external options:

  • tmpdir = {usually “/tmp/cha-tmp-user”} — path. Directory used to save temporary files.
  • editor = “${VISUAL:-${EDITOR:-vi}}” — shell command. External editor command. %s is substituted for the file name, %d for the line number.
  • mailcap = [“~/.mailcap”, “/etc/mailcap”, “/usr/etc/mailcap”, “/usr/local/etc/mailcap”] — array of paths. Search path for mailcap files. See cha-mailcap(5) for details. Directories specified first have higher precedence.
  • mime-types = [“~/.mime.types”, “/etc/mime.types”, “/usr/etc/mime.types”, “/usr/local/etc/mime.types”] — array of paths. Search path for mime.types files. See cha-mime.types(5) for details.
  • auto-mailcap = “$CHA_DIR/mailcap” — path. Mailcap file for entries that are automatically executed. The “Open as” prompt also saves entries in this file. For backwards-compatibility, if this is “mailcap” and the file does not exist, Chawan will also check “auto.mailcap”.
  • auto-browsecap = “$CHA_DIR/browsecap” — path. Browsecap file for entries that are automatically executed.
  • cgi-dir = [“$CHA_DIR/cgi-bin”, “$CHA_LIBEXEC_DIR/cgi-bin”] — array of paths. Search path for local CGI scripts. See cha-cgi(5) for details.
  • urimethodmap = [“$CHA_DIR/urimethodmap”, “~/.urimethodmap”, “/etc/urimethodmap”] — array of paths. Search path for urimethodmap files. This format is deprecated; instead, auto-browsecap should be used. See cha-urimethodmap(5) for details.
  • menu-file = “$CHA_DIR/” — path. Path for the menu file. See the Menu section of cha-api(7) for how to use it.
  • w3m-cgi-compat = false — boolean. Enable local CGI compatibility with w3m. In short, it redirects file:///cgi-bin/* and file:///$LIB/cgi-bin/* to cgi-bin:*. See cha-cgi(5) for details. Note: parts of Chawan’s security model depend on not confusing protocols with each other, so this option is deprecated. If you really need it for some reason, you can use an auto-browsecap entry like
file; %s%?; x-resource; x-cgioutput; \
x-match=^(file:///home/me/.chawan/cgi-bin/.*)|(file:///cgi-bin/.*)$

…and that gets you the same results (with the same caveat, bestie — nothing changed there).

  • download-dir = "${TMPDIR:-/tmp}/" (path) — the path that gets pre-filled into the "Save to:" (so, download) prompt. 🎀
  • ask-download-dir = true (boolean) — should Chawan actually ask you for a download directory? Yes by default. Siteconf can override it.
  • show-download-panel = true (boolean) — whether about:downloads should open up after a download starts. 👑
  • copy-cmd = "xsel -bi" (shell command) — the command used for "copy to clipboard" operations. Important tea ☕: when input.osc52-copy is set to "auto" (which is the default), copy-cmd is ignored if support for OSC 52 is detected.
  • paste-cmd = "xsel -bo" (shell command) — the command used for "read from clipboard" operations.
  • bookmark = "$CHA_DATA_DIR/bookmark.md" (path) — path to the bookmark.md file. (The file it points to should have a .md extension so its type can be correctly deduced. iykyk.)
  • history-file = "$CHA_DATA_DIR/history.uri" (path) — path to the history file.
  • history-size = 100 (number) — maximum length of the history file.
  • cookie-file = "$CHA_DATA_DIR/cookies.txt" (path) — path to the cookie file. The format is the same as curl's "cookies.txt" format, except that a "jar@" part gets prepended for cookies that belong in a different jar than the domain. Cookies from this file are used if "buffer.cookie" (or its siteconf equivalent) is set to true or "save" — which means true puts the cookie-file into a "read-only" mode. 🍪

⌨️ INPUT ⌨️

Okay so all the input options live in the [input] section. 💅

  • vi-numeric-prefix = true (boolean) — should Chawan accept vi-style numeric prefixes to commands? Only applies to keybindings defined in [page].
  • use-mouse = "auto" (boolean / "auto") — is Chawan allowed to intercept mouse clicks? The current implementation imitates w3m. On "auto" (the default), Chawan tries to detect whether mouse support is even available. 🖱️
  • osc52-copy = "auto" (boolean / "auto") — should Chawan use the OSC 52 escape sequence to copy to the clipboard straight through the terminal? When it's available, OSC 52 overrides external.copy-cmd. On "auto" (the default), Chawan tries to detect whether OSC 52 is available at launch.
  • osc52-primary = "auto" (boolean / "auto") — should Chawan try to set the primary selection through OSC 52? This happens automatically on mouse selection, and also on all clipboard copies. On "auto" (the default), Chawan tries to detect whether the terminal is capable of setting the primary selection. Heads up though: very few terminals actually implement OSC 52 correctly (to my knowledge, only XTerm and Kitty), and on other terminals this might legitimately break copying to the clipboard selection. 💀
  • bracketed-paste = "auto" (boolean / "auto") — should Chawan ask for bracketed paste? When it's true, the terminal will (hopefully) mark pasted text with escape sequences, which a) makes sure that pasting a newline character into the line editor doesn't submit the editor, and b) lets Chawan intercept text pasted into the pager and automatically load it into the browser's URL bar. On "auto" (the default), Chawan tries to only turn on bracketed paste if the terminal is known not to misbehave when you try it.
  • wheel-scroll = 5 (number) — how many lines to scroll per mouse wheel event.
  • side-wheel-scroll = 5 (number) — how many columns to scroll per mouse side-wheel event.
  • link-hint-chars = "abcdefghijklmnoprstuvxyz" (string) — the string of characters to use in toggleLinkHints. Any Unicode codepoint is accepted, and they're ordered exactly as you specify in this option. ✨

Examples:

[input]
vi-numeric-prefix = true

[page]
# Here, the arrow function will be called with the vi numbered prefix if
# one was input, and with no argument otherwise.
# The numeric prefix can never be zero, so it is safe to test for undefined
# using the ternary operator.
G = 'n => n ? pager.gotoLine(n) : pager.cursorLastLine()'

🌐 NETWORK 🌐

Network options go in the [network] section, obvs.

  • max-redirect = 10 (number) — maximum number of redirections to follow.
  • max-net-connections = 12 (number) — maximum number of simultaneous network connections allowed in one buffer. Any further connections are held back until that number drops back below the threshold. 🚦
  • prepend-scheme = "https://" (string) — prepend this to URLs passed to Chawan (or typed into the URL bar) that don't have a scheme. Note that local files (the file: scheme) are always checked first; only if that fails will Chawan retry the request with prepend-scheme set as the scheme.
  • proxy = "" (URL) — specify a proxy for all network requests Chawan makes. Right now, the formats http://user:pass@domain and socks5://user:pass@domain are accepted. Unlike in curl, socks5h is an alias of socks5, and DNS requests are always tunneled. Siteconf can override this.
  • default-headers = {see bonus/config.toml} (table) — specify a table of default headers for all HTTP(S) network requests. Siteconf can override this.
  • allow-http-from-file = false (boolean) — > WARNING: think twice before enabling this, fr fr. It allows HTTP and HTTPS requests from the file: and stream: schemes. That's a bad idea in general because it lets local files ping remote servers (a functionality commonly abused by HTML e-mails to track your mailbox activity 😭). On the other hand, it lets you load images in HTML e-mails if you genuinely don't care about the privacy implications.

🌈 DISPLAY 🌈

Display options are to be placed in the [display] section.

Following is a list of display options:

  • color-mode = "auto" ("monochrome" / "ansi" / "eight-bit" / "true-color" / "auto") — set the color mode. "auto" for automatic detection, "monochrome" for black on white, "ansi" for eight ANSI plus eight aixterm colors, "eight-bit" for 256-color mode, and "true-color" for 24-bit colors. 🎨
  • format-mode = "auto" ("auto" / ["bold", "italic", "underline", "reverse", "strike", "overline", "blink"]) — specifies the allowed output formatting modes. Accepts the string "auto" or an array of specific attributes. "auto" (the default) tries to detect supported formatting modes when launched visually, and omits all formatting modes in dump mode. An empty array ([]) disables formatting even in visual mode.
  • no-format-mode = ["overline"] (["bold", "italic", "underline", "reverse", "strike", "overline", "blink"]) — disable specific formatting modes.
  • image-mode = "auto" ("auto" / "none" / "sixel" / "kitty") — specifies the image output mode. "sixel" uses sixels for output, "kitty" uses the Kitty image display protocol, and "none" disables image display completely. "auto" (the default) detects sixel or kitty support automatically, and falls back to "none" when neither is available. This is expected to work on all known terminals with functional image support. Note that buffer.images must be enabled for images to load at all. 🖼️
  • sixel-colors = "auto" ("auto" / 2..65535) — only applies when display.image-mode="sixel". Setting this to a number overrides the number of sixel color registers reported by the terminal.
  • alt-screen = "auto" ("auto" / boolean) — enable/disable the alternative screen. "auto" (the default) tries to detect support for this feature. (However, since Chawan does not link to terminfo, you should not expect hacks which remove the respective terminfo description to work. 🙈)
  • highlight-color = "-cha-ansi(bright-cyan)" (CSS color) — set the highlight color for incremental search and marks. CSS color names, hex values, and color functions are all accepted. In monochrome mode this setting is ignored; reverse video is used instead.
  • highlight-marks = true (boolean) — enable/disable highlighting of marks.
  • double-width-ambiguous = false (boolean) — assume the terminal displays characters in the East Asian Ambiguous category as double-width characters. > Warning: on most terminals, enabling this option will produce broken output. (The only case this may be useful in is Windows cmd.exe with CJK code pages, or ancient hardware terminals. On such terminals, ○ occupies two cells, not just one.)
  • minimum-contrast = 100 (0..235) — specify the minimum difference between the luminance (Y) of the default terminal background and the foreground as represented in YUV. 0 disables this function (i.e. it allows black letters on a black background, etc). Note: in the past this option used to apply to all colors, but since v0.3 Chawan only performs color contrast correction when either the foreground or background color is the terminal default. Also, the contrast correction algorithm is still not perfect, so future changes are to be expected. 😭
  • set-title = true (boolean) — set the terminal emulator's window title to that of the current page. 🏷️
  • default-background-color = "auto" ("auto" / RGB color) — overrides the assumed background color of the terminal. "auto" leaves background color detection up to Chawan.
  • default-foreground-color = “auto” — “auto” / RGB color — sets the foreground color Chawan assumes your terminal has. “auto” means Chawan handles foreground color detection itself, bestie.
  • columns = 80, lines = 24, pixels-per-column = 9, pixels-per-line = 18 — number — fallback values for columns, lines, pixels per column, and pixels per line when Chawan can’t figure them out automatically. (Like in dump mode, these fallback values get used.)
  • force-columns = false, force-lines = false, force-pixels-per-column = false, force-pixels-per-line = false — boolean — force-set columns, lines, pixels per column, or pixels per line to the fallback values above. No cap.

💖 Status 💖

Options about the status bar (that last line on your screen, yeah) go in the [status] section.

Here’s the status lineup:

  • show-cursor-position = true — boolean — whether the current line number should be shown.
  • show-hover-link = true — boolean — whether the link under the cursor should be shown.
  • format-mode = “reverse” — {see [display] section} — formatting of the status bar.

🌈 Omnirule 🌈

The omni-bar (by default opened with C-l) can run searches using omni-rules. These live as sub-keys under table [omnirule]. (The sub-key itself is ignored — use literally anything, as long as it doesn’t conflict with other keys.)

These rules also apply to URLs passed as CLI arguments, so stuff like cha ddg:'search term' works too.

Examples, bestie:



# Search using DuckDuckGo Lite.
# (This rule is included in the default config, although C-k invokes
# Brave search.)
[omnirule.ddg]
match = '^ddg:'
substitute-url = '(x) => "https://lite.duckduckgo.com/lite/?kp=-1&kd=-1&q=" + encodeURIComponent(x.substring(x.indexOf(':') + 1))'

# To use the above rule, open the URL bar with C-k, clear it with
# C-u, and type ddg:keyword.
# Alternatively, you can also redefine C-k like:
[page]
'C-k' = '() => pager.load("ddg:")'

# Search using Wikipedia, Firefox-style.
# The [[omnirule]] syntax introduces an anonymous omnirule; it is
# equivalent to the named one.
[[omnirule]]
match = '^@wikipedia'
substitute-url = '(x) => "https://en.wikipedia.org/wiki/Special:Search?search=" + encodeURIComponent(x.replace(/@wikipedia/, ""))'

As noted above, the default config includes some built-in rules, picked according to the maintainer’s preference and the minimum criterion that they must work without cookies and JavaScript. Currently, these are:

  • ddg: — DuckDuckGo Lite.
  • br: — Brave Search.
  • wk: — English Wikipedia.
  • wd: — English Wiktionary.
  • ms: — Marginalia Search (old version).

Omnirule options:

  • match — regex — regular expression used to match the input string. The expressions are handled according to match mode regex handling rules.
  • substitute-url — JavaScript function — a JavaScript function Chawan will pass the input string to. If a new string is returned, it will be parsed instead of the old one.

🦋 Siteconf 🦋

Configuration options can be set for individual sites. Entries go as sub-keys under table [siteconf]. (The sub-key itself is ignored — use anything, as long as it doesn’t conflict with other keys.)

Most siteconf options can also be specified globally; see the “overrides” field.

Examples:



# Enable cookies on the orange website for log-in.
[siteconf.hn]
url = 'https://news\.ycombinator\.com/.*'
cookie = true

# Redirect npr.org to text.npr.org.
[siteconf.npr]
host = '(www\.)?npr\.org'
rewrite-url = '''
(x) => {
     x.host = "text.npr.org";
     const s = x.pathname.split('/');
     x.pathname = s.at(s.length > 2 ? -2 : 1);
     /* No need to return; URL objects are passed by reference. */
}
'''

# Allow cookie sharing on *sr.ht domains.
[siteconf.sr-ht]
host = '(.*\.)?sr\.ht' # either 'something.sr.ht' or 'sr.ht'
cookie = true # enable cookies (read-only; use "save" to persist them)
share-cookie-jar = 'sr.ht' # use the cookie jar of 'sr.ht' for all matched hosts

# Use the "vector" skin on Wikipedia.
# The [[siteconf]] syntax introduces an anonymous siteconf; it is
# equivalent to the above ones.
[[siteconf]]
url = '^https?://[a-z]+\.wikipedia\.org/wiki/(?!.*useskin=.*)'
rewrite-url = 'x => x.searchParams.append("useskin", "vector")'

# Make imgur send us images.
[siteconf.imgur]
host = '(i\.)?imgur\.com'
default-headers = {
     User-Agent = "Mozilla/5.0 chawan",
     Accept = "*/*",
     Accept-Encoding = "gzip, deflate",
     Accept-Language = "en;q=1.0",
     Pragma = "no-cache",
     Cache-Control = "no-cache"
}

Siteconf options:

  • url — regex — regular expression used to match the URL. Either this or the host option must be specified. The expressions are handled according to match mode regex handling rules.
  • host — regex — regular expression used to match the host part of the URL (i.e. domain name/ip address). Either this or the url option (but not both) must be specified. The expressions are handled according to match mode regex handling rules.
  • rewrite-url — JavaScript function — a JavaScript function Chawan will pass the site’s URL object to. If a new URL is returned, or the URL object is modified in any way, Chawan will transparently redirect the user to this new URL.
  • cookie = buffer.cookie — boolean / “save” — whether loading (with “save”, also saving) cookies should be allowed for this URL.
  • share-cookie-jar — host string — cookie jar to use for this domain. Useful for e.g. sharing cookies with subdomains.
  • referer-from = buffer.referer-from — boolean — whether or not Chawan should send a Referer header when opening requests originating from this domain. Simplified example: if you click a link on a.com that refers to b.com, and referer-from is true, b.com is sent “a.com” as the Referer header.
  • scripting = buffer.scripting — boolean / “app” — enable/disable JavaScript execution on this site. See buffer.scripting for details.
  • styling = buffer.styling — boolean — enable/disable author styles (CSS) on this site.
  • images = buffer.images — boolean — enable/disable loading of images on this site.
  • document-charset = encoding.document-charset — charset label string — specify the default encoding for this site.
  • proxy = network.proxy — URL string — specify a proxy for network requests fetching contents of this buffer.
  • default-headers = network.default-headers — table — specify a list of default headers for HTTP(S) network requests to this buffer.
  • insecure-ssl-no-verify = false — boolean — when set to true, this disables peer and hostname verification for SSL keys on this site, like curl --insecure would.
🚨 Please do not use this unless you are absolutely sure you know what you are doing. Like, genuinely.
  • autofocus = buffer.autofocus — boolean — when set to true, elements with an “autofocus” attribute are focused on automatically after the buffer is loaded. If scripting is enabled, this also allows scripts to focus on elements.
  • meta-refresh = buffer.meta-refresh — “never” / “always” / “ask” — whether or not http-equiv=refresh meta tags and headers should be respected. “never” completely disables them, “always” automatically accepts all of them, “ask” brings up a pop-up menu.
  • history = buffer.history — boolean — whether or not browsing history should be saved to the disk for this URL.
  • mark-links = buffer.mark-links — boolean — add numeric markers before links.
  • user-style = buffer.user-style — string — specify a user style sheet specific to the site. Refer to buffer.user-style for details.
  • ask-download-dir = external.ask-download-dir — string — specify whether the user should be prompted for a path when saving resources from this URL.

🎀 Keybindings 🎀

Keybindings go in these sections:

  • for pager interaction: [page]
  • for line editing: [line]

Keybindings are configured using the syntax



'<keybinding>' = '<action>'

Where <keybinding> is a combination of unicode characters using the syntax described below.

<action> is either a command defined in the [cmd] section, or a JavaScript expression. This document only describes the pre-defined actions in the default config; for a description of the API, see cha-api(7).

Examples:



# show change URL when Control, Escape and j are pressed
'C-M-j' = 'load'

# go to the first line of the page when g is pressed twice without a preceding
# number, or to the line when a preceding number is given.
'g g' = 'gotoLineOrStart'

# JS functions and expressions are accepted too. Following replaces the
# default search engine with DuckDuckGo Lite.
# (See api.md for a list of available functions, and a discussion on how
# to add your own "namespaced" commands like above.)
'C-k' = '() => pager.load("ddg:")'

✨ Keybinding format ✨

A keybinding is a space-separated list of keys, optionally prefixed by modifiers S- (shift), C- (control), or M- (meta).

In general, ASCII/Unicode keys can be written as-is. The exception is space, which is written as SPC.

Other supported named keys are: TAB, ESC, RET (return key), LF (enter key/line feed), Left, Up, Down, Right (cursor keys), PageUp, PageDown (page up/down), Home, End, and function keys F1 through F20.

okay so real talk about spaces in key sequences 👀 — for backwards-compatibility, spaces can be omitted from key sequences that do not start with an upper-case letter. so gg and g g? literally the same thing, no cap ✨. BUT — components that start with an upper-case letter (think Gg) are reserved for key names, so those must be space-separated (write it as G g) or the parsing gets ambiguous and everything falls apart 😭.

also, for backwards-compatibility, a single space at the beginning/end of the keybinding is translated to SPC.

🫶 heads up bestie: this feature is deprecated, and will be removed in a future version. don't get too attached.

🎀 Pager actions 🎀

Default keybindings are highlighted in bold.

  • quit — q — exit the browser. bye bestie 👋💅
  • suspend — C-z — temporarily suspend the browser. and yeah, this also suspends child processes including buffers or CGI scripts, so if you are downloading something, that download is suspended too until you restart the process (e.g., with the shell command fg). it's giving "nap time for everyone" 😴
  • load — C-l — open the current address in the URL bar.
  • loadCursor — M-l — open the address of the link or image being hovered in the URL bar. if there's no link/image under the cursor, you just get an empty URL bar. vibe check: empty 🫙
  • loadEmpty — open an empty address bar.
  • webSearch — C-k — open the URL bar with an arbitrary search engine. at the moment this is Brave Search, but this may change in the future 👀
  • dupeBuffer — M-u — duplicate the current buffer. this is a shallow clone, so modifications to one buffer will affect the other. they're twins, not copies, fr fr 👯
  • reloadBuffer — U — open a new buffer with the current buffer's URL, replacing the current buffer.
  • lineInfo — C-g — display information about the current line on the status line.
  • toggleSource — \ (backslash) — if you're viewing an HTML buffer, open a new buffer with its source. otherwise, open the current buffer's contents as HTML. flip it and reverse it 🔄
  • saveScreen — s s — save the rendered buffer to a file.
  • saveSource — s S — save the buffer's source to a file.
  • editScreen — s e — open the rendered buffer in an editor.
  • editSource — s E — open the buffer's source in an editor.
  • discardBuffer — D — discard the current buffer, and move back to the previous/next buffer depending on what the previously viewed buffer was.
  • discardBufferPrev, discardBufferNext — d , (d and then a comma), d . (d and then a period) — discard the current buffer, and move back to the previous/next buffer.
  • discardTree — M-d — discard all child buffers of the current buffer. whole family tree, gone 🫡
  • nextBuffer, prevBuffer — . (period), , (comma) — switch to the next or previous buffer respectively.
  • enterCommand — M-c — directly enter a JavaScript command. note that this interacts with the pager, not the website being displayed. important distinction bestie 💅
  • searchForward, searchBackward — search for a string in the current buffer, forwards or backwards. an empty string repeats the previous search in the respective direction.
  • isearchForward, searchBackward — / (slash), ? (question mark) — incremental-search for a string, highlighting the first result, forwards or backwards. (that is, the search result will be highlighted as you type. live results, iconic ✨) an empty string repeats the previous search in the respective direction.
  • searchNext, searchPrev — n, N — jump to the nth (or if unspecified, first) next/previous search result in the current search direction. e.g., if you searched with / (slash), then searchPrev will jump to the previous item, but if you searched with ? (question mark), then it will jump to the next item. directions are lowkey sneaky like that 😭
  • peek — display a message of the current buffer's URL on the status line.
  • peekCursor — u — display a message of the URL or the value of the title attribute under the cursor on the status line. multiple calls let you cycle through the two. (press u once → title, press again → URL) it's a little toggle, we love a toggle 🔁
  • showFullAlert — s u — show the last alert inside the line editor. you can also view previous ones using C-p or C-n.
  • copyURL — M-y — copy the current buffer's URL to the system clipboard.
  • copyCursorLink — y u — copy the link under the cursor to the system clipboard.
  • copyCursorImage — y I — copy the URL of the image under the cursor to the system clipboard.
  • gotoClipboardURL — M-p — go to the URL currently on the clipboard.
  • openBookmarks — M-b — open the bookmark file.
  • addBookmark — M-a — add the current page to your bookmarks.
  • toggleLinkHints — f — show hints before each link (or button). after typing a hint, the cursor is placed on the respective link. the hint character set may be customized with input.link-hint-chars 🎀
  • toggleLinkHintsAutoClick — same as toggleLinkHints, but it also clicks the selected link. one step instead of two, we stan efficiency ⚡

🌸 Buffer actions 🌸

n refers to a number preceding the action. e.g. in 10gg, n is 10. if no preceding number is input, then it is left unspecified. no n, no problem 🫶

Default keybindings are highlighted in bold.

  • cursorUp, cursorDown — j/C-p/Up, k/C-n/Down — move the cursor upwards/downwards by n lines, or if n is unspecified, by 1.
  • cursorLeft, cursorRight — h/Left, l/Right — move the cursor to the left/right by n cells, or if n is unspecified, by 1.
  • cursorLineBegin — 0/Home — move the cursor to the first cell of the line.
  • cursorLineTextStart — ^ (caret) — move the cursor to the first non-blank character of the line.
  • cursorLineEnd — $ (dollar)/End — move the cursor to the last cell of the line.
  • cursorNextWord, cursorNextViWord, cursorNextBigWord — w, W — move the cursor to the beginning of the nth next word.
  • cursorPrevWord, cursorPrevViWord, cursorPrevBigWord — move the cursor to the end of the nth previous word.
  • cursorWordEnd, cursorViWordEnd, cursorBigWordEnd — e, E — move the cursor to the end of the current word, or if you're already there, to the end of the nth next word.
  • cursorWordBegin, cursorViWordBegin, cursorBigWordBegin — b, B — move the cursor to the beginning of the current word, or if you're already there, to the end of the nth previous word.
  • cursorPrevLink, cursorNextLink — [, ] — move the cursor to the end/beginning of the previous/next clickable element (e.g. link, input field, etc). hop hop hop 🦋
  • cursorPrevParagraph, cursorNextParagraph — { (left brace), } (right brace) — move the cursor to the end/beginning of the nth previous/next paragraph.
  • cursorRevNthLink — move the cursor to the nth link of the document, counting backwards from the document's last line.
  • cursorNthLink — move the cursor to the nth link of the document.
  • pageUp, pageDown, pageLeft, pageRight — C-b/PageUp, C-f/PageDown, z H, z L — scroll up/down/left/right by n pages, or if n is unspecified, by one page.
  • halfPageUp, halfPageDown, halfPageLeft, halfPageUp — C-u, C-d — scroll up/down/left/right by n half pages, or if n is unspecified, by one page.
  • scrollUp, scrollDown, scrollLeft, scrollRight — K/C-y, J/C-e, z h, z l — scroll up/down/left/right by n lines, or if n is unspecified, by one line.
  • click — RET/LF — click the HTML element currently under the cursor. n specifies the number of clicks in JS events. 👆👆
  • rightClick — c — send a right click to the buffer. if it doesn't catch the event (i.e. no JS context menu is shown), toggle the menu instead.
  • toggleMenu — C — toggle the menu.
  • openBufferMenu — open the buffer selection menu.
  • viewImage — I — view the image currently under the cursor in an external viewer. 🖼️
  • reshape — R — reshape the current buffer (= render the current page anew). useful if the layout is not updating even though it should have. it's giving stubborn 😤
  • redraw — r — redraw screen contents. useful if something messed up the display.
  • cursorFirstLine, cursorLastLine — move to the beginning/end in the buffer.
  • cursorTop, cursorMiddle, cursorBottom — H, M, L — move to the first line/line in the middle of/last line on the screen. (equivalent to H, M, L in vi.)
  • raisePage, raisePageBegin, centerLine, centerLineBegin, lowerPage, lowerPageBegin — z t, z RET, z z, z ., z b, z - (z and then minus) — if n is specified, move the cursor to line n. then:
    • raisePage scrolls down so that the cursor is on the top line of the screen. (vi z RET, vim z t.)
    • centerLine shifts the screen so that the cursor is in the middle of the screen. (vi z ., vim z z.)
    • lowerPage scrolls up so that the cursor is on the bottom line of the screen. (vi z -, vim z b.) the -Begin variants also move the cursor to the line's first non-blank character, as the original keybindings in vi do.
  • nextPageBegin — z + (z and then plus) — if n is specified, move to the screen before the nth line and raise the page. otherwise, go to the next screen's first line and raise the page.
  • previousPageBegin — z ^ (z and then caret) — if n is specified, move to the screen before the nth line and lower the page. otherwise, go to the previous screen's last line and lower the page.
  • cursorLeftEdge, cursorMiddleColumn, cursorRightEdge — g 0, g c, g $ (g and then dollar) — move to the first/middle/last column on the screen.
  • centerColumn — center screen around the current column. (w3m Z.)
  • gotoLineOrStart, gotoLineOrEnd — g g, G — if n is specified, jump to line n. otherwise, jump to the first/last line of the buffer. ✨ iconic jump ✨
  • gotoColumnOrBegin, gotoColumnOrEnd — | (pipe) — if n is specified, jump to column n of the current line. otherwise, jump to the first/last column.
  • mark — m — wait for a character x and then set a mark with the ID x. 📌
  • gotoMark, gotoMarkY — ` (grave accent), ’ (apostrophe) — wait for a character x, then jump to the mark with the ID x (if it actually exists on the page, that is). gotoMark sets both the X and Y positions; gotoMarkY only sets the Y position.
  • markURL — : (colon) — turns URL-like strings into anchors on the current page. cute little auto-linker 💅
  • saveLink — s RET — save the resource from the URL the cursor is pointing at to the disk.
  • saveSource — s S — save the source of the current buffer to the disk.
  • saveImage — s I — save the image currently under the cursor.
  • toggleImages — M-i — toggle display of images in the current buffer.
  • toggleScripting — M-j — reload the current buffer with scripting enabled/disabled.
  • toggleCookie — M-k — reload the current buffer with cookies enabled/disabled.
  • cursorSearchWordForward — C-a, * (asterisk) — search for the word currently under the cursor.
  • cursorSearchWordBackward — # (hash) — search for the word currently under the cursor, but backwards.

🎀 Select actions 🎀

okay so select menu actions go in the [select] section, bestie. these keybindings apply to both <select> tags and the context menu (the one you invoke with c).

n means a number you typed before the action. like in 10gg, n is 10. if you didn't type a number first, then it's just left unspecified. no stress.

Default keybindings are highlighted in bold, down below 👇

  • select.cursorUp, select.cursorDown — j/C-p/Up/[, k/C-n/Down/] — move the cursor upwards/downwards by n menu items, or by 1 if n is unspecified.
  • select.scrollUp, select.scrollDown — K/C-y, J/C-e, z h, z l — scroll up/down/left/right by n lines, or by one line if n is unspecified.
  • select.click — RET/LF/l/Right — submit the option you've currently got selected.
  • select.cancel — C-c/C-g/c/C/h/Left — close the select menu. (the c/C defaults are there for symmetry with opening the context menu, iykyk.)
  • select.pageUp, select.pageDown — C-u, C-d — move up/down one page on the select menu.
  • select.halfPageUp, select.halfPageDown — C-u, C-d — move up/down by half the select menu's size.
  • select.gotoLineOrStart, select.gotoLineOrEnd — g g, G — jump to the first/last line of the select menu.
  • select.searchForward, select.searchBackward — / (slash), ? (question mark) — search & jump to a menu item. an empty string just repeats the previous search in that direction. 🔍
  • select.searchNext, select.searchPrev — n, N — jump to the nth (or the first, if n is unspecified) next/previous search result in the current search direction. e.g., if you searched with / (slash), then searchPrev jumps to the previous item, but if you searched with ? (question mark), then it jumps to the next item. yes it flips, that's the whole point 💫

🦋 Line-editing actions 🦋

line-editing actions live in the [line] section. obviously.

  • line.submit — RET, LF — submit the text you've currently entered.
  • line.cancel — C-g — close the editor and cancel whatever operation it was opened for.
  • line.copySelection — M-w — copy the current selection.
  • line.copyOrCancel — C-c — if there's an active selection, copy it. otherwise it's literally the same as line.cancel.
  • line.backspace, line.delete — C-h, C-d — delete the character before (backspace)/after (delete) the cursor.
  • line.clear, line.kill — C-u/C-x C-?, C-k — delete text before (clear)/after (kill) the cursor.
  • line.openEditor — C-x C-e — open the line editor's contents in $EDITOR. main character behaviour tbh.
  • line.clearWord, line.killWord — C-w, M-d — delete the word before (clear)/after (kill) the cursor.
  • line.backward, line.forward — C-b, C-f — move the cursor backward/forward by one character.
  • line.prevWord, line.nextWord — M-b, M-f — move the cursor to the previous/next word by one character
  • line.begin, line.end — C-a/Home, C-e/End — move the cursor to the beginning/end of the line.
  • line.escape — C-v — ignore keybindings for the next character.
  • line.prevHist, line.nextHist — C-p, C-n — jump to the previous/next history entry
Note: to make URL editing actually bearable, the line editor has a different definition of what a word is than the pager does. for the line editor, a word is either a sequence of alphanumeric characters, or any single non-alphanumeric character. (so like, https:// consists of four words: https, :, / and /. yes really, four. 🙈)
# Control+A moves the cursor to the beginning of the line.
'C-a' = 'line.begin'

# Escape+D deletes everything after the cursor until it reaches a word-breaking
# character.
'M-d' = 'line.killWord'

🌈 Appendix 🌈

Regex handling

so regexes are currently handled with the libregexp library from QuickJS. which means every regular expression works exactly like it does in JavaScript. no cap.

there are two different modes of regex preprocessing in Chawan: “search” mode and “match” mode. Match mode is what configs use (so every value in this document described as “regex”). Search mode is what the on-page search function uses (via searchForward/isearchForward etc.).

Match mode

regexes are assumed to be exact matches — except when they start with a caret (^) sign or end with an unescaped dollar ($) sign.

in other words, here are the transformations that happen:

^abcd -> ^abcd (no change, only beginning is matched)
efgh$ -> efgh$ (no change, only end is matched)
^ijkl$ -> ^ijkl$ (no change, the entire line is matched)
mnop -> ^mnop$ (changed to exact match, the entire line is matched)

match mode has no way to toggle JavaScript regex flags like i. nope. none. 😭

Search mode

for on-page search, those transformations above do not apply; searching /abcd searches for the string abcd inside all lines.

search mode also has a couple other convenience transformations (and heads up: these do not work in match mode):

  • the string \c (backslash + lower-case c) inside a search-mode regex turns on case-insensitive matching.
  • conversely, \C (backslash + capital C) turns case-insensitive matching off. (super useful if you have ignore-case set to true, which is the default.)
  • \< and \> get converted to \b (as in vi, grep, etc.)

just like match mode, search mode operates on individual lines. which means search patterns do not match text that wraps over multiple lines. sorry 💀

Path handling

the rules for path handling are similar to how the shell handles strings.

  • Tilde-expansion is used to figure out the user's home directory. so like ~/whatever totally works.
  • Environment variables can be used like $ENV_VAR.
  • Relative paths are relative to the Chawan configuration directory (i.e. $CHA_DIR).

some environment variables are also exported by Chawan:

  • $CHA_BIN_DIR: the directory the cha binary resides in. symbolic links are automatically resolved to determine this path.
  • $CHA_LIBEXEC_DIR: the directory for all the executables Chawan uses for its operation. by default this is $CHA_BIN_DIR/../libexec/chawan.
  • $CHA_DIR: the configuration directory. (this can also be set by the user; see the top section for details.)
  • $CHA_DATA_DIR: if the configuration file uses XDG base directories, this is ${XDG_DATA_HOME:-$HOME/.local/share}/chawan. otherwise it's the same as $CHA_DIR.
    • Exception: if $CHA_DIR is set before cha is invoked, then $CHA_DATA_DIR is also read. this is so nested invocations work in configurations with XDG basedirs. 🫶

Word types

word-based pager commands can operate with different definitions of what a word even is. currently, these are:

  • w3m words
  • vi words
  • Big words

w3m word

a w3m word is a sequence of alphanumeric characters. symbols are treated the same way as whitespace.

vi word

a vi word is a sequence of characters in the same character category. currently the character categories are alphanumeric characters, symbols, han letters, hiragana, katakana, and hangul.

vi words may be separated by whitespace; however, vi words from separate categories don't have to be whitespace-separated. e.g. the following character sequence contains two words:

hello[]+{}@`!

Big word

a big word is a sequence of non-whitespace characters.

it's essentially the same as a w3m word, but with symbols being defined as non-whitespace. big word energy honestly 👑

👀 See also

cha(1) cha-api(7)

and that's a wrap on CHA-CONFIG(5) — section 5 of Chawan's manual, bestie 💜 go forth and configure your heart out, you absolute icon 🎀✨

📦 where this page comes from