joplin-plugin-tag-navigator 2.7.3 → 2.8.0

package/README.md

@@ -84,7 +84,12 @@ After installing the plugin, check the commands listed under `Tag Navigator` in
 
 ## Tips
 
+### Getting Started
 - [Troubleshooting](#troubleshooting)
+- [Saved queries](#saved-queries)
+- [Keyboard shortcuts](#keyboard-shortcuts)
+
+### Working with Tags
 - [Custom tag definitions](#custom-tag-definitions)
 - [Tag inheritance](#tag-inheritance)
 - [Date tags](#date-tags)
@@ -92,15 +97,17 @@ After installing the plugin, check the commands listed under `Tag Navigator` in
 - [Tag ranges](#tag-ranges)
 - [Tag values](#tag-values)
 - [Front matter tags](#front-matter-tags)
-- [Saved queries](#saved-queries)
+
+### Views & Display
 - [Table views](#table-views)
 - [Kanban views](#kanban-views)
 - [Filtering results](#filtering-results)
 - [Context expansion](#context-expansion)
-- [Inline TODOs](#inline-todos)
 - [Colour tags](#colour-tags)
 - [Styling inline tags](#styling-inline-tags)
-- [Keyboard shortcuts](#keyboard-shortcuts)
+
+### Advanced
+- [Inline TODOs](#inline-todos)
 - [Converting Joplin tags](#converting-joplin-tags)
 
 ### Troubleshooting
@@ -110,12 +117,20 @@ After installing the plugin, check the commands listed under `Tag Navigator` in
 ### Custom tag definitions
 
 - The definition of a "tag" can be adjusted with user-defined regular expressions (see the advanced setting `Tag regex`).
-    - Example: Every word in the text may be defined as a tag using a custom regex such as `[A-Za-z0-9]+[\w]*`.
 - You may also define an exclusion rule to ignore certain tags (see the advanced setting `Exclude regex`).
-    - Example: Numeric (`#123`) or hexanumeric (`#C0FF1E`) tags can be filtered using an exclusion regex such as `#(\d+|[a-fA-F0-9]{6})$`.
+
+<details>
+<summary>Regex examples</summary>
+
+- **Custom tag regex**: Every word in the text may be defined as a tag using a custom regex such as `[A-Za-z0-9]+[\w]*`.
+- **Exclusion regex**: Numeric (`#123`) or hexanumeric (`#C0FF1E`) tags can be filtered using an exclusion regex such as `#(\d+|[a-fA-F0-9]{6})$`.
+
+</details>
 
 ### Tag inheritance
 
+> **TL;DR:** Tags automatically apply to child content via indentation, headings, or note-level inheritance.
+
 - Tag inheritance allows tags to be automatically applied to related content based on document structure, making it easier to organize and find information without manually tagging every line.
 - When the `Tag inheritance` setting is enabled (by default), tags are automatically inherited in three ways:
     1. **Outline/indentation inheritance**: Tags are inherited from parent items to their children based on indentation levels.
@@ -128,6 +143,8 @@ After installing the plugin, check the commands listed under `Tag Navigator` in
 
 ### Date tags
 
+> **TL;DR:** Use `#today`, `#week`, `#month` for dynamic dates. Add arithmetic like `#today+7`.
+
 Date tags provide flexible ways to work with dates in your notes, supporting both relative dates that update automatically and absolute dates that remain fixed.
 
 #### Relative date tags
@@ -176,20 +193,26 @@ Date tags provide flexible ways to work with dates in your notes, supporting bot
 
 ### Tag ranges
 
+> **TL;DR:** Search tag ranges with `#min -> #max`. Use `*` wildcard for prefix/suffix matching.
+
 - Tag ranges can be used to search for a range of tags, according to their lexicographic order.
     - Example: `#2024/07 -> #2024/08` will search for all tags starting with `#2024/07` and up to `#2024/08` (inclusive, i.e., returning two months).
+    - Note: Non-wildcard ranges require both min and max values to avoid unexpected matches across different tag types.
 - You may also use ranges with the `*` wildcard to search for tags starting with a certain prefix or ending with a suffix.
     - Example: `#prefix* ->` will search for all tags starting with `#prefix`.
-    - Example: `*suffix ->` will search for all tags ending with `suffix`.
+    - Example: `-> *suffix` will search for all tags ending with `suffix`.
+    - Wildcard ranges can be open-ended (only min or max specified).
 - Tag ranges can be inserted using the "Tag range" input boxes, or by right-clicking on a tag in the query area, and selecting `Edit query`.
     - Example: Edit a tag or tag range and type `#prefix* ->` to search for all tags starting with `#prefix`.
     - If you type only `#prefix`, the query will be converted to a standard tag search (matching only the tag `#prefix`).
 - Tag ranges can be used to search for tags by today's date.
-    - Example: `#today ->` will search for all tags starting with `#today`.
+    - Example: `#today -> #today+7` will search for all tags from today up to a week from now (inclusive).
     - Example: `#today -> #today+1` will search for all tags starting with `#today` and up to `#today+1` (inclusive, i.e., returning two days).
 
 ### Tag values
 
+> **TL;DR:** Use `#tag=value` to assign values. Unlike nested tags, values don't clutter the tag list.
+
 Tag values are a bit similar to nested tags as multiple parts of the tag are treated separately, but are distinct from them as explained below.
 
 - Nested tags like `#parent/child` are shown as two separate tags in panels: `#parent` and `#parent/child`.
@@ -203,8 +226,13 @@ Tag values are a bit similar to nested tags as multiple parts of the tag are tre
 
 ### Front matter tags
 
+> **TL;DR:** YAML front matter fields are converted to inline tags automatically.
+
 For example, the following YAML front matter, when inserted at the top of the note:
 
+<details>
+<summary>View YAML front matter example</summary>
+
 ```yaml
 ---
 nested: tag with spaces
@@ -227,12 +255,22 @@ will be converted to the following inline tags and values:
 #frontmatter
 ```
 
+</details>
+
 These tags will be accessible in the search panel / notes / tables like standard inline tags. The last tag is `#frontmatter` and is used to indicate that the tags were extracted from the front matter section of the note.
 
 ### Saved queries
 
+> **TL;DR:** Save search configurations as JSON. Press `Save` on the panel, or edit manually. Switch between queries using the dropdown.
+
 Saved queries allow you to store search configurations in notes and reuse them across devices. They are JSON objects that define search parameters and display options. The easiest way to save a query in the current note is to press the `Save` button on the panel (see the [demo](#saved-search-queries)), but they can also be edited manually.
 
+#### Loading saved queries
+
+- A dropdown in the search panel lists all notes containing saved queries, allowing you to quickly switch between them.
+- When you navigate to a note with a saved query, it is automatically loaded into the search panel.
+- To disable automatic loading (for a static panel that only updates via explicit query selection), turn off the setting `Search: Auto-load saved queries from notes`.
+
 #### Basic structure
 
 ```json
@@ -282,6 +320,7 @@ Saved queries allow you to store search configurations in notes and reuse them a
   - `"heading"`: Group by heading
   - `"consecutive"`: Group adjacent lines
   - `"item"`: Split by item
+  - To change the global grouping, right-click on a note title in the search panel. Saved queries can override this with their own `resultGrouping` property.
 - **`includeCols`**: (Table view only) Comma-separated list of columns to display
   - Can include: note properties, tags, "modified", "created" timestamps
   - Use to slice, sort, or add specific columns
@@ -290,6 +329,9 @@ Saved queries allow you to store search configurations in notes and reuse them a
 
 #### Complete example
 
+<details>
+<summary>View complete JSON example</summary>
+
 ```json
 {
   "query": [
@@ -323,6 +365,8 @@ Saved queries allow you to store search configurations in notes and reuse them a
 
 This example searches for paragraphs that have both `#artist` AND `#album` tags, OR paragraphs with `#single` tag, then filters results containing "rock" anywhere in the text, and displays them in a table sorted by year (ascending) then by artist (descending).
 
+</details>
+
 ### Table views
 
 - To enable table view, start by [saving a query](#saved-queries). Next, select `Tools --> Tag Navigator --> Toggle search results display in note` (or the corresponding toolbar button) until the saved query shows the property `"displayInNote": "table"` and a table appears.
@@ -357,6 +401,9 @@ This example searches for paragraphs that have both `#artist` AND `#album` tags,
 ### Filtering results
 
 - Text entered in the results filter (on the panel or in a saved query) can be used to search within title of the notes, their notebook name / path, or the content of the displayed results.
+- Filtering behaviour depends on the result grouping mode (right-click a note title on the panel to change):
+    - **Group by heading** (default): Shows/hides entire sections based on whether they contain matching content.
+    - **Split by item**: Shows/hides individual items, useful for filtering specific tasks like `"- [ ]"`.
 - To gain more control over filtering by notebook, you may enable the setting `Search: Extract the full notebook path`.
     - Example: Limit results to a notebook that appears in the top level by searching for `|/topNotebook`.
     - Example: Search for `topNotebook/childNotebook` to show only results from childNotebook.
@@ -375,12 +422,18 @@ Context expansion lets you reveal surrounding lines around search results to see
 - When fully expanded, click **↓** to collapse back to the original view.
 - The expanded context is dimmed to help distinguish it from the core matched lines.
 - Configure the number of lines revealed per click in the setting `Search: Context expansion (show surrounding lines)`. Set to 0 to disable.
+- **Panel sections**: Show/hide panel sections (search query, tag list, tag range, note mentions, result filter) by right-clicking anywhere on the panel.
 
 ### Inline TODOs
 
-- Filter results by pending tasks (`"- [ ]"`) or ones done (`"- [x]"`).
+- Filter results by pending tasks (`"- [ ]"`) or ones done (`"- [x]"`). For individual task filtering, use "Split by item" grouping (right-click a note title on the panel).
 - Sort results by tags to reflect their priority (see [custom sorting options](#advanced-options)).
-- Add support for [additional tags](https://github.com/CalebJohn/joplin-inline-todo?tab=readme-ov-file#confluence-style) for @mentions, +projects and //due-dates using a custom tag regex such as `(?<=^|\s)([#@+]|\/\/)([^\s#@'",.()\[\]:;\?\\]+)`.
+<details>
+<summary>Custom regex for @mentions, +projects, //due-dates</summary>
+
+- Add support for [additional tags](https://github.com/CalebJohn/joplin-inline-todo?tab=readme-ov-file#metalist-style) for @mentions, +projects and //due-dates using a custom tag regex such as `(?<=^|\s)([#@+]|\/\/)([^\s#@'",.()\[\]:;\?\\]+)`.
+
+</details>
 - Supported additional checkbox styles (inspired by `[x]it!`).
     - Set any of them to done by clicking the checkbox in the search panel.
 
@@ -391,9 +444,14 @@ Context expansion lets you reveal surrounding lines around search results to see
 ![checkbox commands](img/checkboxes-commands.png)
 
 - You may increase the checkbox size on smaller screens by setting `Search: Panel style` with the CSS `.itags-search-checkbox { width: 18px; height: 18px; font-size: 18px }` (adjust as needed).
-- Furthermore, every checkbox in the text (even ones that are not tagged by any inline #tag) may be defined as a tag using a custom regex such as `(?<=^|\s)(#([^\s#'",.()\[\]:;\?\\]+)|(\-\s\[[x\s@\?!~]\]))`.
+<details>
+<summary>Custom regex for treating checkboxes as tags</summary>
+
+- Every checkbox in the text (even ones that are not tagged by any inline #tag) may be defined as a tag using a custom regex such as `(?<=^|\s)(#([^\s#'",.()\[\]:;\?\\]+)|(\-\s\[[x\s@\?!~]\]))`.
     - You may then use queries to search for tag-tasks based on their state (`- [ ]`, `- [x]`, `- [@]`, ...).
 
+</details>
+
 ### Colour tags
 
 - Colour tags can be used to highlight results in the search panel, e.g., according to their priority.
@@ -410,7 +468,10 @@ Context expansion lets you reveal surrounding lines around search results to see
 
 ### Styling inline tags
 
-The Markdown preview pane and the Tag Navigator search panel wrap every matched tag in the class `itags-search-renderedTag` and, when the token starts with `#`, `@`, `+`, `//`, or any other character, add `itags-search-renderedTag--hash`, `--at`, `--plus`, `--slash`, `--<other char>`. You may modify their appearance in `userstyle.css` (for Markdown preview), or in the `Search: Panel style` setting (for the plugin's search panel). For example:
+The Markdown preview pane and the Tag Navigator search panel wrap every matched tag in the class `itags-search-renderedTag` and, when the token starts with `#`, `@`, `+`, `//`, or any other character, add `itags-search-renderedTag--hash`, `--at`, `--plus`, `--slash`, `--<other char>`. You may modify their appearance in `userstyle.css` (for Markdown preview), or in the `Search: Panel style` setting (for the plugin's search panel).
+
+<details>
+<summary>CSS example for tag styling</summary>
 
 ```css
 /* optional: specify different sub-styles for each type of tag */
@@ -431,6 +492,8 @@ The Markdown preview pane and the Tag Navigator search panel wrap every matched
 }
 ```
 
+</details>
+
 For the Markdown editor see Rich Markdown in the [Companion plugins](#companion-plugins) section.
 
 ### Keyboard shortcuts
@@ -482,21 +545,27 @@ For the Markdown editor see Rich Markdown in the [Companion plugins](#companion-
 - The excellent [Inline Tags](https://github.com/roman-r-m/joplin-inline-tags-plugin) plugin can autocomplete tags while typing.
 - Use [YesYouKan](https://github.com/joplin/plugin-yesyoukan) to visualize kanban views generated by Tag Navigator as interactive kanban boards.
 - You can highlight tags in the Markdown editor using [Rich Markdown](https://github.com/CalebJohn/joplin-rich-markdown) (version ≥ 0.14).
-    - In `Joplin settings --> Rich Markdown --> Advanced Settings --> Custom classes JSON` enter:
-    ```
-    [{"name": "rm-tag", "regex": "(?<=^|\\s)#([^\\s#'\",.()\\[\\]:;\\?\\\\]+)"}]
-    ```
-    - In `Joplin settings --> Appearance --> Custom stylesheet for Joplin-wide app styles` add the following to the style sheet:
-    ```
-    div.CodeMirror .cm-rm-tag {
-        background-color: #7698b3;
-        color: white !important;
-        padding: 0em 2px;
-        border-radius: 5px;
-        display: inline;
-    }
-    ```
-    - On the mobile app, since it is impossible to edit the stylesheet, one could install this [Rich Markdown fork](https://github.com/alondmnt/joplin-rich-markdown/releases/tag/v0.15-mobile-style-v4) (with predefined support for tags and checkboxes) or instead define the name of the tag class to be `"name": "searchMatch"`. This will use the same highlighting style as Joplin search results.
+
+<details>
+<summary>Rich Markdown setup instructions</summary>
+
+- In `Joplin settings --> Rich Markdown --> Advanced Settings --> Custom classes JSON` enter:
+```
+[{"name": "rm-tag", "regex": "(?<=^|\\s)#([^\\s#'\",.()\\[\\]:;\\?\\\\]+)"}]
+```
+- In `Joplin settings --> Appearance --> Custom stylesheet for Joplin-wide app styles` add the following to the style sheet:
+```
+div.CodeMirror .cm-rm-tag {
+    background-color: #7698b3;
+    color: white !important;
+    padding: 0em 2px;
+    border-radius: 5px;
+    display: inline;
+}
+```
+- On the mobile app, since it is impossible to edit the stylesheet, one could install this [Rich Markdown fork](https://github.com/alondmnt/joplin-rich-markdown/releases/tag/v0.15-mobile-style-v4) (with predefined support for tags and checkboxes) or instead define the name of the tag class to be `"name": "searchMatch"`. This will use the same highlighting style as Joplin search results.
+
+</details>
 
 ## Motivation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "joplin-plugin-tag-navigator",
-  "version": "2.7.3",
+  "version": "2.8.0",
   "scripts": {
     "dist": "webpack --env joplin-plugin-config=buildMain && webpack --env joplin-plugin-config=buildExtraScripts && webpack --env joplin-plugin-config=createArchive",
     "prepare": "npm run dist",

package/publish/joplin.plugin.alondmnt.tag-navigator.json

@@ -6,7 +6,7 @@
 		"desktop",
 		"mobile"
 	],
-	"version": "2.7.3",
+	"version": "2.8.0",
 	"name": "Inline Tag Navigator",
 	"description": "Type inline tags or frontmatter in the note editor. View your tagged paragraphs and tasks / TODOs in a search panel, or in a generated note / kanban. Build a table view / database from notes and tags. Convert between Obsidian tags and Joplin tags.",
 	"author": "Alon Diament",
@@ -24,6 +24,6 @@
 	],
 	"screenshots": [],
 	"icons": {},
-	"_publish_hash": "sha256:622bf8902bb438f84f5d5646c753109bb593645baa2bc5b6ad643f0533cde7e6",
-	"_publish_commit": "main:c18a6f026f379e4a89661d96672e2c1075ccdcc6"
+	"_publish_hash": "sha256:1d782497553a684a46e1f4d649bab293093cb305a05ad1eae5b0b6e70bf6fe69",
+	"_publish_commit": "main:271b27c93be4c63f0e14ef494b7a806b8161c7c5"
 }