User Variables

Conkeror has many behaviors that can be customized by setting certain ordinary variables in your rc. We will try to describe them all here.

NOTE: variables are not the same thing as preferences.

active_hint_background_color

String color for the active hint. Default is "#88FF00".

active_img_hint_background_color

String color for the active image hint. Default is "#88FF00".

allow_browser_window_close

If this is set to true, if a content buffer page calls window.close() from JavaScript and is not prevented by the normal Mozilla mechanism that restricts pages from closing a window that was not opened by a script, the buffer will be killed, deleting the window as well if it is the only buffer. Default is true.

auto_mode_list

A list of mappings from URI regular expressions to page modes. This should probably only be changed to add new page modes. See modules/page-modes/ for examples.

block_content_focus_change_duration

Duration (in milliseconds) during which an element is allowed to gain focus following a mouse click or key press, if block_content_focus_change_mode is enabled.

browser_automatic_form_focus_window_duration

note: As of November 2, 2009, this variable was renamed to block_content_focus_change_duration. The documentation for it will be left up for a reasonable amount of time in order to be available to people running an older version of Conkeror from their OS.

Time window (in milliseconds) during which a form element is allowed to gain focus following a mouse click or key press, if browser_prevent_automatic_form_focus_mode is enabled. Default is 20.

browser_default_open_target

Specifies how new window requests by content pages (e.g. by window.open from JavaScript or by using the target attribute of anchor and form elements) will be handled. This will generally be OPEN_NEW_BUFFER, OPEN_NEW_BUFFER_BACKGROUND, or OPEN_NEW_WINDOW. Default is OPEN_NEW_BUFFER.

browser_form_field_xpath_expression

XPath expression matching elements to be selected by browser-focus-next-form-field and browser-focus-previous-form-field. Default is

•   "//input[" + (
          //        "translate(@type,'RADIO','radio')!='radio' and " +
          //        "translate(@type,'CHECKBOX','checkbox')!='checkbox' and " +
          "translate(@type,'HIDEN','hiden')!='hidden'"
          //        "translate(@type,'SUBMIT','submit')!='submit' and " +
          //        "translate(@type,'REST','rest')!='reset'"
      ) +  "] | " +
          "//xhtml:input[" + (
              //        "translate(@type,'RADIO','radio')!='radio' and " +
              //        "translate(@type,'CHECKBOX','checkbox')!='checkbox' and " +
              "translate(@type,'HIDEN','hiden')!='hidden'"
              //        "translate(@type,'SUBMIT','submit')!='submit' and " +
              //        "translate(@type,'REST','rest')!='reset'"
          ) +  "] |" +
          "//select | //xhtml:select | " +
          "//textarea | //xhtml:textarea | " +
          "//textbox | //xul:textbox"

browser_relationship_patterns

Patterns used by follow-next and follow-previous. By default, we have

•   browser_relationship_patterns[RELATIONSHIP_NEXT] =
      [/^next$/i,
       new RegExp("^>$","i"),
       new RegExp("^(>>|»)$","i"),
       new RegExp("^(>|»)","i"),
       new RegExp("(>|»)$","i"),
       new RegExp("\\bnext","i")
      ];
  
     browser_relationship_patterns[RELATIONSHIP_PREVIOUS] =
      [/^(prev|previous)$/i,
       new RegExp("^<$","i"),
       new RegExp("^(<<|«)$","i"),
       new RegExp("^(<|«)","i"),
       new RegExp("(<|«)$","i"),
       new RegExp("\\bprev|previous\\b","i")
      ];

bury_buffer_position

Behavior of bury-buffer command with respect to buffer order. See Buffer Order.

can_kill_last_buffer

Boolean controlling whether the kill-buffer command can kill the last buffer in a window.

clicks_in_new_buffer_button

Which mouse button should open links in a new buffer.

• 0 = left, 1 = middle, 2 = right. Default is 1. (With require("clicks-in-new-buffer.js")).

clicks_in_new_buffer_target

How to open links in a new buffer, in the foreground or the background. Set to one the constants OPEN_NEW_BUFFER or OPEN_NEW_BUFFER_BACKGROUND. Default is OPEN_NEW_BUFFER.

