Dean Sas

This is my opinionated guide on migrating note-taking apps from Roam Research to Obsidian.md. I go through this in three parts, the initial export and import, cleansing the data and some tweaks to make Obsidian a little bit more Roam-like.

I’d also highly recommend reading Denise Todd spelling out some different options in her thorough migration guide.

Initial export & import

1. In Roam press the three dots menu
2. Press Export all
3. Choose Flat markdown and export
4. Unzip the downloaded Roam files
5. Rename the directory something more sensical
6. Start Obsidian and load the directory from the previous step as a vault

Cleanse data

The export from Roam is in Markdown and Markdown is Obsidian’s native format, this means you don’t have to do any clean-up, or can do it on a ad-hoc basis as you go but I wanted to make Obsidian at least feel livable.

This section assumes you’re comfortable with running scripts from the command line and making some minor changes. In places it assumes you’re using a mac.

Depending upon what Roam features you used, then you might need to clean up different items to me but here are the ones I’ve found it useful to automate so far:

• The markdown syntax differs slightly between the two programs
• Roam handles tags differently, they need to be normal links for Obsidian
• There’s a whole bunch of empty files and directories
• Images and attached files are in Roams firebase account, for data ownership reasons I’d rather have them with the data
• Roam uses an unsightly naming scheme for daily notes files

Before getting started, I’d recommend versioning with git to make it easy to undo data cleansing steps and check that they worked as expected. You can always throw away the .git directory once you’re happy.

1. Open the terminal in your vault directory
2. Run git init && git add . && git commit -m 'Initial import'
3. Keep this window around, it’ll be used in other steps

Markdown and tagging

The most egregious markdown issues and the tagging issue can be corrected by using the core Format Converter plugin bundled in Obsidian.

1. Open Obsidian settings
2. Go to Core plugins
3. Find Format converter in the list
4. Close settings
5. Press the Format converter button in the left sidebar
6. Tick all of the Roam Research options and then press Start conversion
7. Once done, go back to the terminal and run git add . && git commit -m 'Run core format converter'

Empty files

The empty files can just be left, but they feel untidy to me and might never be needed. If I do follow a link to an empty file the file will be regenerated by Obsidian, so there’s little to lose.

1. To remove the (possibly numerous) empty files, again in the terminal run find . -size 0 -delete.
2. This is now a good chance to check to see if the export created unwanted folders (a forward slash in a page title will result in a folder). If so tidy up as you see fit
3. Remove any empty directories, in the terminal run find . -type d -empty -delete
4. Review with git diff and then run git add . && git commit -m 'Take out the empties'

Downloading media files

Roam stores images and other attachments on Firebase. So that my notes vault is self-contained I want to store the media with the notes. There’s no telling when Roam might move or remove the files. Simply downloading the files isn’t enough, all of the references to those files also need changing. Thankfully Nicole van der Hoeven has done the hard work of writing a script to download the files to an assets subdirectory and changing all of the references in the notes.

1. Download the python script outside of the vault directory curl https://gist.githubusercontent.com/nicolevanderhoeven/b25c97a8a68ea97e7bdf5ee674fdaec4/raw/5f997442da189df19cd04457e55a13ed6bb81f7b/downloadfirebase.py > ~/Documents/downloadfirebase.py
2. Edit the script to replace /PATH with the fully qualified directory name of your notes vault
3. Run it with python3 downloadfirebase.py
4. Check it with git diff and then run git add . && git commit -m 'Download from Firebase'

If you get complaints about not having python3, install it with brew. If you get complaints about requests, temporarily install it with sudo python3 -m pip install requests and then after running the script, remove it again with sudo python3 -m pip uninstall requests.

For consistency its also worth changing the Default location for new attachments Obsidian setting to use the same assets directory.

Daily files naming

I wanted to use an ISO8601 date, which is the default for Obsidian. Roam is in a weird format.
I adapted a script by pmbauer to automate the change. My adaptation is mac only but can be simply modified to work under linux.

1. Download the script into the top of the vault directory curl https://gist.githubusercontent.com/dsas/46f3364be61bcdddd40febc9772e6012/raw/27388deb5f82e2516918ceecb1e926d05ba7ef6b/convert_daily_notes.sh > convert_daily_notes
2. Update the PREFIX variable if you want to store the daily notes with a prefix or in a certain folder. I used Dailies
3. Install some prereqs: brew install gsed coreutils
4. Run PATH=/usr/local/opt/coreutils/libexec/gnubin:$PAT *,\ 202[01].md | ./convert_daily_note
5. Check it with git diff and then run git add . && git commit -m 'Moved daily files'

Make Obsidian more Roaman

Using Roam has changed the way I take notes forever. I want to keep some of the things it does, that isn’t the same out of the box in Obsidian. Obsidian has tonnes more plugins and I’m sure I’ll get to grips with them later.

Directories

Obsidian exposes files and directories, whereas with Roam everything is stored in a database. Seeing directories and files makes me want to organise my notes frop a top-down perspective. Past experiences working with a directory and file hierarchies show that this doesn’t work for me – I over-organise and end-up in a mess. The only directories I use are assets for attached files, Dailies for daily notes, templates for templates.

Change the sidebar to the Search sidebar and pretend the directory listing doesn’t exist.

Daily notes

I love daily notes. They’re the foundation to my note taking and often a very useful aide to find specific things.

1. Enable the Daily notes core plugin
2. Click the options icon
3. Enable the Open daily note on startup setting
4. Also if you’ve put your daily notes into a directory then set that setting here

Backlinks

1. Ensure the backlinks plugin is enabled
2. Click the options icon
3. Enable the Backlink in document setting