• TOC {:toc}

Motivation

Around 04/16/2024, after hearing again somewhere on the Internet that [[Roam]] is dead, I decided to try some alternatives, and this time around, I focused on Obsidian.

I would prefer an [[AsciiDoc]] -based system to a [[Markdown]] -based one, but such does not exist...

I am not paranoid about my notes being stored in the cloud, and actually prefer them to be, since it gets me the ability to synchronize them across my devices and also guarantees that I am not going to lose them. Still, I thought that if I set up backup to something like Google Drive, Obsidian could work for me - although I won't be able to use it from my phone unless I pay for Obsidian Sync (which I did eventually, in 2026 :))

One of the advantages of the move: I want to be able to publish my notes easily, in a way that preserves internal links between them (Digital Garden?); [[Roam]] doesn't let me do this, and Obsidian does.

More: I can publish my notes and my blog (currently generated by Jekyll and hosted by GitHub pages) in the same place.

More still: I can host the notes themselves in the same repository as my website and blog! This way, I do not need any separate backup to Google Drive, and everything is kept together, modified together and published together (notes that I do not want published need to be moved out of the repository).

Also, there is something to be said for the ability to edit my notes using tools other than Obsidian - e.g., IntelliJ Idea ;)

Import

To move my notes from [[Roam]], I installed Importer plugin in Obsidian and followed the export/import instructions; results of the import required manual clean-up:

  • outline bullets from Roam got translated into stars at wrong indent level;
  • tags like #jewish-calendar that I had at the start of some Roam notes moved into the YAML frontmatter's tags array;
  • tags like #buy and #learn were converted to page references like [​[buy]] and [​[learn]] so that thy are recognized as links by Obsidian and back-links are available at the appropriate pages;
  • similarly, TODOs were prefixed by [​[TODO]], to facilitate seeing them in the list of back-links; once done, [​[TODO]] becomes a [​[DONE]];
    •   [[TODO]] look into Obsidian plugins that support TODOs
  • code blocks needed touch-up;
  • I used Find Orphaned Files and Broken Links Obsidian plugin to clean up broken links (it found two block references :)).

Setup

In this unified setup:

  • blog posts are, as usual, under _posts;
  • blog post drafts - under _drafts;
  • notes are under notes; in Obsidian Settings | Files and Links:
    • Default location for new notes: In the folder specified below
    • Folder to create new notes in: "notes"
  • daily notes are under days; in Obsidian Settings | Core plugins:
    • Daily notes / New file location: "days"
  • Outliner Obsidian plugin could allegedly help with the Roam-style outlining.

Publishing

[[Obsidian]] sells its own Obsidian Publish, but - although Obsidian Publish and Obsidian Sync together cost less than [[Roam]] - I want to explore other publishing options: I would like to publish my notes using a custom domain, but Obsidian Publish supports custom domains only at CloudFlare or some such; also, my goal is to keep my notes in the same GitHub repository as my blog and publish everything from there on GitHub Pages.

I looked (briefly) at Obsidian digital garden, Quartz and PublishKit, but decided to see first if I can add publish my notes using Jekyll, which I use currently to publish my blog.

GitHub Publisher is an Obsidian plugin which converts [[Obsidian]] document into a form suitable for publication and pushes them into a GitHub repository. Unfortunately, it can not handle the situation where the source documents are kept in the same GitHub repository: "If you use your vault directly in a repository, the upload will corrupt your files! This module is not intended for this type of workflow."

Even if there was a way to keep both the sources of the notes and the result of their conversion to the publishable form in the same repository, just as I rely on Jekyll running on GitHub pages to convert my [[Markdown]] to HTML, and do not check in the results of running [[Jekyll]] locally, I prefer not to check in the notes processed for publication by some Obsidian plugins. For now I am pursuing the approach where all the processing needed for publication is handled by Jekyll (with some plugins and other customization), without relying on any Obsidian plugins. Of course, if it turns out to be impossible to make Jekyll produce the results I want, I may have to reconsider this choice of approach.

It used to be the case that GitHub Pages restricted Jekyll plugins that could be used; since I recently switched to running Jekyll using GitHub Actions workflow (and soon everyone will switch), this is no longer a problem: all Jekyll trickery is available now ;) The question is: how to make Jekyll do what needs to be done?

Setup that I used from 2024 to 2026 is described in [[Jekyll]]; in 2026 I wrote my own [[Site Publisher]] and abandoned Jekyll ;)

Zotero Integration