# Dillo User Manual

Welcome to the user manual of the Dillo browser. The manual is divided into sections but is written in a single page to allow search by keywords. Generated for version 3.3.0.

Table of contents:

## Introduction

Dillo is a web browser designed to be fast, use few resources and support slow and unreliable networks on resource-constrained machines. It can load local and remote files via HTTP, HTTPS and FTP. Other protocols like Gemini, Gopher, IPFS and others are available as plugins.

Dillo supports a subset of HTML 4.01 and CSS 2.1 but it doesn't support JavaScript and only implements some elements of HTML 5 and CSS 3. It also renders plain text documents and images in PNG, JPG, GIF, SVG and WebP formats.

## Reading

In this section we cover the basics to read a web page, scrolling and finding or copying text.

### Basics

The graphical interface is designed to be used with a mouse or pointing device. At the top of the browser window you have the location bar and the main buttons to control the browser. You can leave the mouse for a brief moment over any part of the menu to show a tooltip with more information.

Dillo has context sensitive menus, which are opened with the right mouse button, available on pages, links, images, forms, the Back and Forward buttons, and the bug meter. They show different actions to be performed specific to the element. For example, to save a page you can right-click on the page and select "Save page as...". Or to copy a link URL you can right-click on a link and select "Copy link location".

Dillo can hide all panels and use the whole window area to display the page. To switch between modes use the ESC key. You can also choose the control panel size by going to the Tools button and selecting a different one under "Panel size".

You can open this manual from Dillo by clicking on the top right "?" button. It doesn't require a network connection.

### Scrolling

There are several methods to move or scroll the view of the current page.

- Using the keyboard:
  - Use the `Home` or `End` keys to jump to the top or to the end of a page.
  - Use `PgUp` or `PgDn` to advance a whole page (window size) minus one step.
  - Use the arrow keys to move the view a step in that direction.
  - You can also use the `Space` key as `PgDn` and `b` as PgUp.
- Using the mouse or pointing device:
  - Rotate the mouse wheel to move one step in that direction. Hold Shift to move one page instead.
  - Keep the middle button (or mouse wheel button) pressed while dragging to scroll the page precisely.
- Using the scrollbar:
  - Drag the thumb in the scrollbar on the side up or down to scroll the page.
  - Left-click or right-click on the scrollbar above or below the thumb to move one page in that direction.
  - Middle-click on the scrollbar above or below the thumb to jump to that specific position of the page.
  - Click the scrollbar arrows to move the view one step in that direction.
  - Rotate the mouse wheel over the vertical scrollbar to move one page in that direction.

You can control the size of a step by setting the `scroll_step` option in the dillorc configuration file. By default it will scroll 100 pixels per step. The vertical scrollbar can be positioned on the left side setting the `scrollbar_on_left` option to `YES`, by default it is on the right side.

The vertical scrollbar has another mode of operation to navigate full pages that can be enabled by setting the `scrollbar_page_mode` option to `YES` or temporarily by holding the Shift key. When this mode is active, left-clicking anywhere on the scrollbar will scroll down one page and right-clicking will scroll up one page. Middle clicking on the scrollbar will move the thumb to that position, which can also be dragged. The Shift key can also be used to temporarily disable this mode if it was enabled in the configuration.

### Find text

To find text in a document right-click to open the Page menu and select Find text or press `Ctrl+F` on the keyboard. Then type the substring that you want to find and click Next (or the `Enter` key).

Dillo will scroll the page and highlight found text starting from the top. To find a word (not a substring) use spaces around it to limit the search to matching words only.

To close the find bar you can click on the red X on the bottom right or press ESC.

### Copy and paste

Dillo uses the Primary and Clipboard selections to copy and paste text. The Primary selection captures text that gets selected as soon as the left button is released, while to copy it in the Clipboard selection it requires the usual Ctrl+C and Ctrl+V shortcut.

To copy some text in the Primary selection just hold down the left mouse button and move to select the area to copy. To paste, go to the target application and press the middle mouse button. To copy text into the Clipboard, select the text and press Ctrl+C then go to the destination and press Ctrl+V to paste.

