If you’re like me, a user of both Readwise and Obsidian, you know how valuable it is to seamlessly integrate your highlights and notes from Readwise into Obsidian for long-term knowledge management. To make this process efficient and automated, I’ve built a custom export template that formats my Readwise data perfectly for Obsidian vaults.
I want to share the core parts of my configuration that handle file naming, metadata formatting, highlight organization, and front matter YAML - all designed to maximize readability and usability within Obsidian.
Why This Setup Works for Me
By automating these formatting rules, I can quickly import and review Readwise highlights in a clean, consistent way inside Obsidian. It supports my knowledge workflow by making highlights searchable, linkable, and context-rich.
If you’re looking to build a similar export template or workflow, feel free to use this as a base. It’s a blend of practical file naming, markdown structuring, and metadata management that turns your reading highlights into a powerful personal knowledge base.
File Naming Convention
First things first, the filename. A consistent naming scheme is key for organizing hundreds of highlights. My format looks like this:
{% macro slug(s, length) -%}
{{ s
| lower
| replace('#','-')
| replace('*','-')
| replace(':','-')
| replace("and","")
| replace(' ','-')
| replace(' - ','-')
| replace(' -','-')
| replace('- ','-')
| replace('..','')
| replace('.','-')
| replace('"','')
| replace("'","")
| replace('…','-')
| replace('(','')
| replace(')','')
| replace(',','')
| replace('|','')
| replace('/','')
| replace('--','-')
| truncate(length, True, '')
| replace('--','-')
| replace('^-','')
| replace('-$','')
}}
{%- endmacro %}
hl-{{ slug(author, 50) }}-{{ slug(title, 50) }}
Breaking it down:
- Starts with
hl-to denote original highlights while working though the material - Author name is sanitized: lowercase, removing “and”, replacing spaces with dashes, removing ellipses, truncated to 20 characters
- Book or article title is also cleaned and truncated (30 characters max)
This ensures filenames remain readable, unique, and manageable, avoiding problematic characters like quotes or slashes.
Page Title
For each exported highlight page, the title is formatted as:
## {{ full_title }} (Highlights)
This clear header allows me to immediately identify the source material and that the page contains highlights, improving navigation inside Obsidian.
Page Metadata Block
Metadata is essential to provide context without cluttering the note. My export includes:
{% macro slug(s, length) -%}
{{ s
| lower
| replace('#','-')
| replace('*','-')
| replace(':','-')
| replace("and","")
| replace(' ','-')
| replace(' - ','-')
| replace(' -','-')
| replace('- ','-')
| replace('..','')
| replace('.','-')
| replace('"','')
| replace("'","")
| replace('…','-')
| replace('(','')
| replace(')','')
| replace(',','')
| replace('|','')
| replace('/','')
| replace('--','-')
| truncate(length, True, '')
| replace('--','-')
| replace('^-','')
| replace('-$','')
}}
{%- endmacro %}
{% if image_url -%}
Source published date: {{published_date}}
{% endif -%}
{% if url -%}
**Source link:** [{{full_title}}]({{url}})
{% else %}
source: {{source}}
{% endif -%}
<!-- Line brake - br -->
- [ ] **Literature note:** [[{{ slug(author, 50) }}-{{ slug(title, 50) }}]]
If available, the book or article cover image is included, alongside publication date. I also embed the source link when present, or fallback to a source name. This enriches the note and helps later retrieval or citation.
Literature note is made to a checkbox to signify that the highlighted note has been summarized and media source is “consumed” (i.e. listened to, have been read, was watched).
Example:
- Literature note: Has not been “consumed” and summarized in my own words for quick recall and comprehension
- Literature note: Source has been summarized in my own words and has been, to my best ability, written for future recall and quick comprehension.
Highlight Section Headers
To organize highlights clearly, I dynamically include:
{% if is_new_page %}
## Highlights
{% elif has_new_highlights -%}
## New highlights added {{date|date('F j, Y')}} at {{time}}
{% endif -%}
This means on a fresh export, the section is simply titled “Highlights,” but on updates, I can track when new highlights were added - great for incremental review and daily workflows.
Formatting Individual Highlights
Each highlight is formatted with location info or ID:
---
{% if highlight_location == "View Highlight" %}### id{{ highlight_id }}{% elif highlight_location == "View Tweet" %}### id{{ highlight_id }}{% else %}### {{highlight_location}}{% endif %}
{% if highlight_tags %}**Tags:** {{ highlight_tags|join(', ') }} {% endif %}
> [!cite]
> {{ highlight_text }}{% if highlight_location_url %}
> \- [{{ highlight_location }}]({{ highlight_location_url }}) {% elif highlight_location %} > \- {{ highlight_location }}
> {% endif %}
> {% if highlight_note %}
> **Marginalia / Reflection:**
> {{ highlight_note }} {% endif %}
This includes:
- Highlight location or an ID if location is generic
- The highlight text itself in blockquote format for readability
- Optional links to the highlight’s exact location or tweet
- Any personal notes attached, labeled as “Reflection”
This structured formatting makes it easy to visually parse each highlight and reflect on it within Obsidian.
YAML Front Matter
Finally, each file begins with comprehensive YAML front matter metadata:
{% macro fixup(s) -%}
{{ s
| replace('*','')
| replace('--','-')
| replace('^-','')
| replace('-$','')
}}
{%- endmacro %}
aliases: "Highlights of {{author}} - {{fixup(title)}}"
authors: {{author}}
categories:
- highlights
- {{category}}
date: {{date|date("Y-m-d")}}
draft: true
media: {{category}}
source: {{source}}
tags: {% for tag in document_tags %}
- {{tag}} {% endfor %}
title: "Highlights of {{author}} - {{fixup(title)}}"
This front matter enables:
- Author and source tracking
- Categorization and tagging for Obsidian plugins or queries
- Draft status for workflow management
- Standardized titles for note previews