refactor: 💬 update settings text and documentation for consistency

Author: johannrichard

CHANGELOG.md

@@ -1,39 +1,50 @@
 # Changelog
 
-## 2.x.x 
+## 2.0.0 
 
 Version 2.x.x is a major rewrite of the plugin, with a focus on implementing a deduplication logic, more atomic upgrades (keeping existing additional or protected frontmatter intact) and handling of special characters in filenames.
 
 > [!WARNING]  
-> Readwise Mirror 2.0 is a major rewrite of the plugin which might break things due to changes how filenames are generated and validated. If you update without following the steps in the documentation, you might break links to items in your Readwise library.
-> Below is step-by-step guide how you can prepare an existing Readwise library by adding the `uri` tracking property to your items before upgrading to ensure links to items in your Readwise library will be updated after an upgrade.
+>If you update to 2.0.0 without following these steps, you will likely end up with duplicate notes for the same Readwise item or, if you delete the whole Readwise folder in your Obsidian vault first, will likely lose any existing internal links to notes created by the plugin.
+>
+>If you plan to upgrade the plugin from v1.x.x to v2.0.0, and want to make sure any internal links in your Obsidian vault to notes created by the plugin remain intact, then you should ensure all your notes have the file tracking property in their frontmatter before the upgrade.
 
-1. Make sure you have a backup of your vault (or at least your Readwise Mirror folder)
-2. In the plugin settings, add the `uri` tracking property to the Frontmatter template. Just add the following at the end of the template and enable Frontmatter[^1]:
+Below is a step-by-step guide how you can prepare an existing Readwise library by adding the `uri` tracking property to your items before upgrading to ensure links to items in your Readwise library will be updated after an upgrade.
+
+1. Make sure you have a backup of your Obsidian vault (or at least your Readwise mirror folder with the notes created by this plugin).
+2. In the plugin settings in v1.x.x, add the `uri` tracking property (or whatever property key you plan to use for file tracking) to the Frontmatter template. You can replace (recommended) the frontmatter template with the following, and enable Frontmatter[^1]:
 
    ```yaml
+   ---
    uri: {{ highlights_url }}
+   ---
    ```
 
-3. Run **a full sync** to establish proper tracking properties (this will overwrite your local changes, but will preserve the filenames of your existing files according to the way version 1.4.11 of the plugin creates them)
+3. Run **a full sync** to establish proper tracking properties (this will overwrite your local changes based on the current settings for the colon, but it will preserve the filenames of your existing files according to the way v1.4.11 of the plugin creates these. In consequence, all internal links will remain valid).
+
+4. Upgrade the plugin to `2.0.0` and enable file tracking (this will ensure the tracking property will always be added to newly created or updated notes).
+5. Rebuild the frontmatter templates and adjust the filename settings to your liking (you can also reset the templates to their default: simply delete the whole template value).
+6. Run **a full sync** to rebuild all the notes according to the new settings and enjoy the new features of Readwise mirror 2.x.x. 
 
-4. Upgrade the plugin to 2.x.x and enable File Tracking
+Your subsequent syncs will then use the `uri` property to track unique files and ensure links to items in your Readwise library will be updated, even if the note filenames change with the new version of the plugin.
 
-Your subsequent syncs will then use the `uri` property to track unique files and ensure links to items in your Readwise library will be updated, even if the generated filenames change with the new version of the plugin.
+>[!TIP]
+>If you are unsure what the plugin will do to your Obsidian Obsidian vault after the upgrade, we would recommend that you create a copy of the Obsidian vault and run a test upgrade according to the steps described above.
 
 ### Major Changes
 
 - Switched to using Readwise's "export" API, providing access to document summaries and additional metadata (implements #39)
 - Completely rewrote the deduplication logic to handle edge cases like special characters and items with identical titles
-- Implemented consistent use of `normalizedPath()` throughout for better filename handling
-- Added robust frontmatter validation and preservation during updates
-- Introduced file tracking using unique Readwise URLs for reliable deduplication
+- Implemented consistent use of `normalizedPath()` throughout for better filename generation and handling (BREAKING CHANGE)
+- Added robust frontmatter creation, validation and preservation during note creation and updates, resulting in more reliable generation of valid frontmatter (precondition for using frontmatter as reliable basis for file tracking)
+- Introduced file tracking using unique Readwise URLs for reliable deduplication and internal linking in Obsidian
 - Implemented `/api_auth` endpoint for token retrieval, you can now retrieve your token from the plugin settings page
+- Implemented filters for use with Readwise notes
 
 ### New Features
 
 - Added Q&A parsing with new `is_qa` and `qa` nunjucks filters for `.qa` action tags in Readwise  
