GNU Hyperbole: many have heard of it, but what does it do? This is my answer.

GNU Hyperbole is an Emacs Lisp system that has been around since the early 90s and is still actively maintained. It is very well documented, but I have noticed a lot of people still have trouble understanding what it actually does, even after browsing through the documentation. So I wrote this article to try to explain it simply. Special thanks to Hyperbole author Bob Weiner (/u/rswgnu) for fact checking and proof reading this article for me!

Thanks for writing this! I’ve been using emacs since the early 90s but somehow I’d never heard of this package. How does it interact (or conflict?) with ways of working and key binds established by org mode and org-roam?

Thanks for reading! I don't use Org-Roam myself. But I know that Hyperbole complements Org-Roam well, and I can't think of any way that Hyperbole conflicts with Org-Roam at all. The maintainers of Hyperbole have been working on better Org-Mode integration over the past couple of years. Because the Hyperbole implicit link rules work universally, you could theoretically link to Org-Roam entries from non-Org-Mode buffers. So you could write an Org-Roam UUID into any buffer at all, even in non-Org-Mode buffers (e.g. Git commits, text files, HTML files, Shell buffers, e-mail), and Hyperbole can automatically recognize that UUID as an Org-Roam entry and jump to it when you `{M-RET}` click on it. I don't know if this is the default behavior for Hyperbole (since I don't use Org-Roam), but it would not be hard to write your own hyperlink rules to do this.

IMVHO the synthesis is: hyperbole is a kind-of effective menu, a precursor of org-roam in a certain manner, since it allow a quick access, even if only hierarchical not search&narrow to links and links (buttons) are major-mode almost independent. I do not know how can make sense these days now that we have search&narrow UIs... I do not know how much can scale since buttons get stored in a single text file, one per line... It's impressive for various aspects, like Ubuntu Unity HUD time ago to innovate menus, but it's now surpassed by different UIs IMO...

For the first time I actually feel like I know what Hyperbole does, thank you!

> hyperbole is a kind-of effective menu, a precursor of org-roam The Hyperbole menu, in my mind, is not the most important feature, it is just a convenience. Yes, Hyperbole is similar to Org-Rome, but the big difference is that the markup language is optional, and you do not need to generate UUIDs for every entry, or maintain a SQLite database of UUID-file relations. Hyperbole establishes links between anything **without** the use of the Org markup language. For example, you can link between documents in a large directory of Markdown files, RST files, plain text files, Info-doc files, LaTeX files, and HTML files, and it all works consistently. Implicit links work without needing to maintain a database of UUIDs the way Org-Roam requires. With Hyperbole, you can use a flat-file "Explicit link" database, but this is optional. > I do not know how can make sense these days now that we have search&narrow UIs... I still use the modern search and narrow frameworks (vertico, consult, prescient, orderless, marginalia) for switching to files and buffers. But if you are not using Hyperbole, you have to select the link under the point, copy the text, paste it into the minibuffer, search for and narrow, and then execute. Hyperbole makes the highlight, copy, paste, and execute all a single action with `{M-RET}`. Packages like Embark-DWIM provide very similar functionality to Hyperbole implicit links. ~~~~but Embark always pops-up a menu of actions to do, which doesn't really make sense for things like URLs, or anything where it should be obvious what the link target is.~~~~ (EDIT) > I do not know how much can scale since buttons get stored in a single text file, one per line... This is true for the "Explicit links," but you do not need to use this feature. Instead, try using implicit link rules, they are applied to all buffers at all times without needing to maintain a link database.

Thanks for reading, I am glad I could help!

This is great work! Another similar explanation a little-understood emacs mode that some people might also like is Leah Neukirchen's explanation of *howm* mode: https://leahneukirchen.org/blog/archive/2022/03/note-taking-in-emacs-with-howm.html

With `embark` and `org-mode`, is `hyperbole` obsolete?

