FreeBSD Manual Pages

home | help

CHA-CONFIG(5) File Formats Manual CHA-CONFIG(5)

Configuration of Chawan
Chawan supports configuration of various options like keybindings, user
stylesheets, site preferences, etc. The configuration format is simi-
lar to toml, with the following exceptions:

• Inline tables may span across multiple lines.

• Regular tables ([table]) and inline tables (table = {}) have differ-
ent semantics. The first is additive, meaning old values are not re-
moved. The second is destructive, and clears all 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.

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

Following is a list of start-up options:

Name Value Default Function
--------------------------------------------------------------------------------------
visual-home url "about:chawan" Page opened when Chawan is called with
the -V option and no other pages are
passed as arguments.
--------------------------------------------------------------------------------------
startup-script JavaScript "" Script Chawan runs on start-up. Pages
code will not be loaded until this function
exits. (Note however that asynchro-
nous functions like setTimeout do not
block loading.)
--------------------------------------------------------------------------------------
headless boolean / false When set to true or "dump", the
"dump" 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 re-
quests 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 set-
Interval.)

Piping cha to an external pro-
gram or passing the -d switch
has the same effect as setting
this option to "dump".
--------------------------------------------------------------------------------------
console-buffer boolean true Whether Chawan should open a console
buffer in non-headless mode.

