Introduction

Org-supertag is a package designed to enhance the tagging functionality of org-mode, drawing its main inspiration from Tana, a bi-directional linking note-taking software. Like Tana, org-supertag’s tags can both assign properties to nodes and directly operate on them.

Org-supertag follows the principle of non-destructive updates, meaning its use won’t interfere with org-mode’s existing features. The original tagging system remains functional (though not recognized by org-supertag), and I believe the combination of both systems will create more interesting possibilities.

Why Tags?

Let me share my experience: most of our notes are linear, arranged in a certain order. However, when we need to reorganize these notes from different perspectives, we encounter some difficulties.

For example, many notes are about concepts, and many are about methods, but these properties are hard to express in linear note-taking. This is because when recording notes, we focus more on understanding the knowledge itself, and it’s difficult to step back and view it from a higher level at that moment. When we review later, by tagging previously recorded knowledge, we restructure our knowledge. This makes both querying and organizing much more convenient.

Most importantly, it increases the reuse rate of knowledge, creating a compound effect. Given that tagging is a very flexible way of organization, this compound effect extends far beyond the knowledge level.

Here’s my concept diagram:

Practical Example

Let’s say you have the following content in your inbox.org:

* Read a good article about Emacs performance optimization
https://example.com/emacs-performance

* Need to contact John about project progress
Phone: 123-456-7890

* Ideas for improving project documentation
1. Add more examples
2. Optimize formatting

Processing steps:

Convert to nodes and add tags

* Read a good article about Emacs performance optimization  :#article:
https://example.com/emacs-performance

* Need to contact John about project progress  :#contact: :#task:
Phone: 123-456-7890

* Ideas for improving project documentation  :#idea:
1. Add more examples
2. Optimize formatting

Use query function for batch processing
- M-x org-supertag-query enter “article” to find all articles
- Export selected results to articles.org
- Repeat these steps for other types of content
Results after processing
- articles.org now contains article collections
- tasks.org now contains new tasks
- contacts.org now contains contact information
- ideas.org now contains new ideas

Advantages of this workflow:

Quick collection: Don’t worry about where to put things, just put everything in inbox first
Delayed organization: Organize when convenient
Batch processing: Quickly categorize and organize using tags and queries

Main Concepts

Node

A node is the basic unit in org-supertag, corresponding to a headline in org-mode. Each node has a unique ID and can be referenced and searched.

A node includes the org-mode headline, its property drawer, and all content under the headline (including special blocks, subheadings, etc.).

Super Tag

Super tags are not just simple markers; they define a set of field templates. When a super tag is applied to a node, these field templates are applied to the node. For example:

A tag marked as “task” might include fields like “priority”, “status”, “deadline”, etc.
A tag marked as “contact” might include fields like “email”, “phone”, “address”, etc.

Org-supertag treats nodes as objects, so tags will introduce more functionality in the future, such as automatic command triggers and AI integration.

Org-supertag tags look like this: :#tag-name:, differing from org-mode tags only in appearance.

If you click it, you can still see the org-agenda menu (though I don’t recommend doing this).

⚠️Warning: org-supertag only records tags set through org-supertag, not tags set through org-mode.

Field

Fields are node properties (once created, they are synchronized to the property drawer in org-mode) defined by tags. Each field has:

Type: such as string, number, date, options, reference, etc.
Name: field identifier
Value: field content
Validation rules: ensure field values meet expected formats

Supported field types include:

string: text
options: predefined options
number: numeric values
date: dates
timestamp: timestamps
reference: node references
tags: tag lists
list: lists
range: numeric ranges

Query

Org-supertag provides powerful query capabilities:

Unified search: keywords can search across nodes, tags, and fields simultaneously
Multiple keywords can be used with AND logic
Query results can be exported to:
1. A new file
2. An existing file
3. Inserted at the current cursor position

Common Commands

Node Operations

M-x org-supertag-node-create: Convert current headline 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 a tag to the 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 a tag from the 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

Preset Tags

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

project

Project management

status: Status (planning/active/on-hold/completed/cancelled)
priority: Priority level (high/medium/low)
deadline: Due date
owner: Project owner

task

Task management

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

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.

Customizing Preset Tags in init.el

You can customize preset tags by setting the `org-supertag-preset-tags` variable in your 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")))))

Field definitions support the following properties:

:name: Field name
:type: Field type (string/options/date/number etc.)
:options: List of options (only for options type)
:description: Field description
:min/:max: Number range (only for number type)

Query Commands

M-x org-supertag-query

Start query interface

Enter keywords (multiple keywords separated by spaces)
Select query results (multiple selections separated by commas)
Choose export method:
- Export to new file
- Export to existing file
- Insert 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

Query Result Export

Query results can be exported in three ways, triggered by the following commands or shortcuts:

Export to New File

Command: M-x org-supertag-query-export-results-to-new-file
Shortcut: C-c C-x n

After selecting results, choose “Export to New File”
Enter new filename
Choose insertion position:

File End
Insert at end of file

Under Heading
Insert as child of selected heading

Same Level
Insert as sibling of selected heading

Export to Existing File

Command: M-x org-supertag-query-export-results-to-file
Shortcut: C-c C-x f

After selecting results, choose “Export to Existing File”
Select target file
Choose insertion position (same as above)

Insert at Current Position

Command: M-x org-supertag-query-export-results-here
Shortcut: C-c C-x h

After selecting results, choose “Insert at Point”
Results will be inserted as an org-mode special block, for example:

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: Deselect all results in region

Installation

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

Changelog

2024-12-20

0.0.2 release

fix org-supertag-remove: Fix issue of removing tags not taking effect
fix org-supertag-tag-add-tag: Fix issue of adding duplicate tags to org-headline when adding tags
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

2024-12-19

0.0.1 release

Future Plans

Expand query scope to support searching within specific files or multiple files
Implement a command system allowing tags to trigger commands automatically. For example, when a node is tagged as “Task”, it automatically sets TODO state, priority A, and changes the background color to yellow
Initial AI integration, with different tags associated with different prompts. For example, when a node is tagged as “task”, it automatically triggers an AI command to generate a task list
Implement a task scheduling system that combines multiple nodes to complete a series of tasks. For example, automatically schedule daily reviews at 9 PM and insert review results into a review node (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.