Guide: File tracking and naming

This guide explains how Readwise Mirror tracks and names your note files. Properly configuring these settings is the most important step to ensure a stable and predictable Readwise library in Obsidian. These settings enable advanced features like single-note updates, Readwise library-wide frontmatter updates, or the possibility to deduplicate Readwise notes, and deal with name collisions for Readwise items that share the same title. They can also be used to ensure all your Readwise notes following the same file name scheme, even if you change them.

File tracking and naming settings are found in the settings tab with the same name and consist of three sections:

• File tracking
• File name update on sync
• Filename customizations

What is File tracking?

Important

Due to legacy reasons, File tracking is currently disabled on default. It is however highly recommended that you enable File tracking immediately after installing the plugin.

File tracking is the mechanism the plugin uses to uniquely identify each item from your Readwise library. When enabled, the plugin embeds a unique Readwise URL (highlights_url) into each note's frontmatter under a dedicated (customisable) frontmatter property name. As this URL is unique to each Readwise item, it can be used to link a note in Obsidian back to Readwise.

Warning

Without precautions and a manual migration process, file tracking and links back to Readwise will break if you change the tracking property name after your Readwise library has been synced at least once. Please consult the section on changing the tracking property below if you wish to change it anyway.

Why is File tracking essential?

There are a number of reasons why File tracking is an essential feature of the Readwise mirror plugin:

1. Enables Advanced Features: Powerful features like Frontmatter protection, the "Update current note" and the "Update all frontmatter" commands depend on file tracking to work correctly.
2. Prevents Duplicates: If you change an article's title in Readwise, the plugin will still find the corresponding note in the Obsidian Vault and update it instead of creating a new Obsidian note with a different name.
3. Maintains Internal Links: If the respective setting is turned on, the plugin can also update the File name on sync while keeping the link to Readwise.
4. Future uses: Combining reliable links from notes into Readwise could be used for future uses. For example, the plugin could be extended to update certain metadata like author, title, tags, or even the category of an item in Readwise when the corresponding property in a Readwise note on your Obsidian vault changes.

Important

The tracking field will automatically be added to a note's frontmatter, independent of the "Frontmatter" settings. File tracking currently works across your entire vault. If you move a tracked note out of the Readwise library folder, the plugin will still find and overwrite it during the next sync. To stop a note from being tracked, you must manually remove the tracking property (e.g., uri) from its frontmatter. It is planned to change this such that only notes within the Readwise library folder are considered.

---

File tracking settings

