Guide: Frontmatter management

Readwise Mirror provides powerful tools to manage the frontmatter (also called "properties") of your notes. This allows you to integrate your Readwise library with other plugins and workflows without losing your manual edits during syncs.

All advanced frontmatter features require File Tracking to be enabled.

How Frontmatter Updates Work

The "Update frontmatter" setting controls how the plugin handles existing frontmatter during a sync.

When Enabled (Recommended, default for new installs)

This is the "merge" or "update" mode.

• The plugin will update the values for any fields defined in your frontmatter template.
• Crucially, it will leave any additional fields you've added manually untouched.
• This is the best option for most users, as it protects your work.

Example:

• Your existing note has:

  ---
  status: in-progress
  tags: [readwise]
  uri: ...
  ---

• Your frontmatter template defines tags and author.

• Result after sync: The plugin merges the changes.

  ---
  status: in-progress  # This manual field is kept
  tags: [readwise, books] # This field is updated by the template
  author: "Jane Doe"     # This new field is added by the template
  uri: ...
  ---

When Disabled

This is the "overwrite" mode.

• The plugin will completely delete the existing frontmatter and replace it with the newly generated frontmatter from your template.
• Any manual additions or changes will be permanently lost.
• This is only useful if you want to ensure your frontmatter is always in a pristine, template-controlled state.

---

Frontmatter Protection

Frontmatter protection provides a more granular way to prevent specific fields from being overwritten, even when "Update frontmatter" is enabled. This is perfect for fields that you intend to manage manually after the first sync.

Common Use Cases:

• Protecting an aliases field that you curate by hand.
• Protecting a status field that you use for a project management workflow (e.g., status: to-process).
• Protecting tags if you prefer to manage them in Obsidian rather than Readwise.
• Protecting a connections field that you use to link to other notes (making robust linking from Readwise notes to other notes in your Vault possible).

How to Use Frontmatter Protection

1. Enable "Protect frontmatter fields" in the settings.

2. Enter the names of the fields you want to protect in the text box, one per line. For example:

   aliases
   status
   tags
   

3. On the next sync, the plugin will follow these rules:

   • If a protected field already exists in the note, its value will not be changed, even if the template would normally update it.
   • If a protected field does not exist in the note, the plugin will add it normally based on the template. It will then be protected in all future syncs.

Note

The file tracking key (e.g., uri) is a special field and cannot be protected. It must always be managed by the plugin.

---

Standalone Command: Update All Frontmatter

Command: Update all readwise note frontmatter

This command provides a way to apply changes from your frontmatter template to your entire library without re-syncing the note content.

This is extremely useful when you:

• Decide to add a new metadata field (e.g., date_read) to all your existing notes.
• Want to change the format of an existing field (e.g., change a date format).
• Don't want to wait for a full content sync to update your metadata.

How it Works

• The command scans your vault for notes with a Readwise tracking key.
• For each note found, it fetches the latest metadata from Readwise.
• It then applies your current frontmatter template and protection rules, saving the changes to the file.
• It does not modify note content, filenames, or the "last sync" date.