[[!meta title="Questions and answers to help you fly with Hyperbole"]]
[[!meta copyright="Copyright © 2025 Bob Weiner"]]
[[!inline pages="internal(2025/info/hyperboleqa-nav)" raw="yes"]]
# Questions and answers to help you fly with Hyperbole
Bob Weiner - Pronunciation: Wine-er, , ,
[[!inline pages="internal(2025/info/hyperboleqa-before)" raw="yes"]]
RSW, the autthor of Hyperbole, will answer your questions on Hyperbole
live and demonstrate how it can make you more productive.
Hyperbole is an extensive, easy-to-use package that brings
hypertextual information management across all of Emacs to files with
minimal or no markup, including source code files. It works with all
modern versions of Emacs and does not require the use of any
third-party packages or compiled modules. Its keyboard-driven
minibuffer menus let you learn the key bindings for one set of
features at a time. Its global minor mode lets you turn on and off
its features with a single command.
Many people express interest in Hyperbole but find its breadth makes
it difficult for them to get started with it. Or they struggle to
find specific workflows because of its infinite flexibility. This Q
and A session is intended to help people over this initial hump by
covering introductory topics such as the Action Key and how Implicit
Buttons in your existing documents act as hyperlinks automatically.
If more advanced topics are of interest, we could even answer
questions such as:
- How can I quickly turn my Lisp expressions into hypertext buttons?
- Can I point Hyperbole at thousands of Org files and have it quickly
jump to arbitrary sections in the files without any prior indexing
or need for a database system?
- Can Hyperbole build a wiki with Org files, automatically
highlighting WikiWord references with no special markup and then
publish it to the web?
- When programming, can Hyperbole help me rapidly select, move and
display programmatic information?
- What if I need an entire outline with builtin hyperlink anchors
and automatic paragraph numbering?
- So Hyperbole just augments everything I do in Org mode already?
The session will be driven by the topics that participants want to
know about, so come with your questions and lets dive in together to
see whether its all just Hyperbole.
About the speaker:
Bob Weiner (rsw) has been developing hypertextual systems since the
dawn of the web in 1991 and using Emacs since 1982, though the other
day someone said I look 28-years-old, so neither I nor Hyperbole feel
that old. We have gained some perspective through the years, so maybe
I can help you learn something new or see something in a new way.
## Discussion / notes
- Q: I'm excited to know opinion on current state of using MCP and Ai
for PKM and PIEs. Since they do carry lot of burden out of us and
ease lot of process. How does hyperbole stand with coming days?
- A: We haven't yet done anything specific for MCP-based modes
but Hyperbole is a toolchest of capabilities for interlinking
information across Emacs. You can use existing link types or
create your own with just a few lines of code.
- AI is obviously on everybody's mind. We haven't done a lot of
integration with any of the popular AI engines, but I think as
you'll see through this Q&A session, Hyperbole's function is
really to interlink your information everywhere throughout
Emacs. And so, whether you're using a chatbot in a specific
buffer, you can use hyperbole implicit links, implicit buttons
to activate different actions there as well. So sometimes it
takes a bit of customization, a small amount of two to seven
lines of code to do that. As we get to working with more of
these engines, we'll build that into the core part of
Hyperbole. But right now, that's left as an extension for users
who are heavily using MCP or other protocols right now. We have,
for example, integrated with LSPs, you know, for coding and have
that interface through xref and basically using the single key,
the action key, which is made a return. You can jump around to
any of your source definitions from any reference in almost any
language that anybody uses today. So you can extrapolate from
that how that might work with AI as well. And I think you'll
see later when we talk about HyWiki that we're now enabling
just just wiki words to be buttons in hyperbole. So those could
be part of your chat with an AI and you just click on it and you
jump right to all your references associated with that
terminology.
- Q: As a normal user who codes and takes notes, I really want to
deep-dive and learn Hyperbole, but always end up winding back up to
embark and org-mode being the better system. For me hyperbole looks
like over-engineered (or over-configured) system which other
individual packages do well. And outside emacs there is no system
supporting hyperbole nor any usability.
- A: Listen to this Q&A session and take it one bite at a time.
Across time, you will see how the parts of Hyperbole integrate
together and why they are all there.
- Right, Hyperbole is large, but there's reasons behind that.
We're just trying to link all your information in Emacs. So I
think you can see my screen here in Emacs. So for example, you
can take any Lisp expression, even a variable like here we have
in Hyperbole, hyperb:dir variable, and I just hit the action key
M-RET, and in my minibuffer, I see the value of that variable,
but I could just as well take any other expression and take the
outer parens off and change them to angle brackets and now
that's a live hyperbutton. Could be in a comment in a
programming buffer in this case. It's in Koutliner buffer,
which is a an auto-numbered outliner part of hyperbole. So
let's just try this and say M-RET. I pressed and it ran occur
and found all the occurrences of buttons. And similarly in here,
I could just jump and go to any of these lines directly by
hitting M-RET in that buffer as well. So all your text, all your
sort of what we call implicit links become live in Hyperbole.
And you didn't have to learn much. You just learn, you know, if
you know a little Lisp or how to type any expression, then you
just change the outer brackets. And all of a sudden, you have
hyperbuttons. So Hyperbole, you can learn a little bit at a
time. And although it seems daunting at first because it has so
much functionality, very large and rich architecture. But what
we do is teach people one piece at a time.
- So just to continue on that a little bit, implicit buttons are
buttons that exist just from the text pattern in the buffer. So
you saw an example of changing Lisp into implicit buttons right
there. I could do keystrokes. I can just type them out in my
buffer and surround them with braces. So here's something,
let's see, this is actually a command in the K Outliner to jump
to the cell numbered four. So let's just do that. And it took
me right there, right? So I'm just pressing M-RET to activate
these buttons. Similarly, any sort of, this is a complex
example, but any path name I can surround with double quotes,
and it's a live hyperbutton. In this case, I want to jump to a
path name called readme.md, but it's in a directory that's
specified by an actual list variable. And then I want to go
directly to a headline within that file called Hyperbole manual.
And within that headline, I wanna go to the eighth line relative
to that. So all I have to do, M-RET again, and boom, I'm in
that, I'm directly linked to that. And Hyperbole has ways that
you can just split your windows like this and create that
reference in the source buffer right there. You just press a few
keys and it'll embed that link. We'll see that a little later.
- Another example, so all of these buttons, if I just show you
here, you can press C-h A anytime. and it will show you exactly
what M-RET will do in that context. In this case, it's an
implicit button, and it shows you even where the button starts
and ends, what type of action it will run, it's a link to a
file line, and then what arguments it takes. So Hyperbole
extracts all this meta information just from the text in your
buffer and displays it to you conveniently so you can know
before you ever touch a hyper button if it will do something
that you want it to do. Here we have a fairly advanced button
that's very simple to do. You just specify a bug in Emacs that
you want to reference to. Notice no delimiters, just bug pound,
whatever, M-RET. And I'm in Gnus reading the conversation for
that bug. And I can just, you know, move through all the
conversation. I can quit out of there and go back to where I
was. So very, very easy to use these implicit buttons because
they're already there throughout your Emacs buffers. I
described the C-h A, what that does. And there's other types of
buttons that we can get into as questions go on, but you can
create your own explicit buttons that have a little slightly
different delimiter than you see in the implicit buttons. And
this one I just put in here to show you that If you use it and
you go, this is the hyperbole to do list, which is an org
buffer. But I wanted to show in here that similarly, we have
implicit buttons for TODOs in the work. And when we hit M-RET,
it just changes the state of that to do. And I can cycle through
those but even better with the prefix argument if I have
multiple sequences of TODOs because there's Bob and Mats that
maintain hyperbole so I can shift to Bob's TODOs with C-u M-RET
and then cycle through the states for me So very very easy to
use, you know something that's a little bit more difficult to
do I think in org without it.
- So that's an explicit button where I had to actually say I want
to create this button, and I had to specify what type it is. If
I show you the information there again, you see it has a little
different type called a keyboard key, which runs just the key
sequence. So you're starting to see already that explicit
buttons have a type that's connected to an action that an
implicit button can do as well. So all of this ties back
together.
- And finally, there's a homepage that Hyperbole has, a personal
homepage that you have. You hit C-h h, which is our mini-buffer
menu, and then you hit what is it, b for button file and then p
for personal file. And that just brings you to basically a set
of links that you can create buttons in any format you want.
There's no structure that you see here. But the nice thing is
that all of these buttons that have these names, as we call
them, with the delimiters here, can be referenced now as what we
call global buttons wherever you are in Emacs. So I'm in a
separate buffer here and say I want to jump to that to-do button
that's labeled td on line 10 down there. No matter what I have
on screen, I can hit C-h h g for global button, a for activate,
and then it gives me a list of those. So I know it's td, I just
put td in. Okay, that's a path link problem I have, but when I
fix the link, it would go to it. So you can create buttons that
you can access in any mode, anywhere, and just give them quick
names, and it's very easy. So that kind of gives you an idea of
how you can get very productive with hyperbole with just a few
simple techniques.
- Q: I've been using "activities.el" and "Bufferlo" to save
dedicated workspaces (open buffers, window positions) in tabs and
frames for tasks/projects across Emacs sessions. Could I do
something similar with Hyperbole?
- A: We plan to have Hyperbole activities.el integration in about
another month, so stay tuned for that. In the meantime, there
is the Win/ minibuffer menu, that lets you save window and frame
configurations by name or onto a window config ring similar to
the kill-ring.
- Yes, you can. And activities is a nice package from alphapapa.
We've actually been working with it lately. So we're probably
in the next month or so we'll have a specific integration to
activities built into Hyperbole. But right now, we don't. But
of course, you can call any of its functions or key bindings
using the techniques that I just showed you earlier. But what we
do have built in if you go to the menu again. and you see C-h h,
and then there's a w, Windows, WinConfig menu, and there's two
types of window configurations that you can save here. They are,
right now, they're per Emacs session. They're not stored
beyond that, but we'll probably add that in as well, or we'll
use activities for that. so the two types are you can either
just save a window configuration in a frame... Actually, it
stores the frame configuration to a ring just like the kill
ring. So you have the three commands at the right. you can save
with an s, you can pop one off the ring with p, or you can just
yank and keep cycling through with a y and it will restore the
frame configuration that you saved. Similarly, you can just do
it by name, and you can say "I want to add a name" and then
just give it a name again, winc, and store it and it stores it
there and then you can get back to it by name as well. So fairly
easy to use as well and again integrated in the same simple menu
system. S
- Q: How well do Hyperbole and org-mode work together? Is there any
kind of integration?
- A: Hyperbole is very well integrated with Org mode and most
Hyperbole capabilities are live within Org mode buffers. We did
an EmacsConf talk in an earlier year about the integration.
Find it here:
[https://emacsconf.org/2022/talks/hyperorg/](https://emacsconf.org/2022/talks/hyperorg/)
- How well do hyperbole and org mode work together? Is there any
kind of integration? Yes, in fact, that's really good. I'll
just mention something. Let me go back to my homepage. I just
stored that here. So we gave a talk at an earlier Emacs
conference right here on org and hyperbole integration. So
that's a good one to go back to. And I believe it's in this
files included with hyperbole as well. So you can learn various
techniques of how the action key helps you in org. It does
special things in tables. And there's some nice support for,
for example, working with code blocks. Let me see where that is.
Okay, so right back here. So you can run them with the action
key. You can refresh the output and do things like that. So
again, if I just hit C-h A, it'll tell me that it's in smart
org, and it'll give me all the different contexts that that
operates within. So there's a lot that it does in here. And you
can see it would point on the dir value of a code block
definition that will actually display a summary and all sorts of
functionality. So the integration is quite tight. And one of the
things we do since M-RET is used in org, we have a customization
setting, c then o. And you have these three settings where you
can say, I want M-RET to... I want hyperbole to control that
and everything that the action key does I want to happen, or I
only want hyperbole to control when I'm over a hyperbole
implicit/explicit button, or I want org to control that key and
never use hyperbole. So you just set that once, it's persistent
across sessions and you're good to go. And again, it's built
right into the menus.
- But even following that we've the latest addition to hyperbole
is something, and this is the first time we're really showing
it publicly, is the Hywiki, which is a new subsystem as we call
it, and this is I think the best wiki capability in Emacs. Now
what it does is it automatically highlights... Let me turn it
on. I have to turn on hywiki mode. And you see those wiki words
now got highlighted, so any any wiki word which is the
capitalized alpha word you know, so you can have multiple
capitals in there and it'll get recognized, can be used as a
wiki word. So for example when I just type HyWiki here, it
automatically recognizes it, and you see it turned it into a
hyperlink button, which again, C-h a will tell me exactly what
it does there. But I can just hit the action key, M-RET, and
it'll display my hywiki.org file. All wiki pages are org files.
So we're using that for the wikis, and you have You can export
an entire wiki using essentially the org export capability with
a little extra set of features that we've added in, but let's
say, even better. You see I have this heading here, so let me
just change this. You go back here, and I'll say go to heading,
so you just put a pound on it, and now that whole thing is a
reference to a specific org section. Notice there's no org IDs
here. There's nothing other than the text that you're seeing.
There's not even a delimiter. So we have automatic implicit
hyper buttons being added in any buffer. Could be a comment in a
programming buffer with all you You don't have to add anything.
I'll show you how to create a new page in a minute. But you see
I can link to any org section without any IDs. And then I can
also do like org-roam does, but without the indexing or database
that it requires. I can scan over all of my wiki files and
headings. find a match really quickly. So we can get into some
of that a little later as well. But, you know, very convenient.
There's nothing that you change on org to do this. So how do I
create a wiki word? Well, let's say I wanted, you know, wiki
word for me. So that's already, that was a wiki word, but now
this is a new one. So you see it doesn't highlight because I
haven't created a wiki page yet. So all I hit is the action
key, and boom. Now it created it as a new wiki word. It created
the .org file. If I don't edit this file, it won't save it,
and it'll not become a word in case you made an accident. But
let's just say I want to say it. So, you know, heading. That's
it. I'm just in org mode. Now anytime that hywiki mode is
active, in any buffer essentially, I can type that out and
it'll recognize it. Notice so that's not a wiki word. So it's
highlighting and it's unhighlighting right as I type. So,
again, you can embed these as org links in org. There's a
special format like this, HyWiki word that you can make an org
link if I was in org mode, just like that. So there's all sorts
of compatibility, but basically it's just words, and HyWiki
takes care of the rest for you. So there's a directory where
all these, it's HyWiki, hywiki, ~/hywiki is the default place
where all these would be found, and there's a menu now in
hyperbole for hywiki, h, and you can see, it has a lot of
capabilities. But I can say, b, go into the directory of all the
files, just pull them up, and any of these you'll see... Let
me give you one like this. Okay. So you can see the other wiki
words being highlighted in here. It's very fast too. There's
almost no delay for anything, and yet very flexible, and you
have this ability where you could type emacs#section-1-2 and if
you didn't have delimiters around it, but you can put any
delimiters like double quotes or parentheses, and then it'll
match without you having to change the header at all with the
spaces included, and all of those will get recognized. I don't
know if the section exists right there. So anyway a lot of
capability you can see that here where I did the hy... it
actually highlights as an org link because it is an org link,
and it'll operate just like any other org link even though
it's a hywiki word link as well. So very powerful stuff and
totally integrated with Org Mode throughout. Great.
- Q: Are there any talks from this year's emacsconf that discussed
things that would work well with Hyperbole?
- A: Had to work yesterday so I haven't followed the talks. Pick
your favorite mode/type of information. Can Hyperbole work with
that? The answer is yes.
- Demo of how to create an implicit button type. See
documentation here:
[https://rswgnu.github.io/hyperbole/man/hyperbole.html#Creating-Types](https://rswgnu.github.io/hyperbole/man/hyperbole.html#Creating-Types)
- No. Unfortunately, I had to work yesterday, so I haven't been
following the conference as much as I do. Maybe somebody else
could comment on that. But I think, you know, again, it's like
pick your favorite mode, pick your favorite type of information.
Can hyperbole work with that? You know, the answer is almost
always yes. So, you know, if I show you just a little bit, if I
show you some of these implicit button types, just so you know
the amount of code involved to create a type. So here's like a
mail, recognizing an email address as a button. It's a little
long, so that it creates a lot of things, but you know it's
less than 15 lines of code for that. Path names are complicated,
so that's a longer one, but let's look at... So here's one
recognizing a bibliography entry. So it can be between two and
20 lines of code to create an entirely new button type. And you
create it once, and you just add it to the set of types, just
like at the fun, except it's done with this macro called def
implicit button type, and defib. And it's part of your
hyperlinking system forever then. So say you got dumped with
5,000 documents that were in this weird text format, and they
all had cross-references among them, but it was, again, using a
weird format. You could just write your own little type for
that, and then those 5,000 documents are hyperlinked for you
every time you're browsing them in Emacs automatically. So we
do that all the time, create small things, but all of these are
built into Hyperbole. Markdown links, texinfo links, all of
that's automatic. I could even be in a shell mode, and I just
say ls, and these are hyperlinks that Hyperbole understands,
right? It just jumps right to the file. So grep -n, you know,
looking at any line numbers, you don't have to remember all
these different commands anymore. You just hit M-RET, and
Hyperbole does the right thing in all these different contexts,
including following cross-references in code. So I would say
that's your answer. Most things that people are talking about,
we've already probably integrated with Hyperbole or with a
little bit of custom coding. You can do it.
- Comment: Interesting, but the many different link formats makes
reading and analyzing my notes much harder and less usable outside
Emacs.
- Well, I mean, the different formats that you're saying, like
angle brackets or curly braces, are just so that you can utilize
many different types. of buttons, but if you just want to use
key sequences, there's only one markup format. With org,
you've got the square brackets, which are consistent, but in
order to have different types, you have to type a prefix name,
like you see the HY for the HyWiki buttons in org mode. So I
think the trade-off is pretty much the same, but Hyperbole
always, always works to minimize the amount of markup. Markdown
is pretty simple. A lot of people like that. But I think you'll
find in hyperbole texts, they read just like regular language. I
mean, the delimiters are fairly invisible. So I'm not sure what
the issue is there. And again, you can choose your own. You can
make your own types with your own delimiters. There's even a
custom macro that instead of using that defib where you have to
type out Lisp code, you can use regular expressions. And in one
line, you can define your own type of button with its own
delimiters. So, you know, depending on what works well for your
eyes, you can make Hyperbole adapt quite well to that. And
again, if you start using the HyWiki, there's literally zero
markup on that. So you're just reading text, and when you want
something hyperlinked, it's like a glossary or a dictionary
entry. It's just there, and it's just highlighted in the text.
So I don't see much barrier to using it with many different
types of documents.
- Q: Is there any doc on Hyperbole's design and architecture?
- A: See this very interesting AI-generated document with a bunch
of diagrams covering Hyperbole's architecture:
[https://deepwiki.com/rswgnu/hyperbole/1-gnu-hyperbole-overview](https://deepwiki.com/rswgnu/hyperbole/1-gnu-hyperbole-overview)
- interesting but the many different link formats makes
reading/analysing my notes much harder, and less usable outside
emacs
- Hyperbole is designed to minimize the markup necessary on
hyperbuttons and with HyWikiWords there is literally no markup. Org
has uniform link delimiters but requires different link prefixes to
embed different link types. Hyperbole uses different delimiters for
different types instead, but they are always easy to read and not
heavyweight like some Org markup is, e.g. drawers and IDs.
[[!inline pages="internal(2025/info/hyperboleqa-after)" raw="yes"]]
[[!inline pages="internal(2025/info/hyperboleqa-nav)" raw="yes"]]