Org Inline Tags

^ Sample text generated by ChatGPT 😉

Quick Start

Clone the repository or download the org-inline-tags.el file.
Add the following to your Emacs configuration:

(use-package org-inline-tags
 :load-path "/path/to/org-inline-tags")

Replace ~”/path/to/org-inline-tags”~ with the actual path to the directory containing org-inline-tags.el.

Introduction

org-inline-tags is an Emacs package that extends org-mode functionality by allowing users to add hashtag-style tags to plain list items (and plain text generally), making it easy to mark items for later review or action. Tags are fontified with a custom face to make them stand out visually, and are searchable via a custom command.

Features

Add hashtag-style tags to plain list items #likethis
Fontify tags with a custom face
Search for tagged items in the current buffer or project-wide
Insert predefined tags with a single keystroke

Dependencies

Emacs 26.1 or higher
Org 9.1 or higher
counsel-projectile-ag (optional)
consult-git-grep (optional)

Plain lists

A plain list in Emacs org-mode is what you think of when you think of a bulleted list — a simple, plain-text list. Each line begins with either a bullet or hyphen (an “unordered” i.e., bulleted list) or a number (an “ordered” i.e. numbered list).

Plain lists are useful for organizing information, capturing ideas, and creating outlines. The syntax for plain lists is simple and easy to manipulate, making them an ideal format for quickly and frictionlessly capturing and organizing ideas, notes, or tasks.

The org-inline-tags package enhances org-mode’s default plain list behavior by allowing you to add inline tags to individual list items, making it easier to categorize, search, and filter items so you can act on them later.

Why take notes as plain text lists?

I like the idea, popularized by Workflowy and Roam Research, that any text I type automatically sits within a hierarchical outline. Not all ideas are hierarchical, and that’s fine — I just don’t indent and every thought I record sits at the same level of hierarchy.
But if I hit upon an idea I want to drill down on, I can indent to the next level of the hierarchy to signal to myself that these new thoughts are now sub-items.
When I’m done drilling down on the sub-ideas, I outdent again so I can continue where I left off.

Why would plain lists need tags?

I take notes in plain text, not in the form of org-mode headings
As I’m writing, I often hit upon an idea I want to act on later in some way.
- a task I want to remember to do later #task
- an idea I want to think more about #thinkonthis
- an idea for a Tweet #tweet
- an idea I want to “cook” over time by coming back to it every day over a period of weeks and recording new thoughts each time
- a well-formed sentence I want to put in the book I’m writing #book
When I have an idea I want to act on later, I usually want to act on the idea itself, not the broader heading or category it’s under. But by default, org-mode tags can be added only to headings, not to plain lists. I don’t know about you, but when I’m trying to capture my ideas, I’m not typing them down in the form of org-mode headings.
I needed a way to flag ideas for later action without promoting a granular idea into a heading — a way that would flag not the general heading the idea falls under, but the specific idea or thought itself.
Hence the need for inline tags in plain lists. The org-inline-tags package provides this functionality, allowing users to easily tag and find ideas for later review or action.

Installation

Clone the repository or download the org-inline-tags.el file.
Add the following to your Emacs configuration:

(add-to-list 'load-path "/path/to/org-inline-tags") (require 'org-inline-tags)

Replace /path/to/org-inline-tags with the actual path to the directory containing org-inline-tags.el.

Manual installation

Download the `org-inline-tags.el` file from the GitHub repository.
Place the file in your Emacs load-path.
Add the following to your Emacs configuration:

(use-package 'org-inline-tags)

Usage

To insert a tag at the end of a plain list item, place the cursor at the end of the item and call the org-inline-tags-insert function with M-x org-inline-tags-insert or bind it to a key:

(global-set-key (kbd "C-c t") 'org-inline-tags-insert)

When prompted, select a predefined tag by pressing the corresponding key:

makefiler: review b: book t: todo u: urgent p: tweet i: insight c: cook-ideas-over-time

Searching for tagged items

To search for items tagged with a specific tag in the current buffer, call the org-inline-tags-search-buffer function with M-x org-inline-tags-search-buffer and enter the tag you’re looking for.

To search for items tagged with a specific tag project-wide, call the org-inline-tags-search-project-wide function with M-x org-inline-tags-search-project-wide and enter the tag you’re looking for. This function requires consult-git-grep.

The org-inline-tags-search-project-wide function in this package allows you to search for inline tags across your entire project. If you have the consult package installed, it will use consult-git-grep for this search. consult-git-grep provides a fast and convenient interface for searching Git repositories. If consult-git-grep is not available, the function will fall back to using the occur function, which will search for the tag in the current buffer. Please note that occur only searches the current buffer, so it’s not a direct replacement for consult-git-grep. If you frequently need to search for tags project-wide, we recommend installing the consult package for the best experience.”

Customization

To customize on your setup, you can modify the org-inline-tags-face face to change the appearance of tags:

(custom-set-faces
'(org-inline-tags-face ((t (:foreground "your-color" :weight bold)))))

Replace ~”your-color”~ with the desired color for the tags.

You can also customize the predefined tags by modifying the tag-alist within the org-inline-tags-insert function.

If you prefer different keybindings, you can customize them in your Emacs configuration. For example, to bind `org-inline-tag-insert` to `C-c C-t`, add the following to your configuration:

(define-key org-mode-map (kbd "C-c C-t") #'org-inline-tag-insert)

Contributing

Contributions are welcome! I’m not a programmer and I truly have no idea what I’m doing. Please open an issue or submit a pull request on the GitHub repository.

Features I Need Help Implementing

Improved tag search via consult-ripgrep

Tag search via consult-ripgrep kind of works… but as of now, the user has to manually go to the beginning of the line in the minibuffer and add a \ before the #.
- This is because consult-ripgrep automatically pre-fills the search query with a #, which is interpreted not as a symbol. To require the search to match the # at the beginning of the tag, we need to add a \ before the #.
- I tried to get the function to do this automatically — or rather, I tried to get ChatGPT to do it — but it couldn’t figure out how. You can see the failed attempts here.
Ideally, the user could call org-inline-tags-search-project-wide and just enter a text string like “psychology” to initiate a project-wide tag search, without having to manually enter \# at the beginning of the query.

Automatic tag search

Ideally, when the point is on an inline tag, the user could simply hit RETURN to automatically perform a project-wide search for that tag. This almost works, but currently has two limitations:

As mentioned above, the user has to manually enter \# at the beginning of the query.
Instead of being pre-filled with the tag at point, the user has to enter the tag manually.

License

This project is licensed under the GNU General Public License v3.0 or later. See the LICENSE file for details.

incandescentman / org-inline-tags