中文版说明

Introduction

Org-supertag is a package that enhances org-mode’s tag functionality. It empowers tags to not only assign attributes to nodes but also directly manipulate them, enabling more flexible knowledge management.

Org-supertag adopts a non-intrusive design, coexisting harmoniously with org-mode’s original features while providing more possibilities.

Why Tags?

Traditional linear note-taking systems have limitations:

1. Single Perspective :: Knowledge is confined to fixed hierarchical structures
2. Difficult to Reorganize :: Lacks flexible association mechanisms
3. Fragmentation :: Knowledge points lack organic connections

Tag systems provide a higher-dimensional organization method:

1. Multi-dimensional Classification :: A piece of knowledge can have multiple attributes simultaneously
2. Dynamic Reorganization :: Content can be reorganized from different perspectives at any time
3. Relationship Network :: Weave scattered knowledge points into a network through tags

This organization method not only makes knowledge easier to retrieve and reuse but, more importantly, can stimulate connections between knowledge points, creating a compound effect. Tags, as a metadata management tool, have applications far beyond knowledge management.

Here’s my concept diagram:

Main Concepts

Node

A node is an abstract information unit containing (org-mode) headings, properties, and content. Each node has a unique identifier and can be referenced and queried.

Super Tag

A super tag is a metadata template that defines the structure and behavior of nodes. Tags not only describe node properties but can also trigger automated operations.

Tag format is :#tag-name:.

Field

Fields are structured properties of nodes, defined and enforced by tags. The field system supports multiple data types.

Behavior

Behaviors are automated operations defined and enforced by tags. The behavior system supports various automation operations.

Query

The query system supports unified searching across nodes, tags, and fields, supports compound queries with multiple conditions, and query results can be exported and reorganized.

Common Commands

Node Operations

M-x org-supertag-node-create

Convert current heading to a supertag node

M-x org-supertag-query

Search nodes

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

Add reference to current node

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

Remove reference from current node

Tag Operations

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

Add tag to current org-headline, automatically creating a node and setting fields (if they exist)

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

Batch add tags to multiple org-headlines

M-x org-supertag-tag-remove

Remove tag from current node

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

Set field value

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

Set both tag field and value simultaneously

Query Commands

M-x org-supertag-query

Start query interface

1. Enter keywords (multiple keywords separated by spaces)
2. Select query results (use C-c C-c in results page)
3. Choose export method:
   • Export to new file
   • Export to existing file
   • Insert links at current position

Query results are presented as org-mode links, clicking a link jumps directly to the corresponding node.

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

Query within current buffer

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

Query in specified files, can specify multiple files

Behavior Commands

M-x org-supertag-behavior-attach

Attach behavior to tag

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

Execute behavior at current node, prompts for behavior name

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

Execute multiple behaviors at current node sequentially

Installation

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

Advanced Features

Preset Tag Modification

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

project

Project management

• status: Status (planning/active/on-hold/completed/cancelled)
• priority: Priority (high/medium/low)
• deadline: Deadline
• owner: Owner

task

Task management

• status: Status (todo/in-progress/blocked/done/cancelled)
• priority: Priority (A/B/C)
• due: Due date
• assignee: Assignee

Other preset tags include: person, meeting, place, company, note, etc.

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

Edit preset tags

Use this command to edit preset tags, it will automatically add custom-set-variables configuration to your init.el.

Setting Custom Preset Tags in init.el

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

(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")))))

Query Result Export

Three export methods are provided, supporting both commands and keyboard shortcuts:

Export to New File

• Command: M-x org-supertag-query-export-results-to-new-file
• Shortcut: C-c C-x n
• Function: Export query results to a new file, supports selecting insertion position:
  • End of file
  • As subheading
  • As same-level heading

Export to Existing File

• Command: M-x org-supertag-query-export-results-to-file
• Shortcut: C-c C-x f
• Function: Export query results to selected position in specified file

Insert at Current Position

• Command: M-x org-supertag-query-export-results-here
• Function: Insert results as org-mode block at cursor position

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

Other Related Commands

C-c C-c

Toggle selection state of current line

C-c C-x C-r

Select all results in region

C-c C-x C-u

Unselect all results in region

Behavior System

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

Behavior Types

org-supertag provides three types of behaviors:

Basic Behaviors

The most fundamental behavior units:

• Single functionality, flexibility through parameters
• Directly manipulate node properties or content
• Examples:
  • @todo - Set task state
  • @priority - Set priority
  • @timestamp - Add timestamp
  • @property - Set property
  • @clock - Manage time tracking

Derived Behaviors

Extensions of basic behaviors:

• Preset parameter combinations
• Optimized for specific scenarios
• Examples:
  • @done - Complete task and record time
  • @start - Start task and record time
  • @cancel - Cancel task and add note

Combined Behaviors

Multiple behaviors in workflows:

• Chain multiple behaviors into workflows
• Implement complex automation scenarios
• Examples:
  • @meeting - Add template + set schedule + mark todo
  • @archive - Mark complete + move to archive

Behavior Definition

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 "📅"))

Parameter Passing in Behavior Lists

When using :list to chain behaviors, parameters are passed using a special syntax:

1. Basic Format:

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

2. Examples with 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 to :params definition in order
   • For “@property=name,value”, matches :params ‘(name value)
   • For “@todo=state”, matches :params ‘(state)
4. Complex Examples:

   ;; 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
       

Trigger Types

Behaviors can be triggered at different times:

• :on-add - Triggered when tag is added
• :on-remove - Triggered when tag is removed
• :on-change - Triggered when node content changes
• :always - Triggered on all events

Changelog

2024-12-31

1.0.0 release

feat behavior-system

Complete behavior system implementation, forming automated workflows

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

docs

Provide interactive demo document DEMO.org

refactor

Core refactoring

• Optimize data structures
• Improve error handling
• Enhance performance

2024-12-20

0.0.2 release

fix org-supertag-remove

Fix issue where tag removal was not effective

fix org-supertag-tag-add-tag

Fix issue where duplicate tags could be added to org-headline

feat org-supertag-tag-edit-preset

Edit preset tags

feat org-supertag-query-in-buffer

Query within current buffer

feat org-supertag-query-in-files

Query in specified files, can specify multiple files

2024-12-19

0.0.1 release

Future Plans

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

Acknowledgments

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

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