Basic Page Mode

We will walk through building a whiz-bang little page mode for that most ubiquitous of Internet grottos,


The main form of any page mode is the define_page_mode form. Its two required arguments are the symbolic name of the page mode, and the human-readable name. In addition to the required arguments, it accepts several optional keyword arguments. Typically, you will use both $enable and $disable, which give the setup and teardown functions for your mode. Each takes a buffer as its single argument.

define_page_mode("example_mode", "Example",
                 $enable = function (buffer) {
                     // setup
                 $disable = function (buffer) {
                     // teardown


Telling Conkeror when to turn on your page mode is as simple as adding a handler to auto_mode_list. You make a regular expression that matches the urls for which your page mode is intended, and push that, in association with your page mode function, onto auto_mode_list. This registration should be the last thing in the javascript file for your page mode. We'll start with a short example, then we'll pick it apart.

let (re = build_url_regex($domain = "example",
                          $tlds = ["com", "net", "org"],
                          $allow_www = true)) {
    auto_mode_list.push([re, example_mode]);


Since creating regular expressions to match urls has patterns that are used over and over again, Conkeror has a function to simplify the creation of these regular expressions, called build_url_regex. It takes several keyword arguments that specify parts of an url, and produces a regexp.


A regexp or a literal string to match the domain name, not including the top-level domain (.com, .net, .org, etc), and not including www., unless the www. is required.


Boolean where true means that the domain name may optionally have the subdomain www.. Default is false.


A list of allowed top-level domains. The default is the list ["com"].


A regexp or a literal string to match against the path portion of the url, excluding the initial /. The default matches any path.