• Enable file tracking: Enabling this setting allows the plugin to link synced notes with the Readwise item in your Readwise account (https://readwise.io). Highly recommended and necessary for advanced features (Default: off).
  • Tracking property: The plugin uses a frontmatter key:value pair (also called property) to keep track of the notes Readwise item. It also serves as a handy way to directly open the Readwise item on https://readwise.io. Normally there is no need to change this setting unless you want to use the default property name for another purpose in your vault (Default: uri).
  • Track across vault: If enabled, the plugin will try to find synced Readwise notes across your vault. This allos you to move notes out of the Readwise library folder defined under General settings and still keep them updated there (Default: off).
  • Remove duplicate files: In case multiple notes linking to the same Readwise item exist, the plugin will mark them with a property duplicate: true. If you enable this setting, the plugin will delete all but one notes instead. Use with care (Default: off).

Once File tracking is enabled, an additional setting to enable updates to notes' file names and two additional commands become available to the user.

• Update current note: Update the currently selected note based on the Readwise tracking property. Pro tip: You can use this command to quickly test how changes to templates or the file name properties (see below) will impact your notes before you go and rebuild your entire Readwise Library in your vault.
• Update all readwise note frontmatter: Scan all notes in your Readwise library folder and update their frontmatter according to your current frontmatter template and protection settings, without changing the note content or filename. This is useful after changing your frontmatter template or protection settings.

Warning

If you enable tracking across your vault, move notes, and then disable tracking across the vault again, you will end up with a new Readwise note being created in your Readwise library. The plugin will only look for tracked notes in the Readwise library and since it won't find (existing, but moved) notes there, it will recreate them in their corresponding category folder.

Update file names on sync

When the File name updates toggle is on, the plugin will update a note's file name to the current filename settings (below) as soon as a specific note is synced/updated in Obsidian:

• When you download the full library with Download entire Readwise library (force)
• When you run Sync new highlights and the note is included in the update
• When you run the Update current note

Otherwise, the filename of a note will remain stable across syncs, even if you change the settings related to filenames. Keeping this off might be of relevance if your workflow requires stable file names in your Obsidian vault.

File name updates can be customized quite extensively with the following additional settings (explained in detail below):

• Use custom filename templates: Use a filename template to define the file name of a note based on the same fields and variables available in the Frontmatter and Heading templates. This is very powerful and can be used for different use cases (Default: off).
  • Filename template: Your filename template. (Default: {{title}})
• Colon replacement in filenames: What character to use instead of the ":" (colon) character in filenames (Default: -).
• Use slugify for filenames: An URL slug is the part of a web address that identifies a specific page, typically found at the end of the URL. By enabling this setting, the plugin will create a "slug" for each synced note (Default: off).
  • Slugify separator: what character to use between words in the slug (Default: -).
  • Slugify lowercase: whether to convert all slugs to lowercase (Default: off).

Tip

If you enable custom filenames, an good way to test this is to use the "Update current note" command with a Readwise note. This way, you can validate the result of your filename template before updating your whole library.

Enabling this setting also enables the following command in Obsidian:

• Adjust Filenames to current settings: Clean up filenames of existing notes in your Readwise library folder based on current filename settings (whitespace removal and slugify only for the time being)

This setting requires file tracking to be enabled.

Customizing Filenames

When File name update on sync is enabled, you can further define a custom filename template using Nunjucks variables. The filename will be sanitized, and illegal characters will be removed.

Basic Template Variables

You can use most of the Document Variables in your template. The most common are:

Variable	Description
{{ title }}	The title of the document.
{{ author }}	The author's name.
{{ id }}	The unique Readwise ID for the item.
{{ category }}	The category (e.g., books, articles).

Example Filename Templates

• Default (Title only):

  {{ title }}

  Result: The Psychology of Money.md

• Title and Author:

  {{ title }} - {{ author }}

  Result: The Psychology of Money - Morgan Housel.md

• Unique ID with Timestamp:

  {{ created | date("YYYYMMDD") }}-{{ title }}

  Result: 20230115-The Psychology of Money.md

Important

To avoid creating duplicates, enable file tracking and run a full sync before you change your filename template.

Slugify Filenames

This option converts filenames into a URL-friendly format by replacing spaces and special characters.

• Example: My Book: An Awesome Title
• Becomes: my-book-an-awesome-title

You can customize the separator character (default is -) and choose whether to convert the entire filename to lowercase.

Colon Replacement

Since colons (:) are not allowed in filenames on most operating systems, the plugin allows you to specify a replacement character.

• Example Title: My Book: A Great Story
• With ⁝ as the replacement: My Book⁝ A Great Story.md

---

Processing Logic Explained

As outlined above, a number of factors define how the filename of a note created from a Readwise item is computed. One key element is that the plugin's behavior changes depending on whether file tracking is enabled.

With File Tracking (Recommended)

1. Existing files with a matching highlights_url:

   • The plugin finds the note with the matching URL, no matter its current filename or location, and updates its content and frontmatter.

2. Filename collision (different highlights_url but same desired filename):

   • If two different Readwise items would result in the same filename (e.g., two articles with the same title), the plugin creates the first note with the normal filename and appends a unique hash to the second filename to prevent it from overwriting the first.
   • Example: My Article.md and My Article-a1b2c3d.md.

Without File Tracking

• The plugin relies solely on matching filenames. If you change a title in Readwise, the plugin will see it as a completely new item and create a new file, resulting in duplicates.
• This mode is not recommended and should only be used if you have a specific reason to avoid adding tracking keys to your frontmatter.

For tracked files (file tracking enabled)

1. Existing files with matching highlights_url

   📄 "My Article.md" (primary, matching highlights_url)
   └── Updates content and frontmatter
   📄 "Same Article.md" (duplicate, matching highlights_url)
   └── Either deleted or marked as duplicate: true

2. Filename collision (different highlights_url but same filename)

   📄 "My Article.md" (existing file)
   📄 "My Article <hash>.md" (new file)
   └── Creates new file with hash suffix

For untracked files (file tracking Disabled)

When multiple files share the same path:

📄 "My Article.md" (first file)
📄 "My Article <hash1>.md" (second file)
📄 "My Article <hash2>.md" (third file)
└── First file keeps original name, others get unique hashes added to it.

Changing the name of the tracking property

Although not recommended, it is possible to change the tracking property from one name to another. Proceed as follows if you change your mind about the (default) name of the tracking property:

1. Backup your Vault

2. Optional but highly recommended: Install the "Linter" plugin in Obsidian and run "Lint" on the "Readwise library" folder in your Vault. This will help identify all notes which have invalid frontmatter / properties. Fix those errors.

3. Only needed of not enabled already: Enable frontmatter in the Readwise mirror settings

4. Add the desired new property name / value pair as a separate line in the Frontmatter template (The new property name is rwid in our example. The value after the colon must always be {{ highlights_url }}):

   ---
   rwid: {{ highlights_url }}
   ---

5. Run "Update current note" with a note to verify that the new tracking property is properly added and that the old property is kept. In our example, our note would have both uri and rwid with identical values in its frontmatter. If not, any further steps risk messing up with your Readwise library.

6. Run "Update all readwise note frontmatter" on your Vault to update all notes in your Readwise library with the new property (Do some tests, possibly run Lint again)

7. Change the tracking property under the „File tracking and naming“ settings tab of the Readwise plugin to the new name (in our example from uri rwid), and remove the line from the frontmatter template which you added under step 2.

8. Optionally: run "Update all readwise note frontmatter" to remove the old property or remove it via another means (Linter can also remove individual frontmatter fields)