Setting up Readwise for Roam

This article covers how to set up Readwise for Roam. If you want to learn how to use Readwise itself, I recommend you check out Readwise’s knowledge base.

Integrating with Roam

Once you have a few highlights and notes synced from some of the many services Readwise integrates with, it’s time to send things to Roam.

The integration between Readwise and Roam works via a browser plugin. This is because Roam currently has no official API to enter data. But, Readwise’s approach is 100% safe and they don’t have read access to your graph.

Follow the steps below to get started.

Step 1—Export highlights.

From the Connect & Sync button in the top menu, click on the Export Highlights option:

Readwise export highlights button

Step 2—Configure Roam.

On the next page, click the Configure button in the Roam card:

Step 3—Install the plugin.

If you don’t have the Readwise-Roam plugin installed yet, you will see the screen below. Clicking the big blue button that says Connect Roam to Readwise will open either the Firefox or Chrome plugin stores:

Readwise connect Roam button

Install the plugin, and the page should refresh to show you the metadata page.

Metadata best practices

Every time you export from Readwise to Roam, Readwise will create a page for each article and book you’ve highlighted or annotated. Normally, it would be hard to find the pages that were exported, but luckily we can add some additional metadata (literally data about data; i.e. describing what it’s about).

By setting up metadata, you save yourself a lot of time and make finding your highlights easier. In Readwise, you only need to do this once, but it pays to experiment with the format that works best for you.

Out of the box, Readwise has some simple metadata templates set up. But, to get most out of features likes queries and attribute tables, I recommend you use a variation of the templates below.

Page title

The code below may seem complex, but it does three things: it adds the content category to the page title as a namespace, capitalizes the namespace, and adds the title of the highlighted content.

If you’re somewhat familiar with programming, you’ll see that you can do a lot a cool stuff with Readwise metadata using the Jinja templating language, capitalize() being one of them. Here it’s used to capitalize the first character of the category name.


Page metadata

Different from the standard Readwise metadata, I prefer to have all of the metadata in one block. This enables me to use the values in queries, which is not possible if the metadata is in separate blocks (unless you nest them one under another).

The line of code below does the following:

  • Add the metadata attribute
  • Add the author’s name and make it a link
  • Add an external link to the content (if available)
  • Add the category and capitalize it
  • Add a #Readwise NEW tag for easy retrieval and further processing
Metadata:: [[{{author}}]]{% if url %} | [Source]({{url}}){% endif %} | #{{category.capitalize()}} | #[[Readwise NEW]]

Highlights header

When syncing content to Roam, Readwise first checks if it already created a page in your graph for it.

The code below adds a block with the Highlights:: attribute if there’s no page yet, and nests all highlights under that block.

If there’s already a page but there are new highlights, a new block will created with the data and time, and the new highlights are nested under that block.

{% if is_new_page %}
{% elif has_new_highlights %}
New #Highlights added [[{{date}}]] at {{time}}
{% endif %}

Highlight formatting

Not only can we add metadata to pages, we can even add them to individual highlights! First, Readwise picks up any notes we’ve added to the highlights. Next, it’s possible to add tags to your notes. However, Readwise tags work a bit differently, so read up on it.

The bit of code below does the following:

  • Add the highlight text and style it as a blockquote ([[>]])
  • Add the highlight location (if available and enabled in the sync settings)
  • Add the highlight URL (if available and enabled in the sync settings)
  • Add any notes and prepend them with the Note:: attribute
  • Add any tags and prepend them with the Tags:: attribute

With this code, notes and tags are nested underneath the corresponding highlight, making it easier to find in Roam.

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

Sync notification

Any time Readwise syncs new highlights, it will add a notification to the Readwise page within your Roam graph. The code below makes it easier to find the newly added pages by giving a clickable link to the Readwise NEW page, which lists all newly synced pages in its linked references.

On [[{{date}}]] at {{time}} Readwise synced {{num_highlights}} highlight{{num_highlights|pluralize}} from {{num_books}} book{{num_books|pluralize}}. [See them here]([[Readwise NEW]])

Further reading

If you want to dive deeper into what’s possible with Readwise for Roam, have a look at these articles:

Tags: ,

Was this helpful?