Your rc is your own script or scripts loaded at startup that you can use to configure Conkeror. The abbreviation rc is derived from the tradition of naming startup scripts with the suffix rc in unix-like platforms. Your conkeror-rc is written in ordinary javascript. You can use it to define key bindings, define new commands, set preferences, set user-variables, configure extensions, and much more.

1. RC File Location

The default location of the rc is $HOME/.conkerorrc (where "$HOME" is your home directory). The rc can be an ordinary file or a directory. If it is an ordinary file, Conkeror will load that file as javascript. If it is a directory, Conkeror will load all files in that directory that have the .js file extension.

2. Syntax

Your rc file is a JavaScript file. You can set user variables just as you would assign any other variable in JavaScript:

variable_name = value;

You can set user and session preferences (not be confused with user variables) using the user_pref and session_pref functions, e.g.:

session_pref("preference_name", value);

3. Reloading

Conkeror is designed, to what extent possible, to be fully configurable, and fully reconfigurable at runtime, interactively. You only need to be aware of a simple precaution and you can start hacking, and greatly reduce your number of restarts. The simple precaution is this: remember that javascript is an imperative language; things run in a particular order, and there is no undo. Just because you delete something from your rc, or change it, does not mean that the previous evaluation is magically voided. Whatever the code did by way of side-effect still happened, and if you want to undo something you previously did, you will need to address those side-effects directly. Examples of side-effectual actions that cause pitfalls on repeated evaluation include using add_hook, adding widgets to the GUI, registering stylesheets, and so on. Now, with the foregoing precaution in mind, for those in a hurry to get underway, you can reload your rc with the command:

M-x reinit

But as your rc grows in size, with more and more and customizations, you may find the reinit command to be a blunter instrument than you wish. To use it successfully, you often have to write side-effectual code in non-idiomatic or obfuscated ways to protect against the effects of repeat evaluation. For those who have reached this level, we recommend evaluating only parts of your code at a time. You can use M-: for the trivial cases, and we highly recommend MozRepl for more in-depth hacking sessions. Happy hacking!

4. Debugging

• Run Conkeror from a terminal and watch for error output. A javascript error in your rc can prevent things in the file following that error from being evaluated. On the Windows platform, you may need to start Conkeror with the -console command line switch to be able to see terminal out.

• Comment out the contents of your rc (with /* and */) and put a dumpln call at the beginning, like dumpln("hello, world!");. See if the text is printed to the terminal.

• Start Conkeror and browse to about:config. See if you have inadvertently set a value for the pref conkeror.rcfile. If you have, clear it and try again.

5. Changing the RC Location

You change your rc by doing:

M-: user_pref('conkeror.rcfile', '/home/foo/conkeror-rc'); RET

or from the command line:

conkeror -q -batch -e "user_pref('conkeror.rcfile', '/home/foo/conkeror-rc');"

If conkeror.rcfile is set to the empty string, Conkeror will not attempt to load any rc.

5.1. Attn: Windows users

Set your rc with a native Windows-style path with drive letter and backslash separators. If you set your rc with the M-: method above, you will need to double up the backslashes because backslash is the character-escape character in javascript strings. Your path would look like c:\\path\\to\\conkeror-rc.

6. Editing the RC

If you're an emacs user, there's an emacs minor-mode designed for editing your .conkerorrc file (though it also applies to any conkeror javascript file).

It offers:

1. Syntax coloring;
2. A command that sends statements to be evaluated by conkeror (bound to "C-c C-c");
3. Indentation of macros.

It's called conkeror-minor-mode. You can install it from Melpa or download it from its GitHub page.