If you want to select more than one screen, hold the mouse left button down and scroll with PgUp, PgDn or the arrow keys.

When a link is copied from the context menu, it is placed both in the Primary and Clipboard selections, so you can paste the URL with the middle click or with Ctrl+V.

If you want to paste an URL into Dillo from the Primary selection, do it on the "clear-URL" button (the "X" next to the location bar) and the URL will be opened as well. You can also paste the URL using the Clipboard by using the Ctrl+V shortcut then pressing Enter to visit it.

### Zoom

You can increase or decrease the size of the elements of a page by changing the zoom factor. Use `Ctrl +` to increase the size, `Ctrl -` to decrease it and `Ctrl 0` to reset the value to 100%.

The initial zoom factor is specified by the `zoom_factor` option in the dillorc configuration file. When a new tab or window is opened, the current zoom factor value is inherited.

## Navigation

This section focuses on how to navigate to other pages by following hyperlinks, using bookmarks, typing or pasting a new URL or using the history.

### Hyperlinks

Hyperlinks (or just links) allow you to navigate to other pages by clicking them. They change the cursor to a hand to indicate that an element can be clicked with the left button:

Links to other pages usually appear in blue and underlined by default and once they are visited they change to purple. However, this is not always the case, so using the mouse cursor shape is the best indicator of a link.

When you follow a link by clicking on it, the previous pages will be remembered in case you want to go back to them. Use the Back and Forward buttons on the top bar to navigate among history pages.

### History

When you follow several links across different web pages, they are remembered in case you can to go back. Use the "Back" and "Forward" buttons of the panel to go to the previous or next page. Click with the left button to open the page in the same tab or use the middle button to open it in a new tab.

You can also right-click on the Back or Forward buttons to open a menu with the list of previous or next pages available, so you can jump directly to them. Use the left button to open them in the current tab or the middle button to open them in a new tab.

The `,` (comma) and `.` (dot) keys can be used to jump backwards or forward (mnemonic: those keys are usually labeled "<" and ">"). You can also use the back and forward buttons on your mouse if they are available.

### Location bar

The location bar on the top displays the URL of the current page loaded and can be used to access other pages by typing the new URL or by pasting it and pressing Enter.

The red x on the left clears the location bar content when left clicked. Then you can type or paste a new address from the clipboard by middle clicking on the location bar. As these two actions are usually performed together, you can simply middle-click on the x button to go to the URL in the clipboard.

You can also select the location bar content from the keyboard by pressing `Ctrl+L`.

### Web search

Several search engines are available by pressing the magnifying glass icon next to the location bar or by pressing `Ctrl+S`. The search engines are configured in Dillorc with the option `search_url`. Use it multiple times to define multiple search engines.

The location bar can also be used to search the web by using a special prefix for each search engine. For example, the following line:

    search_url="dd DuckDuckGo http://duckduckgo.com/lite/?kp=-1&kd=-1&q=%s"

Defines the "DuckDuckGo" search engine with the prefix "`dd`", so you can type in the location bar "`dd dillo browser`" to search with DuckDuckGo for the keywords "dillo browser".

### Tabs

Dillo can open different web pages into tabs. To open a link in a new tab click the middle button instead of the left button or keep `Control` pressed while left-clicking a link. The same applies to buttons to submit a form. A new tab can also be opened from the `File` menu or using the shortcut `Ctrl+T`.

Press `Shift` while opening a page in a new tab to focus the tab. If you want this behaviour to be the default, set the following option in the dillorc configuration file:

    focus_new_tab=YES

If this option is set, pressing `Shift` will instead avoid focusing the new tab.

It is also possible to have the middle-click open a window instead of a tab. For this set the option:

    middle_click_opens_new_tab=NO

To close a tab press the X button on the top right (only visible with multiple tabs). You can also close the tab by clicking with the right button on the tab label. The middle button can be used instead by setting the option:

    right_click_closes_tab=NO