I had never heard of that one before, thanks! After reading over it briefly, I think I would like the ad-hoc nature of linking documents, and using Grep to find link targets. Hyperbole does not make use of Grep or any external tools to link documents together, although it can make use of `TAGS` files if they are available. Also, Hyperbole does not require a markup language or a major mode to declare links. Hyperbole does provide a `.kotl` markup format, and it does provide an "Explicit link" flat file database, but these are optional features.

Great piece! I do feel like I have a handle on this part of hyperbole now :) I will say, the thing this writing does best compared to some other documentation is NOT mentioning the various other bits and pieces that seem to be included for some reason. I feel like any time I've read the (very well written and thought out) comments on Hyperbole, they end up with "oh and this ties in nicely with the outline mode which is bundled in, and our window layout manager which is bundled in", which is usually what made me say "huh?"

I think Embark is most similar in functionality to Hyperbole implicit links, except it always pops up a menu of options, instead of acting immediately. I don't think Hyperbole is obsolete, Embark is just an alternative to Hyperbole. Embark is often compared to a "right mouse click" because it provides a context menu of actions you can take for a matching piece of text. In my blog post, I compare Hyperbole to a "left mouse click," because `{M-RET}` has that behavior of acting immediately without giving you a menu of options. So I guess you could install both Hyperbole and Embark and have a whole virtual 2-button mouse in Emacs! 🤣 Org-Mode is a markup format, so it is pretty different from Hyperbole's core functionality. Hyperbole does have a "KOutline" markup language which is much simpler than Org-Mode, but it is an optional feature -- you can use Hyperbole without ever using KOutline. This is because Hyperbole uses pattern matching rules to link documents, and these rules are always available regardless of your document format or major mode.

Thanks for your kind words, I am glad you enjoyed my writing! And I know exactly how you feel! I ran across Hyperbole in ELPA a few years back, and I had the same problem when reading the documentation. This was my motivation for writing this article, I tried to focus on that one core bit of functionality that makes Hyperbole unique. As I understand it, most all other Hyperbole features like "explicit buttons," the "KOutline" document format, and the "HyRolo" database, are each just a convenient package of additional features built on top of the core "implicit link" functionality.

Thank you, I have been meaning to delve into Hyperbole. The article gave much inspiration to start. I am installing it now.

Thanks for you kind words! Definitely check out the "FAST-DEMO" file, which you can access with `{C-h h d d}`. This documentation provides a thorough list of the implicit link rules that are enabled by default.

>I think Embark is most similar in functionality to Hyperbole implicit links, except it always pops up a menu of options There is also `embark-dwim` which immediately acts based on context. It jumps to definition in programing modes, opens the file at point if you're over a file path, opens citations and links. It's one downside is it can find multiple contexts and sometimes it defaults to an unexpected one. Specifically, it tends to put high priority to org-mode headings, so if you're on a link in a heading it won't open the link. But a.) I assume there's a way to change this and b.) I never actually noticed this until playing around with it while writing this since I always use `C-c C-o` for opening links.

I actually wanted to ask about a demo, and there it is. It is wonderful package, I love the feeling of the deep, well-thought out, poised engineering. It may be from the 90s, but it feels like a breath of fresh air to me.

Maybe the specialness (if any) of hyperbole could be it has smarter handling of these contexts? Would be interesting to test.

Number one problem BY FAR for Hyperbole IMHO is communication, and this blog post fails in the same way; almost every preesentation or blog post etc goes into a wall of text (no pics), and/or into long description beating around the bush with all kinds of flowery crap, without actually giving a short catchy 'heres what this will do for you', which is REALLY WEIRD. You can read the above post and still not have an idea. Hyperbole is this, at its simplest: Automatically match text in all buffers, to actions; example: if a URL is seen, a special action can open a browser to visit it; for files, open the file; for org-mode files, open them up and jump to the referred section, etc. No need for special markup. There you go, one short paragraph summarizing it all. I have no idea why people don't just say that :) Yes it can do more, but thats the basic hook, unless I'm totally missing it.

