yibie/org-supertag: Enhance org-mode tag system, borrow idea from tana.

Chinese version description

Org-supertag is a software package that enhances the functionality of org-mode tags. It enables tags not only to assign attributes to nodes, but also to directly manipulate nodes, enabling more flexible knowledge management.

Org-supertag adopts a non-invasive design and coexists harmoniously with the original characteristics of org-mode while providing more possibilities.

Traditional linear note-taking systems have their limitations:

1. Single Perspective:: Knowledge is limited to a fixed hierarchy
2. Difficulties in restructuring:: Inelastic coalition mechanisms
3. Fragmentation:: Knowledge points lack organic connections

The tag system provides a higher-dimensional organization method:

1. Multi-dimensional classification:: A piece of knowledge can have multiple attributes at the same time
2. Dynamic reorganization: Content can be reorganized from different angles at any time
3. Relationship network:: weaving scattered knowledge points into a network through tags

This kind of organization not only makes knowledge easier to retrieve and reuse, but more importantly, it can stimulate connections between knowledge points and produce compound effects. As a metadata management tool, tags have applications far beyond knowledge management.

Here is my concept diagram:

Nodes are abstract units of information that contain (organizational patterns) titles, attributes, and content. Each node has a unique identifier and can be referenced and queried.

Super tags are metadata templates that define the structure and behavior of nodes. Tags not only describe node properties but can also trigger automated actions.

The label format is :#tag-name:.

Fields are structured properties of nodes, defined and enforced by tags. On-site systems support a variety of data types.

Behaviors are automated actions defined and enforced by tags. Behavioral systems support various automated operations.

The query system supports unified search across nodes, labels, and fields, and supports multi-condition compound queries. The query results can be exported and reorganized.

M-x org-supertag-node-create

Convert the current title to a supertab node

M-x org-supertag-query

search node

M-x org-supertag-node-add-reference

Add a reference to the current node

M-x org-supertag-node-remove-reference

Remove reference from current node

M-x org-supertag-tag-add-tag

Add labels to the current organization title, automatically create nodes and set fields (if existing)

M-x org-supertag-tag-batch-add-tag

Add tags to multiple organization titles in batches

M-x org-supertag-tag-remove

Remove label from current node

M-x org-supertag-tag-set-field-value

Set field value

M-x org-supertag-tag-set-field-and-value

Set label fields and values ​​simultaneously

M-x org-supertag-query

Start query interface

1. Enter keywords (multiple keywords separated by spaces)
2. Select query results (use a copy of the results page)
3. Select export method:
   • Export to new file
   • Export to existing file
   • Insert link at current location

The query results are presented in the form of organization mode links. Click the link to jump directly to the corresponding node.

M-x org-supertag-query-in-buffer

Query within the current buffer

M-x org-supertag-query-in-files

Query in the specified file, multiple files can be specified

M-x org-supertag-behavior-attach

Attach behavior to label

M-x org-supertag-behavior-execute-at-point

Execute the behavior on the current node and prompt to enter the behavior name

M-x org-supertag-behavior-execute-batch

Execute multiple actions sequentially on the current node

(use-package org-supertag
  :straight (:host github :repo "yibie/org-supertag")
  :after org
  :config
  (org-supertag-setup))

Org-supertag provides some preset tag types, the following are examples:

project

project management

• status: status (planned/active/paused/completed/cancelled)
• Priority: Priority (High/Medium/Low)
• Deadline: Deadline
• Owner: Owner

Task

work management

• status: status (to-do/in progress/blocked/completed/cancelled)
• Priority: Priority (A/B/C)
• Two: two dates
• Assignee: Assignee

Other preset tags include: people, meetings, places, companies, notes, etc.

M-x org-supertag-tag-edit-preset

Edit default labels

Use this command to edit a default tag and it will automatically add custom-set-variables settings to your init.el.

You can customize the default tags by setting the org-supertag-preset-tags variable in init.el. Each default label consists of a label name and a field definition:

(setq org-supertag-preset-tags
      '(("book" . ((:name "status"
                   :type options 
                   :options ("reading" "completed" "want-to-read")
                   :description "Reading status")
                  (:name "rating"
                   :type number
                   :description "Rating")
                  (:name "author"
                   :type string
                   :description "Author")))))

Provides three export methods, supporting commands and keyboard shortcuts:

• Order: M-x org-supertag-query-export-results-to-new-file
• shortcut: C-c C-x n
• Function: Export query results to a new file, supporting selection of insertion location:
  • End of file
  • as subtitle
  • as sibling title

• Order: M-x org-supertag-query-export-results-to-file
• shortcut: C-c C-x f
• Function: Export query results to the selected location in the specified file

• Order: M-x org-supertag-query-export-results-here
• Function: Insert the result as an organization mode block at the cursor position

⚠️Note: This command can only be used outside the search results page

C-c C-c

Toggle the selection state of the current row

C-c C-x C-r

Select all results in this area

C-c C-x C-u

Deselect all results for this area

