中文版说明

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

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

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

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

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

Automatic Synchronization

Automatically maintain node organization:

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

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

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

Add tags to current heading, can set properties simultaneously.

Creating References

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

Add references to other nodes.

Searching

M-x org-supertag-query

Search nodes using multiple keywords.

Adding Behaviors

M-x org-supertag-behavior-attach

Attach automated behaviors to tags.

Basic Installation

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

Advanced Usage

Behavior System Configuration

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

Here’s an example

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

For more examples, please refer to DEMO.org.

For more usage details, please refer to 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

• 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 contribution guidelines.