Links Specification

Overview

This document describes the enhanced linking functionality introduced in QuickNotes. Users can create links to items in various domains using a unified syntax. These links are processed by both the backend and the frontend to generate clickable hyperlinks that navigate to the appropriate detail pages.

Link Syntax

Users should create links using the following syntax:

[[<domain>:::<uuid>]]

<domain> specifies the type of the referenced item. Allowed values are:
- note – for notes
- feed – for feed subscriptions
- entry – for individual feed entries
- doc – for uploaded documents
- post – for posts (if implemented in the future)
<uuid> is the unique identifier of the target item.

Example

For example, to link to a note:

[[note:::123e4567-e89b-12d3-a456-426614174000]]

Backend Implementation Changes

Link Extraction: Update the link extraction function (e.g., ExtractLinks) to recognize the new pattern. A suggested regular expression is:
```
re := regexp.MustCompile(`\[\[([a-z]+):::(.+?)\]\]`)
```
This regex captures two groups: the domain ([a-z]+) and the UUID (.+?).
Validation and URL Generation:
- Validate that the extracted domain is one of the allowed values: note, feed, entry, doc, or post.
- Generate the appropriate URL based on the domain:
  - For note: /notes/<uuid>
  - For feed: /feeds/<uuid>
  - For entry: /feeds/entries/<uuid>
  - For doc: /documents/<uuid>
  - For post: /posts/<uuid> (if posts are later implemented)
Link Storage and Updates: When a note is created or updated, the link management routines should:
- Extract all links using the new regex.
- Validate and resolve these links by verifying the existence of the target items.
- Store the relationships if needed, so that bidirectional navigation or graph visualization can be supported.

Frontend Implementation Changes

Rendering: Modify the markdown or HTML rendering components so that when the new link syntax is encountered, it is transformed into an HTML <a> tag whose href attribute is the generated URL.
Routing: Ensure that client-side routing is properly set up so that clicking the link navigates to the corresponding detail page (e.g., a note detail view, feed entry view, or document viewer).
Styling: Apply CSS rules to these links to visually indicate their interactive nature.

Summary

The enhanced linking functionality unifies the way references to various content types are created and handled within QuickNotes. By adopting the [[<domain>:::<uuid>]] syntax, the system improves consistency and makes it easier to navigate across different domains.

Future Enhancements

A potential future improvement is to implement a search drop-down feature in the editor. When a user types "[[:::" (for example, "[[note:::"), the editor could display a drop-down list of items from the selected domain, searchable by title. Upon selection, the link would be automatically completed with the corresponding item's UUID. This enhancement would improve usability by making it easier to find and link to existing items.

3.2 KiB Raw Permalink Blame History Unescape Escape