'\" t
.\" Automatically generated by Pandoc 3.3
.\"
.TH "cha\-config" "5" "" "" "Configuration of Chawan"
.SH Configuration of Chawan
Chawan supports configuration of various options like keybindings, user
stylesheets, site preferences, etc.
The configuration format is very similar to toml, with the following
exceptions:
.IP \[bu] 2
Inline tables may span across multiple lines.
.IP \[bu] 2
Table arrays can be cleared by setting a variable by the same to the
empty array.
This allows users to disable default table array rules.
.PP
Example:
.IP
.EX
omnirule = [] # note: this must be placed at the beginning of the file.

[[omnirule]] # this is legal. all default omni\-rules are now disabled.
.EE
.PP
Chawan will look for a config file in the $XDG_CONFIG_HOME/chawan/
directory called \f[CR]config.toml\f[R].
(Chawan defaults to \[ti]/.config if the XDG_CONFIG_HOME environment
variable is not set.)
See the default configuration file in the res/ folder, and bonus
configuration files in the bonus/ folder for further examples.
.SS Start
Start\-up options are to be placed in the \f[CR][start]\f[R] section.
.PP
Following is a list of start\-up options:
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
visual\-home
T}@T{
url
T}@T{
Page opened when Chawan is called with the \-V option (and no other
pages are passed as arguments.)
T}@T{
T}
T{
startup\-script
T}@T{
JavaScript code
T}@T{
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.)
T}@T{
T}
T{
headless
T}@T{
boolean
T}@T{
Whether Chawan should always start in headless mode.
Automatically enabled when Chawan is called with \-r.
T}@T{
T}
T{
console\-buffer
T}@T{
boolean
T}@T{
Whether Chawan should open a console buffer in non\-headless mode.
Defaults to true.
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.
T}@T{
T}
.TE
.SS Buffer
Buffer options are to be placed in the \f[CR][buffer]\f[R] section.
.PP
Following is a list of buffer options:
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
styling
T}@T{
boolean
T}@T{
Enable/disable author style sheets.
Note that disabling this does not affect user styles set in
\f[CR][css]\f[R].
Defaults to true (i.e.\ enabled).
T}@T{
T}
T{
scripting
T}@T{
boolean
T}@T{
Enable/disable JavaScript in \f[I]all\f[R] buffers.
Defaults to false.
For security reasons, users are encouraged to selectively enable
JavaScript with \f[CR][[siteconf]]\f[R] instead of using this setting.
T}@T{
T}
T{
images
T}@T{
boolean
T}@T{
Enable/disable experimental image support.
Defaults to false.
T}@T{
T}
T{
cookie
T}@T{
boolean
T}@T{
Enable/disable cookies on sites.
Defaults to false.
Note: 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 \f[CR][[siteconf]]\f[R] \[lq]cookie\-jar\[rq] and
\[lq]third\-party\-cookie\[rq] settings to adjust this behavior for
specific sites.
T}@T{
T}
T{
referer\-from
T}@T{
boolean
T}@T{
Enable/disable the \[lq]Referer\[rq] header.
Defaults to false.
For security reasons, users are encouraged to leave this option
disabled, only enabling it for specific sites in
\f[CR][[siteconf]]\f[R].
T}@T{
T}
T{
autofocus
T}@T{
boolean
T}@T{
When set to true, elements with an \[lq]autofocus\[rq] attribute are
focused on automatically after the buffer is loaded.
Defaults to false.
T}@T{
T}
T{
meta\-refresh
T}@T{
\[lq]never\[rq] / \[lq]always\[rq] / \[lq]ask\[rq]
T}@T{
Whether or not \f[CR]http\-equiv=refresh\f[R] meta tags should be
respected.
\[lq]never\[rq] completely disables them, \[lq]always\[rq] automatically
accepts all of them, \[lq]ask\[rq] brings up a pop\-up menu.
Defaults to \[lq]ask\[rq].
T}@T{
T}
.TE
.SS Search
Search options are to be placed in the \f[CR][search]\f[R] section.
.PP
Following is a list of search options:
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
wrap
T}@T{
boolean
T}@T{
When set to true, searchNext/searchPrev wraps around the document.
T}@T{
T}
T{
ignore\-case
T}@T{
\[lq]auto\[rq] / boolean
T}@T{
When set to true, document\-wide searches are case\-insensitive by
default.
When set to \[lq]auto\[rq], searches are only case\-sensitive when the
search term includes a capital letter.
Defaults to \[lq]auto\[rq].
Note: this can also be overridden inline in the search bar (vim\-style),
with the escape sequences \f[CR]c\f[R] (ignore case) and \f[CR]C\f[R]
(strict case).
See search mode for details.)
T}@T{
T}
.TE
.SS Encoding
Encoding options are to be placed in the \f[CR][encoding]\f[R] section.
.PP
Following is a list of encoding options:
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
document\-charset
T}@T{
array of charset label strings
T}@T{
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.
T}@T{
T}
T{
display\-charset
T}@T{
string
T}@T{
Character set for keyboard input and displaying documents.
Used in dump mode as well.
(This means that e.g.\ \f[CR]cha \-I EUC\-JP \-O UTF\-8 a > b\f[R] is
equivalent to \f[CR]iconv \-f EUC\-JP \-t UTF\-8\f[R].)
T}@T{
T}
.TE
.SS External
External options are to be placed in the \f[CR][external]\f[R] section.
.PP
Following is a list of external options:
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
tmpdir
T}@T{
path
T}@T{
Directory used to save temporary files.
T}@T{
T}
T{
sockdir
T}@T{
path
T}@T{
Directory used to store UNIX domain sockets used for inter\-process
communication.
T}@T{
T}
T{
editor
T}@T{
shell command
T}@T{
External editor command.
%s is substituted for the file name, %d for the line number.
T}@T{
T}
T{
mailcap
T}@T{
array of paths
T}@T{
Search path for mailcap files.
(See \f[B]cha\-mailcap\f[R](5) for details.)
T}@T{
T}
T{
mime\-types
T}@T{
array of paths
T}@T{
Search path for mime.types files.
(See \f[B]cha\-mime.types\f[R](5) for details.)
T}@T{
T}
T{
cgi\-dir
T}@T{
array of paths
T}@T{
Search path for local CGI scripts.
(See \f[B]cha\-localcgi\f[R](5) for details.)
T}@T{
T}
T{
urimethodmap
T}@T{
array of paths
T}@T{
Search path for urimethodmap files.
(See \f[B]cha\-urimethodmap\f[R](5) for details.)
T}@T{
T}
T{
w3m\-cgi\-compat
T}@T{
boolean
T}@T{
Enable local CGI compatibility with w3m.
In short, it redirects \f[CR]file:///cgi\-bin/*\f[R] and
\f[CR]file:///$LIB/cgi\-bin/*\f[R] to \f[CR]cgi\-bin:*\f[R].
For further details, see \f[B]cha\-localcgi\f[R](5).
T}@T{
T}
T{
download\-dir
T}@T{
string
T}@T{
Path to pre\-fill for \[lq]Save to:\[rq] prompts.
This is not validated, you can set it to whatever you find useful.
T}@T{
T}
.TE
.SS Input
Input options are to be placed in the \f[CR][input]\f[R] section.
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
vi\-numeric\-prefix
T}@T{
boolean
T}@T{
Whether vi\-style numeric prefixes to commands should be accepted.
When set to true, commands that return a function will be called with
the numeric prefix as their first argument.
Note: this only applies for keybindings defined in [page].
T}@T{
T}
T{
use\-mouse
T}@T{
boolean
T}@T{
Whether Chawan is allowed to use the mouse.
Currently, the default behavior imitates that of w3m.
T}@T{
T}
.TE
.PP
Examples:
.IP
.EX
[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 = \[aq]n => n ? pager.gotoLine(n) : pager.cursorLastLine()\[aq]
.EE
.SS Network
Network options are to be placed in the \f[CR][network]\f[R] section.
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
max\-redirect
T}@T{
number
T}@T{
Maximum number of redirections to follow.
T}@T{
T}
T{
prepend\-scheme
T}@T{
string
T}@T{
Prepend this to URLs passed to Chawan without a scheme.
Note that local files (\f[CR]file:\f[R] scheme) will always be checked
first; only if this fails, Chawan will retry the request with
\f[CR]prepend\-scheme\f[R] set as the scheme.
By default, this is set to \[lq]https://\[rq].
Note that the \[lq]://\[rq] part is mandatory.
T}@T{
T}
T{
prepend\-https
T}@T{
boolean
T}@T{
Deprecated: use prepend\-scheme instead.
When set to false, Chawan will act as if prepend\-scheme were set to
\[lq]\[lq].
T}@T{
T}
T{
proxy
T}@T{
URL
T}@T{
Specify a proxy for all network requests Chawan makes.
All proxies supported by cURL may be used.
Can be overridden by siteconf.
T}@T{
T}
T{
default\-headers
T}@T{
table
T}@T{
Specify a list of default headers for all HTTP(S) network requests.
Can be overridden by siteconf.
T}@T{
T}
.TE
.SS Display
Display options are to be placed in the \f[CR][display]\f[R] section.
.PP
Following is a list of display options:
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
color\-mode
T}@T{
\[lq]monochrome\[rq] / \[lq]ansi\[rq] / \[lq]eight\-bit\[rq] /
\[lq]true\-color\[rq] / \[lq]auto\[rq]
T}@T{
Set the color mode.
\[lq]auto\[rq] for automatic detection, \[lq]monochrome\[rq] for black
on white, \[lq]ansi\[rq] for ansi colors, \[lq]eight\-bit\[rq] for
256\-color mode, and \[lq]true\-color\[rq] for true colors.
\[lq]8bit\[rq] is accepted as a legacy alias of \[lq]eight\-bit\[rq].
\[lq]24bit\[rq] is accepted as a legacy alias of \[lq]true\-color\[rq].
T}@T{
T}
T{
format\-mode
T}@T{
\[lq]auto\[rq] / [\[lq]bold\[rq], \[lq]italic\[rq], \[lq]underline\[rq],
\[lq]reverse\[rq], \[lq]strike\[rq], \[lq]overline\[rq],
\[lq]blink\[rq]]
T}@T{
Specifies output formatting modes.
Accepts the string \[lq]auto\[rq] or an array of specific attributes.
An empty array (\f[CR][]\f[R]) disables formatting completely.
T}@T{
T}
T{
no\-format\-mode
T}@T{
[\[lq]bold\[rq], \[lq]italic\[rq], \[lq]underline\[rq],
\[lq]reverse\[rq], \[lq]strike\[rq], \[lq]overline\[rq],
\[lq]blink\[rq]]
T}@T{
Disable specified formatting modes.
T}@T{
T}
T{
image\-mode
T}@T{
\[lq]auto\[rq] / \[lq]none\[rq] / \[lq]sixel\[rq] / \[lq]kitty\[rq]
T}@T{
Specifies the image output mode.
\[lq]sixel\[rq] uses sixels for output, \[lq]kitty\[rq] uses the Kitty
image display protocol, \[lq]none\[rq] disables image display
completely.
\[lq]auto\[rq] tries to detect sixel or kitty support, and falls back to
\[lq]none\[rq] when neither are available.
Defaults to \[lq]auto\[rq].
However, images are still disabled by default, unless you also enable
\f[CR]buffer.images\f[R] which allows the browser to actually download
images.
T}@T{
T}
T{
sixel\-colors
T}@T{
\[lq]auto\[rq] / 2..65535
T}@T{
Only applies when \f[CR]display.image\-mode=\[dq]sixel\[dq]\f[R].
Setting a number overrides the number of sixel color registers reported
by the terminal, while \[lq]auto\[rq] leaves color detection to Chawan.
Defaults to \[lq]auto\[rq].
T}@T{
T}
T{
alt\-screen
T}@T{
\[lq]auto\[rq] / boolean
T}@T{
Enable/disable the alternative screen.
T}@T{
T}
T{
highlight\-color
T}@T{
color
T}@T{
Set the highlight color.
Both hex values and CSS color names are accepted.
T}@T{
T}
T{
highlight\-marks
T}@T{
boolean
T}@T{
Enable/disable highlighting of marks.
T}@T{
T}
T{
double\-width\-ambiguous
T}@T{
boolean
T}@T{
Assume the terminal displays characters in the East Asian Ambiguous
category as double\-width characters.
Useful when e.g.\ ○ occupies two cells.
T}@T{
T}
T{
minimum\-contrast
T}@T{
number
T}@T{
Specify the minimum difference between the luminance (Y) of the
background and the foreground.
\-1 disables this function (i.e.\ allows black letters on black
background, etc).
T}@T{
T}
T{
force\-clear
T}@T{
boolean
T}@T{
Force the screen to be completely cleared every time it is redrawn.
T}@T{
T}
T{
set\-title
T}@T{
boolean
T}@T{
Set the terminal emulator\[cq]s window title to that of the current
page.
T}@T{
T}
T{
default\-background\-color
T}@T{
\[lq]auto\[rq] / color
T}@T{
Overrides the assumed background color of the terminal.
\[lq]auto\[rq] leaves background color detection to Chawan.
T}@T{
T}
T{
default\-foreground\-color
T}@T{
\[lq]auto\[rq] / color
T}@T{
Sets the assumed foreground color of the terminal.
\[lq]auto\[rq] leaves foreground color detection to Chawan.
T}@T{
T}
T{
query\-da1
T}@T{
bool
T}@T{
Enable/disable querying Primary Device Attributes, and with it, all
\[lq]dynamic\[rq] terminal querying.
It is highly recommended not to alter the default value (which is true),
or the output will most likely look horrible.
(Except, obviously, if your terminal does not support Primary Device
Attributes.)
T}@T{
T}
T{
columns, lines, pixels\-per\-column, pixels\-per\-line
T}@T{
number
T}@T{
Fallback values for the number of columns, lines, pixels per column, and
pixels per line for the cases where it cannot be determined
automatically.
(For example, these values are used in dump mode.)
T}@T{
T}
T{
force\-columns, force\-lines, force\-pixels\-per\-column,
force\-pixels\-per\-line
T}@T{
boolean
T}@T{
Force\-set columns, lines, pixels per column, or pixels per line to the
fallback values provided above.
T}@T{
T}
.TE
.SS Protocol
Protocol\-related rules are to be placed in objects keyed as
\f[CR][protocol.{protocol\-name}]\f[R].
e.g.\ FTP related rules are placed in in \f[CR][protocol.ftp]\f[R].
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
form\-request
T}@T{
http, ftp, data, mailto
T}@T{
Specify which protocol to imitate when submitting forms to this
protocol.
Defaults to HTTP.
T}@T{
T}
.TE
.SS Omnirule
The omni\-bar (by default opened with C\-l) can be used to perform
searches using omni\-rules.
These are to be placed in the table array \f[CR][[omnirule]]\f[R].
.PP
Examples:
.IP
.EX
# Search using DuckDuckGo Lite. (Bound to C\-k by default.)
[[omnirule]]
match = \[aq]\[ha]ddg:\[aq]
substitute\-url = \[aq](x) => \[dq]https://lite.duckduckgo.com/lite/?kp=\-1&kd=\-1&q=\[dq] + encodeURIComponent(x.split(\[dq]:\[dq]).slice(1).join(\[dq]:\[dq]))\[aq]