Use the `new_tab_page` option to control which page is loaded in a newly opened tab, by default is an empty page. To open the bookmarks page set the following line in dillorc:

    new_tab_page="dpi:/bm/"

You can quickly focus the N-th tab by pressing `Alt` and the tab number, for example `Alt+3` will focus the third tab. Using `Alt+0` focuses the tenth tab, as they start counting at 1.

### Bookmarks

Dillo can save URLs of web pages as bookmarks so you can open them later. To bookmark the current page, open the Page menu by right-clicking on the page and select "Bookmark this page" (it also works over a link).

To see or edit the bookmarks, click on the Bookmarks button on the panel or press `Ctrl+B`.

Bookmarks are handled by a built-in Dillo plugin named `bm` (read more about plugins in the Plugins section) and are synchronized across all instances of the browser. The list of bookmarks can also be shown by opening the URL `dpi:/bm/`.

The bookmarks are stored in a simple plain text file named `bm.txt` (see the details of this file in the bm.txt section). You can edit the file directly to change the bookmarks.

## Privacy and network

The default privacy policy in Dillo attempts to keep the user safe from tracking, even if this policy breaks a lot of website functionality. In this section you can add exceptions or relax the configuration at your own risk.

### HTTPS

Dillo has support for HTTPS, allowing secure connections to remote websites. Use the protocol "`https:`" to specify the use of HTTPS. When a problem is encountered with the remote certificate, a warning dialog explains the details and allows you to choose what to do: continue loading the website or cancel.

By default Dillo looks for a TLS library at build time, which can be OpenSSL or mbedTLS. You can see which library is being used by looking at the console when it starts:

    $ dillo
    dillo_dns_init: Here we go! (threaded)
    TLS library: OpenSSL 3.2.1 30 Jan 2024
    ...

### Cookies

Due to privacy concerns, cookies are disabled by default unless explicitly enabled in the configuration.

Support for cookies is implemented using a built-in plugin that shares them between several instances of Dillo and follows the RFC 6265 specification. Current cookie limits are 20 per domain and 1200 in total.

Cookies are configured by the `cookiesrc` configuration file. See the Cookiesrc section to see how to enable cookies for some domains or accept them by default.

### Proxy

Dillo can use a HTTP proxy by setting the environment variable `http_proxy` or the configuration option with the same name. All HTTP and HTTPS traffic will be sent through the proxy.

Note: Plugins may not implement proxy support.

### Ad blocking

Dillo has the ability to block content when loading a page based on the domain the embedded content is being loaded from. You can control how Dillo handles automatic requests for resources (like images and style sheets) that aren't at the same domain as the original page.

See the domainrc configuration file to find out how to specify which domains are blocked or allowed.

### Downloads

Downloads are made using wget with a FLTK-based GUI wrapper, through the Dillo plugin (dpi) framework. If you close the browser window, downloads will continue.

### Images-off mode

You can browse without images now:

- There is an option in the Tools menu to disable automatic image loading. An image's alt text (or `[IMG]` placeholder) will appear in the page.
- If you want to load an individual image, left click on its text.
- You can set "no images" as the default mode in dillorc.

## Configuration

Dillo has several configuration files that control the behavior of the browser. Each configuration file is searched first in the `~/.dillo` directory and, if not found, in the default system configuration directory (typically `/etc/dillo`).

Most configuration files can include comments by starting a line with the "`#`" symbol. Their specific syntax is described in the following sections.

### Dillorc

The main configuration of Dillo is controlled by the `dillorc` file. The list of all available options can be found in the system configuration file, typically `/etc/dillo/dillorc`. You may want to copy it into `~/.dillo/dillorc` and edit it to suit your needs.

The file is commented to describe what each option does. The default value for each option as well as other interesting values are also available as comments:

- "`#option=...`" shows the built-in default.
- "`# option=...`" is an additional example.
- "`option=...`" overrides the built-in value.

The `search_url` option can be specified multiple times:

    search_url="dd DuckDuckGo (https) https://duckduckgo.com/lite/?kp=-1&q=%s"
    search_url="Wikipedia http://www.wikipedia.org/w/index.php?search=%s&go=Go"