• (With require("clicks-in-new-buffer.js")).

clock_time_format

Format string for the mode-line clock widget. It takes the same format as strftime() in C. See http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html for details. Default is "%R", which is hours and minutes in 24-hour format.

content_handlers

A mime type table mapping mime types to content handlers. This table will be checked for a match when a navigation event causes Conkeror to encounter a mime type which is not supported by Mozilla. If no appropriate content handler is found in this table, the user will be prompted to choose from among common actions. No handlers are registered by default. See ContentHandlers for details on how to manipulate the table.

cwd

Abbreviation for current working directory. It is used as your default download directory, and the directory for shell commands. Individual buffers and pages may have their own local cwd. The change-directory command sets the buffer-local cwd. The value must be an nsILocalFile object. The function make_file will make an nsILocalFile from a string path. The default value of cwd is your home directory.

daemon_quit_exits

Boolean controlling whether daemon-mode abides the quit command. Default is true.

default_minibuffer_auto_complete_delay

Delay (in milliseconds) after the most recent key stroke before auto-completing. Default is 150.

delete_temporary_files_for_command

If this is set to true (the default), temporary files downloaded to run a command on them will be deleted once the command completes. If not, the file will stay around forever unless deleted outside the browser.

download_buffer_automatic_open_target

Target for download buffers created by open_download_buffer_automatically. The default is OPEN_NEW_WINDOW.

download_buffer_min_update_interval

Minimum interval (in milliseconds) between updates in download progress buffers. Lowering this interval will increase the promptness of the progress display at the cost of using additional processor time. Default is 2000 (ms).

download_temporary_file_open_buffer_delay

Delay (in milliseconds) before a download buffer is opened for temporary downloads. This variable takes effect only if open_download_buffer_automatically is in download_added_hook, as it is by default. Default is 500.

edit_field_in_external_editor_extension

Default is "txt". File extension for the temp files created by edit-current-field-in-external-editor. Obsolete Dec 31, 2010. See external_editor_extension_overrides.

editor_shell_command

Shell command used to invoke an external editor. Default is the value of the environment variable EDITOR. It is used as part of a shell command in the following two ways:

•     <editor_shell_command> <file>
      <editor_shell_command> +<line> <file>

Windows users should reference ConkerorSpawnHelper and include a trailing .exe on any executables set here. Non-null run_external_editor_function overrides this setting. Default is

•   getenv("VISUAL") || getenv("EDITOR") || "emacs"

external_content_handlers

A mime-type table containing associations of mime types to programs that can handle content of that type. Used by commands and actions that entail running an external program on content. The default contents of the table are:

•   {
        "*": getenv("EDITOR"),
        text: { "*": getenv("EDITOR") },
        image: { "*": "feh" },
        video: { "*": "mplayer" },
        audio: { "*": "mplayer" },
        application: {
            pdf: "evince",
            postscript: "evince",
            "x-dvi": "evince"
        }
    }

See ContentHandlers for more information about manipulating the table.

external_editor_extension_overrides

Mime-type table giving file extensions for temp files used in external editing. The contents of this table are for overrides only. Defaults are gotten from the mime service.

eye_guide_context_size

A setting for the eye-guide commands. Context size in pixels for eye-guide-scroll-down and eye-guide-scroll-up. Default is 50.

eye_guide_highlight_new

A setting for the eye-guide commands. When true, the new part of the view is highlighted instead of the old. Default is false.

eye_guide_interval

A setting for the eye-guide commands. Interval during which the eye guide is visible (in ms). When 0, the eye guide will remain visible. Default is 800.

favicon_image_max_size

Maximum (pixel) width and height of an image document that is considered for use as a favicon. Default is 1024.

forced_charset_list

An alist mapping url regexps to charsets.

generate_filename_safely_fn

A function called by suggest_file_name which sanitizes a filename prior to saving. The default is a function appropriate to the current OS. This variable can be customized in order to impose additional sanitization rules on filenames, for example, if you wanted to always convert spaces to underscores or the like.