# Search using Wikipedia, Firefox\-style.
[[omnirule]]
match = \[aq]\[ha]\[at]wikipedia\[aq]
substitute\-url = \[aq](x) => \[dq]https://en.wikipedia.org/wiki/Special:Search?search=\[dq] + encodeURIComponent(x.replace(/\[at]wikipedia/, \[dq]\[dq]))\[aq]
.EE
.PP
Omnirule options:
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
match
T}@T{
regex
T}@T{
Regular expression used to match the input string.
Note that websites passed as arguments are matched as well.
Note: regexes are handled according to the match mode regex handling
rules.
T}@T{
T}
T{
substitute\-url
T}@T{
JavaScript function
T}@T{
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.
T}@T{
T}
.TE
.SS Siteconf
Configuration options can be specified for individual sites.
Entries are to be placed in the table array \f[CR][[siteconf]]\f[R].
.PP
Examples:
.IP
.EX
# Enable cookies on the orange website for log\-in.
[[siteconf]]
url = \[aq]https://news.ycombinator.com/.*\[aq]
cookie = true

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

# Allow cookie sharing on *sr.ht domains.
[[siteconf]]
host = \[aq](.*.)?sr.ht\[aq] # either \[aq]something.sr.ht\[aq] or \[aq]sr.ht\[aq]
cookie = true # enable cookies
share\-cookie\-jar = \[aq]sr.ht\[aq] # use the cookie jar of \[aq]sr.ht\[aq] for all matched hosts
third\-party\-cookie = \[aq].*.sr.ht\[aq] # allow cookies from subdomains
.EE
.PP
Siteconf options:
.PP
.TS
tab(@);
lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n).
T{
Name
T}@T{
Value
T}@T{
Function
T}@T{
T}
_
T{
url
T}@T{
regex
T}@T{
Regular expression used to match the URL.
Either this or the \f[CR]host\f[R] option must be specified.
Note: regexes are handled according to the match mode regex handling
rules.
T}@T{
T}
T{
host
T}@T{
regex
T}@T{
Regular expression used to match the host part of the URL (i.e.\ domain
name/ip address.)
Either this or the \f[CR]url\f[R] option must be specified.
Note: regexes are handled according to the match mode regex handling
rules.
T}@T{
T}
T{
rewrite\-url
T}@T{
JavaScript function
T}@T{
A JavaScript function Chawan will pass the URL to.
If a new URL is returned, it will replace the old one.
T}@T{
T}
T{
cookie
T}@T{
boolean
T}@T{
Whether loading cookies should be allowed for this URL.
By default, this is false for all websites.
Overrides \f[CR]buffer.cookie\f[R].
T}@T{
T}
T{
third\-party\-cookie
T}@T{
array of regexes
T}@T{
Domains for which third\-party cookies are allowed on this domain.
Note: this only works for buffers which share the same cookie jar.
Note: regexes are handled according to the match mode regex handling
rules.
T}@T{
T}
T{
share\-cookie\-jar
T}@T{
host
T}@T{
Cookie jar to use for this domain.
Useful for e.g.\ sharing cookies with subdomains.
T}@T{
T}
T{
referer\-from
T}@T{
boolean
T}@T{
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 referer\-from is true, b.com is sent \[lq]a.com\[rq] as the Referer
header.
Overrides \f[CR]buffer.referer\-from\f[R].
T}@T{
T}
T{
scripting
T}@T{
boolean
T}@T{
Enable/disable JavaScript execution on this site.
Overrides \f[CR]buffer.scripting\f[R].
T}@T{
T}
T{
styling
T}@T{
boolean
T}@T{
Enable/disable author styles (CSS) on this site.
Overrides \f[CR]buffer.styling\f[R].
T}@T{
T}
T{
images
T}@T{
boolean
T}@T{
Enable/disable image display on this site.
Overrides \f[CR]buffer.images\f[R].
T}@T{
T}
T{
document\-charset
T}@T{
charset label string
T}@T{
Specify the default encoding for this site.
Overrides \f[CR]encoding.document\-charset\f[R].
T}@T{
T}
T{
stylesheet
T}@T{
CSS stylesheet
T}@T{
Specify an additional user\-stylesheet for this site.
Note: other user\-stylesheets (specified under [css] or additional
matching siteconfs) are not overridden.
(In other words, they will be concatenated with this stylesheet to get
the final user stylesheet.)
T}@T{
T}
T{
proxy
T}@T{
URL
T}@T{
Specify a proxy for network requests fetching contents of this buffer.
Overrides \f[CR]network.proxy\f[R].
T}@T{
T}
T{
default\-headers
T}@T{
table
T}@T{
Specify a list of default headers for HTTP(S) network requests to this
buffer.
Overrides \f[CR]network.default\-headers\f[R].
T}@T{
T}
T{
insecure\-ssl\-no\-verify
T}@T{
boolean
T}@T{
Defaults to false.
When set to true, this disables peer and hostname verification for SSL
keys on this site, like \f[CR]curl \-\-insecure\f[R] would.
WARNING: this is insecure, and opens up your connections to
man\-in\-the\-middle attacks.
Please do not use this unless you are absolutely sure you know what you
are doing.
T}@T{
T}
T{
autofocus
T}@T{
boolean
T}@T{
When set to true, elements with an \[lq]autofocus\[rq] attribute are
focused on automatically after the buffer is loaded.
Overrides \f[CR]buffer.autofocus\f[R].
T}@T{
T}
T{
meta\-refresh
T}@T{
\[lq]never\[rq] / \[lq]always\[rq] / \[lq]ask\[rq]
T}@T{
Whether or not \f[CR]http\-equiv=refresh\f[R] meta tags should be
respected.
\[lq]never\[rq] completely disables them, \[lq]always\[rq] automatically
accepts all of them, \[lq]ask\[rq] brings up a pop\-up menu.
Overrides \f[CR]buffer.meta\-refresh\f[R].
T}@T{
T}
.TE
.SS Stylesheets
User stylesheets are to be placed in the \f[CR][css]\f[R] section.
.PP
There are two ways to import user stylesheets:
.IP "1." 3
Include a user stylesheet using the format
\f[CR]include = \[aq]path\-to\-user.css\[aq]\f[R].
To include multiple stylesheets, use
\f[CR]include = [\[aq]first\-stylesheet.css, second\-stylesheet.css\[aq]]\f[R].
Relative paths are interpreted relative to the config directory.
.IP "2." 3
Place your stylesheet directly in your configuration file using
\f[CR]inline = \[dq]\[dq]\[dq]your\-style\[dq]\[dq]\[dq]\f[R].
.SS Keybindings
Keybindings are to be placed in these sections:
.IP \[bu] 2
for pager interaction: \f[CR][page]\f[R]
.IP \[bu] 2
for line editing: \f[CR][line]\f[R]
.PP
Keybindings are configured using the syntax
.PP
`' = `'
.PP
Where \f[CR]<keybinding>\f[R] is a combination of unicode characters
with or without modifiers.
Modifiers are the prefixes \f[CR]C\-\f[R] and \f[CR]M\-\f[R], which add
control or escape to the keybinding respectively (essentially making
\f[CR]M\-\f[R] the same as \f[CR]C\-[\f[R]).
Modifiers can be escaped with the \[ga]\[ga] sign.
.PP
\f[CR]<action>\f[R] is either a command defined in the \f[CR][cmd]\f[R]
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:
.PP
The API documentation at \f[B]cha\-api\f[R](5).
.PP
Examples:
.IP
.EX
\f[I]# show change URL when Control, Escape and j are pressed\f[R]
\[aq]C\-M\-j\[aq] = \[aq]cmd.pager.load\[aq]
\f[I]# go to the first line of the page when g is pressed twice without a preceding\f[R]
\f[I]# number, or to the line when a preceding number is given.\f[R]
\[aq]gg\[aq] = \[aq]cmd.buffer.gotoLineOrStart\[aq]
.EE
.SS Pager actions
.PP
.TS
tab(@);
lw(32.1n) lw(11.7n) lw(23.3n) lw(2.9n).
T{
Default key
T}@T{
Name
T}@T{
Function
T}@T{
T}
_
T{
q
T}@T{
\f[CR]cmd.pager.quit\f[R]
T}@T{
Exit the browser.
T}@T{
T}
T{
C\-z
T}@T{
\f[CR]cmd.pager.suspend\f[R]
T}@T{
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.
T}@T{
T}
T{
C\-l
T}@T{
\f[CR]cmd.pager.load\f[R]
T}@T{
Open the current address in the URL bar.
T}@T{
T}
T{
C\-k
T}@T{
\f[CR]cmd.pager.webSearch\f[R]
T}@T{
Open the URL bar with an arbitrary search engine.
At the moment, this is DuckDuckGo Lite, but this may change in the
future.
T}@T{
T}
T{
M\-u
T}@T{
\f[CR]cmd.pager.dupeBuffer\f[R]
T}@T{
Duplicate the current buffer by loading its source to a new buffer.
T}@T{
T}
T{
U
T}@T{
\f[CR]cmd.pager.reloadBuffer\f[R]
T}@T{
Open a new buffer with the current buffer\[cq]s URL, replacing the
current buffer.
T}@T{
T}
T{
C\-g
T}@T{
\f[CR]cmd.pager.lineInfo\f[R]
T}@T{
Display information about the current line on the status line.
T}@T{
T}
T{
\[rs]
T}@T{
\f[CR]cmd.pager.toggleSource\f[R]
T}@T{
If viewing an HTML buffer, open a new buffer with its source.
Otherwise, open the current buffer\[cq]s contents as HTML.
T}@T{
T}
T{
D
T}@T{
\f[CR]cmd.pager.discardBuffer\f[R]
T}@T{
Discard the current buffer, and move back to the previous/next buffer
depending on what the previously viewed buffer was.
T}@T{
T}
T{
d,, d.
T}@T{
\f[CR]cmd.pager.discardBufferPrev\f[R],
\f[CR]cmd.pager.discardBufferNext\f[R]
T}@T{
Discard the current buffer, and move back to the previous/next buffer,
or open the link under the cursor.
T}@T{
T}
T{
M\-d
T}@T{
\f[CR]cmd.pager.discardTree\f[R]
T}@T{
Discard all child buffers of the current buffer.
T}@T{
T}
T{
\&., ,, M\-,, M\-., M\-/
T}@T{
\f[CR]cmd.pager.nextBuffer\f[R], \f[CR]cmd.pager.prevBuffer\f[R],
\f[CR]cmd.pager.prevSiblingBuffer\f[R],
\f[CR]cmd.pager.nextSiblingBufer\f[R], \f[CR]cmd.pager.parentBuffer\f[R]
T}@T{
Traverse the buffer tree.
\f[CR]nextBuffer\f[R] and \f[CR]prevBuffer\f[R] are the most intuitive,
traversing the tree as if it were a linked list.
\f[CR]prevSiblingBuffer\f[R] and \f[CR]nextSiblingBuffer\f[R] cycle
through the buffers opened from the same buffer.
Finally, \f[CR]parentBuffer\f[R] always returns to the buffer the
current buffer was opened from, even if e.g.\ the user returns and opens
another page \[lq]in between\[rq].
T}@T{
T}
T{
M\-c
T}@T{
\f[CR]cmd.pager.enterCommand\f[R]
T}@T{
Directly enter a JavaScript command.
Note that this interacts with the pager, not the website being
displayed.
T}@T{
T}
T{
None
T}@T{
\f[CR]cmd.pager.searchForward\f[R], \f[CR]cmd.pager.searchBackward\f[R]
T}@T{
Search for a string in the current buffer, forwards or backwards.
T}@T{
T}
T{
/, ?
T}@T{
\f[CR]cmd.pager.isearchForward\f[R], \f[CR]cmd.pager.searchBackward\f[R]
T}@T{
Incremental\-search for a string, highlighting the first result,
forwards or backwards.
T}@T{
T}
T{
n, N
T}@T{
\f[CR]cmd.pager.searchNext\f[R], \f[CR]cmd.pager.searchPrev\f[R]
T}@T{
Jump to the nth (or if unspecified, first) next/previous search result.
T}@T{
T}
T{
c
T}@T{
\f[CR]cmd.pager.peek\f[R]
T}@T{
Display a message of the current buffer\[cq]s URL on the status line.
T}@T{
T}
T{
u
T}@T{
\f[CR]cmd.pager.peekCursor\f[R]
T}@T{
Display a message of the URL or title 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)
T}@T{
T}
T{
su
T}@T{
\f[CR]cmd.pager.showFullAlert\f[R]
T}@T{
Show the last alert inside the line editor.
You can also view previous ones using C\-p or C\-n.
T}@T{
T}
T{
M\-y
T}@T{
\f[CR]cmd.pager.copyURL\f[R]
T}@T{
Copy the current buffer\[cq]s URL to the system clipboard.
T}@T{
T}
T{
yu
T}@T{
\f[CR]cmd.pager.copyCursorLink\f[R]
T}@T{
Copy the link under the cursor to the system clipboard.
T}@T{
T}
T{
yI
T}@T{
\f[CR]cmd.pager.copyCursorImage\f[R]
T}@T{
Copy the URL of the image under the cursor to the system clipboard.
T}@T{
T}
T{
M\-p
T}@T{
\f[CR]cmd.pager.gotoClipboardURL\f[R]
T}@T{
Go to the URL currently on the clipboard.
T}@T{
T}
.TE
.SS Buffer actions
Note: \f[CR]n\f[R] in the following text refers to a number preceding
the action.
e.g.
in \f[CR]10gg\f[R], n = 10.
If no preceding number is input, then it is left unspecified.
.PP
.TS
tab(@);
lw(32.1n) lw(11.7n) lw(23.3n) lw(2.9n).
T{
Default key
T}@T{
Name
T}@T{
Function
T}@T{
T}
_
T{
j, k
T}@T{
\f[CR]cmd.buffer.cursorUp\f[R], \f[CR]cmd.buffer.cursorDown\f[R]
T}@T{
Move the cursor upwards/downwards by n lines, or if n is unspecified, by
1.
T}@T{
T}
T{
h, l
T}@T{
\f[CR]cmd.buffer.cursorLeft\f[R], \f[CR]cmd.buffer.cursorRight\f[R]
T}@T{
Move the cursor to the left/right by n cells, or if n is unspecified, by
1.
T}@T{
T}
T{
0
T}@T{
\f[CR]cmd.buffer.cursorLineBegin\f[R]
T}@T{
Move the cursor to the first cell of the line.
T}@T{
T}
T{
\[ha]
T}@T{
\f[CR]cmd.buffer.cursorLineTextStart\f[R]
T}@T{
Move the cursor to the first non\-blank character of the line.
T}@T{
T}
T{
$
T}@T{
\f[CR]cmd.buffer.cursorLineEnd\f[R]
T}@T{
Move the cursor to the last cell of the line.
T}@T{
T}
T{
w, W
T}@T{
\f[CR]cmd.buffer.cursorNextWord\f[R],
\f[CR]cmd.buffer.cursorNextViWord\f[R],
\f[CR]cmd.buffer.cursorNextBigWord\f[R]
T}@T{
Move the cursor to the beginning of the next word.
T}@T{
T}
T{
None
T}@T{
\f[CR]cmd.buffer.cursorPrevWord\f[R],
\f[CR]cmd.buffer.cursorPrevViWord\f[R],
\f[CR]cmd.buffer.cursorPrevBigWord\f[R]
T}@T{
Move the cursor to the end of the previous word.
T}@T{
T}
T{
e, E
T}@T{
\f[CR]cmd.buffer.cursorWordEnd\f[R],
\f[CR]cmd.buffer.cursorViWordEnd\f[R],
\f[CR]cmd.buffer.cursorBigWordEnd\f[R]
T}@T{
Move the cursor to the end of the current word, or if already there, to
the end of the next word.
T}@T{
T}
T{
b, B
T}@T{
\f[CR]cmd.buffer.cursorWordBegin\f[R],
\f[CR]cmd.buffer.cursorViWordBegin\f[R],
\f[CR]cmd.buffer.cursorBigWordBegin\f[R]
T}@T{
Move the cursor to the beginning of the current word, or if already
there, to the end of the previous word.
T}@T{
T}
T{
[, ]
T}@T{
\f[CR]cmd.buffer.cursorPrevLink\f[R],
\f[CR]cmd.buffer.cursorNextLink\f[R]
T}@T{
Move the cursor to the end/beginning of the previous/next clickable
element (e.g.\ link, input field, etc).
T}@T{
T}
T{
{, }
T}@T{
\f[CR]cmd.buffer.cursorPrevParagraph\f[R],
\f[CR]cmd.buffer.cursorNextParagraph\f[R]
T}@T{
Move the cursor to the end/beginning of the nth previous/next paragraph.
T}@T{
T}
T{
None
T}@T{
\f[CR]cmd.buffer.cursorRevNthLink\f[R]
T}@T{
Move the cursor to the nth link of the document, counting backwards from
the document\[cq]s last line.
T}@T{
T}
T{
None
T}@T{
\f[CR]cmd.buffer.cursorNthLink\f[R]
T}@T{
Move the cursor to the nth link of the document.
T}@T{
T}
T{
C\-b, C\-f, zH, zL
T}@T{
\f[CR]cmd.buffer.pageUp\f[R], \f[CR]cmd.buffer.pageDown\f[R],
\f[CR]cmd.buffer.pageLeft\f[R], \f[CR]cmd.buffer.pageRight\f[R]
T}@T{
Scroll up/down/left/right by n pages, or if n is unspecified, by one
page.
T}@T{
T}
T{
C\-u, C\-d
T}@T{
\f[CR]cmd.buffer.halfPageUp\f[R], \f[CR]cmd.buffer.halfPageDown\f[R],
\f[CR]cmd.buffer.halfPageLeft\f[R], \f[CR]cmd.buffer.halfPageUp\f[R]
T}@T{
Scroll up/down/left/right by n half pages, or if n is unspecified, by
one page.
T}@T{
T}
T{
K/C\-y, J/C\-e, zh, zl
T}@T{
\f[CR]cmd.buffer.scrollUp\f[R], \f[CR]cmd.buffer.scrollDown\f[R],
\f[CR]cmd.buffer.scrollLeft\f[R], \f[CR]cmd.buffer.scrollRight\f[R]
T}@T{
Scroll up/down/left/right by n lines, or if n is unspecified, by one
line.
T}@T{
T}
T{
Enter/Return
T}@T{
\f[CR]cmd.buffer.click\f[R]
T}@T{
Click the HTML element currently under the cursor.
T}@T{
T}
T{
R
T}@T{
\f[CR]cmd.buffer.reshape\f[R]
T}@T{
Reshape the current buffer (=render the current page anew.)
Useful if the layout is not updating even though it should have.
T}@T{
T}
T{
r
T}@T{
\f[CR]cmd.buffer.redraw\f[R]
T}@T{
Redraw screen contents.
Useful if something messed up the display.
T}@T{
T}
T{
None (see gotoLineOrStart/End instead)
T}@T{
\f[CR]cmd.buffer.cursorFirstLine\f[R],
\f[CR]cmd.buffer.cursorLastLine\f[R]
T}@T{
Move to the beginning/end in the buffer.
T}@T{
T}
T{
H
T}@T{
\f[CR]cmd.buffer.cursorTop\f[R]
T}@T{
Move to the first line on the screen.
(Equivalent to H in vi.)
T}@T{
T}
T{
M
T}@T{
\f[CR]cmd.buffer.cursorMiddle\f[R]
T}@T{
Move to the line in the middle of the screen.
(Equivalent to M in vi.)
T}@T{
T}
T{
L
T}@T{
\f[CR]cmd.buffer.cursorBottom\f[R]
T}@T{
Move to the last line on the screen.
(Equivalent to L in vi.)
T}@T{
T}
T{
zt, z Return, zz, z., zb, z\-
T}@T{
\f[CR]cmd.buffer.raisePage\f[R], \f[CR]cmd.buffer.raisePageBegin\f[R],
\f[CR]cmd.buffer.centerLine\f[R], \f[CR]cmd.buffer.centerLineBegin\f[R],
\f[CR]cmd.buffer.lowerPage\f[R], \f[CR]cmd.buffer.lowerPageBegin\f[R]
T}@T{
If n is specified, move cursor to line n.\ Then, * \f[CR]raisePage\f[R]
scrolls down so that the cursor is on the top line of the screen.
(vi \f[CR]z<CR>\f[R], vim \f[CR]zt\f[R].)
* \f[CR]centerLine\f[R] shifts the screen so that the cursor is in the
middle of the screen.
(vi \f[CR]z.\f[R], vim \f[CR]zz\f[R].)
* \f[CR]lowerPage\f[R] scrolls up so that the cursor is on the bottom
line of the screen.
(vi \f[CR]z\-\f[R], vim \f[CR]zb\f[R].)
The \-\f[CR]Begin\f[R] variants also move the cursor to the line\[cq]s
first non\-blank character, as the variants originating from vi do.
T}@T{
T}
T{
z+
T}@T{
\f[CR]cmd.buffer.nextPageBegin\f[R]
T}@T{
If n is specified, move to the screen before the nth line and raise the
page.
Otherwise, go to the previous screen\[cq]s last line and raise the page.
T}@T{
T}
T{
z\[ha]
T}@T{
\f[CR]cmd.buffer.previousPageBegin\f[R]
T}@T{
If n is specified, move to the screen before the nth line and raise the
page.
Otherwise, go to the previous screen\[cq]s last line and raise the page.
T}@T{
T}
T{
g0, gc, g$
T}@T{
\f[CR]cmd.buffer.cursorLeftEdge\f[R],
\f[CR]cmd.buffer.cursorMiddleColumn\f[R],
\f[CR]cmd.buffer.cursorRightEdge\f[R]
T}@T{
Move to the first/middle/last column on the screen.
T}@T{
T}
T{
None
T}@T{
\f[CR]cmd.buffer.centerColumn\f[R]
T}@T{
Center screen around the current column.
(w3m \f[CR]Z\f[R].)
T}@T{
T}
T{
gg, G
T}@T{
\f[CR]cmd.buffer.gotoLineOrStart\f[R],
\f[CR]cmd.buffer.gotoLineOrEnd\f[R]
T}@T{
If n is specified, jump to line n.\ Otherwise, jump to the start/end of
the page.
T}@T{
T}
T{
m
T}@T{
\f[CR]cmd.buffer.mark\f[R]
T}@T{
Wait for a character \f[CR]x\f[R] and then set a mark with the ID
\f[CR]x\f[R].
T}@T{
T}
T{
\[ga], \[cq]
T}@T{
\f[CR]cmd.buffer.gotoMark\f[R], \f[CR]cmd.buffer.gotoMarkY\f[R]
T}@T{
Wait for a character \f[CR]x\f[R] and then jump to the mark with the ID
\f[CR]x\f[R] (if it exists on the page).
\f[CR]gotoMark\f[R] sets both the X and Y positions; gotoMarkY only sets
the Y position.
T}@T{
T}
T{
:
T}@T{
\f[CR]cmd.buffer.markURL\f[R]
T}@T{
Convert URL\-like strings to anchors on the current page.
T}@T{
T}
T{
s Return
T}@T{
\f[CR]cmd.buffer.saveLink\f[R]
T}@T{
Save resource from the URL pointed to by the cursor to the disk.
T}@T{
T}
T{
sS
T}@T{
\f[CR]cmd.buffer.saveSource\f[R]
T}@T{
Save the source of the current buffer to the disk.
T}@T{
T}
.TE
.SS Line\-editing actions
.PP
.TS
tab(@);
lw(32.1n) lw(11.7n) lw(23.3n) lw(2.9n).
T{
Default key
T}@T{
Name
T}@T{
Function
T}@T{
T}
_
T{
Return
T}@T{
\f[CR]cmd.line.submit\f[R]
T}@T{
Submit the line.
T}@T{
T}
T{
C\-c
T}@T{
\f[CR]cmd.line.cancel\f[R]
T}@T{
Cancel the current operation.
T}@T{
T}
T{
C\-h, C\-d
T}@T{
\f[CR]cmd.line.backspace\f[R], \f[CR]cmd.line.delete\f[R]
T}@T{
Delete character before (backspace)/after (delete) the cursor.
T}@T{
T}
T{
C\-u, C\-k
T}@T{
\f[CR]cmd.line.clear\f[R], \f[CR]cmd.line.kill\f[R]
T}@T{
Delete text before (clear)/after (kill) the cursor.
T}@T{
T}
T{
C\-w, M\-d
T}@T{
\f[CR]cmd.line.clearWord\f[R], \f[CR]cmd.line.killWord\f[R]
T}@T{
Delete word before (clear)/after (kill) the cursor.
T}@T{
T}
T{
C\-b, C\-f
T}@T{
\f[CR]cmd.line.backward\f[R], \f[CR]cmd.line.forward\f[R]
T}@T{
Move cursor backward/forward by one character.
T}@T{
T}
T{
M\-b, M\-f
T}@T{
\f[CR]cmd.line.prevWord\f[R], \f[CR]cmd.line.nextWord\f[R]
T}@T{
Move cursor to the previous/next word by one character
T}@T{
T}
T{
C\-a, C\-e
T}@T{
\f[CR]cmd.line.begin\f[R], \f[CR]cmd.line.end\f[R]
T}@T{
Move cursor to the beginning/end of the line.
T}@T{
T}
T{
C\-v
T}@T{
\f[CR]cmd.line.escape\f[R]
T}@T{
Ignore keybindings for next character.
T}@T{
T}
T{
C\-p, C\-n
T}@T{
\f[CR]cmd.line.prevHist\f[R], \f[CR]cmd.line.nextHist\f[R]
T}@T{
Jump to the previous/next history entry
T}@T{
T}
.TE
.PP
Note: to facilitate URL editing, the line editor has a different
definition 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\-alphanumeric character.
(This means that e.g.\ \f[CR]https://\f[R] consists of four words:
\f[CR]https\f[R], \f[CR]:\f[R], \f[CR]/\f[R] and \f[CR]/\f[R].)
.IP
.EX
# Control+A moves the cursor to the beginning of the line.
\[aq]C\-a\[aq] = \[aq]cmd.line.begin\[aq]

