Merge pull request #3569 from obsidian-tasks-group/docs-for-outlinks

docs: Initial documentation for Links feature

Author: claremacrae

docs/Getting Started/About Getting Started.md

@@ -45,6 +45,8 @@ publish: true
   - Then adjust your searches, perhaps to see tasks that are [[Filters#Blocking Tasks|blocking others]], or hide ones that are [[Filters#Blocked Tasks|blocked]] and cannot yet be done.
 - [[Obsidian Properties]]
   - Learn how to use data in Obsidian [Properties](https://help.obsidian.md/Editing+and+formatting/Properties) in your queries, for example to only search tasks in Kanban plugin files.
+- [[Links]]
+  - Learn how to search for tasks based upon [Links between notes](https://help.obsidian.md/link-notes).
 
 ## Easy editing of tasks
 

docs/Getting Started/Links.md

@@ -0,0 +1,64 @@
+---
+publish: true
+---
+
+# Links
+
+> [!released]
+> Use of Links in searches was introduced in Tasks X.Y.Z.
+
+> [!Tip]
+> This documentation was written a little more quickly than usual, because to the need to release a fix for a bug in iOS and iPadOS versions [18.6](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/3546) and [26 Public Beta 2](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/3560).
+>
+> We plan to refine this page, based on user feedback after its initial release.
+
+## How does Tasks treat Links?
+
+You might want to start with the [[#Links Query Examples|examples below]] for an idea of *what* Tasks can do with Links.
+
+This section describes the *how*...
+
+- Links can be used in Tasks searches with the following instructions:
+  - `filter by function`
+  - `sort by function`
+  - `group by function`
+- Links recognises these styles on links in your notes:
+  - `[[filename|optional alias]]`
+  - `[alias](filename.md)`
+  - Headings and nested headings in the links are also supported.
+
+The following values are available:
+
+| Value                             | Return Type | Notes                                                                                                                                                 |
+| --------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`task`**                        |             |                                                                                                                                                       |
+| `task.outlinks`                   | `Link[]`    | Returns a list of links in the task's line.<br>It does not contain links in any nested tasks or list items.                                           |
+| `task.file.outlinksInProperties`  | `Link[]`    | Returns all the links in the task file's [[Obsidian Properties]].                                                                                     |
+| `task.file.outlinksInBody`        | `Link[]`    | Returns all the links in the body of the note containing the task.<br>Naturally, this includes any links on the task line itself.                     |
+| `task.file.outlinks`              | `Link[]`    | Returns all the links anywhere in the task's file.<br>It contains all the links in `task.file.outlinksInProperties` and `task.file.outlinksInBody`.   |
+| **`query`**                       |             |                                                                                                                                                       |
+| `query.file.outlinksInProperties` | `Link[]`    | Returns all the links in the query file's [[Obsidian Properties]].                                                                                    |
+| `query.file.outlinksInBody`       | `Link[]`    | Returns all the links in the body of the note containing the query.                                                                                   |
+| `query.file.outlinks`             | `Link[]`    | Returns all the links anywhere in the query's file.<br>It contains all the links in `query.file.outlinksInProperties` and `query.file.outlinksInBody` |
+
+The return values are all arrays of `Link` objects.
+
+## Link class
+
+> [!NOTE] Documentation coming soon
+> Documentation coming soon. In the meantime, you can see the comments in [Link.ts](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/src/Task/Link.ts) on GitHub.
+
+## Links Query Examples
+
+> [!NOTE] Documentation coming soon
+> In the meantime, you can see some examples in [Accessing Links](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/resources/sample_vaults/Tasks-Demo/How%20To/Access%20links.md) on GitHub.
+
+## Limitations of Links Handling and Searches
+
+- Currently, searching of links is only possible via [[About Scripting|custom searches]].
+- Tasks does not yet treat [Embeds](https://help.obsidian.md/embeds) as links. This will be fixed soon.
+- Tasks does not yet provide an `inlinks` concept, that is, links *to* a particular file.
+- `Link.destinationPath` is calculated when the file containing the task is read.
+  - This will either have been during Obsidian startup, or when the file was last modified during the current session.
+  - For performance reasons, if files are moved to different folders during an Obsidian session, any tasks that link to the moved files are not updated.
+  - The workaround is to run the built-in `Reload app without saving` command.

docs/Quick Reference.md

@@ -50,6 +50,7 @@ This table summarizes the filters and other options available inside a `tasks` b
 | **[[Filters#Description\|Description]]**, **[[Filters#Tags\|Tags]]** and other odds and ends                                                                                                                                                                                                                                                         |                                             |                        |                        |                                                                                                                                                                          |
 | `description (includes, does not include) <string>`<br>`description (regex matches, regex does not match) /regex/i`                                                                                                                                                                                                                                  | `sort by description`                       |                        |                        | `task.description`<br>`task.descriptionWithoutTags`                                                                                                                      |
 | `has tags`<br>`no tags`<br>`tag (includes, does not include) <tag>`<br>`tags (include, do not include) <tag>`<br>`tag (regex matches, regex does not match) /regex/i`<br>`tags (regex matches, regex does not match) /regex/i`                                                                                                                       | `sort by tag`<br>`sort by tag <tag_number>` | `group by tags`        | `hide tags`            | `task.tags`                                                                                                                                                              |
+| **[[Links]]**                                                                                                                                                                                                                                                                                                                                        |                                             |                        |                        | `task.outlinks`<br>`task.file.outlinks`<br>`task.file.outlinksInBody`<br>`task.file.outlinksInProperties`                                                                |
 |                                                                                                                                                                                                                                                                                                                                                      |                                             |                        | `show tree`            |                                                                                                                                                                          |
 |                                                                                                                                                                                                                                                                                                                                                      |                                             |                        |                        | `task.originalMarkdown`<br>`task.lineNumber`                                                                                                                             |
 |                                                                                                                                                                                                                                                                                                                                                      | `sort by random`                            |                        |                        |                                                                                                                                                                          |

docs/Scripting/Query Properties.md

@@ -38,6 +38,9 @@ This page documents all the available pieces of information in Queries that you
 | `query.file.hasProperty('non_existent_property')` | `boolean` | `false` |
 | `query.file.property('task_instruction')` | `string` | `'group by filename'` |
 | `query.file.property('non_existent_property')` | `null` | `null` |
+| `query.file.outlinksInProperties` | `Link[]` | `['Test Data/link_in_yaml.md']` |
+| `query.file.outlinksInBody` | `Link[]` | `['Test Data/link_in_file_body_with_custom_display_text.md']` |
+| `query.file.outlinks` | `Link[]` | `['Test Data/link_in_yaml.md', 'Test Data/link_in_file_body_with_custom_display_text.md']` |
 
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 
@@ -48,6 +51,14 @@ This page documents all the available pieces of information in Queries that you
 1. `query.file.filenameWithoutExtension` was added in Tasks 4.8.0.
 1. `query.file.hasProperty()` was added in Tasks 7.15.0.
 1. `query.file.property()` was added in Tasks 7.15.0.
+1. Accessing links:
+    - The 3 `outlinks` methods were added in Tasks X.Y.Z.
+    - They all return an array of `Link` objects.
+    - For details, see [[Links]].
+    - The table above shows the result of `link.destinationPath`
+    - `query.file.outlinksInProperties` returns all the links in the query file's [[Obsidian Properties]].
+    - `query.file.outlinksInBody` returns all the links in the body of the note containing the query.
+    - `query.file.outlinks` returns all this links in both [[Obsidian Properties]] and the body of the note containing the query.
 
 ## Values for Query Search Properties
 

docs/Scripting/Task Properties.md

@@ -235,3 +235,29 @@ These are described in full in [[Obsidian Properties]].
 1. `task.file.hasProperty()` and `task.file.property()` were added in Tasks 7.7.0
 1. `task.file.hasProperty('property name')` returns true if the property `'property name'` is both present in the file and has a non-`null` value.
 1. `task.file.property('property name')` returns either the value in the file, or `null` if there is no value.
+
+## Values for Links
+
+> [!released]
+> Access to the Links was introduced in Tasks X.Y.Z.
+
+These are described in full in [[Links]].
+
+<!-- placeholder to force blank line before included text --><!-- include: TaskProperties.test.task_links.approved.md -->
+
+| Field | Type 1 | Example 1 |
+| ----- | ----- | ----- |
+| `task.outlinks` | `Link[]` | `['Test Data/link_in_task_wikilink.md']` |
+| `task.file.outlinksInProperties` | `Link[]` | `['Test Data/link_in_yaml.md', 'Test Data/links_everywhere.md']` |
+| `task.file.outlinksInBody` | `Link[]` | `['Test Data/link_in_file_body.md', 'Test Data/link_in_heading.md', 'Test Data/link_in_task_wikilink.md']` |
+| `task.file.outlinks` | `Link[]` | `['Test Data/link_in_yaml.md', 'Test Data/links_everywhere.md', 'Test Data/link_in_file_body.md', 'Test Data/link_in_heading.md', 'Test Data/link_in_task_wikilink.md']` |
+
+<!-- placeholder to force blank line after included text --><!-- endInclude -->
+
+1. These all return an array of `Link` objects.
+1. The table above shows the result of `link.destinationPath`
+1. `task.outlinks` contains any links in the task description.
+    - It does not contain links in any nested tasks or list items.
+1. `task.file.outlinksInProperties` returns all the links in the task file's [[Obsidian Properties]].
+1. `task.file.outlinksInBody` returns all the links in the body of the note containing the task. Naturally, this includes any links on the task line itself.
+1. `task.file.outlinks` returns all this links in both [[Obsidian Properties]] and the body of the note containing the task.

docs/Support and Help/Known Limitations.md

@@ -87,6 +87,10 @@ This page gathers together all the documentation on known limitations of the plu
 
 ![[Custom Sorting#Limitations of Custom Sorting]]
 
+## Queries: Links
+
+![[Links#Limitations of Links Handling and Searches]]
+
 ## Queries: Presets
 
 ![[Presets#Limitations]]

docs/What is New/Changelog.md

@@ -12,6 +12,9 @@ _In recent [Tasks releases](https://github.com/obsidian-tasks-group/obsidian-tas
 
 ## 7.x releases
 
+- X.Y.Z:
+  - Add support for [[Links]] in custom filters, sorting and grouping.
+  - The Tasks API can now edit existing task lines with [[Tasks Api#`editTaskLineModal(taskLine string) Promise<string>;`|editTaskLineModal()]].
 - 7.20.0:
   - Add [[Presets]] feature to save commonly used task query instructions.
   - Document [[Missing tags, aliases and cssclasses in some Obsidian 1.9.x versions]] - for Insider users of Obsidian 1.9.x.

resources/sample_vaults/Tasks-Demo/How To/Access links.md

@@ -5,10 +5,7 @@ TQ_extra_instructions:
 
 # Accessing Links
 
-> [!Warning]
->
-> - The queries in this file are **experimental**, and **may not continue to work**.
-> - For example, once the Obsidian Bases facility is finalised, we *may* update the vocabulary used here to match that of Obsidian.
+These facilities were introduced in Tasks X.Y.Z.
 
 ## Filtering
 
@@ -18,56 +15,56 @@ TQ_extra_instructions:
 ```tasks
 # Task line has a link
 filter by function task.outlinks.length > 0
-limit groups 1
+limit 10
 ```
 ````
 
 ```tasks
 # Task line has a link
 filter by function task.outlinks.length > 0
-limit groups 1
+limit 10
 ```
 
 ### `task.file.outlinksInProperties`: Tasks in files whose properties/frontmatter contains a link
 
 ````text
 ```tasks
 filter by function task.file.outlinksInProperties.length > 0
-limit groups 1
+limit 10
 ```
 ````
 
 ```tasks
 filter by function task.file.outlinksInProperties.length > 0
-limit groups 1
+limit 10
 ```
 
 ### `task.file.outlinksInBody`: Tasks in files whose markdown body contains a link
 
 ````text
 ```tasks
 filter by function task.file.outlinksInBody.length > 0
-limit groups 1
+limit 10
 ```
 ````
 
 ```tasks
 filter by function task.file.outlinksInBody.length > 0
-limit groups 1
+limit 10
 ```
 
 ### `task.file.outlinks`: Tasks in files whose file contains a link anywhere
 
 ````text
 ```tasks
 filter by function task.file.outlinks.length > 0
-limit groups 1
+limit 10
 ```
 ````
 
 ```tasks
 filter by function task.file.outlinks.length > 0
-limit groups 1
+limit 10
 ```
 
 ### Task lines that contain broken links
@@ -90,12 +87,12 @@ This should match one task, in [[Link to Access links file]].
 
 ````text
 ```tasks
-filter by function task.outlinks.some(link => link.destinationPath === query.file.path)
+filter by function task.outlinks.some(link => link.linksTo(query.file))
 ```
 ````
 
 ```tasks
-filter by function task.outlinks.some(link => link.destinationPath === query.file.path)
+filter by function task.outlinks.some(link => link.linksTo(query.file))
 ```
 
 #### Tasks - version 2
@@ -104,12 +101,12 @@ This should match one task, in [[Link to Access links file]].
 
 ````text
 ```tasks
-filter by function task.outlinks.some(link => link.linksTo(query.file))
+filter by function task.outlinks.some(link => link.destinationPath === query.file.path)
 ```
 ````
 
 ```tasks
-filter by function task.outlinks.some(link => link.linksTo(query.file))
+filter by function task.outlinks.some(link => link.destinationPath === query.file.path)
 ```
 
 #### Dataview version
@@ -157,3 +154,10 @@ group by function task.outlinks.map(link => link.destinationPath).sort().join('
 filter by function task.outlinks.length > 0
 group by function task.outlinks.map(link => link.destinationPath).sort().join(' · ')
 ```
+
+### Demonstrate link.displayText
+
+```tasks
+filter by function task.outlinks.length > 0
+group by function task.outlinks.map(link => `\`${link.originalMarkdown}\` -><br> \`${link.displayText}\``)
+```

resources/sample_vaults/Tasks-Demo/Test Data/query_using_properties.md

@@ -13,12 +13,15 @@ task_instructions_with_continuation_line: |
   path \
     includes query_using_properties
 task_instruction_with_spaces: "  path includes query_using_properties  "
+link-in-frontmatter: "[[link_in_yaml]]"
 ---
 
 # query_using_properties
 
 - [ ] #task Task in 'query_using_properties'
 
+Example link in body of a file, for documentation purposes: [[link_in_file_body_with_custom_display_text]].
+
 ## Use a one-line property: task_instruction
 
 Read a Tasks instruction from a property in this file, and embed it in to any number of queries in the file:

src/Task/Link.ts

@@ -21,6 +21,9 @@ export class Link {
      * Return the original Markdown, exactly as specified in the original markdown.
      * For "[ab](cd.md)", it would return "[ab](cd.md)".
      *
+     * **Tip**: For use in `group by function`, {@link markdown} will also work for header-only links,
+     * like `[[#heading in this file]]`.
+     *
      * See also {@link markdown}
      */
     public get originalMarkdown(): string {
@@ -52,7 +55,9 @@ export class Link {
      * Return the destination, exactly as specified in the original markdown.
      * For "[ab](cd.md)", it would return "cd.md".
      *
-     * It is not able to supply the full path of the link destination.
+     * **Tip**: Use {@link destinationPath} instead.
+     *
+     * This method is not able to supply the full path of the link destination.
      * Note that if you have two files called `cd.md`, Tasks does not yet do anything
      * to select the closest file of that name.
      *
@@ -65,17 +70,37 @@ export class Link {
         return this.rawLink.link;
     }
 
+    /**
+     * The actual full path that Obsidian would navigate to if the user clicked on the link,
+     * or `null` if the link is to a non-existent file.
+     *
+     * For "[[link_in_file_body]]", it might return "Test Data/link_in_file_body.md".
+     *
+     * Note that this value is not usually configured correctly in tests.
+     * See {@link LinkResolver} docs for more info.
+     */
     public get destinationPath(): string | null {
         return this._destinationPath;
     }
 
     /**
+     * For "[[Styling of Queries]]", it would return "Styling of Queries"
+     * For "[[link_in_task_wikilink|alias]]", it would return "alias"
      * For "[ab](cd.md)", it would return "ab".
+     * For "[[Project Search#Search 1]]", it would return "Project Search > Search 1"
      */
     public get displayText(): string | undefined {
         return this.rawLink.displayText;
     }
 
+    /**
+     * Returns true if this link points to the given value
+     * - Pass in `query.file` or `task.file` for the most precise results.
+     * - If supplying a string, it is case-sensitive, and it will return true if:
+     *     - the string matches the link destination's filename (it ignores `.md` file extension)
+     *     - or the string matches the link destination's full path (it ignores `.md` file extension)
+     * @param destination
+     */
     public linksTo(destination: string | TasksFile): boolean {
         if (typeof destination === 'string') {
             const removeMd = /\.md$/;