Using Hyperbole with tab completion

Home About Codeberg

In my previous article in the Emacs for Professionals series, I talked about the way in which I personally use the Emacs Bookmarks feature to create my own custom list of files and directories through which I can search much more quickly than I could when using the ordinary buffer switching {C-x b} command. I also mentioned that I do not actually use this method very often because of the limitations of what Emacs allows you to bookmark — Bookmarks must be associated with an actual file.

In this article, I will talk about the Hyperbole package for Emacs, and what I actually use to create customized sets of files through which I can quickly search using a tab completion and narrowing framework such as Icomplete or Vertico. I actually use Vertico.

How Hyperbole compares with Emacs Bookmarks

Hyperbole is a markup language for creating hyperlinks (among many other things), so it is not too difficult to understand how it can be used to create lists of links to files in the same way you would with the built-in Emacs Bookmarks feature.

One big difference between them is when you compare the *Bookmark List*, a special buffer that you use to edit your list of bookmarks. With Hyperbole, there is no such special buffer for managing your bookmarks. Instead you simply have an Org-Mode or similar such plain text file into which you write a mix of text and Hyperbole hyperlink markup to define your bookmarks. Hyperbole takes advantage of the fact that the hyperlink markup is easy to parse, and so a list of hyperlink completions can be constructed quickly even if the file does not use a rigid database format.

The most important difference, however, is that while Bookmarks must point to a file in the filesystem, Hyperbole allows you to link to nearly anything at all, so it overcomes the biggest limitation of the built-in Emacs Bookmarks feature.

That said, Hyperbole does not replace the Bookmarks feature. Though you could rebind the Bookmarks keys {C-x r m}, {C-x r b}, and {C-x r l} with equivalent Hyperbole commands, this is really not necessary as Hyperbole provides it's own key binding conventions. So both systems can be used side-by-side if you choose.

Bookmarks keys Hyperbole keys What it does
{C-x r m} {C-h h g c}

Create a bookmark in a globally accessible set of bookmarks

{C-x r b} {C-h h g a}

Prompt for a hyperlink to which you wish to jump, with tab completion.

{C-x r l} {C-h h b p}

Show the globally accessible set of bookmarks so it can be updated.

Using Hyperbole with Emacs Bookmarks

In fact, Hyperbole allows you to creat links to Emacs Bookmark links. If you use Emacs Bookmarks as a large, long-term database of bookmarks, you can use entries in the Emacs Bookmarks database as the link targets in the Hyperbole personal button file

The Personal Buttons File

The plain text file into which you can write your bookmarks is the Personal Buttons File. You can open this file for editing using the {C-h h b p} key binding, and this could be thought of as a substitute for the Bookmarks {C-x r l} (list-bookmarks) command. You can modify or delete anything by simply editing the text of the buffer directly. You can add bookmarks as well, by simply typing them in, or you can use the {C-h h g c} key binding, which works from any buffer.

After pressing {C-h h g c} you are prompted for bookmark details in the minibuffer:

  1. Enter a bookmark label (actually an explicit button label), the human readable label that shows up in the tab completion list.

  2. an action type — tell Hyperbole what to actually link to here: a file, a directory, a buffer, a URL, a Git commit, etc. For files, use the link-to-file link type (type and use tab completion).

  3. If you are linking to a file, select the file you want to link as the hyperlink. You would select the current file.

  4. The link-to-file action type also will ask if you want to link to the current point/cursor position. I select yes because I want to quickly jump back to where I was when I created this bookmark.

Using global buttons

To activate a hyperlink from within the personal buttons file, navigate the cursor to a hyperlink and press {M-RET} (that is, Alt-Return) — the {M-RET} key works in any buffer anywhere in Emacs as long as the Hyperbole global minor mode is active.

All hyperlinks that are defined in this personal buttons file become what are called Global Buttons, and can be accessed by way of the Global Buttons Menu. To jump to a global button hyperlink without visiting the personal buttons file, use {C-h h g a}. This can be thought of as a substitute for the Bookmarks {C-x r b} (bookmark-jump) command. Here a tab completion and narrowing framework like Icomplete, Vertico, or Helm, can make it much easier to select the item you want.

Unlimited bookmarking power

Unlike the built-in Emacs Bookmarks function, Hypebole buttons do not need to point to a file on some file system. You can create hyperlinks that execute arbitrary Emacs Lisp code, and arbitrary async shell commands, so you can link to almost anything imaginable.

This makes it more useful to me as a bookmarking feature because I can bookmark URLs on the Internet as well file paths on my local filesystem. I can also make a set of commonly used shell commands accessible from the {C-h h g a} command. I can even activate Bookmarks created by the {C-x r m}.