Warning: this is only useful
for debugging. Disabling this
option without manually redi-
recting standard error will re-
sult 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 UA styles like this: */
@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 }
@media (monochrome) { /* only in color-mode "monochrome" (or -M) */
/* 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 here, but I strongly recommend using
# [[siteconf]] to enable it on a per-site basis instead.

Following is a list of buffer options:

Name Value Default Function
--------------------------------------------------------------------------------
styling boolean true Enable/disable author style sheets.
Note that disabling this does not af-
fect user styles.
--------------------------------------------------------------------------------
scripting boolean / false Enable/disable JavaScript in all
"app" buffers.

"app" also enables JavaScript
APIs that can be used to fin-
gerprint 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 reasons, users are
encouraged to selectively en-
able JavaScript with [[site-
conf]] instead of using this
setting.
--------------------------------------------------------------------------------
images boolean false Enable/disable inline image display.
--------------------------------------------------------------------------------
cookie boolean / false Enable/disable cookies on sites.
"save"
If the string "save" is speci-
fied, 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 web-
sites relying on cross-site
cookies may not work as ex-
pected. You may use the
[[siteconf]] "share-cookie-jar"
setting to adjust this behavior
for specific sites.
--------------------------------------------------------------------------------
referer-from boolean false 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 boolean false 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 "never" / "ask" Whether or not http-equiv=refresh meta
"always" / tags should be respected. "never"
"ask" completely disables them, "always" au-
tomatically accepts all of them, "ask"
brings up a pop-up menu.
--------------------------------------------------------------------------------
history boolean true Whether or not browsing history should
be saved to the disk.
--------------------------------------------------------------------------------
mark-links boolean false Add numeric markers before links. In
headless/dump mode, this also prints a
list of URLs after the page.
--------------------------------------------------------------------------------
user-style string "" A user stylesheet applied to all
buffers.

External stylesheets can be im-
ported using the @import
'file.css'; syntax. Paths are
relative to the configuration
directory.

Nested @import is not supported
yet.

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

Following is a list of search options:

Name Value Default Function
--------------------------------------------------------------------------------
wrap boolean true Whether on-page searches should wrap
around the document.
--------------------------------------------------------------------------------
ignore-case "auto" / "auto" When set to true, document-wide
boolean searches are case-insensitive by de-
fault. When set to "auto", searches
are only case-sensitive when the
search term includes a capital letter.

Note: this can also be overrid-
den inline in the search bar
(vim-style), with the escape
sequences \c (ignore case) and
\C (strict case). See search
mode for details.)

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

Following is a list of encoding options:

Name Value Default Function
--------------------------------------------------------------------------------
docu- array of ["utf-8", List of character sets for loading
ment-charset charset "sjis", documents.
label "euc-jp",
strings "latin2"] 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 differ-
ent charset, so long as the
specified charset can decode
the document correctly.
--------------------------------------------------------------------------------
dis- string "auto" Character set for keyboard input
play-charset and displaying documents.

Used in dump mode as well.

(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:

Name Value Default Function
------------------------------------------------------------------------------------
tmpdir path {usually Directory used to save tempo-
/tmp/cha-tmp-user} rary files.
------------------------------------------------------------------------------------
editor shell {usually $EDITOR} External editor command. %s is
command substituted for the file name,
%d for the line number.
------------------------------------------------------------------------------------
mailcap array {see mailcap docs} Search path for mailcap files.
of (See cha-mailcap(5) for de-
paths tails.) Directories specified
first have higher precedence.
------------------------------------------------------------------------------------
mime-types array {see mime.types Search path for mime.types
of docs} files. (See cha-mime.types(5)
paths for details.)
------------------------------------------------------------------------------------
auto-mailcap path "auto.mailcap" Mailcap file for entries that
are automatically executed.

The "Open as" prompt
also saves entries in
this file.
------------------------------------------------------------------------------------
cgi-dir array {see local CGI Search path for local CGI
of docs} scripts. (See cha-localcgi(5)
paths for details.)
------------------------------------------------------------------------------------
urimethodmap array {see urimethodmap Search path for urimethodmap
of docs} files. (See
paths cha-urimethodmap(5) for de-
tails.)
------------------------------------------------------------------------------------
w3m-cgi-compat boolean false Enable local CGI compatibility
with w3m. In short, it redi-
rects file:///cgi-bin/* and
file:///$LIB/cgi-bin/* to
cgi-bin:*. For further de-
tails, see cha-localcgi(5).
------------------------------------------------------------------------------------
download-dir path {same as tmpdir} Path to pre-fill for "Save to:"
prompts.
------------------------------------------------------------------------------------
show-down- boolean true Whether the about:downloads
load-panel should be shown after starting
a download.
------------------------------------------------------------------------------------
copy-cmd shell "xsel -bi" Command to use for "copy to
command clipboard" operations.
------------------------------------------------------------------------------------
paste-cmd shell "xsel -bo" Command to use for "read from
command clipboard" operations.
------------------------------------------------------------------------------------
bookmark path "bookmark.md" Path to the bookmark.md file.
(The file it points to should
have a .md extension, so that
its type can be correctly de-
duced.)
------------------------------------------------------------------------------------
history-file path "history.uri" Path to the history file.
------------------------------------------------------------------------------------
history-size number 100 Maximum length of the history
file.
------------------------------------------------------------------------------------
cookie-file path "cookies.txt" Path to the cookie file.

The format is equivalent
to curl's "cookies.txt"
format, except that a
"jar@" part is prepended
for cookies that belong
in a different jar than
the domain.

Cookies from this file
are used if
"buffer.cookie" (or its
equivalent siteconf
override) is set to true
or "save". This means
that true sets the
cookie-file to a
"read-only" mode.

Input
Input options are to be placed in the [input] section.

Name Value Default Function
---------------------------------------------------------------------------------------
vi-nu- boolean true Whether vi-style numeric prefixes to com-
meric-prefix mands should be accepted.

Only applies for keybindings de-
fined in [page].
---------------------------------------------------------------------------------------
use-mouse boolean true Whether Chawan is allowed to intercept
mouse clicks.

The current implementation imitates
w3m.
---------------------------------------------------------------------------------------
osc52-copy boolean auto Whether Chawan should use the OSC 52 es-
/ cape sequence for copying to the clipboard
"auto" directly through the terminal. When
available, OSC 52 overrides exter-
nal.copy-cmd.

When set to "auto" (the default),
Chawan tries to detect whether OSC
52 is available on launch.
---------------------------------------------------------------------------------------
brack- boolean true Whether Chawan should ask for bracketed
eted-paste paste.

When true, the terminal will (hope-
fully) mark pasted text with escape
sequences, which a) ensures that
pasting a newline character into
the line editor does not submit the
editor, b) allows Chawan to inter-
cept text pasted into the pager,
automatically loading it into the
browser's URL bar.
---------------------------------------------------------------------------------------
wheel-scroll number 5 Number of lines to scroll for a mouse
wheel event.
---------------------------------------------------------------------------------------
side-wheel-scroll number 5 Number of columns to scroll for a mouse
side-wheel event.
---------------------------------------------------------------------------------------
link-hint-chars string abcde- A string of characters to use in tog-
fghijklmno- gleLinkHints. Any Unicode codepoint is
prstu- accepted, and they are ordered as speci-
vxyz fied 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 are to be placed in the [network] section.

Name Value Default Function
---------------------------------------------------------------------------------
max-redirect number 10 Maximum number of redirections to
follow.
---------------------------------------------------------------------------------
max-net-connec- number 12 Maximum number of simultaneous net-
tions work connections allowed in one
buffer. Further connections are
held back until the number returns
below the threshold.
---------------------------------------------------------------------------------
prepend-scheme string "https://" Prepend this to URLs passed to
Chawan without a scheme.

Note that local files (file:
scheme) will always be
checked first; only if this
fails, Chawan will retry the
request with prepend-scheme
set as the scheme.
---------------------------------------------------------------------------------
proxy URL unset Specify a proxy for all network re-
quests Chawan makes. Currently,
the formats http://user:pass@domain
and socks5://user:pass@domain are
accepted. (Unlike in curl, socks5h
is an alias of socks5, and DNS re-
quests are always tunneled.)

Can be overridden by site-
conf.
---------------------------------------------------------------------------------
default-headers table {omitted} Specify a list of default headers
for all HTTP(S) network requests.
Can be overridden by siteconf.
---------------------------------------------------------------------------------
al- boolean false WARNING: think twice before en-
low-http-from-file abling this.

Allows HTTP and HTTPS re-
quests from the file: and
stream: schemes. This is a
very bad idea in general,
because it allows local
files to ping remote servers
(a functionality commonly
abused by HTML e-mails to
track your mailbox activ-
ity.)

On the other hand, it allows
loading images in HTML
e-mails if you don't care
about the privacy implica-
tions.

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

Following is a list of display options:

Name Value Default Function
--------------------------------------------------------------------------------
color-mode "monochrome" "auto" Set the color mode. "auto"
/ "ansi" / for automatic detection,
"eight-bit" "monochrome" for black on
/ white, "ansi" for ansi col-
"true-color" ors, "eight-bit" for
/ "auto" 256-color mode, and
"true-color" for true col-
ors.
--------------------------------------------------------------------------------
format-mode "auto" / "auto" Specifies output formatting
["bold", modes. Accepts the string
"italic", "auto" or an array of spe-
"underline", cific attributes. An empty
"reverse", array ([]) disables format-
"strike", ting completely.
"overline",
"blink"]
--------------------------------------------------------------------------------
no-format-mode ["bold", "over- Disable specific formatting
"italic", line" modes.
"underline",
"reverse",
"strike",
"overline",
"blink"]
--------------------------------------------------------------------------------
image-mode "auto" / "auto" Specifies the image output
"none" / mode. "sixel" uses sixels
"sixel" / for output, "kitty" uses the
"kitty" Kitty image display proto-
col, "none" disables image
display completely.

"auto" tries to de-
tect sixel or kitty
support, and falls
back to "none" when
neither are avail-
able. This is the
default setting, but
you must also enable
buffer.images for im-
ages to work.
--------------------------------------------------------------------------------
sixel-colors "auto" / "auto" Only applies when dis-
2..65535 play.image-mode="sixel".
Setting a number overrides
the number of sixel color
registers reported by the
terminal.
--------------------------------------------------------------------------------
alt-screen "auto" / "auto" Enable/disable the alterna-
boolean tive screen.
--------------------------------------------------------------------------------
highlight-color color "cyan" Set the highlight color for
incremental search and
marks. Both hex values and
CSS color names are ac-
cepted.

In monochrome mode,
this setting is ig-
nored; instead, re-
verse video is used.
--------------------------------------------------------------------------------
highlight-marks boolean true Enable/disable highlighting
of marks.
--------------------------------------------------------------------------------
double-width-ambiguous boolean false Assume the terminal displays
characters in the East Asian
Ambiguous category as dou-
ble-width characters. Use-
ful when e.g. occupies two
cells.
--------------------------------------------------------------------------------
minimum-contrast number 100 Specify the minimum differ-
ence between the luminance
(Y) of the background and
the foreground. -1 disables
this function (i.e. allows
black letters on black back-
ground, etc).
--------------------------------------------------------------------------------
force-clear boolean false Force the screen to be com-
pletely cleared every time
it is redrawn.
--------------------------------------------------------------------------------
set-title boolean true Set the terminal emulator's
window title to that of the
current page.
--------------------------------------------------------------------------------
default-back- "auto" / "auto" Overrides the assumed back-
ground-color color ground color of the termi-
nal. "auto" leaves back-
ground color detection to
Chawan.
--------------------------------------------------------------------------------
default-fore- "auto" / "auto" Sets the assumed foreground
ground-color color color of the terminal.
"auto" leaves foreground
color detection to Chawan.
--------------------------------------------------------------------------------
query-da1 bool true Enable/disable querying Pri-
mary Device Attributes, and
with it, all "dynamic" ter-
minal querying.

Do not alter this
value unless Chawan
told you so; the out-
put will look awful.
--------------------------------------------------------------------------------
columns, lines, pix- number 80, 24, Fallback values for the num-
els-per-column, pix- 9, 18 ber of columns, lines, pix-
els-per-line els per column, and pixels
per line for the cases where
it cannot be determined au-
tomatically. (For example,
these values are used in
dump mode.)
--------------------------------------------------------------------------------
force-columns, boolean false Force-set columns, lines,
force-lines, force-pix- pixels per column, or pixels
els-per-column, per line to the fallback
force-pixels-per-line values provided above.

Status
Options concerning the status bar (last line on the screen) are to be
placed in the [status] section.

Following is a list of status options:

Name Value Default Function
--------------------------------------------------------------------------------
show-cursor-position boolean true Whether or not the current
line number should be dis-
played.
--------------------------------------------------------------------------------
show-hover-link boolean true Whether or not the link un-
der the cursor should be
displayed.

Omnirule
The omni-bar (by default opened with C-l) can be used to perform
searches using omni-rules. These are to be specified as sub-keys to
table [omnirule]. (The sub-key itself is ignored; you can use anything
as long it doesn't conflict with other keys.)

Examples:

# 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.split(":").slice(1).join(":"))'

# 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, se-
lected according to the maintainer's preference and the minimum crite-
rion that they must work without cookies and JavaScript. Currently,
these are:

• ddg: - DuckDuckGo Lite.

• br: - Brave Search.

• wk: - English Wikipedia.

• wd: - English Wikitionary.

• mo: - Mojeek.

Omnirule options:

Name Value Function
-----------------------------------------------------------------------------
match regex Regular expression used to match
the input string. Note that web-
sites passed as arguments are
matched as well.

Note: regexes are handled
according to the match mode
regex handling rules.
-----------------------------------------------------------------------------
substitute-url JavaScript func- A JavaScript function Chawan will
tion 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 specified for individual sites. Entries
are to be specified as sub-keys to table [siteconf]. (The sub-key it-
self is ignored; you can use anything as long it doesn't conflict with
other keys.)

Most siteconf options can also be specified globally; see the "over-
rides" 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:

Name Value Overrides Function
----------------------------------------------------------------------------------
url regex n/a Regular expression
used to match the URL.
Either this or the
host option must be
specified.

Note: regexes
are handled ac-
cording to the
match mode
regex handling
rules.
----------------------------------------------------------------------------------
host regex n/a Regular expression
used to match the host
part of the URL
(i.e. domain name/ip
address.) Either this
or the url option must
be specified.

Note: regexes
are handled ac-
cording to the
match mode
regex handling
rules.
----------------------------------------------------------------------------------
rewrite-url JavaScript n/a A JavaScript function
function Chawan will pass the
site's URL object to.
If a new URL is re-
turned, or the URL ob-
ject is modified in
any way, Chawan will
transparently redirect
the user to this new
URL.
----------------------------------------------------------------------------------
cookie boolean / buffer.cookie Whether loading (with
"save" "save", also saving)
cookies should be al-
lowed for this URL.
----------------------------------------------------------------------------------
share-cookie-jar host n/a Cookie jar to use for
this domain. Useful
for e.g. sharing cook-
ies with subdomains.
----------------------------------------------------------------------------------
referer-from boolean buffer.referer-from Whether or not we
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 ref-
erer-from is true,
b.com is sent "a.com"
as the Referer header.
----------------------------------------------------------------------------------
scripting boolean / buffer.scripting Enable/disable
"app" JavaScript execution
on this site. See
buffer.scripting for
details.
----------------------------------------------------------------------------------
styling boolean buffer.styling Enable/disable author
styles (CSS) on this
site.
----------------------------------------------------------------------------------
images boolean buffer.images Enable/disable image
display on this site.
----------------------------------------------------------------------------------
document-charset charset encoding.docu- Specify the default
label ment-charset encoding for this
string site.
----------------------------------------------------------------------------------
proxy URL network.proxy Specify a proxy for
network requests
fetching contents of
this buffer.
----------------------------------------------------------------------------------
default-headers table network.de- Specify a list of de-
fault-headers fault headers for
HTTP(S) network re-
quests to this buffer.
----------------------------------------------------------------------------------
inse- boolean n/a Defaults to false.
cure-ssl-no-ver- When set to true, this
ify disables peer and
hostname verification
for SSL keys on this
site, like curl --in-
secure would.

Please do not
use this unless
you are ab-
solutely sure
you know what
you are doing.
----------------------------------------------------------------------------------
autofocus boolean buffer.autofocus When set to true, ele-
ments with an "autofo-
cus" attribute are fo-
cused on automatically
after the buffer is
loaded.

If scripting is
enabled, this
also allows
scripts to fo-
cus on ele-
ments.
----------------------------------------------------------------------------------
meta-refresh "never" / buffer.meta-refresh Whether or not
"always" / http-equiv=refresh
"ask" meta tags should be
respected. "never"
completely disables
them, "always" auto-
matically accepts all
of them, "ask" brings
up a pop-up menu.
----------------------------------------------------------------------------------
history boolean buffer.history Whether or not brows-
ing history should be
saved to the disk for
this URL.
----------------------------------------------------------------------------------
mark-links boolean buffer.mark-links Add numeric markers
before links.
----------------------------------------------------------------------------------
user-style string buffer.user-style Specify a user style
sheet specific to the
site.

Please refer to
buffer.user-style
for details.

Keybindings
Keybindings are to be placed 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 with or with-
out modifiers. Modifiers are the prefixes C- and M-, which add control
or escape to the keybinding respectively (essentially making M- the
same as C-[). Modifiers can be escaped with the \ sign.

<action> is either a command defined in the [cmd] section, or a
JavaScript expression. Here we only describe the pre-defined actions
in the default config; for a description of the API, please see:

The API documentation at 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.
'gg' = '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:")'

Pager actions
Default key Name Function
-----------------------------------------------------------------------------
q quit Exit the browser.
-----------------------------------------------------------------------------
C-z suspend Temporarily suspend the browser

Note: this also suspends
e.g. buffer processes or CGI
scripts. So if you are
downloading something, that
will be delayed until you
restart the process.
-----------------------------------------------------------------------------
C-l load Open the current address in the URL
bar.
-----------------------------------------------------------------------------
M-l loadCursor Open the address of the link or im-
age being hovered in the URL bar.

If no link/image is under
the cursor, an empty URL bar
is opened.
-----------------------------------------------------------------------------
None loadEmpty Open an empty address bar.
-----------------------------------------------------------------------------
C-k webSearch Open the URL bar with an arbitrary
search engine. At the moment, this
is Brave Search, but this may
change in the future.
-----------------------------------------------------------------------------
M-u dupeBuffer Duplicate the current buffer by
forking its content process.
-----------------------------------------------------------------------------
U reloadBuffer Open a new buffer with the current
buffer's URL, replacing the current
buffer.
-----------------------------------------------------------------------------
C-g lineInfo Display information about the cur-
rent line on the status line.
-----------------------------------------------------------------------------
\ toggleSource If viewing an HTML buffer, open a
new buffer with its source. Other-
wise, open the current buffer's
contents as HTML.
-----------------------------------------------------------------------------
D discardBuffer Discard the current buffer, and
move back to the previous/next
buffer depending on what the previ-
ously viewed buffer was.
-----------------------------------------------------------------------------
d,, d. discardBufferPrev, Discard the current buffer, and
discardBufferNext move back to the previous/next
buffer, or open the link under the
cursor.
-----------------------------------------------------------------------------
M-d discardTree Discard all child buffers of the
current buffer.
-----------------------------------------------------------------------------
., ,, M-,, nextBuffer, pre- Traverse the buffer list.
M-., M-/ vBuffer, prevSibling-
Buffer, nextSibling- nextBuffer and prevBuffer
Buffer, parentBuffer switch to the next or previ-
ous buffer respectively.

prevSiblingBuffer and par-
entBuffer are deprecated
aliases for prevBuffer,
while nextSiblingBuffer is a
deprecated alias for
nextBuffer.
-----------------------------------------------------------------------------
M-c enterCommand Directly enter a JavaScript com-
mand. Note that this interacts
with the pager, not the website be-
ing displayed.
-----------------------------------------------------------------------------
None searchForward, Search for a string in the current
searchBackward buffer, forwards or backwards.
-----------------------------------------------------------------------------
/, ? isearchForward, Incremental-search for a string,
searchBackward highlighting the first result, for-
wards or backwards.
-----------------------------------------------------------------------------
n, N searchNext, search- Jump to the nth (or if unspecified,
Prev first) next/previous search result.
-----------------------------------------------------------------------------
None peek Display a message of the current
buffer's URL on the status line.
-----------------------------------------------------------------------------
u peekCursor Display a message of the URL or ti-
tle under the cursor on the status
line. Multiple calls allow cycling
through the two. (i.e. by default,
press u once -> title, press again
-> URL)
-----------------------------------------------------------------------------
su showFullAlert Show the last alert inside the line
editor. You can also view previous
ones using C-p or C-n.
-----------------------------------------------------------------------------
M-y copyURL Copy the current buffer's URL to
the system clipboard.
-----------------------------------------------------------------------------
yu copyCursorLink Copy the link under the cursor to
the system clipboard.
-----------------------------------------------------------------------------
yI copyCursorImage Copy the URL of the image under the
cursor to the system clipboard.
-----------------------------------------------------------------------------
M-p gotoClipboardURL Go to the URL currently on the
clipboard.
-----------------------------------------------------------------------------
M-b openBookmarks Open the bookmark file.
-----------------------------------------------------------------------------
M-a addBookmark Add the current page to your book-
marks.
-----------------------------------------------------------------------------
f toggleLinkHints 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 in-
put.link-hint-chars.

Buffer actions
Note: n in the following text refers to a number preceding the action.
e.g. in 10gg, n = 10. If no preceding number is input, then it is
left unspecified.

Default key Name Function
-----------------------------------------------------------------------------
j/C-p/Up ar- cursorUp, cursorDown Move the cursor upwards/down-
row, wards by n lines, or if n is
k/C-n/Down ar- unspecified, by 1.
row
-----------------------------------------------------------------------------
h/Left arrow, cursorLeft, cursorRight Move the cursor to the
l/Right arrow left/right by n cells, or if n
is unspecified, by 1.
-----------------------------------------------------------------------------
0/Home cursorLineBegin Move the cursor to the first
cell of the line.
-----------------------------------------------------------------------------
^ cursorLineTextStart Move the cursor to the first
non-blank character of the
line.
-----------------------------------------------------------------------------
$/End cursorLineEnd Move the cursor to the last
cell of the line.
-----------------------------------------------------------------------------
w, W cursorNextWord, cur- Move the cursor to the begin-
sorNextViWord, cur- ning of the next word.
sorNextBigWord
-----------------------------------------------------------------------------
None cursorPrevWord, cursor- Move the cursor to the end of
PrevViWord, cursorPre- the previous word.
vBigWord
-----------------------------------------------------------------------------
e, E cursorWordEnd, cursorVi- Move the cursor to the end of
WordEnd, cursorBigWor- the current word, or if already
dEnd there, to the end of the next
word.
-----------------------------------------------------------------------------
b, B cursorWordBegin, cur- Move the cursor to the begin-
sorViWordBegin, cursor- ning of the current word, or if
BigWordBegin already there, to the end of
the previous word.
-----------------------------------------------------------------------------
[, ] cursorPrevLink, cur- Move the cursor to the end/be-
sorNextLink ginning of the previous/next
clickable element (e.g. link,
input field, etc).
-----------------------------------------------------------------------------
{, } cursorPrevParagraph, Move the cursor to the end/be-
cursorNextParagraph ginning of the nth previ-
ous/next paragraph.
-----------------------------------------------------------------------------
None cursorRevNthLink Move the cursor to the nth link
of the document, counting back-
wards from the document's last
line.
-----------------------------------------------------------------------------
None cursorNthLink Move the cursor to the nth link
of the document.
-----------------------------------------------------------------------------
C-b, C-f, zH, pageUp, pageDown, Scroll up/down/left/right by n
zL pageLeft, pageRight pages, or if n is unspecified,
by one page.
-----------------------------------------------------------------------------
C-u, C-d halfPageUp, halfPage- Scroll up/down/left/right by n
Down, halfPageLeft, half pages, or if n is unspeci-
halfPageUp fied, by one page.
-----------------------------------------------------------------------------
K/C-y, J/C-e, scrollUp, scrollDown, Scroll up/down/left/right by n
zh, zl scrollLeft, scrollRight lines, or if n is unspecified,
by one line.
-----------------------------------------------------------------------------
Enter/Return click Click the HTML element cur-
rently under the cursor. n
specifies the number of clicks
in JS events.
-----------------------------------------------------------------------------
c rightClick 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.
-----------------------------------------------------------------------------
C toggleMenu Toggle the menu.
-----------------------------------------------------------------------------
I viewImage View the image currently under
the cursor in an external
viewer.
-----------------------------------------------------------------------------
R reshape Reshape the current buffer
(=render the current page
anew.) Useful if the layout is
not updating even though it
should have.
-----------------------------------------------------------------------------
r redraw Redraw screen contents. Useful
if something messed up the dis-
play.
-----------------------------------------------------------------------------
None (see go- cursorFirstLine, cursor- Move to the beginning/end in
toLine- LastLine the buffer.
OrStart/End
instead)
-----------------------------------------------------------------------------
H, M, L cursorTop, cursorMiddle, Move to the first line/line in
cursorBottom the middle of/last line on the
screen. (Equivalent to H, M, L
in vi.)
-----------------------------------------------------------------------------
zt, z Return, raisePage, raisePageBe-
zz, z., zb, z- gin, centerLine, center- If n is specified, move
LineBegin, lowerPage, cursor to line n. Then,
lowerPageBegin
• raisePage scrolls down
so that the cursor is
on the top line of the
screen. (vi z<CR>,
vim zt.)

• centerLine shifts the
screen so that the
cursor is in the mid-
dle of the screen.
(vi z., vim zz.)

• lowerPage scrolls up
so that the cursor is
on the bottom line of
the screen. (vi z-,
vim zb.) The -Begin
variants also move the
cursor to the line's
first non-blank char-
acter, as the variants
originating from vi
do.
-----------------------------------------------------------------------------
z+ nextPageBegin 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.
-----------------------------------------------------------------------------
z^ previousPageBegin 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.
-----------------------------------------------------------------------------
g0, gc, g$ cursorLeftEdge, cur- Move to the first/middle/last
sorMiddleColumn, cursor- column on the screen.
RightEdge
-----------------------------------------------------------------------------
None centerColumn Center screen around the cur-
rent column. (w3m Z.)
-----------------------------------------------------------------------------
gg, G gotoLineOrStart, gotoLi- If n is specified, jump to line
neOrEnd n. Otherwise, jump to the
start/end of the page.
-----------------------------------------------------------------------------
|, None gotoColumnOrBegin, goto- If n is specified, jump to col-
ColumnOrEnd umn n of the current line.
Otherwise, jump to the
first/last column.
-----------------------------------------------------------------------------
m mark Wait for a character x and then
set a mark with the ID x.
-----------------------------------------------------------------------------
`, ' gotoMark, gotoMarkY Wait for a character x and then
jump to the mark with the ID x
(if it exists on the page).

gotoMark sets both the X
and Y positions; go-
toMarkY only sets the Y
position.
-----------------------------------------------------------------------------
: markURL Convert URL-like strings to an-
chors on the current page.
-----------------------------------------------------------------------------
s Return saveLink Save resource from the URL
pointed to by the cursor to the
disk.
-----------------------------------------------------------------------------
sS saveSource Save the source of the current
buffer to the disk.
-----------------------------------------------------------------------------
sI saveImage Save the image currently under
the cursor.
-----------------------------------------------------------------------------
M-i toggleImages Toggle display of images in the
current buffer.
-----------------------------------------------------------------------------
M-j toggleScripting Reload the current buffer with
scripting enabled/disabled.
-----------------------------------------------------------------------------
M-k toggleCookie Reload the current buffer with
cookies enabled/disabled.

Line-editing actions
Default key Name Function
-----------------------------------------------------------------------------
Return line.submit Submit the line.
-----------------------------------------------------------------------------
C-c line.cancel Cancel the current operation.
-----------------------------------------------------------------------------
C-h, C-d line.backspace, Delete character before (back-
line.delete space)/after (delete) the cursor.
-----------------------------------------------------------------------------
C-u/C-xC-?, line.clear, line.kill Delete text before (clear)/after
C-k (kill) the cursor.
-----------------------------------------------------------------------------
C-xC-e line.openEditor Open the line editor's contents in
$EDITOR.
-----------------------------------------------------------------------------
C-w, M-d line.clearWord, Delete word before (clear)/after
line.killWord (kill) the cursor.
-----------------------------------------------------------------------------
C-b, C-f line.backward, Move cursor backward/forward by one
line.forward character.
-----------------------------------------------------------------------------
M-b, M-f line.prevWord, Move cursor to the previous/next
line.nextWord word by one character
-----------------------------------------------------------------------------
C-a/Home, line.begin, line.end Move cursor to the beginning/end of
C-e/End the line.
-----------------------------------------------------------------------------
C-v line.escape Ignore keybindings for next charac-
ter.
-----------------------------------------------------------------------------
C-p, C-n line.prevHist, Jump to the previous/next history
line.nextHist entry

Note: to facilitate URL editing, the line editor has a different defin-
ition of what a word is than the pager. For the line editor, a word is
either a sequence of alphanumeric characters, or any single non-al-
phanumeric character. (This means that e.g. https:// consists of four
words: https, :, / and /.)

# 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
Regular expressions are currently handled using the libregexp library
from QuickJS. This means that all regular expressions work as in
JavaScript.

There are two different modes of regex preprocessing in Chawan:
"search" mode and "match" mode. Match mode is used for configurations
(meaning in all values in this document described as "regex"). Search
mode is used for the on-page search function (using searchFor-
ward/isearchForward etc.)

Match mode
Regular expressions are assumed to be exact matches, except when they
start with a caret (^) sign or end with an unescaped dollar ($) sign.

In other words, the following transformations occur:

^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.

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

Search mode also has some other convenience transformations (these do
not work in match mode):

• The string \c (backslash + lower-case c) inside a search-mode regex
enables case-insensitive matching.

• Conversely, \C (backslash + capital C) disables case-insensitive
matching. (Useful if you have ignore-case set to true, which is the
default.)

• \< and \> is converted to \b (as in vi, grep, etc.)

Like match mode, search mode operates on individual lines. This means
that search patterns do not match text wrapped over multiple lines.

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

• Tilde-expansion is used to determine the user's home directory. So
e.g. ~/whatever 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 which the cha binary resides in. Sym-
bolic links are automatically resolved to determine this path.

• $CHA_LIBEXEC_DIR: the directory for all executables Chawan uses for
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
is the same as $CHA_DIR.

• Exception: if $CHA_DIR is set before cha is invoked, then
$CHA_DATA_DIR is also read. This is to make nested invocations
work in configurations with XDG basedirs.

Word types
Word-based pager commands can operate with different definitions of
words. Currently, these are:

• w3m words

• vi words

• Big words

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

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

vi words may be separated by whitespace; however, vi words from sepa-
rate categories do not have to be whitespace-separated. e.g. the fol-
lowing character sequence contains two words:

hello[]+{}@`!

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

It is essentially the same as a w3m word, but with symbols being de-
fined as non-whitespace.

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages