How can I customize the Readwise to Roam Export?

One of the most powerful features of the Readwise to Roam integration is the ability to customize the formatting of exactly how you'd like your data imported into Roam.

You can customize the formatting of your notes':

  • Page Title
  • Metadata (such as author, url, category, title, image)
  • Highlight header (parent of your new highlights added)
  • Sync notification (that shows up in the #Readwise page, letting you know of new highlights from your daily

You can customize your export by going to the Roam Export Preferences page and toggling on "Use custom formatting". 

At a high level, the way the customization works is that each section of the export has a "template". You can customize each template string to format exactly how you like in Roam. The template uses the Jinja2 templating language. As you tweak the templates, you'll be able to see a live preview of what your notes will look like in Roam. 

The explanations below should illustrate how customization works, and give some useful examples:

Customizing Page Title

By default, Readwise will append "(highlights)" to each page so you can differentiate a Readwise created page from your own. Here's the default template:

{{ title }} (highlights)

Notice the {{ title }} variable. When a note comes into Roam, that {{ title }} will be replaced with the book/article/tweet's actual title.

You also have some other variables available to you. For example, here's how you can prepend each title with the category (i.e is this a book, article, or tweet?)


If you want all of your Readwise highlights to just show up in one page (though we don't recommend this), you could set the template to a non-variable string such as this:

{{"All Highlights"}}

Of course, you can customize the title significantly further, using inline-if statements, Jinja2 filters, and much more. The templating language is quite powerful!

Important note: please do not include [[references]] in your title template, as a currently outstanding bug with Roam JSON import may cause your sync to break entirely.

Customizing Page metadata

From the Roam Preferences page, you can also edit your Roam page metadata, such as author, url, category, title, image, as well as anything else you want to show up when each new book/article/tweet is imported.

Here's the default template:

Author:: [[{{author}}]]
Full Title:: {{full_title}}
Category:: #{{category}}
{% if url %}URL:: {{url}}{% endif %}
{% if image_url %}![]({{image_url}}){% endif %}

Here's an example of some modifications you can make to, e.g, create a TODO for each new highlight, add custom backlinks, and customize formatting based on the category of book/article/tweet.

{% if category == "tweets" %}
#twitter 🐦
{% elif category == "books" %}
{{"{{"}}[[TODO]]{{"}}"}} #toprocess process & summarize the highlights from this book
{% else %}
This is a podcast/article
{% endif %}

Author:: [[{{author}}]]
Full Title:: {{full_title}}
Category:: #{{category}}{{ " 📚" if category == "books"}}{{" 📰" if category == "articles"}}{{" 🐦" if category == "tweets"}}{{" 🎙" if category == "podcasts"}}
{% if url %}URL:: {{url}}{% endif %} 
{% if image_url %}![]({{image_url}}){% endif %}

You can customize how the Header text above each set of synced highlights is formatted. By default, each time your highlights are synced they will be subullets of this default header:

{% if is_new_page %}
Highlights first synced by #Readwise [[{{date}}]]
{% elif has_new_highlights %}
New highlights added [[{{date}}]] at {{time}}
{% endif %}

Note the if statement used above. By default we format the header differently for when the highlights are for a newly synced page, or if they are new highlights on a previously synced page.

A common usecase may be that you don't want the highlights backlinked to the date (the day they are synced). If that's the case, you can simply remove the [[]] wrapping the date, e.g:

Highlights synced by #Readwise: {{date}} at {{time}}

Customizing the Sync Notification

Finally, every time Readwise syncs new highlights you've made into your Roam account, it appends a little message into your #Readwise page in Roam, notifying you of them. This links to your daily note as well, so that you can see all of the highlights you made in one day. Here's the default template:

On [[{{date}}]] at {{time}} Readwise synced {{num_highlights}} highlight{{num_highlights|pluralize}} from {{num_books}} book{{num_books|pluralize}}.

Note the use of the pluralize filter from Jinja2, which can be useful. In the case that you don't want these notifications in your daily note, you can simply unlink the date reference like so:

On {{date}} at {{time}} Readwise synced {{num_highlights}} highlight{{num_highlights|pluralize}} from {{num_books}} book{{num_books|pluralize}}.

If you don't want these sync notifications at all, you can delete the entire template for your sync notifications.