Modeline buttons in Conkeror

Conkeror Mac Modeline Buttons - CMMB is an extension (based on the built-in mode-line-buttons.js) for Conkeror to display any buttons that you want in the Modeline.


Conkeror is a keyboard-oriented browser. I’m sure many of you when you see this page will argue that it’s designed for the keyboard and it’s much faster when we interact with it through keyboard. I totally agree! So what is the reason why I develop this package? Well, look at these pictures below to see why

Sometimes, we use the computer this way

Alt Text\ Alt Text

Or even this crazy way :LOL:

Alt Text

Now you know why this package appears. That is sometimes I’m just lazy or I’m using the computer on bed or some other reasons, it prevent me from using the computer with both hands. In that case, I have to either switch to other browser or change to other place (the desk), which is impossible because I’m lazy at that time :LOL: This package also acts as a gateway drug to Conkeror for new people.

Let me explain briefly the name of this project: Conkeror Mac Modeline Buttons. Conkeror already has built-in basic navigation buttons on modeline, which you can activate using this in your .conkerorrc

mode_line_add_buttons(standard_mode_line_buttons, true);

This works fine on Linux. However, on MacOS, there is no moz-icon://stock/gtk so that all the buttons cannot display correctly on MacOS. Moreover, the built-in function is limited as you can only add and remove button in your init file, not at run time. Yeah I want more! I’m a Mac user and I developed this library for using with my Mac so that I named it Conkeror Mac Modeline Buttons. However, I’m pretty sure that you can run it on Linux because they have the same file structure. I’m not sure if it works on Windows (I have not tested yet) but in the code, I use the dynamic code for getting home directory, not hard code, so if you’re lucky, it will work.


Firefox’s default icons

Button icons are extracted from Mozilla Firefox’s default icons on Mac OSX Lion

Alt Text

Built-in button groups

3 built-in button groups: navigation, editing and download buttons

  • Navigation: find-url, find-url-new-buffer, back, forward, reload, kill-current-buffer, buffer-previous, buffer-next, minibuffer-abort

Alt Text

  • Editing: cut, copy, paste

Alt Text

  • Download (mostly available in download buffer): download-manager-show-builtin-ui, download-cancel, download-retry, download-resume, download-pause

Alt Text

Multiple button groups

Multiple button groups can be display at the same time by activating their add commands. You can call any button group’s remove command without affecting the other ones.

Alt Text

Alt Text

Easily add new button of any command

You can easily add new button group follow the instruction below. Simply add the interactive command name and it’s image into the button definition, define the command to activate and you’re done. Using this one in combination with the tip on how to define interactive command for often used sites you even add a button groups of your favorite pages.

Download and Installation

It’s very easy to install since you just have to clone it from github. Make sure you have git installed and your .conkerorrc is a directory (new style).

First, clone it from github into your .conkerorrc

$ cd ~/.conkerorrc
$ git clone

You’re encouraged (but not compelled) to clone it into .conkerorrc. In that case, put this one into your init file to load it

let (path = get_home_directory()) {

If you put the package outside .conkerorrc folder, use this one


You also have to set the image path if you place the package outside .conkerorrc. See the Configurations section for more information


Simply type M-x and activate one of these commands to show the buttons

  • cmmb-add-navigation-buttons (show navigation buttons)
  • cmmb-remove-navigation-buttons (hide navigation buttons)
  • cmmb-add-editing-buttons (show editing buttons)
  • cmmb-remove-editing-buttons (hide navigation buttons)
  • cmmb-add-download-buttons (show download buttons)
  • cmmb-remove-download-buttons (hide navigation buttons)

You can also bind the commands to any keystroke that you want


If you want to use your own images, you can replace the images already exist inside the images folder with the ones that you want. You can also use your own image folder by setting variable cmmb_image_path. Also, if you have placed the package outside .conkerorrc, setting this variable is a must. Otherwise, just ignore this part and leave everything default.

cmmb_image_path = "/path/to/images/folder";

Add your custom buttons list

First, create an empty array for holding the widgets

var my_button_widgets = new Array();

Second, create an array for button definitions

my_buttons = [
    ["find-url", "open"],
    ["find-url-new-buffer", "new"],
    ["back", "go-back"],
    ["forward", "go-forward"],
    ["reload", "refresh"],
    ["kill-current-buffer", "close"],
    ["buffer-previous", "go-up"],
    ["buffer-next", "go-down"],

Each item in the array is also another array. The first element in that array indicates the interactive command to be executed when clicking on the button The second element in that array is the name of the image file (without extension) in PNG format. The image size should be 20x20. By default, the images are located under ~/.conkerorrc/conkeror-mac-modeline-buttons/images

Next, define an interactive command like this and pass in the two arrays that you have created before. This command is for adding the buttons

	"Add basic navigation buttons to the mode line",
	  cmmb_add_buttons(my_buttons, true, my_button_widgets);

After that, define another interactive command for removing modeline buttons and pass in the widgets array that you have created before

	"Remove navigation buttons from mode line", 

Finally, bind that two interactive commands to the keystrokes that you want

If you don’t want to use interactive commands, just want the buttons to be added automatically when you start conkeror, replace the interactive commands with

cmmb_add_buttons(my_buttons, true, my_button_widgets);

You can add many button lists without interfering other buttons list.