acme-denote

Denote note management for the acme editor. Implements the denote file naming convention with search, filtering, and journaling capabilities.

File Naming Convention

Notes follow the denote naming pattern:

IDENTIFIER--TITLE__KEYWORDS.EXT
IDENTIFIER==SIGNATURE--TITLE__KEYWORDS.EXT  (with optional signature)

Where:

• IDENTIFIER: Timestamp in format YYYYMMDDTHHmmss
• SIGNATURE: Optional signature field
• TITLE: Hyphen-separated title (spaces become hyphens)
• KEYWORDS: Underscore-separated tags
• EXT: File extension (.org, .md, .txt)

Example: 20251103T183000--meeting-notes__work_project.md

Commands

Denote

Search and manage denote notes.

Usage in acme:

Denote                              # List all notes (sorted by ID, newest first)
Denote tag:meeting                  # Notes tagged 'meeting'
Denote date:/2025.*/                # Notes from 2025
Denote date:/202510.*/ !tag:journal # October 2025, not journal
Denote new 'My Note' tag1 tag2      # Create new note
Denote sort:title                   # List all notes sorted alphabetically
Denote tag:journal sort:title       # Journal entries sorted by title

Filter syntax:

• date:/regex/ - Match date/identifier
• title:/regex/ - Match title (from filename or file content)
• tag:/regex/ - Match tags/keywords
• /regex/ - Match any field
• !filter - Negate filter
• plain-text - Exact match (no regex)

Sort options:

• sort:id - Sort by identifier/date (default, newest first)
• sort:date - Sort by date (same as ID)
• sort:title - Sort alphabetically by title

Creating notes:

Denote new 'Meeting Notes' work project
Denote new -f org 'Todo List' tasks
Denote new -f txt 'Journal Entry' journal
Denote new -e 'Secret Notes' encrypted

Options:

• -f type - File type (default: md-yaml). Supported: org, md-yaml, md-toml, txt
• -e - Encrypt the file using GPG (requires acme-crypt and ACME_CRYPT_RCPT environment variable)

Renaming notes:

Denote rename /path/to/file.md                    # Use front matter title/tags
Denote rename /path/to/file.md New Title          # Update title, keep tags
Denote rename /path/to/file.md New Title tag1 tag2  # Update title and tags

The rename command:

• Updates front matter (if file supports it)
• Renames file according to denote convention
• Preserves identifier from filename or front matter
• Extracts title from front matter or first heading if no arguments provided

Opening notes by identifier:

Denote open 20251103T183000

Opens a note by its identifier. This is particularly useful with plumbing integration - see PLUMBING.md for how to make denote:<identifier> links clickable in acme.

Journal

Daily journaling with automatic date-based titles.

Usage in acme:

Journal              # Find or create today's entry
Journal 20251025     # Find or create entry for specific date (YYYYMMDD)
Journal +1d          # Tomorrow
Journal -1d          # Yesterday
Journal +3d          # 3 days from now
Journal +2h          # 2 hours from now
Journal -30m         # 30 minutes ago
Journal add          # Create additional entry for today
Journal add 20251025 # Create entry for specific date (YYYYMMDD)

Relative dates:

• +/-Nd - days (e.g., +1d, -7d)
• +/-Nh - hours (e.g., +2h, -5h)
• +/-Nm - minutes (e.g., +15m, -30m)
• +/-Ns - seconds (e.g., +30s, -45s)

Journal encryption:

Journal -e              # Create encrypted journal entry (requires -e flag or config)
Journal -f org -e       # Create encrypted org journal entry

Options:

• -f type - File type (default: md-yaml). Supported: org, md-yaml, md-toml, txt
• -e - Encrypt the journal entry using GPG (requires acme-crypt and ACME_CRYPT_RCPT environment variable)

Configuration file: ~/.config/acme-denote/journal.cfg

always_encrypt = true

• Set always_encrypt = true to encrypt all journal entries by default
• The -e flag can still be used to encrypt individual entries when always_encrypt = false
• If configuration file doesn't exist, defaults to no encryption

Journal entries are automatically:

• Titled with format: "Monday 3 November 2025 16:56"
• Tagged with journal
• Stored in $JOURNAL_DIR subdirectory (default: journal/)
• Encrypted with .gpg extension when using -e flag or always_encrypt = true

Acme Integration

Both commands output to a +Denote window with clickable results. Output format:

denote:20251103T183000 | Meeting Notes | work, project
denote:20251103T090000 | Monday 3 November 2025 09:00 | journal

The denote:<identifier> prefix makes results clickable when plumbing is configured - see PLUMBING.md for setup instructions.

Workflows:

Simple execution:

1. Middle-click Denote tag:work in tag bar or scratch window
2. Results appear in +Denote window
3. Right-click file paths to open notes

Mouse chording (argument passing):

1. Type or select filter arguments: tag:mytag date:20251010
2. Middle+left chord on Denote command
3. Selected text becomes arguments to Denote

Creating notes:

1. Middle-click Denote new 'Title' tags in scratch window
2. Or chord: select 'My Title' work urgent, middle+left on Denote new

Renaming notes:

1. Select file path and new title/tags: /path/to/file.md New Title tag1 tag2
2. Middle+left chord on Denote rename
3. Or middle-click Denote rename /path/to/file.md to use existing front matter

Quick journal access:

1. Middle-click Journal anywhere
2. Shows today's entry in the search result, creating it if necessary

Configuration

Environment variables:

• DENOTE_DIR - Base directory for notes (default: ~/doc)
• JOURNAL_DIR - Subdirectory for journal entries (default: journal)

Example:

export DENOTE_DIR="$HOME/notes"
export JOURNAL_DIR="daily"

Installation

mk install

Installs Denote and Journal to ~/bin/.

GPG File Support

For encrypted .gpg files, install acme-crypt:

git clone https://github.com/lneely/acme-crypt
cd acme-crypt && mk install
export ACME_CRYPT_RCPT="your@email.com"  # Your GPG key for encryption

acme-denote will automatically detect .gpg files and use CryptGet to open them with decryption support in acme. To create encrypted notes, use the -e flag with Denote new.

Front Matter

Notes include front matter based on file type:

Markdown (YAML):

---
title:      "Meeting Notes"
date:       2025-11-03 Mon 18:30
tags:       [work, project]
identifier: "20251103T183000"
---

Org-mode:

#+title:      Meeting Notes
#+date:       [2025-11-03 Mon 18:30]
#+filetags:   :work:project:
#+identifier: 20251103T183000

Text:

title:      Meeting Notes
date:       2025-11-03 Mon 18:30
tags:       work project
identifier: 20251103T183000

Title Extraction

The title: field in search results is extracted from:

1. Front matter (#+title: for org, title: for markdown)
2. First heading (* Heading for org, # Heading for markdown)
3. Filename title component (fallback)

This allows searching by actual document titles, not just filenames.