### Cookiesrc

Cookies are configured in the `~/.dillo/cookiesrc` file by using rules, with one rule per line. The rule syntax is very simple, first specify the host and then the action, separated by white spaces. Comment lines start with `#` as the first character and the whole line is ignored.

The host can be in the form `example.com` to match only that domain or `.example.com` to match all subdomains of example.com. The special word `DEFAULT` specifies the default policy, when no other match occurs.

The action can be: `DENY` to ignore cookies, `ACCEPT_SESSION` to only accept session cookies but don't save them to disk and `ACCEPT` to accept and store cookies in disk (this will allow sites to track you over time).

After modifying the cookiesrc file, use the `dpidc stop` command to stop the cookies plugin and force it to load the new configuration. Until the cookies plugin is not restarted, it will continue to use the old settings. You don't need to restart Dillo for the settings to take effect.

When the cookies plugin exits, only the accepted cookies by `ACCEPT` are saved to `~/.dillo/cookies.txt`, and ACCEPT_SESSION cookies are forgotten. The cookies plugin normally exits after a period of inactivity, but you can force it to exit with the command `dpidc stop`.

To remove or edit persistent cookies (those with ACCEPT) first close all Dillo processes and then stop the cookies plugin with `dpidc stop`. After that, you can erase or edit the `~/.dillo/cookies.txt` file with a text editor. In the next start of Dillo, the new persistent cookies will be loaded from disk.

Here is an example `cookiesrc` file:

    # host        action
    DEFAULT       DENY
    fltk.org      ACCEPT
    .example.com  ACCEPT_SESSION

Which is parsed as follows:

- Line 1: Comment line begins with `#`.
- Line 2: Deny all cookies from all domains not otherwise specified (this is the default).
- Line 3: Accept all cookies from fltk.org, and save them to disk when the cookie plugin exits.
- Line 4: Accept all cookies from all subdomains of example.com, but do not save them when the cookie plugin exits.

Dillo is especially concerned about privacy and security issues. Our advice is to avoid cookies whenever possible and at most set ACCEPT_SESSION to specific trusted sites.

### Domainrc

With the `~/.dillo/domainrc` file, you can control how Dillo handles automatic requests for resources (like images and style sheets) that aren't at the same domain as the original page.

The file contains one rule per line. Comments are specified by starting the line with the `#` symbol. The default rule is either `default accept` or `default deny` and will cause Dillo to, respectively, accept all requests by default or deny all requests by default.

Depending on the default rule, the next rules behave as exceptions by denying specific connections or allowing specific connections, respectively.

Exceptions to the default rule are written in the format `source destination`, and match request from the source domain to the destination domain. The source and destination domains can be specified in three ways:

- "`*`" to match any domain
- "`example.com`" to match the specific host example.com
- "`.example.com`" to match example.com and any of its subdomains

Here is an example:

    # Accept all requests by default
    default accept
    # But block some ad-sites and trackers from any domain
    * .doubleclick.net
    * .googleadservices.com
    * .quantserve.com

### Style.css

Custom CSS styles can be placed in the `~/.dillo/style.css` file to set default web page styles. To override page styles add the "`!important`" flag.

### Dpidrc

The configuration for plugins is placed in the `~/.dillo/dpidrc` file.

Plugins are searched in the `~/.dillo/dpi/` directory first, and then in the system directory if not found. The `dpi_dir` option sets the system `dpi` directory and must be specified once. Here is an example:

    dpi_dir=/usr/lib/dillo/dpi

By default, plugins will receive requests at the URL `dpi:/name/`, for example bookmarks are available at `dpi:/bm/`.

Plugins can also be associated with a protocol (like "`file:`"). When a request is made using the given protocol the associated plugin is used to process the request. The rest of the file assigns a plugin to a protocol, one per line. The syntax is `proto.name=path-to-plugin.dpi`. The path of the plugin is relative to the `dpi` directory. Here are protocols used by the built-in plugins:

    proto.file=file/file.dpi
    proto.ftp=ftp/ftp.filter.dpi
    proto.data=datauri/datauri.filter.dpi

