# Readwise Reading Tracker

Readwise Reading Tracker is an Obsidian plugin for tracking reading progress from Readwise and Reader. It turns your reading activity into an Obsidian-native dashboard with a heatmap, current books, completed books, highlight navigation, and inbox notes created from highlights.

It also supports a Zettelkasten-style workflow: you can quickly review highlight notes, move promising fragments into your inbox, and keep the basic links back to the source book, highlight, and reading context.

![img.png](assets/img/img.png)

## Features

- Sync reading documents from the Readwise API.
- Track reading progress with a daily heatmap.
- Show current and completed books with progress and remaining-time estimates.
- Build reading timelines for regular books, EPUBs, and PDFs.
- Use linked highlight notes generated by the Readwise Official plugin or by this plugin's migration command.
- Create clean inbox notes from highlights with Obsidian Properties for `book`, `source`, `date`, and `created`.
- Keep data local in your vault plugin data.

5. Enable `Readwise Reading Tracker` in Obsidian community plugin settings.
6. Open the plugin settings and configure your Readwise token.

## Manual Installation

1. Download these files from the latest GitHub release:

```text
main.js
manifest.json
styles.css
versions.json
```

2. Create this folder in your vault:

```text
.obsidian/plugins/readwise-reading-tracker/
```

3. Place the downloaded files in that folder.
4. Restart Obsidian.
5. Enable `Readwise Reading Tracker`.

## Setup With The Official Readwise Plugin

Readwise Reading Tracker is designed to work together with the official Readwise Obsidian plugin.

The official plugin exports the source book notes from Readwise/Reader into your vault. This plugin then reads those files, extracts highlight timelines, builds linked highlight notes, shows the reading heatmap, and lets you create inbox notes from individual highlights.

### 1. Install both plugins

Install and enable:

- `Readwise Official`
- `Readwise Reading Tracker`

### 2. Configure the official Readwise export

Open the official Readwise plugin settings or the Readwise Obsidian export page.

Use these export settings:

- Enable `Export All Reader Documents`.
- Enable `Group Files in Category Folders`.
- Map categories you want to track into the same books folder:
  - `books -> Books`
  - `articles -> Books`
  - optional: keep `tweets -> Tweets`, `podcasts -> Podcasts`
- Enable `Use Custom Formatting`.

Use this `Page metadata` template:

```django
---
type: book
source: readwise
title: "{{full_title}}"
{% if author %}author: "{{author}}"{% endif %}
{% if category %}category: "{{category}}"{% endif %}
created: {{date}}
{% if url %}url: "{{url}}"{% endif %}
{% if document_tags %}tags:{% for tag in document_tags %}  - {{tag}}{% endfor %}{% endif %}
---
{% if image_url %}![rw-book-cover]({{image_url}}){% endif %}
```

Use this `Highlights header` template:

```django
{% if is_new_page %}
## Highlights

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

Use this `Highlight` template:

```django
> {{ highlight_text }}
{% if highlight_note %}
>> {{ highlight_note }}{% endif %}

📅 *{{ highlight_date | date('Y-m-d, H:i') }}*
{% if highlight_tags %}🏷 {% for tag in highlight_tags %}[[{{tag}}]] {% endfor %}{% endif %}
{% if highlight_location and highlight_location_url %}🔗 [{{highlight_location}}]({{highlight_location_url}})
{% elif highlight_location %}📍 {{highlight_location}}{% endif %}
---
```

Optional: keep `Full Document Text Link` enabled if you want links to full Reader content. It is not required for the tracker.

### 3. Configure Readwise Reading Tracker folders

In Obsidian, open `Settings -> Readwise Reading Tracker`.

Use the same folders as your official Readwise export:

```text
Readwise books folder: Readwise/Books
Linked highlights folder: Readwise/Highlights
Inbox folder: Inbox/Readwise
```

The tracker reads official book notes from `Readwise/Books`. It writes linked per-highlight notes into `Readwise/Highlights` when you run the migration command.

### 4. Add the Readwise API token

Get your Readwise API token from:

```text
https://readwise.io/access_token
```

Paste the token into `Settings -> Readwise Reading Tracker`, then run `Test Readwise Token`.

### 5. First sync

Run the command:

```text
Readwise Reading Tracker: Sync All (Official + Tracker)
```

This command:

1. Runs the official Readwise sync if the official plugin is installed.
2. Syncs document metadata and reading progress from the Readwise API.
3. Migrates official book-note highlights into linked highlight notes.

After sync, open:

```text
Readwise Reading Tracker: Open Progress Dashboard
Readwise Reading Tracker: Open Readwise Book Highlights
```

If the official Readwise plugin is not installed, you can still run `Sync Readwise Data`, but linked highlight notes require official exported markdown files or a compatible Readwise export.

## Privacy

Readwise Reading Tracker stores your Readwise token locally in Obsidian plugin data. The plugin calls the Readwise API directly from Obsidian and does not send your token, notes, highlights, or reading data to any server controlled by the plugin author.

The plugin may read markdown files from the configured Readwise folders in your vault to infer highlight dates and build reading timelines. It only writes notes when you run commands that explicitly create or migrate notes.

## Troubleshooting

- `Readwise token is not set`: add your token in plugin settings.
- Token test fails: verify the token at `https://readwise.io/access_token` and try again.
- No books appear after sync: confirm your Readwise account has Reader/readwise documents and run sync again.
- PDF or EPUB activity looks approximate: Readwise does not always expose exact daily reading sessions. The plugin uses highlight dates when available and falls back to progress updates when exact dates are unavailable.
- Linked highlights are not found: check that the linked highlights folder matches the folder used by the Readwise Official plugin or run the migration command.
- Console logs are noisy: turn off `Debug Logging` in plugin settings.

## Development

```bash
npm install
npm test
npm run build
npm run release
```

The local release bundle is written to:

```text
release/readwise-reading-tracker/
```

For BRAT and Obsidian releases, publish a GitHub release whose tag exactly matches the version in `manifest.json`, for example `1.0.0`.

## License

MIT