A text-mode web browser. It displays websites in your terminal and allows you to navigate on them.
It can also be used as a terminal pager.
Note: a POSIX-compliant operating system is required. (Windows is not supported yet.)
- Clone the Chawan repository:
git clone https://git.sr.ht/~bptato/chawan && cd chawan
- Install the Nim compiler: https://nim-lang.org/install.html
- Please use 1.6.14 or newer, ideally 2.0.2. Versions older than 1.6.14
will not work. (You can check your Nim compiler's version using
nim -v
.)
- Please use 1.6.14 or newer, ideally 2.0.2. Versions older than 1.6.14
will not work. (You can check your Nim compiler's version using
- Install the following dependencies:
- libcurl: https://curl.se/libcurl/
- zlib: https://zlib.net/
- pkg-config, pkgconf, or similar (must be found as "pkg-config" in your
$PATH
) - If you are using a system where the default make program is not GNU make (e.g. BSD), install gmake and use that in the following steps.
- Optional: a termcap library; e.g. ncurses comes with one.
- TLDR for Debian:
apt install libcurl4-openssl-dev zlib1g-dev pkg-config make ncurses-base
- Download parts of Chawan found in other repositories:
make submodule
- Run
make
. (By default, this will build the whole project in release mode; for details, see doc/build.md.) - If you want manpages, run
make manpage
. (This requires pandoc.) - Finally, install using
make install
(e.g.sudo make install
).
Then, try:
$ cha -V # open in visual mode for a list of default keybindings
$ cha example.org # open your favorite website directly from the shell
$ mancha cha # read the cha(1) man page using `mancha'
Currently implemented features are:
- multi-processing (several buffers can be loaded at once)
- multi-charset, double-width aware text display (but no bi-di yet)
- HTML5 support
- a CSS-capable layout engine
- flow layout is supported (now with floats!)
- table layout is supported, except for fixed tables
- the box model is mostly implemented, except for borders
- flexbox layout is supported (some parts are still a WIP)
- forms
- incremental loading of various kinds of documents (plain text, HTML, etc.)
- JavaScript based navigation
- JavaScript support in documents
- some basic DOM manipulation APIs are supported
- off by default; use is discouraged until sandboxing is implemented
- some basic DOM manipulation APIs are supported
- cookies
- supports several protocols: HTTP(S), FTP, Gopher, Gemini, Finger, etc.
- can load user-defined protocols/file formats using local CGI, urimethodmap and mailcap
- markdown viewer
- man page viewer (like w3mman)
- mouse support
...with a lot more planned.
- manpage: doc/cha.1
- configuration options: doc/config.md
- mailcap: doc/mailcap.md
- mime.types: doc/mime.types.md
- urimethodmap: doc/urimethodmap.md
- local CGI: doc/localcgi.md
- protocols: doc/protocols.md
Many other text-based web browsers exist. Here's some recommendations if you want to try more established ones:
- w3m - A text-mode browser, extensible using local-cgi. Also has inline image display and very good table support. Inspired many features of Chawan.
- elinks - Has CSS and JavaScript support, and incremental rendering (it's pretty fast.)
- lynx - "THE text-based web browser."
- edbrowse - This one looks more like
ed
thanless
orvi
. Mainly designed for blind users. - browsh - Firefox in your terminal.
Chawan's display capabilities depend on what your terminal reports. In particular:
- if it does not respond to querying XTGETTCAP, and the
$COLORTERM
environment variable is not set, then Chawan falls back to ANSI colors - if it does not respond to querying the background color, then Chawan's color contrast correction will likely malfunction
You can fix this manually by adjusting the display.default-background-color
,
display.default-foreground-color
, and display.color-mode
variables. See
doc/config.md for details.
Yes; Chawan now has a built-in markdown converter. If you don't like it, you can always replace it with e.g. pandoc.
I've found other text-based web browsers insufficient for my needs, so I thought it'd be a fun excercise to write one by myself, for myself.
Generally, I'm happy if Chawan works on websites I use frequently. If it also works on other websites, that's a bonus.
Please run cha about:chawan
for a list of default keybindings. (By default,
this is equivalent to cha -V
.)
At bonus/w3m.toml. Note that not every w3m feature is implemented yet, so it's not 100% compatible.
I use vi for editing text, and I prefer my pager to function similarly to my editor. Hence the default vi-like keybindings.
By default, text files are not auto-wrapped. This is useful in some cases, but viewing plain text files that were not wrapped properly by the authors becomes slightly annoying.
A simple workaround is to add this to your config's
[page]
section:
' f' = "pager.externFilterSource('fmt')"
and then press <space> f
to view a wrapped version of the current text
file. (This assumes your system has an fmt
program - if not, fold -s
may
be an alternative.)
Alternatively, you can add this to your user style:
plaintext { white-space: pre-wrap }
and then all plain text files will automatically wrap. To do the same for HTML
and ANSI text, use plaintext, pre
.
Usually, this is because it uses some CSS features that are not yet implemented in Chawan. The most common offenders are grid and CSS variables.
There are three ways of dealing with this:
- The hacky solution: if the website's contents are mostly text, install
rdrview. Then bind the following command
to a key of your choice in the config
(e.g.
<space> r
):
' r' = "pager.externFilterSource('rdrview -H -u \"$CHA_URL\"')"
This does not fix the core problem, but will significantly improve your reading experience anyway. - The slow solution: complain here, and wait until the problem goes away.
- If you're feeling adventurous: write a patch to fix the problem, and send it here.
Some potential fixes:
- Usually logging in to websites requires cookies. Some websites also require
cookie sharing across domains. For security reasons, Chawan does not allow
any of this by default, so you will have to fiddle with siteconf to fix
it. (i.e. on all target hostnames, set
cookie
to true,share-cookie-jar
to the main host, andthird-party-cookie
to all target hosts. See doc/config.md#siteconf for details.) - Set the
referer-from
siteconf value to true; this will cause Chawan to send aReferer
header when navigating to other URLs from the target URL. - Enable JavaScript. If something broke, type M-c M-c to check the browser
console, then follow step 3. of the previous answer.
Warning: remote JavaScript execution is inherently unsafe; more so in Chawan, which lacks proper sandboxing of buffer processes. Please only enable JavaScript on websites you trust.
Here's some:
- Written in Nim
- Uses QuickJS for JavaScript execution. (The QuickJS regex engine, libregexp, is also used for in-document searches.)
- Uses multi-processing provided by POSIX. (No threads.) Each buffer gets its own process; as a result, buffers can be duplicated by simply forking their process. File loading is done in yet another process. IPC happens through UNIX domain sockets.
- Layout, CSS cascading, HTML parsing, etc. are handled by built-in modules, not external libraries. (However, the HTML parser and the character coding library are available as separate libraries as well.)
- Uses termcap for basic terminal capability querying, and notcurses-style terminal queries for detecting "modern" features (like true color).
For further details, you will have to read the source code please read
this.
Chawan is dedicated to the public domain. See the UNLICENSE file for details.
Chawan also includes and depends on several other libraries. For further details, see license.html or check the about:license page in Chawan.