That is a very fair criticism. And I believe your summary of how Hyperbole works is accurate. I think it depends on how you prefer to learn things. For some people, simply explaining **how** it works is good enough, they can then decide for themselves how the mechanism can benefit them. For other people, they want some idea of **what** kind of problems it solves; what is the intent of the authors of the code? I try to answer both, but with more narrative form than an instruction manual, because this is the kind of writing I personally like to read. When I first learned about Hyperbole, I got the idea that it was about hyperlinking things, but I was confused because most major and minor modes in Emacs already apply hyperlinks to all relevant text in a buffer. I had the sense that I was missing something. *"It can't simply be about hyperlinks, how would that be useful in Emacs? What does it actually do?"* So I thought a discussion about the user experience was more important than the actual mechanism, which as you point out, is actually very simple. Most of my articles about Emacs are like this. Because a lot of people wonder what Emacs has to offer over other more modern text editors, especially nowadays when there are so many other text editors that are easily programmable, and provide good integration with shell utilities. Simply explaining the features of Emacs is seldom a good enough explanation to satisfy most people, in my personal experience.

> Maybe the specialness (if any) of hyperbole could be it has smarter handling of these contexts? That is a good question. I should learn more about Embark and see how the pattern matching rules it provides differs from Hyperbole. It would also be interesting to compare the macros provided, because you may want to program your own matching rules in your `init.el` file, and it would be nice to know how to do this in either system. But I am guessing that both Hyperbole and Embark provide a very similar set of pattern matching features. So probably, it would come down to a matter of personal preference.