hint_background_color

String color name for hints. Default is "yellow".

hint_digits

Null or a string of the digits to use as the counting base for hint numbers, starting with the digit that represents zero and ascending. If null, base 10 will be used with the normal hindu-arabic numerals. Default is null. See Hinting.

hints_ambiguous_auto_exit_delay

Delay (in milliseconds) after the most recent key stroke before the first of an ambiguous match is automatically selected. If this is set to 0, automatic selection in ambiguous matches is disabled. Default is 0.

hints_auto_exit_delay

Delay (in milliseconds) after the most recent key stroke before a sole matching element is automatically selected. If this is set to 0, automatic selection is disabled. Default is 0.

homepage

Default url for content buffers.

img_hint_background_color

String color for image hints. Default is "yellow".

index_webjumps_directory

A directory (instance of nsILocalFile) for storing the index files corresponding to index webjumps; the index data can be downloaded from the index URL using webjump-get-index. If the index file is available for an index webjump then the webjump will provide completions for the indexed URLs.

index_xpath_webjump_tidy_command

A command to run on the downloaded index. The xulrunner parser is quite fussy and specifically requires xhtml (or other xml). Running something like html tidy can avoid parser problems.

isearch_keep_selection

Default is false. When true, the selection will always be left visible after completing an isearch.

isearch_scroll_center_vertically

When an isearch causes scrolling, the result is normally scrolled into view at the bottom of the screen. If this variable is set to true it will be centered vertically instead. Only available since XULRunner 12, when the SCROLL_CENTER_VERTICALLY flag was added.

key_bindings_ignore_capslock

When true, the state of capslock will be overridden for key combos that contain characters. If shift was pressed with the character, the character will be forced to upper-case, and otherwise forced to lower-case. This only affects keys bound to commands. Capslock will still work as normal when typing in input fields. The default value of this variable is false.

keyboard_key_sequence_help_timeout

Delay (in milliseconds) before the current key sequence prefix is displayed in the minibuffer. Default is 0.

kill_whole_line

Default is false. When true, the command cut-to-end-of-line will also cut the newline character at the end, when point is at the beginning of a line.

load_paths

Array of URL prefixes searched in order when loading a module. Each entry must end in a slash, and should begin with file:// or chrome://.

media_scrape_default_regexp

Regular expression used by the default media scraper to match URIs for embedded media in the page source code. Defaults to

•   new RegExp("(?:http://[a-zA-Z0-9.\\-]+/)?(?!://)[^=&<>\"'|\\s]+\\.(?:aiff|au|avi|flv|mid|mov|mp3|mpg|mpeg|ogg|ra|rm|spl|wav|wma|wmv)(?!\\w)", "ig")

media_scrapers

Function (or coroutine) to use to scrape the current buffer for embedded media. Default is [media_scrape_default] (see media.js).

mime_type_external_handlers

note: this variable was removed as of October 12, 2009. The documentation for it will be left up for a reasonable amount of time in order to be available to people running an older version of Conkeror from their OS. This variable was replaced by external_content_handlers. See ContentHandlers for details.

An array of two element arrays, associating mime type patterns with handler programs. The patterns are regular expressions. When conkeror looks for an external handler, the program corresponding to the first matching pattern will be used. The default value of mime_type_external_handlers is:

• [[/^text\/.*$/, getenv("EDITOR")],
   [/^image\/.*$/, "feh"],
   [/^video\/.*$/, "mplayer"],
   [/^audio\/.*$/, "mplayer"],
   [/^application\/pdf$/, "evince"],
   [/^application\/postscript$/, "evince"],
   [/^application\/x-dvi$/, "evince"],
   [/^.*$/, getenv("EDITOR")]]

  An API exists for manipulating this array; see MimeTypeHandlers for details.

minibuffer_auto_complete_default

Boolean specifying whether to auto-complete by default. The user variable minibuffer_auto_complete_preferences overrides this. Default is false.

minibuffer_auto_complete_preferences

minibuffer_completion_rows

Number of rows in the minibuffer completion display. Default is 8.

minibuffer_history_max_items