-- Improved title, author, and frontmatter template handling 
+- Improved title, author, and frontmatter template handling to persistently create valid frontmatter
 - Added slugify option for filenames (implements #27)
 - Implemented `filenamify` for valid filenames with 255 character limit (implements #37)
 - Enhanced documentation and settings UI with template explanations
@@ -44,14 +55,12 @@ Your subsequent syncs will then use the `uri` property to track unique files and
 ### Developer Updates
 
 - Implemented semantic-release workflow using `brianrodri/semantic-release-obsidian-plugin`
-- Added local deploy and release actions
-- Restructured codebase for better modularity
+- Added local deploy and release actions (`npm run deploy:local`))
+- Restructured codebase 
 - Added GitHub workflow for automated releases
-- Moved semantic-release config to separate `.releaserc.yaml`
-- Improved code organization and modularity
 - Separated settings from main class
 
-BREAKING: This is a major rewrite that changes how filenames are generated and validated. Please consult the documentation for migrating existing libraries, particularly regarding the new URL-based tracking system.
+BREAKING CHANGE: This is a major rewrite that changes how filenames are generated and validated. Please consult the documentation for migrating existing libraries, particularly regarding the new URL-based tracking system.
 
 ## 1.4.11 (2023-10-28)
 - UI: Update "Open in Readwise" text to "View Highlight", to better align with official plugin expected behavior

README.md

@@ -560,7 +560,7 @@ Readwise can contain multiple items sharing the same title but with different ID
 ## Upgrading from 1.x.x to 2.x.x
 
 >[!WARNING]
->If you update to 2.x.x without following these steps, you will likely end up with duplicate notes for the same Readwise item or, if you delete the whole Readwise folder in your Obsidian vault first, will likely lose any internal links to notes created by the plugin.
+>If you update to 2.x.x without following these steps, you will likely end up with duplicate notes for the same Readwise item or, if you delete the whole Readwise folder in your Obsidian vault first, will likely lose any existing internal links to notes created by the plugin.
 
 If you plan to upgrade the plugin from v1.x.x to v2.x.x, and want to make sure any internal links in your Obsidian vault to notes created by the plugin remain intact, then you should ensure all your notes have the file tracking property in their frontmatter before the upgrade.
 

src/ui/settings-tab.ts

@@ -741,7 +741,7 @@ export default class ReadwiseMirrorSettingTab extends PluginSettingTab {
         .setClass('indent')
         .setName('Tracking property')
         .setDesc(
-          'Frontmatter property to store the unique Readwise URL (default: uri). This field will be automatically managed in the frontmatter.'
+          'Frontmatter property used to track the unique Readwise URL across syncs (default: uri). This field will be automatically managed in the frontmatter.'
         )
         .addText((text) =>
           text.setValue(this.plugin.settings.trackingProperty).onChange(async (value) => {
@@ -756,7 +756,7 @@ export default class ReadwiseMirrorSettingTab extends PluginSettingTab {
         .setDesc(
           createFragment((fragment) => {
             fragment.appendText(
-              'When enabled, duplicate files will be removed. Otherwise, they will be marked with duplicate: true in frontmatter.'
+              'When enabled, duplicate files with the same Readwise URL in the tracking property will be removed. Otherwise, they will be marked with duplicate: true in frontmatter.'
             );
             fragment.createEl('br');
             fragment.createEl('blockquote', {
@@ -873,7 +873,7 @@ export default class ReadwiseMirrorSettingTab extends PluginSettingTab {
       .setName('Frontmatter settings')
       .setDesc(
         createFragment((fragment) => {
-          fragment.appendText('Controls the YAML metadata at the top of each note.');
+          fragment.appendText('Controls the YAML metadata at the top of each note');
         })
       )
       .setHeading();
@@ -908,8 +908,9 @@ export default class ReadwiseMirrorSettingTab extends PluginSettingTab {
           createFragment((fragment) => {
             fragment.appendText('Update frontmatter when syncing existing files');
             fragment.createEl('br');
+            fragment.createEl('br');
             fragment.appendText(
-              'When enabled, frontmatter of existing files will be updated, keeping additional fields that are not present in the template. Works best with Deduplication enabled.'
+              'When enabled, frontmatter of existing files will be updated, keeping additional fields that are not present in the template. Works best with file tracking enabled.'
             );
           })
         )
@@ -1047,10 +1048,10 @@ export default class ReadwiseMirrorSettingTab extends PluginSettingTab {
               ['tags_nohash', 'Tags without # prefix (compatible with frontmatter)'],
               ['highlight_tags', 'Tags from highlights with # prefix'],
               ['hl_tags_nohash', 'Tags from highlights without # prefix (compatible with frontmatter)'],
-              ['highlights_url', 'Readwise URL (auto-injected if deduplication enabled)'],
+              ['highlights_url', 'Readwise URL (auto-injected if file tracking enabled)'],
               [
                 'Note:',
-                'If deduplication is enabled, the specified property will be automatically added or updated in the frontmatter template.',
+                'If file tracking is enabled, the specified tracking property will be automatically added or updated in the frontmatter template, independent of the frontmatter settings.',
               ],
             ])
           );
@@ -1186,6 +1187,7 @@ export default class ReadwiseMirrorSettingTab extends PluginSettingTab {
         ])
       )
       .addTextArea((text) => {
+        // TODO: Add header template validation resp. preview
         const initialRows = 15;
         text.inputEl.addClass('settings-template-input');
         text.inputEl.rows = initialRows;
@@ -1238,6 +1240,7 @@ export default class ReadwiseMirrorSettingTab extends PluginSettingTab {
         ])
       )
       .addTextArea((text) => {
+        // TODO: Add settings template validation resp. preview
         const initialRows = 12;
         text.inputEl.addClass('settings-template-input');
         text.inputEl.rows = initialRows;