
The documentation is written in Asciidoctor because I just want to avoid org-roam recognizing it. ;p As for the reproducible environment, it uses Nix (no surprise).
7.7 KiB
Keep taking notes and stop worrying about file organization!
Muh wiki. This documents the "infrastructure" of my notes because I like documenting. It primarily uses the Zettelkasten note-taking method which means all of my notes are scattered in just one location. Fun.
Note
|
On another note, this supercedes my personal notes. I’m not going to import them because I want to start on a clean slate. |
Getting started
Interested in copying my setup? Here’s my IKEA-esque manual for you.
Prerequisites
It needs the following list of software. All of them are required unless noted otherwise.
-
-
Uses Doom Emacs as the preferred Emacs distro with the
org
module enabled. This is optional and you can use your own Emacs config. -
org-roam, the star of the show, is installed.
-
-
Nix package manager because org-babel. You can fully replicate the environment without Nix by looking at the dependencies at
./shell.nix
and install them with your package manager (or anything else, you do you) but I recommend to do so because I say so. -
direnv (optional, by the way) because automatic shell environment. [1]
Conventions
-
Uses timestamp (at localtime) as the filename, it is unique enough (for personal purposes) and doesn’t need to change. [2] The format for the filename is equivalent to
$(date +%F-%H-%M-%S).org
. -
Uses plain org-mode tags for consistency. It also happens to be the only supported tag format starting from org-roam v2 so hoorah for me. :)
-
A list of references are stored at
./references.bib
for org-ref-styled workflows. It is managed with Zotero with the better-bibtex Zotero extension but you can replace however you manage and generate the Bibtex file. -
A creation datetime and a modification datetime is a cruicial part of my notes. It lets me know how up-to-date my notes are without relying on the filesystem metadata because I copy them carelessly, not to mention how various tools deal with them differently. The modification datetime is handled with timestamps automatically. Here’s an example Doom Emacs configuration for that:
(after! org (setq time-stamp-start "date_modified:[ ]+\\\\?[\"<]+" time-stamp-format "%Y-%02m-%02d %02H:%02M:%02S %:z")) ; Automate updating timestamps on save. (add-hook 'before-save-hook 'time-stamp)
Just see my Doom Emacs config in my dotfiles.
-
The related assets are stored in the
./assets/
. The asset folder names should be the same as the filename of the org-mode document — e.g.,2021-04-06-15-04-11.org
should have an asset folder in./assets/2021-04-06-15-04-11/
.-
I sometimes draw a visual aid just to strengthen my learning as well as an excuse to use my graphics tablet and I want to store them in a reasonable location without dumping it like in a landfill. Unfortunately, this means having to scour the assets folder like a clueless babboon holding a hammer because all of it is named after a timestamp but I can deal with it.
-
org-mode can also generate files including text and graphics. I’m lazy and I fear conflicting asset filenames so I’ll just put them in separate folders instead alongside opening a can of worms. [3]
-
For my hand-drawn visual aids, I usually name with a prefix (e.g.,
fds-illustration-${WHAT_THE_GRAPHICS_IS_ABOUT}.webp
). As a side effect, this mitigates against overwriting of generated assets from org-mode if I remember to not name itfds-illustration-*
.
-
Future tasks
This also means expect the following changes if you’re watching this repo for some reason. Keep in mind all of the details are still under consideration.
-
Create a static site for my wiki. org-roam doesn’t have a built-in export option yet but there are solutions. For now, I’m not worrying to much on this one.
-
I could make a custom publication script. I did create a publication script back then for a small org-mode-based for testing purposes but it is messy and life happened so I wasn’t able to get back on it immediately. Here’s a very good example of a org-mode-and-Emacs-powered site complete with features and without JavaScript! [4]
-
Convert the org documents to commonly-supported text formats like Markdown and use static site generators. Most of them supports Markdown and there is an "export to Markdown" option for org-mode. I could whip up an Elisp script and export it by batch then move them over to an SSG setup like Hugo. This is also how Jethro Kuan’s org-roam notes are setup.
-
-
Migrate the notes for org-roam v2. Though I consider v1 to be feature-complete, I do like v2’s reimagining of the plugin with the node (instead of files) as the new atomic unit. It is closer to its original inspiration (Roam Research). It also brings a few simplified options along the way such as choosing to only support
tags
property. Aaaand the primary maintainer said more performance so yay for me.-
Expect to change the links since it doesn’t accept file links anymore.
-
Expect to generate IDs for each node/file. The community is ready to help for it since my Elisp-fu sucks.
-
-
Try out Neuron. I’ve used it on and off and even tried to support both org-roam and Neuron because I like the static site generated and also because org-roam doesn’t have a killer HTML exporter yet (in my opinion). It is simple and nice but I can deviate from that with org-publish or any supported static site generators like Hugo. Once org-mode is reimplemented in Neuron v2, it’s a 100% addition to my workflow.
-
Add/replace Nix with Guix. Maybe add a file intended for setting up a Guix environment. I like both Nix and Guix, all right.