NOTE: This has culminated in the My org-roam workflows for taking notes and writing articles article

Idea ¶

We want to publish a subset of our notes. They’re not necessarily worth turning into proper articles, but some people might still stumble upon them and find them useful. Some of our notes are private and we don’t want to publish those. It’d be safest to tag all notes that are public, but since the majority of them are public, that has poor ergonomics. Tagging private notes takes much less work, but risks accidentally leaking a note.

Existing braindumps ¶

We’re not the first to have this idea, of course. We’ve found the following braindumps that are based on org-roam:

• https://braindump.jethro.dev/
• https://braindump.badykov.com/about/
• https://commonplace.doubleloop.net/
• https://hugocisneros.com/notes/

Existing workflows ¶

Luckily, they’ve all documented their workflows:

• How I publish my org-roam wiki with org-publish — doubleloop [1]
  • org-publish
  • custom code for backlinks
  • custom code for org-roam graph
  • custom CSS and JS
• Options for publishing an org-roam-based digital garden [2]
  • enumerates several options
• Jethro’s Braindump [3]
  • ox-hugo based workflow
  • uses Ninja (a build system) to parallelize and cache ox-hugo
• My org roam notes workflow [4]
  • ox-hugo based workflow
  • works with org-roam’s sqlite database to generate JSON, which is fed into D3.js for visualisation of the graph.

These reveal the following options for turning org-mode files into websites, some of them general, some of them specifically for wikis, knowledge bases and the like.

• org-publish

  This is org-mode’s built-in publishing functionality, which can convert org files to HTML or PDF. It looks like we would have to build our own theming and org-roam specific behavior around this. This seems like the most low-level but dependency-free approach.

  Neil Mather at doubleloop.net has this to say:

  but I have started to get to the point where I’ve customised it so much, I wonder if it would be better to use something else [1]

• ox-hugo

  org-mode exporter backend for eexporting Org to Markdown that is compatible with Hugo. Supports both one post per file and one post per subtree. Perusing the issue tracker suggests that it handles org-roam fine, including ID links. Has its own front matter, but most of it seems optional.

• Emanote

  Application written in Haskell for creating websites

  such as personal webpage, blog, wiki, Zettelkasten, notebook, knowledge-base, documentation, etc.

  It supports org-mode as input.

• Firn

  Firn is a static site generator for org-mode. It is tailored for wikis, knowledge-bases, simple static sites &tc.

  It is an application, written in Rust. Requires to set up a site with firn new, requires custom front matter in your org files. Does come with built-in support for private notes.

  Firn occupies a space similar to Emanote, has cleaner, more streamlined documentation, but also fewer features.

  Neil Mather ran into several issues when he evaluated Firn, such as excessive disk usage and missing support for id links. [5]

• weblorg

  Pure elisp static page generator. It looked too niche for us to further investigate it.

Our workflow ¶

In the end, we decided to use ox-hugo. org-publish seems too low-level for our needs, and we are already using Hugo elsewhere, which is why we prefer it over one of the other, more special-purpose tools.

To get nice, hyperlinked citations and bibliographies we need to have citeproc installed, and add #+cite_export: csl <path to csl file> to the front matter. Each note also needs an explicit #+print_bibliography: to print the bibliography. All of this isn’t specific to ox-hugo but part of org-mode. We’ve settled for the IEEE style.

TODO backlinks TODO tags + tag pages TODO graph

References ¶