How can I customize the Readwise to Obsidian Export?

One of the most powerful features of the Readwise to Obsidian plugin is the ability to customize the formatting of how your highlight data is imported into Obsidian. You can customize a variety of elements including:

  • YAML front matter
  • Page title
  • Metadata (such as author, URL, category, title, cover image)
  • Highlight header (inserted whenever new highlights are added)
  • Highlights themselves (eg inclusion of links to original, tags, notes, etc)
  • Sync notifications (a new entry in Obsidian each time the Readwise plugin

To begin customizing your export, head to the Obsidian Export page from your Readwise Dashboard and toggle on "Use custom formatting". 

At a high level, each component of the export has a "template" using the Jinja2 templating language. As you tweak the template within Readwise, you'll see a live preview of what your notes would look like in Obsidian. 

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


Page Title

By default, Readwise will insert the title of each document as an H1 (# in Markdown) in the default template: 

# {{title}}

Notice the {{title}} variable. As your highlights are exported to Obsidian, Readwise will replace the {{title}} variable with the document's actual title.

Let's say you wanted the first line of your export to be the document's title PLUS the word Highlights in parentheses. All you would have to do is append the text " (Highlights)" to the template as follows:

# {{title}} (Highlights)

You can customize this much more using inline-if statements, Jinja2 filters, and much more. The templating language is quite powerful!


Metadata

One of the nicest aspects of the Readwise plugin is that each document can be enhanced with additional metadata such as author name, document URL, document tags, category, full title, cover image, and more.

The default template below will insert the cover image, if there is one, followed by H2 Metadata, followed by Author name with double brackets, full title, document category (ie Book, Article, or Tweet) with a hashtag, followed by document tags in Readwise, if any.

{% if image_url -%}
![rw-book-cover]({{image_url}})
{% endif -%}<br>
## Metadata
- Author: {% if author %}[[{{author}}]]{% endif %}
- Full Title: {{full_title}}
- Category: #{{category}}
{% if document_tags -%}
- Document Tags: {% for tag in document_tags %}[[{{tag}}]] {% endfor %}
{% endif -%}
{% if url -%}
- URL: {{url}}
{% endif -%}

Below is an example of how you'd modify the category line if you wanted to append an emoji to each category tag:

Category: #{{category}}{{ " 📚" if category == "books"}}{{" 📰" if category == "articles"}}{{" 🐦" if category == "tweets"}}{{" 🎙" if category == "podcasts"}}

Again, this templating language is quite powerful! You go much deeper with the customization using inline-if statements, Jinja2 filters, and more.


Another component of the template is the Header text that appears above each set of synced highlights. The first time a document is exported to Obsidian, the Highlight section will be delineated by an H2 Header. Any new highlights taken in this document will be appended beneath a new H2 header including date and time stamp.

{% if is_new_page %}
## Highlights
{% elif has_new_highlights -%}
## New highlights added {{date|date('F j, Y')}} at {{time}}
{% endif -%}

A common use case in tools for thought such as Roam Research and Obsidian is to backlink the date in this header to your Daily Notes page. To make this work for yourself, you'll need to format the {{date}} variable to match your Daily Notes formatting and then double brackets ([[)) to the template in Readwise.


Highlights

Of course, you can also format the export of the highlights themselves. By default, each highlight is inserted as a bullet (using a dash) followed by a hyperlink to the original highlight followed by sub-bullets for any tags and notes attached to the highlight.

- {{ 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 %}

As mentioned above, there is much more you can do using inline-if statements, Jinja2 filters, and so on.


YAML Front Matter

Many power users of Obsidian use the dataview plugin to accomplish database-like queries from within Obsidian. This requires a special header at the beginning of the Markdown using YAML. By default, this section of the template is off, but if you're a power user of dataview/YAML, you can insert the front matter as desired.


Sync Notifications

Finally, you can configure the Readwise plugin to append an entry to a special file each time the sync runs. This notification is particularly useful in tools such as Roam Research where the backlink appears more front and center in the Daily Note, but is defaulted off in Obsidian.


File and Folder Names

This is not currently supported, but it's on the roadmap.