
gittech. site
for different kinds of informations and explorations.
[[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
- feat behavior-system: Complete behavior system implementation, forming automated workflow
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]].