Migration Plan for Org-Roam Notes to Denote

Laying Out a Game Plan

Building on Exploring the Denote Emacs Package, I want to layout a migration plan. For the migration to be successful, I have the following criteria:

Glossary Migration
When I pull glossary entries into Take on Rules I expect the ./data/glossary.yml to be functionally identical to it’s current state. That is to say no nodes dropped nor added and keys being similar. I would go so far as to say after the migration the pull event should result in no change to ./data/glossary.yml.
Blog Export
I am able to export an Org-Mode 📖 format Denote file for publication on Take on Rules.
Data Structures
I am able to organize and discover notes via different attributes.
Keywords and Controlled Vocabularies
I spent time establishing the tags I use for blogging; I’d want assistance in adhering to that exercise.
Other Stuff
As I write this document, I’m certain other things will emerge.

Feature Tests

These are my guiding “feature tests.” Revisiting Exploring the Denote Emacs Package, you’ll notice that I’ve already introduced feature creep. Such is the life of any project, but especially a software project.

Glossary Migration

I need to consider how I’m handling abbr: and abbr-plural: links; due to the newness of this functionality I don’t have many to consider. This does require navigating the export of Hugo shortcode fragments.

I will need to migrate the Rake 📖 task that I wrote for pulling data into my Hugo 📖 data/glossary.yml file. This should be relatively straight-forward and easier by introducing the convention of a glossary directory.

Yes, I Org-Roam 📖 I could have created a custom directory and template, but I was relying on the search function as my intermediary. In hindsight, having a specific directory for Glossary is something I’m now sensing I want.

Given that I’m uncertain I want to migrate to Denote, it makes sense to move my glossary items to a glossary directory.

Blog Export

I’ll need to revisit the Extending the Ox section of my Emacs configuration. With this document, I did a called jf/export-org-to-tor to see what happened. The main thing I observed was that the Ox-Hugo front-matter I inject into this document was placed at the top of the file.

That clobbers the Denote convention of it’s front-matter at the top of the file. The fix is somewhat straight-forward; I know what to do but not yet how I’ll go about it.

There likely exists a function to detect the entirety of a Denote document’s front-matter. Use that to find where to insert the Ox-Hugo front matter.

Another thing I noticed was that I was adding an :ID: to a properties drawer. This is not necessary as Denote has the :identifier: front-matter entry. This does, however, remind me that I’ll need to consider migrating nodes.

Data Structure

One thing I love thinking about, and all too often forget to think about, is the data structure.

And Denote, by it’s conventions, has me thinking about the data structure; in part because of it’s opinions regarding front-matter. In this case there are two data structure components to consider:

  • File System Conventions
  • Document Metadata

File System Conventions

As a refresher, Denote uses the file name to encode:

  • Identifier
  • Title
  • Keywords (aka Tags)

There is further consideration about the directory structure. There is guidance on how to isolate directories (e.g. “work”, “personal”, “volunteer”) such that they are siloed from each other. See Section 3.3 “Maintain separate directories for notes” of Denote’s manual for further details on separate directories. However, directories need not be siloed. My aforementioned glossary is something I might not want siloed; after all these terms are useful for many contexts.

I do wonder how I might have three directories: glossary, employer, personal. I would want the glossary available to the employer and personal but disallow employer and personal “knowledge” of each other.

To put a name to metadata role of directory, I think of namespace or domain. Namespace feels too generic. Let’s go with domain, and lean on Webster’s 1913 definition:

The territory over which dominion or authority is exerted; the possessions of a sovereign or commonwealth, or the like. Also used figuratively.

I also like overlaying/amalgamating the definition with the Mathematical concept of domain:

The domain of a function is the set of its possible inputs, i.e., the set of input values where for which the function is defined.

With domain I have four pieces of metadata: title, identifier, keywords, and domain.

I should probably consider what are my implicit domains:

I reference many terms.
I collect passages and reference them in posts.
Blog Posts
I’ve written a lot of blog posts; should I move a note into this domain when I publish an internal note?

Do all of these warrant their own directory? Before I get carried away, I should do some preliminary exploration. As previously mentioned, the Glossary domain is a good experiment for adoption.

Document Metadata

I wrote about this quite a bit already, but will reiterate; because Denote allows writing in Org-Mode format, I have access to Org-Mode’s property syntax; though I’ll need to use a different method than I’ve previously used.

Keywords and Controlled Vocabularies

On I migrated the tags of my Blog; compressing 378 tags into 59. I checked Changelog // Take on Rules to see when I made this unceremonious switch. How to Use Tags spurred me to revisit my tagging. This migration inter-relates with my glossary migration; the glossary asserts what tags are allowed on Take on Rules.

To my knowledge, Org-Roam, does not have a concept of a controlled vocabulary for tags. And since I’m using Org-Roam as the mechanism for the initial composition of my blog, I’m butting up against tagging; namely I have to be disciplined about how I tag things.

In my quick read of the documentation, denote-infer-keywords provides the ability to limit tags to only those explicitly set in denote-known-keywords.

Further Considering and Pondering

One thing rattling around in my brain is how I’ve been using my agenda.org file. For my work at Scientist.com I use it as a TODO list and my monthly timesheet. When the month is done, I archive my timesheet.

What if I rethink things just a bit; each month get’s a journal.org file. Then I amend my org-agenda=files variable to point to the timesheet? This would mean I’m not archiving entries but instead removing them from my agenda workflow.

This is a future tangent but one that I’m pondering and considering. And none of this is really dependent on Denote; it is simply a byproduct of thinking about my organization system.

But I do like the idea of not archiving the entries. Why?

I use Git 📖 for version control of my Org-Mode files; and moving a subtree from one file to another gives me trepedations.


This document is about helping me think through a potential migration. And in writing this all down, I’m thinking about what it means to go through a migration.