Here ( ) is an example image using the `data:` protocol used to define a PNG image inline in a HTML document.

### bm.txt

Web page URLs can be saved as bookmarks so they can be accessed in the future. Bookmarks are stored in a plain text file located at `~/.dillo/bm.txt`. The file can be modified by using the Book button in the toolbar and the context menu on a page or link, but they can also be edited manually. Bookmarks are organized into sections and are given a description (usually the page title).

The syntax of the `bm.txt` file is described as follows:

First, the sections are defined at the beginning, prefixed with a `:sN:` identifier, along with the description of the section:

    :s0: News
    :s1: Blog

Then every bookmark is added in a single line, by writing the section identifier, the URL and a description:

    s0 https://slashdot.org Slashdot
    s0 https://news.ycombinator.com/ Hacker News
    s1 https://100r.co/site/log.html 100 Rabbits Log

The `bm.txt` file is designed to be easily read by humans and is suitable to be kept updated among machines by using a version control tool.

### Keysrc

The mapping of keys in Dillo is controlled by the `~/.dillo/keysrc` file. The format is "`key = action`" or "`<modifier>key = action`". Lines that begin with a "#" are comments. The commented-out bindings below show the defaults built into Dillo.

- Modifiers recognized: Shift, Ctrl, Alt, Meta (on Mac OS X use "Meta" for Command).
- Key names recognized: Backspace, Delete, Down, End, Esc, F1 through F12, Home, Insert, Left, Menu, PageDown, PageUp, Print, Return, Right, Space, Tab, Up.
- Multimedia keys: Back, Favorites, Forward, HomePage, Mail, MediaNext, MediaPlay, MediaPrev, MediaStop, Refresh, Search, Sleep, Stop, VolumeDown, VolumeMute, VolumeUp.

If Dillo is running under X11, keys whose names are not recognized can be specified using their keysym value in hexadecimal. Use `xev` to get the keysym, for example:

    0x1008ff27 = forward

The action "nop" (no operation) can be used to remove a binding.

Example file:

    # "close-all" closes all tabs/windows and exits.
    <ctrl>q = close-all

    # "left-tab" and "right-tab" switch to the left/right of the current tab.
    <ctrl><shift>tab = left-tab

    # Use HJKL to move around
    k = line-up
    j = line-down
    h = left
    l = right

## Advanced usage

These sections focus on advanced topics and are recommended for experienced users of Dillo.

### Plugins

The functionality of Dillo can be extended by using plugins, which can translate other formats to HTML, implement new protocols or provide a custom service.

Plugins can be written in any programming language and they interact with the browser using the DPI protocol. A list of plugins is available on the Dillo website. Some plugins are just a few lines of shell script, so you are encouraged to read them to learn how to write your own plugins. Plugins are searched by looking for files that end with the `.dpi` extension (or `.dpi.exe` in Windows) in `~/.dillo/dpi` and `dpi_dir` (see the Dpidrc configuration section).

There are two types of plugins: filters and servers. Filters are executed for each request like a UNIX pipe, they read from the standard input and write to the standard output. The name of filter plugin programs must end in `.filter.dpi`. On the other hand, servers listen on a socket for new requests. They can process several requests at the same time, preventing the overhead of spawning multiple processes and they can easily share information among requests.

You can install plugins from any third party, but you should always review the source before running code written by others. To install a new plugin, copy the files to `~/.dillo/dpi/name/` and then associate the name protocol to the program that must run in the `~/.dillo/dpidrc` file. Plugins may have other software dependencies required for it to work.

Here is an example of how to manually install the Gemini protocol plugin (it comes with a Makefile that automates the process, so this is not necessary), which is a filter plugin written in shell script:

    $ mkdir -p ~/.dillo/dpi/gemini
    $ cp gemini.filter.dpi ~/.dillo/dpi/gemini/
    $ chmod +x ~/.dillo/dpi/gemini/gemini.filter.dpi
    $ echo "proto.gemini=gemini/gemini.filter.dpi" >> ~/.dillo/dpidrc
    $ dpidc stop

