[[!sidebar content=""]]
[[!meta title="Build a Zettelkasten with the Hyperbole Rolodex"]]
[[!meta copyright="Copyright © 2022 Ramin Honary"]]
[[!inline pages="internal(2022/info/rolodex-nav)" raw="yes"]]
<!-- Initially generated with emacsconf-generate-talk-page and then left alone for manual editing -->
<!-- You can manually edit this file to update the abstract, add links, etc. --->
# Build a Zettelkasten with the Hyperbole Rolodex
Ramin Honary ("Rah-mean" (hard-H) "Ho-na-ree", he/him.
- Email: <mailto:ramin.honary@gmail.com>
- Homepage: <https://tilde.town/~ramin_hal9001/>
- Mastodon: <https://emacs.ch/@ramin_hal9001>
- GitHub: <https://github.com/RaminHAL9001>
[[!inline pages="internal(2022/info/rolodex-before)" raw="yes"]]
"Zettelkasten" is a methodology for marshaling your knowledge,
ideas, creativity, into a database of hyperlinked notes, each note
representing a single quantity of knowledge. The method was first
devised by a well-published social scientist named Niklas Luhmann.
Though he constructed his database with actual slips of paper in a
box with a notebook for indexing, naturally, modern software removes
the manual labor from the process.
In the world of Emacs packages, Org Mode is the most well-known
package that provides the tools necessary for building a Zettelkasten,
along with extensions such as "Org Roam" which add functionality that
manage links between Org Mode documents. But Org Mode is not the only
Emacs package to provide such tools.
In this talk, I demonstrate how to use an oft-overlooked package
called Hyperbole as an alternative to Org Roam for managing hyperlinks
and building a Zettelkasten. In particular I use the Hyperbole
"Rolodex" feature, called "HyRolo." It was originally designed for
tracking your personal relations, but it can be used to build a
Zettelkasten with almost no additional configuration or 3rd-party
packages. HyRolo is a purely textual database, and does not require
an external database software to index the notes. It also provides a
very rich set of "actions" so that notes not only link to each other,
but can also trigger Emacs to execute code as well.
# Presentation outline:
## Introduction
- Ramin Honary
- Software Engineer, App Developer (mostly Python and Haskell)
- Emacs user for about 4 years (since 2018)
## Key Takeaway
- The Hyperbole hyperlink markup language lets you create links that
execute arbitrary Emacs commands.
- To link entries, create a hyperlink that executes a **HyRolo**
search.
## Quick overview of the Zettelkasten methodology
- **Note:** most of what I say about the Zettelkasten method comes
from Sacha Fast of <https://zettelkasten.de>
- **Zettelkasten is:** a database of interconnected ideas
## Tools I use in day-to-day writing
- **Hyperbole:** for hyperlinking, search, project management
- **Embark:** arranging text, copy and paste
- **Org-Mode:** for markup
- **Dired:** for working with sets of files
- **Consult, Vertico, Orderless, Marginalia:** interactive search
- **Magit:** Git revision control of my plain-text database
## Quick overview of Hyperbole
- **Core functionality:** a markup language for hyperlinks
- Applications such as **HyRolo** and **Koutline** built on top of
this core functionality.
- **HyRolo** is the feature I use as my Zettelkasten.
## Configuration of Hyperbole using `use-package`
```emacs-lisp
(use-package hyperbole
:config
(setq hbmap:dir-user "~/.emacs.d/hyperb/")
(setq hyrolo-file-list '("~/.emacs.d/hyperb/ideas.org"))
(setq hyrolo-date-format "%Y-%m-%d %H:%M:%S"))
```
## The Hyperbole Menu-Driven User Interface
- Menus are a kind of modal user interface
- Enter menu with Hyperbole leader key `{C-h h ...}`
- Select menu items with key presses
- Works a little like `which-key`
## Getting started with **HyRolo**: Create a *zettel*
- Add entry: `{C-h h r a}` "*hyperbole rolodex add*"
- Prompts you for a title for the entry
- The Zettelkasten file (e.g. ~idea.org~) is opened
- Write the body of the *zettel*, save the file.
## Searching the *HyRolo* database
- Multiple search options: by **string**, by **regex**, by **word**.
- I use **string search** most often: `{C-h h r s}`
- String search provides logical `AND`, `OR`, `XOR`, `NOT`
- Executing a search opens the `*HyRolo*` buffer.
- Read-only mode buffer with useful single-key navigation.
## Searching the **HyRolo** database
- **`{o}` as in "overview":** hides all but the headings
- **`{a}` as in "all":** shows all information under each heading
- **`{t}` as in "top":** shows top-level entries
- **`{n}` and `{p}`:** next/previous result
- **`{h}` and `{s}`:** hide/show a search result subheading
- **`{C-u r}` as in "regex":** prompts for a new string search
- **`{e}` or `{M-RET}` :** jump to that entry for editing, although
using this command inserts a new timestamp, I just use `{C-/}`
to undo insertion of the timestamp.
## How is **HyRolo** a Zettelkasten?
- **Key take-away:** The Hyperbole hyperlink markup language lets
you execute *arbitrary Emacs commands.*
- To link Zettelkasten entries, create an hyperlinks that execute a
**HyRolo** search.
## How to create an explicit link
1. Highlight text to be linked
2. `{C-h h e c}` to create a link
3. Prompted for link text with highlighted region (press enter)
4. Prompted for action: `hyrolo-fgrep`
5. Prompted for search string: `hyperbole`
## How "explicit buttons" encode actions
- A **separate file** from the HyRolo flat-file database.
- By default, called `.hypb`, exists in the same directory as the
HyRolo flat-file database.
## Conclusion
1. A Zettelkasten is database of ideas linked together
2. The Hyperbole **HyRolo** can run search queries
3. The Hyperbole markdown creates links that execute queries
4. This results in a minimal but useful Zettelkasten.
# Discussion
## Notes
- My blog: <https://tilde.town/~ramin_hal9001>
## Questions and answers
- Q: Why is the time-stamp not implemented as an Org mode PROPERTIES
entry? (e,g, :CREATED:)
- A: Hyperbole pre-dates Org-Mode, although the maintainers have
made efforts to make Hyperbole compatible with Org-Mode as much
as possible. You could ask Bob Weiner directly, but it could
just be for backward compatibility, trying to keep the
formatting for current Hyperbole users. You could raise that as
an issue, they may be willing to include a config option
allowing you to specify the time-stamp format.
- Q: why Hyperbole/HyRolo over Org-Roam? (I don't use either, just
curious)
- A: HyRolo and Hyperbole require no other software beyond code
builtin to Emacs. For example, when I first built Org-Roam, it
did not work properly for me and I had to modify the build
process to get it set up. With Hyperbole, you install one
package and you can start working.
- A: ^this, and I find it to be a lighter-weight solution. I was
able to get it working without depending on SQLite or doing any
indexing. Hyperbole is also a more general solution that can be
applied to a wider range of use cases than just Zettelkasten.
- Q: How does this scale to very large data bases?
- A: It works very well with fairly large personal databases. No
one has ever complained about performance. Generally, people
are surprised how fast it is given that there is no separate
indexing in the background.
- A: I personally do not have a large database so I don't know
for sure. But it is basically as efficient as Grep is, and I
have used Grep on multiple-gigabyte files without noticing it
being too slow. Modern computers are fast enough that indexing
isn't required for reasonable performance on smaller databases.
- Q: The demo displayed how to search occurances of certain keywords
in a giant single-document text database. But what about other open
(or not open) Emacs buffers? Think of IRC chars, emails, etc.
- A: Set the hyrolo-file-list variaable to include any directory
of files you want to search.
- I mostly referred to non-file buffers.
- Searching through (for example) an IRC buffer is a
different command than searching through a directory of
files, and this makes sense for the "Rolodex" use
case, since typically your database will be a file, and
not an in-memory buffer. But you can create a hyperlink
button that triggers an ordinary "isearch"-like
command the same way you would execute other Emacs
commands.
- Q: if I may ask, why Hyperbole/HyRolo over Org-Roam? (I don't use either, just curious)
- rswgnu: HyRolo and Hyperbole require no other software beyond code builtin to Emacs. For example, when I first built Org-Roam, it did not work properly for me and I had to modify the build process to get it set up. With Hyperbole, you install one package and you can start working.
- A: @lounge-060 I found Hyperbole to be a more light-weight option over Org-Roam.
- Q: did i misunderstand, that each time he's hitting a button he's going to a temporary buffer which is a search result?
- A: yes, the button executes a search, so the cursor jumps to the search result buffer, but you can jump to other links within the same search result buffer.
- interesting, but i asked if a link can go directly to the source file, not a search buffer. i'm thinking like org's follow link, which isn't always accurate as i'd like.
- A: yes, you could do that. the Hyperbole link syntax does not have to execute a search, you can link directly to a file.
- Q: can the hyperlink goto the ORG file buffer at a specific location?
- Q: Thanks for the links. Can you recommend resources for incremental peg too?
- Q: wonder how that compares to plain org-mode, with links and in particular "elisp" links to built-in org-agenda functions, or org-ql (any of alphapapa's packages really)?
- One relevant distinction is that Hyperbole provides "alternative" action for a link. You may not just follow it, but do other things. Org mode does not have that
- custom link types are quite extensible though, and with the "elisp" type it's possible to call into many things without such customization. I'll have to try Hyperbole though.
- hyperbole looks like it can use code, has some assumption of data types, etc
- A: Yeah, hyperbole is a very general solution for establishing connections between various pieces of information. Hyperbole is a global minor mode so it works everywhere.
- Q: Why do you have only one file?
- A: it is just easier for me to keep all the realted information in a single file. I could split it into several files in a directory, but I don't see any benefit to doing that. You can point the search function to the directory, and it will search all of the files there.
- i honestly find the idea of tons of little files to be a problem. why not have many headings in a file by primary category
- HyRolo does use single files for its databases. Ramin is just migrating from keeping a separate Org file per note.
- Q: One thing that stopped me from using Hyperbole is that is does not load for me :( Reporting bug is still in my todo list
- A: curious. If you load, can you run M-x action-key and get it to work? If so, it probably works but is blocked by your key bindings.
- another obvious issue I faced is M-RET is already used by Org extensively
- I had to compromise on marks by setting leader keybinding C-SPC C-SPC to hyperbole action instead
- Q: rswgnu perhaps already asked before, but M-RET (default hyperbole action key) conflicts with org-mode use. For now I've resorted to using C-SPC C-SPC (with leader package) but is there another better alternative generally preferred? Perhaps one that does not conflict with a major feature like marks?
- Q: what would you recommend with emphasis on "beginner level" when starting with org-mode and planning to create the "2nd brain" approach: org-roam or hyberbole?
- Q: if you have a blog somewhere, I'll be very interested to read more. Your style of explaining and demo-ing things is quite nice
- A: My blog is https://tilde.town/~ramin_hal9001
- Q: what advantage do you see in using hyperbole?
- A: The big advantage for me is the "explicit links" feature, it lets me create a database of links that work universally. For example, you can change the link in the flat file database, and it updates in all of your files. If you and I shared a Hyperbole link file, I could write a link `<(like this)>` right here in the chat buffer and you could use it from within the Emacs chat client ERC.
## Other discussions from IRC
- Feedback
- I like this method of the talk slides being kinda transparent so you can see the speaker behind them.
- This looks very interesting tbf
- Its cool to see how many different note taking packages there are in Emacs
- Very nice talk-- and very understandable for me as a beginner who had never heard of hyperbole and did not understand the use-case. I also have not heard or read of a Zettelkasten, so this was even more useful.
- This talk has already given enough ideas on making some stuff dynamic
- There is a very good chance I'll keep coming back to this talk and its transcript over the next year, just to see how I can improve my presonal workflow more by integrating Hyperbole. Right now, I just use hyperbole to more conveniently (and more importantly, with same keybinding everywhere) open links across Emacs.
- Great talk Rami
n, thank you!
- Hyperbole
- Nice-- I needed this talk yesterday having not been familiar with hyperbole and use cases.
- i've been waiting to see a hyperbole use case, so i'm watching =]
- (Hopefully I can finally grok what this Hyperbole thing is about and how it contrasts with Org/Org-mode and such)
- sounds very vanilla...which I like
- Hyperbole sounds like something I definitely should get into, but I havent looked into it
- finally something that helped me grok hyperbole ;]
- Seeing an application thereof, as opposed to an exposition of its capabilities in the abstract (though quite interesting too, thanks rswgnu!), has given me a slightly better understanding, thanks!
- hyperbole has been something i've struggled to understand from the docs and examples. i think i've finally started to get that it's a text hyperlink with potential code embedded.
- ty for the explaination, like i said, this has helped me refine my impression of hyperbole further.
- I'm quite looking forward to more integration between org and hyperbole
- Thanks ramin_hal9001, I'm further on my way to enlightenment about Hyperbole that I was that's for sure!
- Watching Hyperbole videos like this, not understanding it completely: to me, Hyperbole doesn't have much advantage if you're happy with (bi-directional) Org mode links (as demoed in 15min). However, I do think that Hyperbole does have many advantages when you're starting to embrace the idea of "dynamic links" of all sorts. So far, I did not get creative enough to start with Hyperbole for that
- rswgnu : If I may ask, I keep looking for either uses cases or capabilities that Hyperbole could bring to bear beyond what I'm doing with Org/Org-mode (taking in account that its has custom link types and elisp links and such), are there some that would come to mind? I've watched most videos and skimmed the documentation a few times, but I'm still not reaching the aha moment, yet, but I feel one use case could change that.
- It could be interesting to use Hyperbole to auto-detect various links in Emails by matching common text patterns
[[!inline pages="internal(2022/info/rolodex-after)" raw="yes"]]
[[!inline pages="internal(2022/info/rolodex-nav)" raw="yes"]]
[[!taglink CategoryHyperbole]] [[!taglink CategoryZettelkasten]]
