denote-acme/README.md

acme-denote

(Denote) is based on the idea that notes should follow a predictable and descriptive file-naming scheme. The file name must offer a clear indication of what the note is about, without reference to any other metadata. Denote basically streamlines the creation of such files while providing facilities to link between them.

The goal of this program is to provide an implementation of prot's denote for Acme.

Use at Own Risk

While I use this program daily and do my best to fix bugs quickly, it is relatively new and I don't promise that it's bug-free. If you use this program, use good sense and keep regular backups of your denote directory. (Dbkp provided for convenience.)

Does it work on Plan 9?

Short answer: Maybe? I don't know. I use plan9port. If there are any regular Plan 9 users out there, I would be interested to know if it does, though. :)

Quick Start

This README assumes you already have plan9port installed.

mk install

This installs Denote and all its extensions to $HOME/bin.

Setup

Start the Denote program by middle-clicking Denote anywhere in acme. This will open the /Denote/ window.

Configuration:

Notes are stored in ~/doc by default. To change the default denote directory, edit pkg/config/config.go:

var DefaultDenoteDir = os.Getenv("HOME") + "/doc"

You can also switch between different directories at runtime using the Dsilo command (see Dsilo).

Usage

Create a note

In Acme, you can highlight something like:

'new note title' tag1,tag2,tagN

Pass it as input to the New tag with the 2-1 chord. This will create a new Acme window with Denote frontmatter and an appropriate file path. Important: the actual file is not created until the Put command is executed. (Tags are optional but recommended).

You can organize notes into subdirectories using the /: separator in the title:

'journal/:today's entry' journal
'projects/:new project' project,idea
'meetings/:standup notes' work,meeting

The text before /: becomes the subdirectory path (e.g., journal/, projects/, meetings/), and the text after becomes the note title. Subdirectories are created automatically if they don't exist. This is useful for organizing related notes together.

Open a note

First, be sure to set up the plumbing rules. Then, simply right-click on any identifier in the /Denote/ window.

Edit a note

Edit a note just like any other text file. Use Put to save. The Denote metadata will be refreshed automatically.

Delete a note

To delete a note, highlight its identifier in the /Denote/ window:

20251112T221141

Pass it as input to the Remove tag with the 2-1 chord. This will delete the note file from the filesystem and remove it from the index.

Search notes

Type some search pattern. Examples:

tag:tag1 tag:tag2
title:'my title'
'my title'
tag1
20251120

Highlight this and pass it as input to the Look command with the 2-1 chord. This will filter the list of entries to those that match the search query. Executing Look without arguments resets the search filter. You may also right-click in the Denote window on titles or tags to jump between matches.

Metadata Editing

Quality of life feature: you may edit metadata directly in the Denote window.

-------------------------------------------------------
/Denote/ Del Snarf | Look New Put Remove Get
-------------------------------------------------------
20251112T221141 | my dummy file 7 | dummy
20251112T221140 | my dummy file 6 | dummy
20251112T221139 | my dummy file 5 | dummy
20251112T221138 | my dummy file 4 | dummy
20251112T221137 | my dummy file 3 | dummy
20251112T221136 | my dummy file 2 | dummy
20251112T221135 | my dummy file 1 | dummy

-------------------------------------------------------
/Denote/ Del Snarf | Look New Put Remove Get
-------------------------------------------------------
20251112T221141 | you can edit | dummy
20251112T221140 | the titles | dummy
20251112T221139 | my dummy file 5 | or,the
20251112T221138 | my dummy file 4 | tags
20251112T221137 | or both at the same | time
20251112T221136 | my dummy file 2 | dummy
20251112T221135 | my dummy file 1 | dummy

Middle-click Put to write all metadata changes. This will rename files and, when possible, update front matter.

Get

Reload all notes from disk, discarding any uncommitted changes in the 9P metadata. Middle-click Get to do this. This is useful when notes are modified outside of Acme or when you want to discard metadata changes.

Encrypted Notes

You can integrate encrypted notes with acme-crypt CryptGet and CryptPut commands. This allows you to work with encrypted files (e.g., GPG-encrypted) directly from acme-denote.