Now, when a request is made to an URL that begins with the `gemini:` protocol, it will be processed by the `gemini/gemini.filter.dpi` program, and the output will be displayed by Dillo.

### Bug Meter

Dillo includes a bug meter which shows the number of detected bugs inside the page. The bugs are caught at parsing time, so the error messages also show the line where they occur and provide a hint of what was expected instead.

The primary purpose of the bug meter is to help webmasters and page authors to polish the contents of their sites with a view to making them compliant with HTML standards.

The bug meter is located at the lower right corner of Dillo. Use the left-click to see the messages, right-click for a menu to open other HTML validators.

### Remote control

Dillo is built with support for remote control by default (can be disabled using the flag `--disable-control-socket` at configure time). When enabled, the `dilloc` program is also built, which allows the remote control of dillo given its PID using a UNIX socket. By default, the first process that replies is used. The environment variable `DILLO_PID` can be used to select which instance of dillo to use.

The dilloc program sends commands to dillo and prints the response in the standard output. Some commands can also read data from the standard input and write it to dillo. Use `dilloc help` to see which commands are available and their syntax.

### Custom actions

Users can define custom actions that execute arbitrary programs directly from Dillo's UI. The context menu that appears when clicking with the right mouse button over a link or over the current page can be configured to show additional entries that will run programs defined in the dillorc configuration. The options `link_action` and `page_action` define new entries for the link and page menu respectively, multiple entries can be configured by writting them multiple times.

The format to specify an action is "label`:`command". The label will be shown in the context menu, when clicked the command will be executed with the `system()` function in the system shell, so it can include variables or pipes.

Dillo always sets the `DILLO_PID` environment variable, so that dilloc can select the correct Dillo process to query and manipulate the state of the browser (to use dilloc, the remote control feature must be enabled at build time). Additionally, the following variables are set:

- For link actions, `url` is set to the hyperlink href and `origin` to the current page URL that contains it.
- For page actions, `url` is set to the current page URL.

Some examples are included in the dillorc configuration and shown below:

    link_action="Echo variables:echo url=$url origin=$origin"
    link_action="Open in MPV:mpv $url"
    link_action="Open in Firefox:firefox $url"
    link_action="Open in Mupdf:f=$(mktemp -u /tmp/XXXX.pdf); curl $url -o $f && mupdf $f"

    page_action="Reader mode:dilloc dump | rdrview -H | dilloc load"
    page_action="Mimic Chrome:curl_chrome136 -i --raw $url | dilloc rawload"

### Keyboard shortcuts

Most actions can be issued by using a keyboard shortcut. The key bindings can be changed in the `~/.dillo/keysrc` file (see the keysrc section). To see the current key bindings go to about:keys. The list of default bindings is given in the following table.

Shortcut | Mnemonic | Function
--- | --- | ---
Ctrl-L | Location | Enter a new URL
Ctrl-F | Find | Find text
Ctrl-S | Search | Search the web
Ctrl-R | Reload | Reload current page
Ctrl-N | New | New browser window
Ctrl-T | Tab | New tab
Ctrl-W | Window | Quit tab/window
Ctrl-O | Open | Open file
Ctrl-U |  | View source
Ctrl-B | Bookmarks | View bookmarks
Ctrl-Q | Quit | Quit dillo
Ctrl-C | Copy | Copy to clipboard
Ctrl-+ or Ctrl-= | Bigger | Zoom in
Ctrl-- | Smaller | Zoom out
Ctrl-0 | 100% | Reset zoom to 100%
Back or "," | < | Previous page
Shift-Back or "." | > | Next page
Alt-F | File | File menu
Ctrl-Tab or Ctrl-PageDown | Tab | Next tab
Ctrl-Shift-Tab or Ctrl-PageUp | Tab | Previous tab
Esc | escape | Close dialog, Close findbar, Hide/show control panels