On Storing Glossary Terms in Org Roam Nodes

Hacking on Org-Mode

This post started as a place for me to perform analaysis on my existing blogging ecosystem. The goal is to consolidate where I’m “storing” information. The strategy is moving elements of my blogging ecosystem into my Personal Knowledge Management (PKM 📖) system; and then exporting those back to my blog.

Writing to Think Through the Problem

At present I store my glossary in a YML file. Table 240: Take on Rules's Glossary Entity Attributes describles the attributes.

Table 240: Take on Rules’s Glossary Entity Attributes
abbrOptionalA short-hand means of referencing the entity; it’s abbreviation
auto_mentionTo RemoveUsed by `glossary:autoMention` rake task
content_disclaimersOptionalConnects this entry to a content disclaimer
describedTo RemoveHave we already described this node; useful for preventing repeat querying of Wikidata
descriptionOptionalA terse explanation of the entry; often imported from Wikidata
gameOptionalIndicates the entry is a game; the value should be the entry’s key
itemidOptionalA URL that disambiguates this entry ; From https://schema.org
itemtypeOptionalFurther specification on the classification of this entry; From https://schema.org
keyRequiredHow we programatically reference this entry
mention_asOptionalWhen we add a mentionAs attribute use this value; From https://schema.org
offerOptionalThe URL from which you can buy the item; From https://schema.org
plural_abbrOptionalThe plural form of the abbreviation
plural_titleOptionalThe plural form of the title
same_asOptionalConnect the item to a more verbose description (e.g. a Wikipedia article)
tagOptionalWhen used as a tag, add a "mention" node
titleRequiredHow we linguistically reference this entry
verbose_titleOptionalA more expressive title

Considerations for Migrating Glossary into Org Ecosystem

What would it look like to move the glossary into my Org ecosystem?

Let’s consider the following:

  • What would be the benefit?
  • What would be the storage strategy?
  • How to map the YAML entry to the Node’s data structure?
  • What are the ways in which Take on Rules references the glossary?

What Would be the Benefit?

The primary benefit that I see is in consolidation. Right now the benefits of the glossary are only available in my blogging ecosystem. And the “capture” process for those entries is outside of my normal capture process.

Further, in consolidation there is the process of thinking through the “problem” and designing a solution. The very thought exercise itself is enriching.

What Would Be the Storage Strategy?

I see two options: ./glossary or ./refs. The advantages of ./glossary is crisp demarkation. However I envision “promotion” or “drift” of refs into glossary items.

Store nodes in ./refs and add tag :glossary:

How to map the YAML entry to the Node’s data structure?

There is an analogy between my Epigraphs and my Glossary setup. An Epigraph has properties and it’s textual content (see Even if you decide never to write a single…).

In the case of a Glossary entry, the body of the node would be my additional notes. The node’s #+title: line would be it’s title property.

What Are the Ways in Which Take on Rules References the Glossary?

The following short-codes, part of the TakeOnRules Hugo Theme reference the glossary data:

when quoting a game, I add a purchase link to the citation.
when a post has a glossary tag that has a content disclaimer, I look that up.
this is where the major heavy liftin occurs; a glossary entry can be an abbreviation, mention, link, etc.

themes/hugo-tufte/layouts/_default/list.html :

themes/hugo-tufte/layouts/_default/single.html :

My assumption is that I would generate the ./data/glossary.yml file from my Org ecosystem.

To continue to leverage the ./data/glossary.yml as-is I would want to have means in my Org ecosystem to declare each of these.


There are two major design considerations:

  • Registering New Link Types in Org-Mode
  • Data Migration

Org-Mode 📖 has different link handlers. One example is the roam: scheme; a scheme added by Org-Roam 📖.

The org-link-set-parameters exposes a means of registering new schemes.

I have two “links” that I want to add: abbr: and abbr-plural:. The goal is to use my glossary to “link” to an entry that has an abbreviation and then at the point of export expand that abbreviation.

Reading the org-link-parameters documentation there are functions I want to set for both abbr: and abbr-plural::

What are the possible entries I have that meet the criteria? (e.g. have an abbreviation?)
When I export this link, what should logic should I use? (e.g. for HTML 📖, I should use an ABBR-tag, for other things the title (abbreviation) is perhaps best)
When I “click” on the link in my Org-Mode document, how should it resolve? Where should it go?

Data Migration

I want to export my ./data/glossary.yml to Org-Mode. There are some glossary entries that already have nodes in Org-Roam; for those I need to reconcile and adjust. For the others, I need to create a node for each glossary entry.

Once that is complete, I will stop adding and editing entries in ./data/glossary.yml; instead I will export them from my org repository to that file. An ideal test is that when I complete the round trip, my ./data/glossary.yml is unchanged.

I already do this for Epigraphs, so follow a similar “public” api process.


After a bit of time and exploration, I have enriched my understanding of the Org-Mode / Org-Roam ecosystem and further worked towards treating my blog as a “consumer” of my PKM system.

I’ve also solidified my love of cl-defun, &key parameters, and providing defaults. This helps me repurpose functions and think about their interactions. It’s a pattern I’ve also applied in my Ruby code.

An example perhaps? The following is a method signature: (cl-defun jf/org-roam-external-url-for (&key node (scheme "http"))

To call that method I write the following: (jf/org-roam-external-url-for :node the_node); where the_node is an Org-Roam node. By default I’m looking for URLs that start with the http scheme.

Instead of burying the default http in the method definition, I parameterize it and specify the default.

All of this is in service to sharpening my tools.