Create a note with New as usual:

'secret note' private

This opens a window with a path like /home/user/doc/20251128T120000--secret-note__private.md. Add the appropriate encryption extension to the window path (e.g., .gpg for GPG encryption):

/home/user/doc/20251128T120000--secret-note__private.md.gpg

Write your note content, add CryptPut to the window tag, and middle-click it to save the encrypted file to disk. Then middle-click Get in the /Denote/ window to refresh the 9P index from disk.

Warning: If you accidentally click Put after CryptPut, the file will be overwritten with unencrypted content. If this happens, use CryptPut again to re-encrypt the file.

Drn

Update note metadata (title, tags, signature). Drn has two modes of operation:

Window Mode - Rename from an active note window:

From any open note window, highlight and execute:

Drn 'new title' tag1,tag2
Drn ==newsig 'new title' tag1,tag2

• Works on the window's buffer content
• Regular notes (.md, .org, .txt): Updates frontmatter in buffer
• The window must be Put after Drn to persist changes to disk

Interactive Mode - Rename by identifier:

From the /Denote/ window or anywhere in Acme, highlight and execute:

Drn 20251112T221141 'new title' tag1,tag2
Drn 20251112T221141 ==newsig 'new title' tag1,tag2

• Operates directly on the file
• Regular notes (.md, .org, .txt): Updates frontmatter in file + renames file
• Binary files (PDFs, images): Just renames file
• Changes are applied immediately to disk

File Format

By default notes are markdown files with YAML frontmatter:

• Identifier: YYYYMMDDTHHMMSS
• Filename: <id>--<title>__<tags>.md
• Search works on title and content

You may change this by changing ftype in main.go.

Signature Support

Denote supports an optional signature component in filenames: ID==SIGNATURE--TITLE__TAGS.ext. Signatures are useful for sequential numbering, context markers, or priorities.

Plumbing Configuration:

To plumb files with signatures, you must add = to the file pattern character classes in your plumbing rules. Update these three patterns:

Original patterns:

data matches '([.a-zA-Z<>-\uffff0-9_/\-@]*[a-zA-Z<>-\uffff0-9_/\-])':$twocolonaddr,$twocolonaddr
data matches '([.a-zA-Z<>-\uffff0-9_/\-@]*[a-zA-Z<>-\uffff0-9_/\-])':$twocolonaddr
data matches '([.a-zA-Z<>-\uffff0-9_/\-@]*[a-zA-Z<>-\uffff0-9_/\-])('$addr')?'

Modified patterns (add = to character classes):

data matches '([.a-zA-Z<>-\uffff0-9_/\-@=]*[a-zA-Z<>-\uffff0-9_/\-=])':$twocolonaddr,$twocolonaddr
data matches '([.a-zA-Z<>-\uffff0-9_/\-@=]*[a-zA-Z<>-\uffff0-9_/\-=])':$twocolonaddr
data matches '([.a-zA-Z<>-\uffff0-9_/\-@=]*[a-zA-Z<>-\uffff0-9_/\-=])('$addr')?'

Content Search (grep)

You can easily grep the current denote directory to search for content. Use the following pattern, example with ripgrep:

