How does the Readwise to Roam export integration work?

To get started with syncing your highlights to Roam Research, select the Roam option from Export Highlights on your Readwise Dashboard.

When you first sync to Roam, Readwise will limit the export to your most recent 10 items (books, articles, and tweets), to give you a feel for how the integration works. The Roam integration has numerous customization options, described below. Once you've confirmed everything is working to your liking, you can then go back and select all of your items for syncing.

Here's what the Readwise to Roam integration looks like by default (using Azlen's CSS theme Zenith):

After the initial setup, Readwise will sync new highlights to Roam automatically, enabling some powerful use cases. For example, each new highlight includes a backlink to your Daily Note of the day they were synced (see above on the left).

How do I reset the integration so I can start over fresh?

If you ever want to "reset" the Readwise integration to Roam and perform a fresh resync, then all you need to do is delete any reference to #Readwise from your database. The easiest way to do this is to:

• Go to the All Pages view in Roam (from your side bar)
• Search for #Readwise
• Select All
• Double check that only pages you want to reset and resync are selected
• Delete

On the next sync attempt, Readwise will detect that the notes were deleted within Roam and run a fresh sync of all of your selected books/articles!

What happens when I take new highlights? Will those automatically sync with Roam?

Yes! Whenever you import a new highlight into Readwise, it will be automatically synced with Roam without you needing to do anything. If the highlight is from a new book, article, or Twitter account, a new page in the Roam database will be made. If the highlight is from an existing book, article, or Twitter account, the highlight will be appended to the bottom of the existing page. Because the Readwise integration is append-only, nothing in Roam will ever be overwritten.

What happens when I update highlights in Readwise? Will those changes automatically sync with Roam? (Or vice versa?)

At the moment, no. The Readwise integration is built on top of Roam prior to a proper API, so it would be very technically challenging to search through existing notes for the right highlight and update that text. We hope to enable updating once the API is released!

Can I customize the default how my notes are formatted in Roam?

Absolutely! See customization section below for how to customize the note's title, metadata, headers, and sync notifications.

Where does the Location link after each Kindle highlight take me?

If you have the Kindle app installed on your desktop, clicking the Location link will launch the Kindle app and jump you to the highlight in the book. More on those links here: Can I jump to a highlight directly in the Kindle app?

Can I rename the title of a book, article, or Twitter page in Roam?

Currently, you can rename a page generated by Readwise, but if you do and then add new highlights to that book/article, the Readwise integration will create a second page using the original title for new highlights. So we recommend not changing the title for now, or only doing so after you're done reading a piece!

How do I change the Roam graph I'm exporting to?

1. Sign out of Roam Research
2. Re-authorize the connection here: https://readwise.io/export/roam/login

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, cover image)
• Highlight header (parent of any new highlights added)
• Highlights themselves (links to original, tags, notes, etc.)
• Sync notification (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, each component of the export customization has a "template" that uses the Jinja2 templating language. You can customize each of these templates to achieve your desired formats in Roam. As you tweak the templates in Readwise, 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. And if you're looking for more metadata examples and explanations, check out this great guide :)

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?)

{{category}}/{{title}}

This would result in something like Book/Atomic Habits.

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!

Page Metadata

From the Roam Preferences page, you can also edit your Roam page metadata, including the author, URL, category, title, image, and 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 document_tags %}Document Tags:: {% for tag in document_tags %}#{{tag}} {% endfor %} {% endif %}
{% 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 document_tags %}Document Tags:: {% for tag in document_tags %}#{{tag}} {% endfor %} {% endif %}
{% if url %}URL:: {{url}}{% endif %}
{% if image_url %}![]({{image_url}}){% endif %}

Highlight Header

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 sub-bullets 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, the header is formatted differently when the highlights are for a newly synced page versus new highlights on a previously synced page.

A common use case 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}}

Highlight Content

Customizing the highlight itself is a little more complex, but can support some insane workflows. Here's the default template:

{{ highlight_text }}
{% if highlight_location and highlight_location_url %} ([{{highlight_location}}]({{highlight_location_url}})){% elif highlight_location %} ({{highlight_location}}){% endif %}
    {% if highlight_tags %}
    **Tags**: {% for tag in highlight_tags %}#[[{{tag}}]] {% endfor %}
    {% endif %}
    {% if highlight_note %}
    **Note**: {{ highlight_note }}
    {% endif %}

Note the indentation above. The highlight text is shown at the top level, with the location information (e.g. page number, link back to article/tweet, etc.) inline with it. Nested under the highlight text are any notes and tags attached to that highlight, if they exist.

Why might you want to customize the highlight text? For one, maybe you'd just like to tweak the default formatting, e.g. putting notes inline or at the parent level.

Here's an example of how you can embed saved tweets directly into Roam, rather than having just their text sync:

{% if category == "tweets" %}{{ highlight_location_url }}{% else %}{{ highlight_text }}{% if highlight_location and highlight_location_url %} ([{{highlight_location}}]({{highlight_location_url}})){% elif highlight_location %} ({{highlight_location}}){% endif %}{% endif%}
    {% if highlight_tags %}
    **Tags**: {% for tag in highlight_tags %}#[[{{tag}}]] {% endfor %}
    {% endif %}
    {% if highlight_note %}
    **Note**: {{ highlight_note }}
    {% endif %}

You might also want to enable a more complex workflow, like having all of your highlights synced to the same page, regardless of books. Here's how you might do that:

{{ highlight_text }}
{% if highlight_location and highlight_location_url %} ([{{highlight_location}}]({{highlight_location_url}})){% elif highlight_location %} ({{highlight_location}}){% endif %}
    Category: [[{{ category }}]]
    Title: [[{{title}}]]
    Author: [[{{author}}]]
    {% if highlight_tags %}
    **Tags**: {% for tag in highlight_tags %}#[[{{tag}}]] {% endfor %}
    {% endif %}
    {% if highlight_note %}
    **Note**: {{ highlight_note }}
    {% endif %}

In this case, you would also change the Page Title template to something like:

{{ "Readwise Highlights" }}

(Note that because this example uses no variables, all highlights will have the same page title and thus write to the same page.)

There is, of course, much more you can do with this.

Sync Notification

Finally, every time Readwise syncs new highlights you've made into your Roam account, it appends a message into your #Readwise page in Roam to notify you of the updates. This links to your daily note as well, so you can see all 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 makes the note read more naturally. 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 sync notifications.