中文版说明

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:

1. 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
       

2. 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
3. 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:

1. Quick collection: Don’t worry about where to put things, just put everything in inbox first
2. Delayed organization: Organize when convenient
3. 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

1. Enter keywords (multiple keywords separated by spaces)
2. Select query results (multiple selections separated by commas)
3. 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

1. After selecting results, choose “Export to New File”
2. Enter new filename
3. 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

1. After selecting results, choose “Export to Existing File”
2. Select target file
3. 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

1. After selecting results, choose “Insert at Point”
2. 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.