rg -Hn <search-expr> `{9p read denote/dir}

Extensions

Some extensions have also been ported. While these extensions, like the main program, try to stay as true as possible to the original program and be as feature-complete as possible, they are intentionally not exact replicas.

Djournal

Create or open journal entries with date-based titles. Supports daily, weekly, monthly, or yearly journals. Concept from prot's denote-journal.

Configuration:

Customize journal behavior by editing variables in the Djournal script:

# Journal interval: daily, weekly, monthly, yearly
interval=daily

# Title format: full, date, day, year
# Examples:
#   full: "wednesday 12 november 2025 22:11"
#   date: "wednesday 12 november 2025"
#   day:  "wednesday"
#   year: "2025"
titleformat=full

# Signature (optional, added to filename as ==signature)
signature=''

Basic Usage:

Open today's journal entry (creates if it doesn't exist):

Djournal

Journal entries are stored in journal/ subdirectory with the journal tag.

Time Navigation:

Navigate to past or future dates using time offsets:

Djournal +2d    # 2 days from now
Djournal -1d    # yesterday
Djournal -3h    # 3 hours ago
Djournal +30m   # 30 minutes from now

Supported units: d (days), h (hours), m (minutes). Hours and minutes is not useful except in an sub-daily intervals (e.g., hourly, not yet supported).

Dmerge

Merge notes together or move regions of text between notes while maintaining referential integrity. Concept from prot's denote-merge.

Configuration:

Customize annotations by editing variables in the Dmerge script:

# Annotation for merged files (set to '' to disable)
annotation='MERGED FILE:'

# Annotation for merged regions (set to '' to disable)
regionannotation='MERGED REGION:'

File Merge

Merge an entire note into another note:

Dmerge <source-id> <dest-id>

This will:

• Strip frontmatter from source note
• Append source content to destination note with annotation
• Update all backlinks pointing to source to point to destination
• Delete the source note file

Example:

Dmerge 20251125T120000 20251125T130000

Region Merge

Move a selected region of text from one note to another. Select text in an Acme window, then:

Dmerge <dest-id>

This will:

• Move the selected text to the destination note
• Replace the selection with a link to the destination: denote:<dest-id>
• Leave the source note open (dirty) for you to Put

With Formatting:

You can wrap the merged region in various formats:

Dmerge <dest-id> <format>

Available formats:

• plain - No formatting (default)
• plain-indented - Add 4-space indentation
• org-src - Org source block (#+begin_src / #+end_src)
• org-quote - Org quote block (#+begin_quote / #+end_quote)
• org-example - Org example block (#+begin_example / #+end_example)
• md-quote - Markdown blockquote (prefix with > )
• md-fence - Markdown fenced code block (```)

Examples:

Dmerge 20251125T130000 org-quote
Dmerge 20251125T130000 md-fence

Dbkp

Backup and restore your denote directory. Backups are timestamped tar.gz archives stored in $HOME/Dbkp/ by default.

Configuration:

Customize the backup directory by editing the variable in the Dbkp script:

# Configuration
backupdir=$HOME/Dbkp

Create Backup:

Create a timestamped backup of your denote directory:

Dbkp

This creates $backupdir/YYYYMMddTHHmmss-<denote-dir-name>-dbkp.tar.gz.

List Backups:

List all available backups:

Dbkp l

Output shows timestamps, one per line:

20251127T140558
20251127T142011
20251127T143725

Restore Backup:

Restore a backup to $denoteDir/restore/YYYYMMddTHHmmss/:

Dbkp 20251127T140558

The backup is extracted to a timestamped subdirectory within the restore directory, making it easy to identify when the backup was created.

Dsilo

Concept from prot's denote-silo. Switch between different denote directories (silos) at runtime without restarting the program.

Usage:

Show the current silo:

Dsilo

Switch to a different silo:

Dsilo /path/to/another/directory

What happens when you switch silos:

• The 9P filesystem immediately points to the new directory
• All existing notes are cleared from memory
• New notes are loaded from the new directory
• All subsequent operations (create, update, delete, search) use the new directory
• The Acme log watcher tracks files in the new directory

This is useful for maintaining separate collections of notes (e.g., personal notes, work notes, project notes) and switching between them seamlessly.

Possible Future Work

Templates

Not a core feature of acme-denote, but could be implemented as an extension (e.g., Dtmpl <path> or <tmpl> | Dtmpl). Possible approach:

• New Go binary, cmd/Dtmpl/
• Use text/template
• Read template and active window body
• Build template variable to value mapping
• Define common variables, e.g., {{date}}, {{author}}
• Render template and write to the active window body (echo <content> | 9p write acme/$winid/body)

Support Query "Links"

Support denote-query:<query> style "links" with plumbing (e.g., denote-query:project). Possible approach:

• New rc script, e.g., Dqry
  • Writes the query to denote/filter to mutate the index
  • Reads the index into a search results window
  • Writes empty query to denote/filter to reset the index
• Setup a new plumbing rule denote-query:<expr> to run Dqry