How to Feed Your Roam Graph Using Readwise (Complete Guide)

Readwise makes it easy to revisit and learn from your ebook & article highlights. This article teaches you how to get everything to Roam, fast.

Readwise is a service that helps you extract highlights and notes from many apps. It allows you to integrate with many popular ebook platforms and read-it-later apps, making it easy to collect all of your notes and highlights in one bucket. Best of all: Readwise connects to Roam.

The list of services that Readwise can pull from is astonishing:

Amazon Kindle
Apple Books
Google Play Books
Instapaper
Pocket
Medium
Feedly
Hypothes.is
Goodreads
Twitter
Airr Podcasts
OCR (via mobile app)
PDF
Email
Freeform input

What Readwise does, is periodically connecting to your connected services, pulling all of your saved snippets, and organize them automatically. You can then edit the highlights as you please, add notes, and turn them into flashcards when you want to memorize parts of the books and articles you’ve read.

Exporting to Roam is easy, and Readwise allows you to format your metadata any way you want. If you don’t have a Readwise account yet, you can test out all of its functionality for two months, for free. Use this link to sign up.*

_{* I don’t receive an affiliate commission, but you get two months trial instead of one.}

How to set up Readwise for Roam

This part 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.

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:

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:

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:

{{category.capitalize()[:-1]}}/{{title}}

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 %}
Highlights::
{% 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]])

How to make smart highlights for Readwise

Why do you highlight? What is it that sparked your attention that makes this snippet of text—someone else’s words—worth saving?

If you’re like me, you often highlight more than you should. But, you shouldn’t be careless about saving ideas from books. If you highlight everything you highlight nothing; your attention is pulled in all directions.

Only save the part that gives enough context. Even better, write a note that explains why this resonates with you; take care of your future self by making the insight understandable in the future.

In this article, I’ll show you an approach to saving digital highlights that are useful, have the right amount of context without fluff, and are easy to resurface.

What is highlighting?

This may seem silly, but I’d like to start with definitions.

When I talk about a highlight, I mean an (almost) exact copy of text from some written source. A highlight is a piece of text that someone else has written that you find useful for any reason.

Many apps and services that have a highlighting feature, also have an option to add notes to individual highlights and export these as a complete set. Readwise integrates with many of these apps, enabling us to quickly extract highlights and our notes from a variety of sources.

Paper versus digital highlighting

If you went to college before tablets became a thing, you probably learned to highlight in paper books. While still tricky to do right, paper highlights always have one major advantage: context.

No matter how much or little you highlights in a paper book, you always have direct access to the context. Not so with digital highlights.

Most highlights in apps are extracted and saved in other apps. That’s often the reason to highlight digitally in the first place; to have easy access to your highlights and work with them. Unfortunately, the different reading apps and services don’t offer great integrations, making it difficult to extract highlights while having easy access to their original context.

To make up for the lack of context, digital highlights need to be longer to encapsulate the context within the highlight itself. But with longer highlights, how do we make sure they’re still to-the-point?

A first step is to summarize the key point you want to remember in a note attached to the highlight. But, there’s also a way to cut out the fluff in the highlights themselves; with Readwise’s tags.

Readwise’s tagging system

All of the notes we add to our highlights can be read by Readwise. This comes in handy when we’ve extracted our highlights and need some additional context, which we can provide in the note.

However, Readwise also has a tagging system. Any time it finds a note with a word that starts with a dot (.), it recognizes that word as a tag. So whereas in Roam you’d use a hashtag (#) like in #question or #idea, for Readwise you use .question or .idea (or .q and .i, and have Readwise turn them into full-length tags). When you export your highlights and notes to Roam, Readwise automatically turns the tags into Roam-compatible hashtags.

Apart from creating your own tags to categorize your highlights and notes, there is also a special class of tags that Readwise offers: actions tags.

An action tag isn’t stored as a piece of metadata in your notes. Instead, you use them to instruct Readwise to do something specific, like turning a highlight into a header or stitching several highlights together.

Let’s have a look at both of these action tags.

Headings

The first tool to add context to your highlights is by showing where they are in the book’s structure. To do this, you can turn highlights into headings—with a maximum of three levels (.h1, .h2, .h3).

Any highlight you tag as a heading won’t show up during reviews/Readwise’s daily emails, but the structure will show up in the Readwise (web) app and in your exports to Roam:

*An example of a structure created with Readwise’s `.h1` and `.h2` tags.*

Concatenation

Conca… what? Concatenation! Or in simple terms: connecting things. In our case we’re connecting highlights and combining them into one.

How often do you encounter a paragraph with a bunch of fluff sandwiched between useful bits? Maybe you want the first sentence and the last, but not anything that’s in between. That’s where Readwise’s concatenation tags come in handy.

To string together highlights, you add the .c tag to a highlight as a note, followed by an increasing number. So, you start out by highlighting and add .c1 as a note to that highlight. What tag do you use for the next highlight you want to glue to .c1? I hope you guessed .c2! Want to add another snippet to the highlight? No problem, highlight something else and add a note with the .c3 tag.

Here’s an example where I string together two highlights:

What will be the resulting highlight? See below for the answer.

…

“think in terms of your future self. … Verbose highlights are painful to review, take too long to reread, and contain extraneous content obscuring the big idea you originally wanted to capture.”

That’s some pretty magical stuff. Finally a way to cut out the fluff!

To create a new concatenated highlight, tag a highlight with .c1 to start a new snippet, adding subsequent highlights to it by using .c2, .c3, .c4, etc. Just make sure you don’t skip numbers or use two of the same number in a row; you might end up with a broken-up snippet after all.

You don’t need to use the concatenation tag, although it does allow for you to create to-the-point highlights. Try to strike a balance; any highlight that is clear on its own can be left untouched, even if it’s a bit “fluffy.” Often a short note summarizing the key point is better than hacking together highlights based on someone else’s words.

Get more out of your highlights

In this guide, we’ve looked at setting up Readwise metadata for Roam and how to structure your highlights so they make sense out of context. However, that’s only to feed your Roam database.

Is there a way to fine-tune your highlighting process and benefit your future selves?

Apart from combining short highlights into a coherent whole and turning others into headings, you could consider adding metadata tags (also starting with a dot). Or, write your notes and already link to keywords using [[brackets]].

By already creating links while taking notes, it’ll be easier to find your way back to them. In Roam, links are simply entry points to blocks, so think in what context you’d want your future self to stumble upon the note and tag or link it accordingly.

Videos to learn more

#Automation #Tutorials