The behavior system is one of the core features of org-supertag, enabling tags to perform automated operations.

org-supertag provides three types of behavior:

The most basic unit of behavior:

• Single function, flexibility achieved through parameters
• Directly manipulate node attributes or content
• example:
  • @todo – set task status
  • @priority – set priority
  • @timestamp – Add a new timestamp
  • @property – set properties
  • @clock – Manage time tracking

Extension of basic behavior:

• Preset parameter combination
• Optimize for specific scenarios
• example:
  • @done – complete the task and record the time
  • @start – start the task and record the time
  • @cancel – Cancel the task and add a comment

Various behaviors in the workflow:

• Connect multiple behaviors into workflows
• Implement complex automation scenarios
• example:
  • @meeting – add template + set schedule + mark to-do items
  • @archive – mark complete + move to archive

Behavior definitions are stored in ~/.emacs.d/org-supertag/org-supertag-custom-behavior.el:

;; 1. Basic behavior defines what parameters it accepts
(org-supertag-behavior-register "@todo"
  :trigger :on-add
  :action #'org-supertag-behavior--set-todo
  :params '(state)                                  ; Defines that @todo accepts one parameter named 'state'
  :style '(:face (:foreground "blue" :weight bold)
          :prefix "☐"))

;; When using @todo behavior, parameter is passed after '=' sign:
;; "@todo=DONE"    ; Here "DONE" is passed as the 'state' parameter

;; 2. Example with two parameters
(org-supertag-behavior-register "@property"
  :trigger :on-add
  :action #'org-supertag-behavior--set-property
  :params '(name value)                             ; Defines that @property accepts two parameters
  :style '(:face (:foreground "green" :weight bold)
          :prefix "✓"))

;; When using @property behavior, parameters are separated by comma:
;; "@property=TYPE,meeting"    ; "TYPE" is passed as 'name', "meeting" as 'value'

;; 3. Using behaviors with parameters in :list
(org-supertag-behavior-register "@meeting"
  :trigger :on-add
  :list '("@todo=TODO"                             ; Uses @todo behavior, passes "TODO" as 'state'
          "@property=TYPE,meeting"                  ; Uses @property behavior, passes two parameters
          "@clock")                                ; Uses @clock behavior with no parameters
  :style '(:face (:foreground "purple" :weight bold)
          :prefix "📅"))

When using the :list link behavior, parameters are passed using special syntax:

1. Basic format:

   "@behavior-name=param1,param2,..."
       

2. Examples of different parameter types:
   • Single parameter:

     "@todo=DONE"              ; Set TODO state to DONE
     "@priority=A"             ; Set priority to A
             

   • Multiple parameters:

     "@property=STATUS,active" ; Set property STATUS to active
     "@drawer=LOGBOOK,note"   ; Create LOGBOOK drawer with note
             

   • No parameters:

     "@archive"               ; Execute archive behavior without params
     "@clock"                ; Start clock without specific params
             

3. Parameter matching:
   • Parameters are matched sequentially with :params definitions
   • For “@property=name,value”, match: params ‘(name value)
   • For “@todo=state”, matches: params ‘(state)
4. Complex example:

   ;; Meeting workflow with multiple parameterized behaviors
   (org-supertag-behavior-register "@meeting-start"
     :trigger :on-add
     :list '("@todo=TODO"                    ; Single param
             "@property=TYPE,meeting"         ; Two params
             "@timestamp=SCHEDULED,now"       ; Two params
             "@drawer=LOGBOOK,meeting-note"   ; Two params
             "@clock"))                       ; No params
       

Behaviors can be triggered at different times:

• :on-add – triggered when a new tag is added
• :on-remove – triggered when the tag is removed
• :on-change – triggered when the node content changes
• :always – fires on all events

2024-12-31

1.0.0 Release

Grow into a system

Complete behavioral system implementation to form automated workflow

• Three-tier behavioral architecture (Basic/Derived/Combined)
• Complete trigger system
• Rich behavior library functions
• Style system support

document

Interactive presentation document DEMO.org available

Refactor

Core refactoring

• Optimize data structure
• Improve error handling
• Improve performance

2024-12-20

0.0.2 Release

Fix organization super tag removal

Fixed the problem of invalid label deletion

Fix org-supertag-tag-add-tag

Fixed an issue where duplicate tags could be added to the organization title

feat org-supertag-tag-edit-preset

Edit default labels

feat org-supertag-query-in-buffer

Query within the current buffer

feat org-supertag-query-in-files

Query in the specified file, multiple files can be specified

2024-12-19

Version 0.0.1

• ✅ Provide more query scope, such as query within one file or multiple files
• ✅ Preliminary implementation of the command system, allowing tags to automatically trigger commands
• Preliminary AI integration to associate different labels with different prompts
• Implement a task scheduling system (experimental function, may not be implemented)
• Provide more Tana-like views (experimental feature, may not be implemented)

Thanks to Tana for the inspiration, and thanks to org-mode and the power of Emacs.

I sincerely hope you enjoy this package and benefit from it.