gittech. site

for different kinds of informations and explorations.

Org-Supertag

Published at
Dec 31, 2024

[[file:README_CN.org][中文版说明]]

  • Introduction

Org-supertag is a package that enhances org-mode's tag functionality. It enables tags to not only set properties for nodes, but also directly manipulate nodes and automatically execute certain behaviors based on time, providing a more flexible way of information management.

Org-supertag offers high degrees of freedom, flexibility, and convenience. Through it, you can customize your own behaviors to achieve more complex functionalities - its potential is essentially limitless.

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

  • Features

** Feature Overview

  • Enhanced Tag Functionality
    • Set properties for org-headlines, add multiple org-properties at once and batch fill corresponding values
    • Transform regular org-headlines into searchable and referenceable nodes
    • Add behaviors to tags that can complete multiple operations at once
  • Convenient Search Functionality
    • Search with multiple keywords at once (using AND logic)
    • Beautified search results page showing both titles and content beneath
    • Multiple search result export methods for easy organization
      • Export search results to another file
      • Export search results to a new file (location and filename customizable)
      • Export search results directly to current cursor position
  • Automatic Synchronization
    • Automatically sync position and changes of org-headlines converted to Nodes, saving manual operations
    • Provides manual command to sync all Nodes
  • Integrated Behavior System for Automation
    • Behavior system makes tags "smart", automatically triggering preset actions when adding/removing tags (like changing styles, setting states, etc.)
    • One tag can trigger multiple actions, e.g., adding @urgent tag can simultaneously "turn red", "set priority", "add deadline", etc.
    • Behaviors can be scheduled, combined, and parameterized, making your org-mode workflow more automated and efficient
    • Behavior system includes a behavior library - you can use predefined common behaviors or create your own custom ones. This modular design makes behaviors easily shareable, reusable, and extensible between different org files or users
    • Customizable Behavior Commands
      • Simple configuration syntax
      • Parameterized configuration
      • Can combine multiple Behaviors together

** Enhanced Tag System Make your org-mode tags powerful metadata controllers:

*** Adding Tags/Setting Properties

  • Set multiple properties at once when adding tags
  • Batch fill property values
  • Type validation for property values

[[./picture/figure4.gif]]

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

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

*** Node System

  • Automatic node creation, no manual creation needed
  • Establish reference relationships between nodes

[[./picture/figure5.gif]]

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

If a node isn't automatically created, you can directly run M-x org-supertag-node-create command to convert the current heading into a node.

*** Behavior System Make tags "smart", enabling:

  • Trigger actions when adding/removing tags
  • Combine multiple actions into workflows
  • Set scheduled behaviors
  • Customize tag styles

[[./picture/figure6.gif]]

M-x org-supertag-behavior-attach

M-x org-supertag-behavior-detach

** Powerful Search Efficiently find and organize your nodes:

*** Multi-keyword Search

  • Support multiple keyword combination search (AND logic)
  • Aesthetic search results interface
  • Preview content under headings

[[./picture/figure8.gif]]

M-x org-supertag-query

*** Flexible Export Options Multiple ways to organize search results:

  • Export to existing files
  • Create new files to save results
  • Insert at current position

[[./picture/figure9.gif]]

** Automatic Synchronization Automatically maintain node organization:

  • Track node position changes
  • Automatically update reference relationships
  • Provide manual sync commands

[[./picture/figure7.gif]]

M-x org-supertag-sync-force-all

If some nodes need synchronization but haven't auto-synced, you can directly run M-x org-supertag-sync-force-all command to sync all node information to the database.

  • Basic Usage

** Adding Tags

#+begin_src M-x org-supertag-tag-add-tag #+end_src

Add tags to current heading, can set properties simultaneously.

** Creating References #+begin_src M-x org-supertag-node-add-reference #+end_src

Add references to other nodes.

** Searching #+begin_src M-x org-supertag-query #+end_src

Search nodes using multiple keywords.

** Adding Behaviors #+begin_src M-x org-supertag-behavior-attach #+end_src

Attach automated behaviors to tags.

  • Basic Installation

#+begin_src emacs-lisp (use-package org-supertag :straight (:host github :repo "yibie/org-supertag") :after org :config (org-supertag-setup)) #+end_src

  • Advanced Usage

** Behavior System Configuration Create custom behaviors by editing ~/.emacs.d/org-supertag/org-supertag-custom-behavior.el file:

Here's an example

#+begin_src emacs-lisp ;; Register a behavior named "@urgent" ;; Parameter explanation: ;; - @urgent: behavior name, used to identify and reference this behavior ;; - :trigger: trigger condition, :on-add means trigger when adding tag ;; - :list: list of actions to execute, each action is a command string ;; - :style: tag display style, including font and prefix icon settings (org-supertag-behavior-register "@urgent" <= Register a behavior named "@urgent" :trigger :on-add <= Trigger when adding tag :list '("@todo=TODO" <= Set TODO state "@priority=A" <= Set priority to A "@deadline=today") <= Set deadline to today :style '(:face (:foreground "red" :weight bold) <= Set tag display to red and bold :prefix "🔥")) <= Show fire icon before tag #+end_src

For more examples, please refer to [[./DEMO.org][DEMO.org]].

For more usage details, please refer to [[https://github.com/yibie/org-supertag/wiki/Advance-Usage-%E2%80%90-Behavior-System-Guide][Org‐supertag Advance Usage]]

  • Changelog
  • 2025-01-13 2.0.0 release

    • Added behavior scheduling system
    • Added behavior template variables
    • Added automatic sync system
    • And many improvements See details in [[./CHANGELOG.org][CHANGELOG]]
  • 2024-12-31 1.0.0 release

    • feat behavior-system: Complete behavior system implementation, forming automated workflow
      • Three-layer behavior architecture (basic/derived/composite)
      • Complete trigger system
      • Rich behavior library functions
      • Style system support
    • docs: Provide interactive demo document DEMO.org
    • refactor: Core refactoring
      • Optimized data structures
      • Improved error handling
      • Enhanced performance
  • 2024-12-20 0.0.2 release

    • fix org-supertag-remove: Fixed issue where removing tags wasn't effective
    • fix org-supertag-tag-add-tag: Fixed 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 in 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, like querying against one or multiple files
  • ✅ Initially implement a command system where tags automatically trigger commands, e.g., when a node is tagged as Task, it automatically sets TODO, priority A, and changes node background to yellow
  • ✅ Implement a task scheduling system to combine multiple nodes for completing a series of tasks, e.g., automatically setting daily review at 9 PM and automatically inserting review results into review nodes (experimental feature, may not be implemented)
  • AI integration, different tags associated with different Prompts, e.g., when a node is marked as "task", automatically trigger AI commands to generate a task list
  • Like Tana, provide more views (experimental feature, may not be implemented)
  • Acknowledgments

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

I sincerely hope you'll like this package and benefit from it.

  • Contributing

Contributions welcome! Please check our [[file:.github/CONTRIBUTING.org][contribution guidelines]].