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:

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

To begin customizing your export, head to the Obsidian Export page from your Readwise Dashboard. 

Each component of the export has a "template" using the Jinja2 templating language. 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 the author's name with double brackets, full title, document category (i.e. 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. For example, if your Daily Note uses the format of YYYY-MM-DD, you could match that format by modifying the filter on the date variable like so: {{date|date('Y-m-d')}}


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 and then 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.


Summary

The {{summary}} variable can be used in the Page Metadata or Properties (YAML Front Matter) sections of the export template. You can use this variable to add the summary of documents highlighted in Reader, which can be entered into a document's data manually or generated by Ghostreader, Reader's AI reading copilot.


Properties (a.k.a. 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 off by default in Obsidian.


File and Folder Names

To edit the format of the exported file names, toggle the "Use Custom File Name" setting to ON from the Obsidian export page. This can be useful if you have a specific way you'd like to organize your files in your Obsidian vault. For example, to prepend the file name with the last name of the document's author, you could use this template:

{% set name = author|trim %}{{name.split(" ")|last}} -- {{ title }}

If "Group Files in Category Folders" is toggled ON, you can customize folder names for each category of document (i.e. Books, Articles, Tweets, and Podcasts).