*> wall of text (no pics)* There are screenshots in the Hyperbole manual (available in Info, HTML and PDF versions). There are videos of Hyperbole linked at the start of the Hyperbole [demo](https://www.gnu.org/software/hyperbole/FAST-DEMO) and on the Hyperbole home page: [https://www.gnu.org/s/hyperbole/#videos](https://www.gnu.org/s/hyperbole/#videos) *> without actually giving a short catchy 'heres what this will do for you* The first paragraph of the Hyperbole home page does that. For a more in depth, yet quick summary of my uses, see: [https://www.reddit.com/r/emacs/comments/jk3cn0/daily\_ways\_gnu\_hyperbole\_helps\_me\_stay\_in\_flow/](https://www.reddit.com/r/emacs/comments/jk3cn0/daily_ways_gnu_hyperbole_helps_me_stay_in_flow/) I don't think we can get much more detailed than that. There are also a series of use cases available in Hyperbole on {C-h h d w} (Why Use).

Yes, and built-in handling of a much broader set of contexts. Embark and other packages often rebuild Hyperbole-like functionality to have it in isolation rather than part of a more powerful environment. Hyperbole also has many other information management capabilities through its subsystems including unmatched autonumbered outlining, flexible, hierarchical note and contact management and window and frame management as well, all of which can be used as the targets of links without fancy markup.

Don't worry that Hyperbole has been around for so long (has longevity). It is in active development and generally keeps up with Emacs evolution today with full Emacs and Org compatibility through Emacs 28 right now. Try it out for an hour. Tell us any issues with it. We want it to be fun and easy to use while making you more productive. Pick pieces you want to try and then send feedback on those. Anyone who has followed the evolution of the package can tell we listen to constructive criticism and keep improving it. Once you start using it, it is easy to get addicted.

Neat -- if I understand correctly, Hyperbole is similar to the plumbing system in Plan 9?

> Neat -- if I understand correctly, Hyperbole is similar to the plumbing system in Plan 9? Not quite. The Plan 9 plumbing system is an IPC mechanism with pattern matching, which is more similar to the [message passing system](https://www.erlang.org/doc/getting_started/conc_prog.html#message-passing ) built-in to the Erlang programming language. The fundamental mechanism of Hyperbole is text pattern matching, but there is no message passing. The only "message" is whatever text is under the point/cursor when the `{M-RET}` key chord is pressed. The text is not passed to a network of plumber services capable of responding to the request, it is simply passed to a function that begins matching the message text to a cascade of rule functions. It all happens in a single thread and a single process.

I must say OPs post was very clear to me and much better then previous explanations, even those that had gifs. Previous explanations sidetracked into a list of use-cases and techincal stuff instead of giving the principle. Your version is more concise, but the post basically just said that + some examples and elaboration, it helps the concept sink in.

It would be nice if Hyperbole would follow modern packaging standards with respect to its prefixes and wouldn't lead to so many compilation and package-lint warnings. [https://github.com/melpa/melpa/pull/7820](https://github.com/melpa/melpa/pull/7820)

Yes, it seems that Hyperbole has been surpassed by org/org-roam and the more flexible Embark package for implicit buttons or actions at point.

Seems so. Embark is more flexible. It can be used for implicit buttons (embark-dwim) and on top offers actions at point (embark-act), which are not provided by Hyperbole. Org links can be used everywhere consistently as explicit buttons (org-open-at-point-global) and Org is also much richer than Koutliner.

>So I guess you could install both Hyperbole and Embark and have a whole virtual 2-button mouse in Emacs! 🤣 Embark alone already offers embark-dwim and embark-act - a whole virtual 2-button mouse. Combining Hyperbole and Embark as you suggest sounds problematic since both packages use different target at point finders.

>Yes, and built-in handling of a much broader set of contexts. Embark and other packages often rebuild Hyperbole-like functionality to have it in isolation rather than part of a more powerful environment. Embark is not an isolated package. It augments all kinds of text buffers with actions at point (embark-dwim, embark-act). It seems most users are interested specifically in the linking capabilities, not the additional subpackages offered by Hyperbole (koutliner, hyrolo, hycontrol). Embark focuses only on this linking and action aspect.

We agree in general and have already reduced the warning count significantly and are starting to look at a prefix update. These warnings typically have no operational/usage impact, so Hyperbole’s bug count remains low.

You gave a good idea about this package, but it would have been great if you have added illustrative videos, or pictures. Nevertheless greater job and I am looking forward to trying this package.

Consider that you do not need to "maintain a DB" with org-roam, it's autogenerated and in case of issue auto-regenerated. While hyperbole links (buttons) are a bit fragile and manual... Honestly I briefly tried it, find it nice, but nothing really actual for today usage...

Hi, Thank you for your clear explanation of Hyperbole! I'm intrigued by this package and want to give it a try. However after installing it I noticed that the keybindings are not compatible with evil mode. For example if I try to adjust frames with: "C-h h f s" the option to create a new frame is the "/" key. Hitting this key will only start me searching in the file. The documentation does not mention "evil" or "vim" and a Google search did not help either. Does anybody has successfully combined Hyperbole with evil mode and if so, could you point me in the right direction?

EDIT: Hey, I just figured out what the problem is, the instructions are confusing. So the instruction says `[/]=split win atop/sideways`, which means `[` splits the window horizontally, and `[` splits the window vertically. So the whole command you should type is `C-h h s f [` or `C-h h s f ]`. Thanks for your feedback! ~~Sorry, I had not condiered Evil-mode!~~ ~~Maybe one thing you could try is the Evil-mode `C-v` key, which lets you insert a single literal character. **I don't know if this will actually work.** Usually it is for inserting control characters, but it might work for inserting a `/`. So maybe you can try {C-h h s f **C-v** /} instead? This is probably less than ideal, since it requires more typing, but it is the only thing I can think of right now.~~ ~~I hope /u/rswgnu can answer you better than I can.~~

Interesting, this must be the result of modal editing. Hyperbole assumes a user who uses standard Emacs key binding configurations. We would be happy to work with someone who wanted to support vi-style editing but have no expertise there as I have used Emacs since I started programming and only know how to exit vi when a tool invokes it.

It works fine with evil. `/` is not a valid keybinding. You want `C-h h s f [`.

Embark may be more flexible in that you can match different actions to different types, but hyperbole has many nice implicit links builtin, and if you only need one action (which is the case for me), defining new implicit links is slightly simpler in hyperbole.

I agree that Hyperbole comes with many more "implicit links" out of the box - this is nice. However I would argue that most "implicit link" types are not actually implicit, they have a very specific and explicit syntax, for example `gh#rswgnu/hyperbole/5ae3550`. For explicit links one could just use Org link syntax and use `org-open-at-point-global` and write `gh:rswgnu/hyperbole/5ae3550` or `<gh:rswgnu/hyperbole/5ae3550>`. The Org syntax is not even longer! However defining Org links may be more tedious than defining Hyperbole links. See also what I posted here: https://www.reddit.com/r/emacs/comments/vied1y/gnu_hypobole_10/.

I agree that a lot are not actually implicit, e.g. I put keys, functions, and variables in == in org-mode. I never put keys in curly brackets, but I can add these as implicit links myself. The most useful builtin one I've seen so far is for libraries (e.g. subr.el). Right now I'm only using hyperbole for text that I never wrote with the intention to be a link or button in the first place. I'd also rather just use explicit org links everywhere else.

Currently I try to use this instead of Hyperbole - it gives me the best of Embark and explicit Org links/elements: ``` (defun hypobole-key () (interactive) (or (if (derived-mode-p 'org-mode) (or (ignore-errors (or (org-open-at-point) t)) (ignore-errors (or (org-ctrl-c-ctrl-c) t))) (ignore-errors (or (org-open-at-point-global) t))) (embark-dwim))) ```

I'm using something similar, but it falls back to hyperbole instead of embark. I've added several of my own implicit link types that makes it quite useful. First it tries link-hint, which supports many buttons/links that my guess is are not supported by other packages ootb (see [here](https://github.com/noctuid/link-hint.el#at-point-fallback-commands) for something similar to my command), then it tries lsp-find-definition or smart-jump-go (if applicable), and then it tries hyperbole. I'm using orglink, so org links work in anywhere. I'm considering also having it fall back to simulating C-c C-c (rather than any specific command), but am not sure if this fits well.

Hey, I just figured out what the problem is, the instructions are confusing. So the instruction says `[/]=split win atop/sideways`, which means `[` splits the window horizontally, and `[` splits the window vertically. So the whole command you should type is `C-h h s f [` or `C-h h s f ]`. Thanks for your feedback!

Thanks Ramin for writing this article. I hope many more people see it. Hyperbole is an integrated information management platform atop Emacs that works with pretty much every kind of buffer and file format that people typically work with. It augments rather than replaces Org mode, web sites, file browsers, etc. Embark is a nice small package but lacks the extensive number of contexts that Hyperbole recognizes that people frequently use and those that give them enormous flexibility and power with just some basic knowledge. Just a few examples include: Hyperbole recognizes and resolves links to Posix and Remote Windows paths from multiple OSes, so Linux users can link to Windows shares on the local network without any need for any manual mounting. An Action Key press on a colon-separated PATH value starts dried on the path selected; of course, this works on semicolon-sepated Windows PATHs as well. And "${PATH}/python-program.py" takes you right to that source file. Mark some buffers in the buffer menu or paths in Dired, then press @ and Hyperbole displays a nice grid of windows displaying them (using both horizontal and vertical layouts). Then you can simply use your middle mouse button to drag any other entry to any of the windows you want. There are dozens and dozens of these incredibly easy-to-use yet hard to replicate behaviors that none of these more modern packages offer. You just have to try it for your specific needs and you may be surprised how much of what you want is already built-in and automatically enabled after you install Hyperbole. We often hear that from people who become users. Also, we're not against search and narrow frameworks and you can as easily connect these to Hyperbole as you can to any other package out there. We have done a number of Helm integrations in the past and have used Org Rifle for HyRolo searches.