Cleaning up Markdown exports

This article looks at why you might want to be able to export your Roam data to a Markdown app—and how you can do so.

Markdown apps

One of the worries some people have about their Roam data is that they won’t be able to use their backups if they ever decide to move away from Roam. Having some familiarity with Roam alternatives can put your mind at ease. Having a plan B is always a good strategy.

In this section, we zoom in on Roam’s Markdown exports. Once you have a backup strategy in place, you can start to think about what to do with the exports. You may backup just-in-case, or to use your data in other note-taking systems. One Roam alternative that’s particularly popular is Obsidian. We’ll have a look at how Obsidian makes Markdown exports from Roam useful, but other Markdown apps also work with Roam’s Markdown output.

A word on Markdown flavors

It’s important to mention that not all apps use the same type (also called “flavor”) of Markdown. Each app has its own needs and shortcodes, so Markdown formats differ a bit.

For example, the most popular Markdown flavor (Github) uses a single * or _ on each side of a phrase to italicize it. In Roam, you need __ (double underscores) on each side to italicize a phrase.

Because of this, it’s sometimes necessary to clean up the exported files before you can use them in other Markdown apps (although this depends on the app). One popular way to convert large volumes of Roam Markdown to standard Markdown is by using the note-taking app Obsidian (by the creators of Dynalist).

Importing Roam Markdown exports in Obsidian

Let’s have a step-by-step look at how to clean up Roam Markdown in Obsidian.

Preparation: We assume you have already extracted the .zip file with your Markdown files. Depending on your operating system and your Markdown app of choice, this process differs quite a bit.

There is one quirk in the Roam export that you need to be aware of. It organizes certain notes in subdirectories: If you have a / in your note title, the export will create a folder named with the text that comes before the /. So, a note titled “Book/How to Take Smart Notes” is exported as How to Take Smart, which sits in the folder Book:

Keep this in mind when locating your notes.


Step 1: Import Markdown files in Obsidian.

When you open Obsidian for the first time, or click the Obsidian vault icon button in the left menu, you get the following screen with options:

Select the first option (Open folder as vault) and select the folder to where you extracted the Roam files. Obsidian will open a new screen, with all of your notes showing as a list.


Step 2: Clean up Roam Markdown
Now that you have loaded your Markdown files in an Obsidian vault, you need to do a bit of cleanup to account for differences between Roam and Obsidian.

With your Obsidian vault open, click the Obsidian Markdown importer icon button to open the Markdown importer:


Step 3: Select and apply the Markdown fixes

Once the Markdown importer is open, you see a few selectable options. The first three are relevant to clean up Roam imports:

Some Markdown apps support hashtags (#) to create pages, but Obsidian is not one of them. Select the first option.

As we’ve said in the part on Markdown flavors, some apps use a different shortcode syntax. In the case of Obsidian, you’ll want it to convert Roam highlights (^^) to Obsidian highlights (==).

In Obsidian, TODO boxes are formed with the shortcode [ ], so you’ll want to convert your Roam {{[[TODO]]}} shortcodes.

Your settings will now look like this:

Click the Obsidian Markdown importer start conversion button button to start clean up the files in your Obsidian vault. This will overwrite all tags, highlight, and TODO shortcodes in the vault.

If you want to use another Markdown app with your Roam export, you’ll often have to do this cleaning up manually. But, as Obsidian overwrites the files and other apps can read the same directory, you could use Obsidian to clean up the Roam exports and then use another app to continue working with the files.

Empty Markdown files in Roam export

When you export a large Roam database to Markdown and open the files in other Markdown editors, you will encounter many empty notes. This is because every time you create an internal link in Roam, a new page is created. In Roam, this is useful as every page shows its linked references. However, this is not a feature of most Markdown apps.

Unfortunately, there is currently no easy way that we know of to remove empty notes. If you know of a way, please let us know.


Was this helpful?