# Escape+D deletes everything after the cursor until it reaches a word\-breaking
# character.
\[aq]M\-d\[aq] = \[aq]cmd.line.killWord\[aq]
.EE
.SS Appendix
.SS Regex handling
Regular expressions are currently handled using libregexp which is
included in QuickJS.
This means that all regular expressions work as in JavaScript.
.PP
There are two different modes of regex preprocessing in Chawan:
\[lq]search\[rq] mode, and \[lq]match\[rq] mode.
\[lq]match\[rq] mode is used for configurations (meaning in all values
in this document described as \[lq]regex\[rq]).
\[lq]search\[rq] mode is used for the on\-page search function (using
searchForward/isearchForward etc.)
.SS Match mode
Regular expressions are assumed to be exact matches, except when they
start with a caret (\[ha]) sign or end with an unescaped dollar ($)
sign.
.PP
In other words, the following transformations occur:
.IP
.EX
\[ha]abcd \-> \[ha]abcd (no change, only beginning is matched)
efgh$ \-> efgh$ (no change, only end is matched)
\[ha]ijkl$ \-> \[ha]ijkl$ (no change, the entire line is matched)
mnop \-> \[ha]mnop$ (changed to exact match, the entire line is matched)
.EE
.PP
Match mode has no way to toggle JavaScript regex flags like
\f[CR]i\f[R].
.SS Search mode
For on\-page search, the above transformations do not apply; the search
\f[CR]/abcd\f[R] searches for the string \f[CR]abcd\f[R] inside all
lines.
.PP
\[lq]Search\[rq] mode also has some other convenience transformations:
.IP \[bu] 2
The string \f[CR]c\f[R] (backslash + lower\-case c) inside a
search\-mode regex enables case\-insensitive matching.
.IP \[bu] 2
Conversely, \f[CR]C\f[R] (backslash + capital C) disables
case\-insensitive matching.
(Useful if you have \f[CR]ignore\-case\f[R] set to true, which is the
default.)
.IP \[bu] 2
\f[CR]<\f[R] and \f[CR]>\f[R] is converted to \f[CR]b\f[R] (as in vi,
grep, etc.)
.PP
Note that none of these work in \[lq]match\[rq] mode.
.SS Path handling
Rules for path handling are similar to how strings in the shell are
handled.
.IP \[bu] 2
Tilde\-expansion is used to determine the user\[cq]s home directory.
So e.g.\ \f[CR]\[ti]/whatever\f[R] works.
.IP \[bu] 2
Environment variables can be used like \f[CR]$ENV_VAR\f[R].
.IP \[bu] 2
Relative paths are relative to the Chawan configuration directory.
.PP
Some internal variables are also defined by Chawan.
These can be accessed using the non\-standard syntax
\f[CR]${%VARIABLE}\f[R]:
.IP \[bu] 2
\f[CR]${%CHA_BIN_DIR}\f[R]: the directory which the \f[CR]cha\f[R]
binary resides in.
Note that symbolic links are automatically resolved to determine this
path.
.IP \[bu] 2
\f[CR]${%CHA_LIBEXEC_DIR}\f[R]: the directory for all executables Chawan
uses for operation.
By default, this is \f[CR]${%CHA_BIN_DIR}/../libexec/chawan\f[R].
.SS Word types
Word\-based pager commands can operate with different definitions of
words.
Currently, these are:
.IP \[bu] 2
w3m words
.IP \[bu] 2
vi words
.IP \[bu] 2
Big words
.SS w3m word
A w3m word is a sequence of alphanumeric characters.
Symbols are treated in the same way as whitespace.
.SS vi word
A vi word is a sequence of alphanumeric characters, OR a sequence of
symbols.
.PP
vi words may be separated by whitespace; however, symbolic and
alphanumeric vi words do not have to be whitespace\-separated.
e.g.\ following character sequence contains two words:
.IP
.EX
hello[]+{}\[at]\[ga]!
.EE
.SS Big word
A big word is a sequence of non\-whitespace characters.
.PP
It is essentially the same as a w3m word, but with symbols being defined
as non\-whitespace.
.SS See also
\f[B]cha\f[R](1)