feat: support per-entry aliases in journal templates

Add an :aliases key to vulpea-journal-template-daily and
vulpea-journal-template-monthly. Each element is a strftime string
expanded on the entry's date (or a function of the date), written to
vulpea-buffer-alias-property so an entry can be linked by a short stamp
instead of its heading title. Static strings pass through; multi-word
aliases are quoted.

Also fix the monthly heading path dropping the template :properties: it
now merges them with the journal-managed CREATED property instead of
writing only CREATED (same family as the earlier :body drop).

The spec helpers shared with :entry-groups are generalized
(--normalize-specs, --resolve-spec) and reused for :aliases.

Refs #16

Author: d12frosted

CHANGELOG.org

@@ -11,13 +11,15 @@
 - New =vulpea-journal-tag= customization variable for configuring the journal tag. Template builders use it as the default, and =vulpea-journal-note-p= checks against it directly. ([[https://github.com/d12frosted/vulpea-journal/pull/12][#12]])
 - Monthly journal granularity: one file per month with daily entries as headings. Use =vulpea-journal-template-monthly= to create a monthly template. ([[https://github.com/d12frosted/vulpea-journal/issues/2][#2]])
 - Monthly templates can nest daily entries under date-derived grouping headings via the new =:entry-groups= key of =vulpea-journal-template-monthly=. Each element (a strftime string such as ="week %V"= or a function of the date) adds one heading level between the file and the entry; group headings are created and reused on demand, and =:entry-level= is derived from the number of groups so lookup and creation agree. ([[https://github.com/d12frosted/vulpea-journal/issues/16][#16]])
+- Journal templates can attach computed or static aliases to each entry via the new =:aliases= key of =vulpea-journal-template-daily= and =vulpea-journal-template-monthly=. Each element is a strftime string expanded for the entry's date (e.g. ="%Y-%m-%d"=) or a function of the date; aliases are written to the property named by =vulpea-buffer-alias-property= so an entry can be linked by a short stamp instead of its heading title. ([[https://github.com/d12frosted/vulpea-journal/issues/16][#16]])
 - Template builder functions: =vulpea-journal-template-daily= and =vulpea-journal-template-monthly= with sensible defaults and override support.
 - Active date tracking for sidebar widgets, ensuring correct behavior when navigating between entries in the same file.
 - Migration script now adds journal filetag to migrated files using =vulpea-buffer-tags-add=. ([[https://github.com/d12frosted/vulpea-journal/pull/12][#12]])
 
 ** Fixed
 
 - Fix =:body= from monthly templates being silently dropped for heading-level entries. =vulpea-journal--create-heading-note= now passes the template =:body= through to =vulpea-create=, matching the file-level (daily) path. ([[https://github.com/d12frosted/vulpea-journal/issues/16][#16]])
+- Fix template =:properties= being dropped for monthly (heading-level) entries. =vulpea-journal--create-heading-note= now merges the template =:properties= with the journal-managed =CREATED= property instead of writing only =CREATED=, matching the file-level (daily) path. ([[https://github.com/d12frosted/vulpea-journal/issues/16][#16]])
 - Fix selected day not being highlighted in the calendar widget when the optional =hl-line= library is not loaded. =vulpea-journal-ui-calendar-selected= now inherits from the always-available =highlight= face instead of =hl-line=. ([[https://github.com/d12frosted/vulpea-journal/issues/14][#14]])
 - Fix outdated =vulpea-db-sync= references in README — the function was renamed to =vulpea-db-sync-full-scan= in vulpea. ([[https://github.com/d12frosted/vulpea-journal/issues/11][#11]])
 - Fix journal entries not found after database rebuild (=vulpea-db-sync-full-scan=). Root cause: when =vulpea-db-sync-directories= contains =~= paths (e.g., =~/notes=), the sync stored them unexpanded in the database while the journal always expanded them (e.g., =/home/user/notes=), causing exact-match lookups to fail. Fixed in vulpea by expanding paths in =vulpea-db-sync--list-org-files=. Also adds =abbreviate-file-name= and =file-truename= fallbacks in =vulpea-journal-find-note= for defense-in-depth. ([[https://github.com/d12frosted/vulpea-journal/issues/5][#5]])

README.org

@@ -182,6 +182,7 @@ Monthly template parameters:
 | =:entry-level=  | =1=                 | Heading level for daily entries (derived when =:entry-groups= is set) |
 | =:entry-title=  | =%d %A=             | strftime format for heading      |
 | =:entry-groups= | =nil=               | Optional grouping headings (see below) |
+| =:aliases=      | =nil=               | Per-entry aliases, computed or static (see below) |
 | =:tags=         | =("journal")=       | Tags (first one identifies journals) |
 
 By default, daily entries are placed directly under the monthly file. To nest them under intermediate grouping headings (for example, one heading per ISO week), use =:entry-groups=:
@@ -214,6 +215,20 @@ Each element of =:entry-groups= adds one heading level between the file and the
 
 Because =:body= is inserted verbatim at fixed heading levels, nest its subheadings one level below the entry (=***= for entries at level 2, as above).
 
+*** Entry aliases
+
+Give each entry an alias (or several) with =:aliases=, so you can link to it by a short stamp instead of its full heading title. Each element is a =strftime= string expanded for the entry's date, or a function of the date; a single spec needs no list. Works for daily and monthly templates.
+
+#+begin_src emacs-lisp
+(setq vulpea-journal-default-template
+      (vulpea-journal-template-monthly
+       :entry-title  "journal <%Y-%m-%d %a %H:%M>"
+       :entry-groups '("week %V")
+       :aliases      '("%Y-%m-%d")))
+#+end_src
+
+Every entry then carries a =2026-06-08= style alias (computed from the entry's date, not today), written to the property named by =vulpea-buffer-alias-property= (=ALIASES= by default, =ROAM_ALIASES= if you configure it). See the vulpea user guide, "Managing Aliases", for how aliases are searched and linked.
+
 *** Raw template plist
 
 You can also provide a raw plist directly:

test/vulpea-journal-test.el

@@ -517,6 +517,68 @@ after a full scan rebuild."
         (should (string= (vulpea-note-id (vulpea-journal-find-note d2))
                          (vulpea-note-id n2)))))))
 
+;;; Entry Alias Tests
+
+(ert-deftest vulpea-journal-template-aliases ()
+  "Test :aliases is normalized and stored by the template builders."
+  ;; A single spec is normalized to a one-element list.
+  (let ((tpl (vulpea-journal-template-monthly :aliases "%Y-%m-%d")))
+    (should (equal (plist-get tpl :aliases) '("%Y-%m-%d"))))
+  ;; A list is stored as-is, and daily accepts it too.
+  (let ((tpl (vulpea-journal-template-daily :aliases '("%Y-%m-%d" "alt"))))
+    (should (equal (plist-get tpl :aliases) '("%Y-%m-%d" "alt")))))
+
+(ert-deftest vulpea-journal-monthly-entry-aliases-computed ()
+  "Test monthly entries get an alias computed on the entry's date."
+  (vulpea-test--with-temp-db
+    (let* ((vulpea-journal-default-template
+            (vulpea-journal-template-monthly :aliases '("%Y-%m-%d")))
+           (date (encode-time 0 0 12 8 6 2026)))
+      (let ((note (vulpea-journal-note date)))
+        ;; Alias reflects the entry's date, not the current date.
+        (should (member "2026-06-08" (vulpea-note-aliases note)))))))
+
+(ert-deftest vulpea-journal-daily-entry-aliases-computed ()
+  "Test daily entries get an alias computed on the entry's date."
+  (vulpea-test--with-temp-db
+    (let* ((vulpea-journal-default-template
+            (vulpea-journal-template-daily :aliases '("%Y-%m-%d")))
+           (date (encode-time 0 0 12 8 6 2026)))
+      (let ((note (vulpea-journal-note date)))
+        (should (member "2026-06-08" (vulpea-note-aliases note)))))))
+
+(ert-deftest vulpea-journal-entry-aliases-static-multiword ()
+  "Test a static multi-word alias round-trips as a single alias."
+  (vulpea-test--with-temp-db
+    (let* ((vulpea-journal-default-template
+            (vulpea-journal-template-daily :aliases '("Daily Log")))
+           (date (encode-time 0 0 12 8 6 2026)))
+      (let ((note (vulpea-journal-note date)))
+        (should (member "Daily Log" (vulpea-note-aliases note)))))))
+
+(ert-deftest vulpea-journal-entry-aliases-custom-property ()
+  "Test aliases honor a custom `vulpea-buffer-alias-property'."
+  (vulpea-test--with-temp-db
+    (let* ((vulpea-buffer-alias-property "ROAM_ALIASES")
+           (vulpea-journal-default-template
+            (vulpea-journal-template-daily :aliases '("%Y-%m-%d")))
+           (date (encode-time 0 0 12 8 6 2026)))
+      (let ((note (vulpea-journal-note date)))
+        (should (member "2026-06-08" (vulpea-note-aliases note)))
+        (should (assoc "ROAM_ALIASES" (vulpea-note-properties note)))))))
+
+(ert-deftest vulpea-journal-monthly-entry-properties ()
+  "Test monthly entries honor template :properties alongside CREATED."
+  (vulpea-test--with-temp-db
+    (let* ((vulpea-journal-default-template
+            (vulpea-journal-template-monthly
+             :properties '(("FOO" . "bar"))))
+           (date (encode-time 0 0 12 8 6 2026)))
+      (let ((note (vulpea-journal-note date)))
+        (should (equal (cdr (assoc "FOO" (vulpea-note-properties note))) "bar"))
+        ;; CREATED is still written by the journal.
+        (should (assoc "CREATED" (vulpea-note-properties note)))))))
+
 (ert-deftest vulpea-journal-monthly-find-note ()
   "Test finding a monthly journal note by date."
   (vulpea-test--with-temp-db

vulpea-journal.el

@@ -137,22 +137,22 @@ Or as a function for dynamic configuration:
 
 ;;; Template Builders
 
-(defun vulpea-journal--normalize-groups (groups)
-  "Normalize GROUPS into a list of group specs.
-GROUPS may be nil, a single spec (a strftime string or a function
+(defun vulpea-journal--normalize-specs (specs)
+  "Normalize SPECS into a list of template specs.
+SPECS may be nil, a single spec (a strftime string or a function
 of one argument DATE), or a list of such specs.  A single spec is
-wrapped in a one-element list."
+wrapped in a one-element list.  Shared by :entry-groups and :aliases."
   (cond
-   ((null groups) nil)
-   ((or (stringp groups) (functionp groups)) (list groups))
-   ((listp groups) groups)
-   (t (error "Invalid :entry-groups value: %S" groups))))
+   ((null specs) nil)
+   ((or (stringp specs) (functionp specs)) (list specs))
+   ((listp specs) specs)
+   (t (error "Invalid template spec list: %S" specs))))
 
 (cl-defun vulpea-journal-template-daily (&key
                                          (file-name "journal/%Y-%m-%d.org")
                                          (title "%Y-%m-%d %A")
                                          (tags (list vulpea-journal-tag))
-                                         head body properties meta context)
+                                         aliases head body properties meta context)
   "Create a daily journal template (one file per day).
 
 Returns a plist suitable for `vulpea-journal-default-template'.
@@ -161,9 +161,16 @@ All parameters are optional with sensible defaults:
 - FILE-NAME: strftime format for file path (default: journal/%Y-%m-%d.org)
 - TITLE: strftime format for note title (default: %Y-%m-%d %A)
 - TAGS: list of tags (default: (\"journal\"))
+- ALIASES: optional note aliases, computed per entry.  Each element is
+  a strftime string expanded for the entry's date (e.g. \"%Y-%m-%d\")
+  or a function of one argument (DATE) returning the alias; a single
+  spec may be given without a list.  Written to the property named by
+  `vulpea-buffer-alias-property' so the entry can be linked by a short
+  stamp instead of its title.
 - HEAD, BODY, PROPERTIES, META, CONTEXT: passed to `vulpea-create'"
   (append
    (list :file-name file-name :title title :tags tags)
+   (when aliases (list :aliases (vulpea-journal--normalize-specs aliases)))
    (when head (list :head head))
    (when body (list :body body))
    (when properties (list :properties properties))
@@ -177,7 +184,7 @@ All parameters are optional with sensible defaults:
                                            (entry-level 1)
                                            (entry-title "%d %A")
                                            entry-groups
-                                           head body properties meta context)
+                                           aliases head body properties meta context)
   "Create a monthly journal template (one file per month).
 
 Daily entries are created as headings inside the monthly file.
@@ -200,13 +207,20 @@ All parameters are optional with sensible defaults:
   1 + number of groups so lookup and creation agree.  For example,
   :entry-groups \\='(\"week %V\") nests each day under a \"week NN\"
   heading and entries live at level 2.
+- ALIASES: optional note aliases, computed per entry.  Each element is
+  a strftime string expanded for the entry's date (e.g. \"%Y-%m-%d\")
+  or a function of one argument (DATE) returning the alias; a single
+  spec may be given without a list.  Written to the property named by
+  `vulpea-buffer-alias-property' so the entry can be linked by a short
+  stamp instead of its title.
 - HEAD, BODY, PROPERTIES, META, CONTEXT: passed to `vulpea-create'"
-  (let* ((groups (vulpea-journal--normalize-groups entry-groups))
+  (let* ((groups (vulpea-journal--normalize-specs entry-groups))
          (entry-level (if groups (1+ (length groups)) entry-level)))
     (append
      (list :file-name file-name :title title :tags tags
            :entry-level entry-level :entry-title entry-title)
      (when groups (list :entry-groups groups))
+     (when aliases (list :aliases (vulpea-journal--normalize-specs aliases)))
      (when head (list :head head))
      (when body (list :body body))
      (when properties (list :properties properties))
@@ -426,19 +440,51 @@ an ID property and running `vulpea-db-sync-full-scan'" file))
      :tags (plist-get tpl :tags)
      :head (plist-get tpl :head)
      :body (plist-get tpl :body)
-     :properties (plist-get tpl :properties)
+     :properties (vulpea-journal--entry-properties tpl date nil)
      :meta (plist-get tpl :meta)
      :context (plist-get tpl :context))
     (vulpea-db-get-by-id id)))
 
-(defun vulpea-journal--resolve-group-title (spec date)
-  "Resolve group SPEC to a heading title for DATE.
-SPEC is either a strftime format string or a function of one
-argument (DATE) returning a string."
+(defun vulpea-journal--resolve-spec (spec date)
+  "Resolve template SPEC for DATE to a string.
+SPEC is either a strftime format string (expanded for DATE) or a
+function of one argument (DATE) returning a string.  Shared by
+:entry-groups and :aliases."
   (cond
    ((functionp spec) (funcall spec date))
    ((stringp spec) (format-time-string spec date))
-   (t (error "Invalid :entry-groups spec: %S" spec))))
+   (t (error "Invalid template spec: %S" spec))))
+
+(defun vulpea-journal--resolve-aliases (tpl date)
+  "Return the list of resolved alias strings for DATE from TPL.
+Each TPL :aliases spec is resolved via `vulpea-journal--resolve-spec'.
+Returns nil when TPL has no :aliases."
+  (mapcar (lambda (spec) (vulpea-journal--resolve-spec spec date))
+          (vulpea-journal--normalize-specs (plist-get tpl :aliases))))
+
+(defun vulpea-journal--alias-property (aliases)
+  "Return a one-element alist setting the alias property for ALIASES.
+The property name is `vulpea-buffer-alias-property'.  An alias that
+contains whitespace or a double quote is wrapped in double quotes,
+matching how vulpea stores and parses aliases.  Returns nil when
+ALIASES is empty."
+  (when aliases
+    (list (cons vulpea-buffer-alias-property
+                (mapconcat
+                 (lambda (alias)
+                   (if (string-match-p "[ \t\"]" alias)
+                       (format "%S" alias)
+                     alias))
+                 aliases " ")))))
+
+(defun vulpea-journal--entry-properties (tpl date base)
+  "Build the property alist for a journal entry on DATE.
+BASE is an alist of journal-managed properties (e.g. CREATED).
+Appends TPL :properties and the resolved :aliases property."
+  (append base
+          (plist-get tpl :properties)
+          (vulpea-journal--alias-property
+           (vulpea-journal--resolve-aliases tpl date))))
 
 (defun vulpea-journal--find-child-heading (file level title outline-path)
   "Find heading note in FILE at LEVEL titled TITLE under OUTLINE-PATH.
@@ -452,15 +498,15 @@ first.  Returns the matching `vulpea-note' or nil."
 (defun vulpea-journal--ensure-group-path (container date groups)
   "Ensure the chain of GROUPS headings under CONTAINER for DATE.
 CONTAINER is the file-level container `vulpea-note'.  GROUPS is a
-list of group specs (see `vulpea-journal--resolve-group-title').
+list of group specs (see `vulpea-journal--resolve-spec').
 Missing group headings are created on demand and existing ones are
 reused.  Returns the deepest container note that should parent the
 entry, which is CONTAINER itself when GROUPS is empty."
   (let ((parent container)
         (file (vulpea-note-path container))
         (ancestry nil))
-    (dolist (spec (vulpea-journal--normalize-groups groups) parent)
-      (let* ((title (vulpea-journal--resolve-group-title spec date))
+    (dolist (spec (vulpea-journal--normalize-specs groups) parent)
+      (let* ((title (vulpea-journal--resolve-spec spec date))
              (level (1+ (vulpea-note-level parent)))
              (existing (vulpea-journal--find-child-heading
                         file level title (reverse ancestry))))
@@ -492,7 +538,8 @@ chain of date-derived grouping headings (created on demand)."
      nil
      :parent parent
      :body (plist-get tpl :body)
-     :properties `(("CREATED" . ,date-str))
+     :properties (vulpea-journal--entry-properties
+                  tpl date `(("CREATED" . ,date-str)))
      :after 'last)))
 
 (defun vulpea-journal--ensure-container (file date tpl)