Maximum number of minibuffer history entries stored.Older history entries are truncated after this limit is reached. Default is 100.

minibuffer_input_mode_show_message_timeout

Time duration (in milliseconds) to flash minibuffer messages while in minibuffer input mode. Default is 1000.

minibuffer_read_url_select_initial

Specifies whether a URL presented in the minibuffer for editing should be selected. This affects find-alternate-url. Defaults to true.

new_buffer_position

Insertion position of a new buffer with no opener or with an opener that is not a buffer in the same window. See Buffer Order.

new_buffer_with_opener_position

Insertion position of a new buffer whose opener is a buffer in the same window. See Buffer Order.

opensearch_load_paths

Paths to search for opensearch description files. Default list includes the subdirectory called 'search-engines' in your profile directory and the Conkeror installation directory.

read_buffer_show_icons

Boolean which controls whether read_buffer should display buffer icons. Default is false. Note, simply setting this variable alone does not cause Conkeror to fetch favicons. See Favicons for the full story.

read_url_handler_list

A list of handler functions which transform a typed url into a valid url or webjump. If the typed input is not valid then each function on this list is tried in turn. The handler function is called with a single string argument and it should return either a string or null. The result of the first function on the list that returns a string is used in place of the input. Example:

•   read_url_handler_list = [read_url_make_default_webjump_handler("google")];

run_external_editor_function

Coroutine function called to invoke an external editor. If this variable is set to a function, it is used to invoke an external editor in place of editor_shell_command. It is called with the filename as the first argument, and optionally the boolean keyword argument $temporary specifying whether the file should be deleted after the editor is closed, and optionally the keyword argument $line specifying a line number to display. The create_external_editor_launcher function is convenient for generating a function suitable for use as the value of this variable.

session_save_buffer_access_order

When true, access order of buffers is preserved in sessions. Default is false.

title_format_fn

url_completion_sort_order

Gives the default sort order for history and bookmark completion. The value is given as a string, and the available options include: 'none', 'title_ascending', 'date_ascending', 'uri_ascending', 'visitcount_ascending', 'keyword_ascending', 'dateadded_ascending', 'lastmodified_ascending', 'tags_ascending', and 'annotation_ascending'. For every 'ascending' option, there is a corresponding 'descending' option. Additionally, with XULRunner 6 and later, the options 'frecency_ascending' and 'frecency_descending' are available. See also https://developer.mozilla.org/en/NsINavHistoryQueryOptions#Sorting_methods. The default order is "visitcount_descending".

url_completion_use_bookmarks

Boolean Default is true. Controls whether bookmarks will be included in the completion list when prompting the user for an url, for example, with the open-url command.

url_completion_use_history

Boolean Default is false. Controls whether urls in the browse history will be included in the completion list when prompting the user for an url, for example, with the open-url command.

url_completion_use_webjumps

Boolean. Default is true. Controls whether webjumps will be included in the completion list when prompting the user for an url, for example, with the open-url command.

url_remoting_fn

"Url remoting" is the term for invoking Conkeror with an url (for example, from a command line) when a Conkeror process is already running. The new invocation is said to "remote" the url to the already running process. The variable url_remoting_fn is a function to dispatch on urls remoted into Conkeror. The default value is load_url_in_new_window. Though you can easily write your own url remoting function, obvious ones are already included in conkeror:

• load_url_in_new_window

• load_url_in_new_buffer

• load_url_in_current_buffer

view_source_function

May be set to a user-defined function for viewing source code. The function should accept an nsILocalFile of the filename as its one positional argument, and it will also be called with the keyword $temporary, whose value will be true if the file is considered temporary, and therefore the function must take responsibility for deleting it.

view_source_use_external_editor

When true, the view-source command will send its document to your external editor. Default is false.

webjump_partial_match

Default is true. When entering a url, if the input is not a webjump, but would uniquely complete to a webjump, then accept that webjump only if this is true.

window_extra_argument_max_delay

xkcd_add_title

Default is false. When true, xkcd-mode will scrape the alt text from the xkcd comic and insert it into the page below the comic.