Vulpea Journal

#+title: vulpea-journal #+author: Boris Buliga

#+begin_html

A journaling interface for [[https://github.com/d12frosted/vulpea][vulpea]] that integrates seamlessly with [[https://github.com/d12frosted/vulpea-ui][vulpea-ui]] sidebar.

• What is vulpea-journal?

vulpea-journal brings the power of journaling to your vulpea-based note system. Think of it as [[https://github.com/bastibe/org-journal][org-journal]] rebuilt from the ground up for vulpea, with a modern reactive UI.

Key features:

• Flexible granularity - One file per day, or one file per month with daily headings
• Sidebar widgets - Calendar, navigation, related notes - all in the vulpea-ui sidebar
• Calendar integration - See which days have entries, jump to any date
• Previous years - "On this day" view showing what you wrote in past years
• Zero window management - Uses vulpea-ui sidebar, no custom layouts to break

• Quick Start

** 1. Install

vulpea-journal requires:

• Emacs 29.1+
• [[https://github.com/d12frosted/vulpea][vulpea]] 2.0+
• [[https://github.com/d12frosted/vulpea-ui][vulpea-ui]] 1.0+
• [[https://github.com/magnars/dash.el][dash]] 2.20+

*** Using package.el (MELPA)

#+begin_src emacs-lisp (package-install 'vulpea-journal) #+end_src

*** Using straight.el

#+begin_src emacs-lisp (straight-use-package 'vulpea-journal) #+end_src

*** Using elpaca

#+begin_src emacs-lisp (elpaca vulpea-journal) #+end_src

*** Using Doom Emacs

In =packages.el=:

#+begin_src emacs-lisp (package! vulpea-journal) #+end_src

In =config.el=:

#+begin_src emacs-lisp (use-package! vulpea-journal :after (vulpea vulpea-ui) :config (vulpea-journal-setup)) #+end_src

*** Configuration

#+begin_src emacs-lisp (use-package vulpea-journal :after (vulpea vulpea-ui) :config (vulpea-journal-setup)) #+end_src

** 2. Widgets are auto-registered

=vulpea-journal-setup= automatically loads =vulpea-journal-ui= and registers all sidebar widgets — you don't need to require it separately. Widgets only appear when viewing journal notes.

Default widget order interleaves with vulpea-ui widgets:

| Widget | Order | Appears... | |------------------+-------+---------------------| | journal-nav | 50 | Before stats | | stats | 100 | (vulpea-ui) | | journal-calendar | 150 | After stats | | outline | 200 | (vulpea-ui) | | backlinks | 300 | (vulpea-ui) | | created-today | 350 | After backlinks | | previous-years | 360 | After created-today | | links | 400 | (vulpea-ui) |

To customize the order, see [[*Widget Order Configuration][Widget Order Configuration]] below.

** 3. Add a keybinding

#+begin_src emacs-lisp (global-set-key (kbd "C-c j") #'vulpea-journal) #+end_src

** 4. Start journaling!

Press =C-c j= to open today's journal. The sidebar will show journal-specific widgets.

• How It Works

** Journal Notes

Journal notes are regular vulpea notes identified by a tag (default: ="journal"=). Depending on the template granularity:

• Daily (default): one file per day (e.g., =journal/2025-12-08.org=)
• Monthly: one file per month (e.g., =journal/2025-12.org=) with daily entries as headings (e.g., =* 08 Monday=)

Each note has a CREATED property storing the date for querying.

When you call =vulpea-journal=, it:

1. Finds or creates the note for that date
2. Opens it in your main window (for monthly, navigates to the heading)
3. Shows the vulpea-ui sidebar with journal widgets

** Sidebar Integration

vulpea-journal doesn't create its own windows. Instead, it provides widgets that plug into vulpea-ui's sidebar system. This means:

• No window management bugs
• Consistent UI with the rest of vulpea-ui
• Widgets automatically appear/disappear based on what you're viewing

Journal widgets check if the current note is a journal entry. When you view a non-journal note, they simply hide themselves.

• Configuration

** Template

Customize how journal notes are created. Use the template builder functions for convenience:

*** Daily (one file per day, default)

#+begin_src emacs-lisp (setq vulpea-journal-default-template (vulpea-journal-template-daily)) #+end_src

This is equivalent to the default behavior. You can override any parameter:

#+begin_src emacs-lisp (setq vulpea-journal-default-template (vulpea-journal-template-daily :file-name "daily/%Y-%m-%d.org" :title "%A, %B %d, %Y" :body "* Morning\n\n* Evening\n")) #+end_src

*** Monthly (one file per month)

#+begin_src emacs-lisp (setq vulpea-journal-default-template (vulpea-journal-template-monthly)) #+end_src

This creates one file per month (e.g., =journal/2025-12.org=) with each day as a heading (e.g., =* 08 Monday=). Override any parameter:

#+begin_src emacs-lisp (setq vulpea-journal-default-template (vulpea-journal-template-monthly :file-name "journal/%Y/%m.org" :entry-title "%d %A")) #+end_src

Monthly template parameters:

| Parameter | Default | Description | |-----------------+--------------------+----------------------------------| | =:file-name= | =journal/%Y-%m.org= | strftime format for monthly file | | =:title= | =%Y-%m= | File-level note title | | =:entry-level= | =1= | Heading level for daily entries | | =:entry-title= | =%d %A= | strftime format for heading | | =:tags= | =("journal")= | Tags (first one identifies journals) |

*** Raw template plist

You can also provide a raw plist directly:

#+begin_src emacs-lisp (setq vulpea-journal-default-template '(:file-name "journal/%Y-%m-%d.org" ; File path (strftime format) :title "%Y-%m-%d %A" ; Note title (strftime format) :tags ("journal") ; Tags (first one identifies journals) :head "#+created: %<[%Y-%m-%d]>" ; Header content :body "* Morning\n\n* Evening\n")) ; Initial body #+end_src

Important: The =:file-name=, =:title=, and =:entry-title= use =strftime= format because they're expanded for the /target date/, not the current time. When you open the journal for December 25th, the file will be =journal/2025-12-25.org= regardless of today's date.

Other keys (=:head=, =:body=) use vulpea's =%= syntax and are expanded at creation time.

*** Dynamic Templates

For more control, use a function:

#+begin_src emacs-lisp (setq vulpea-journal-default-template (lambda (date) (let ((weekday (format-time-string "%u" date))) (list :file-name "journal/%Y-%m-%d.org" :title (format-time-string "%Y-%m-%d %A" date) :tags '("journal") :head "#+created: %<[%Y-%m-%d]>" :body (if (member weekday '("6" "7")) "* Weekend\n\n" "* Work\n\n* Personal\n"))))) #+end_src

** Calendar Widget

#+begin_src emacs-lisp ;; Start week on Sunday (0) or Monday (1, default) (setq vulpea-journal-ui-calendar-week-start 1) #+end_src

** Created Today Widget

#+begin_src emacs-lisp ;; Include journal notes in the "created today" list (setq vulpea-journal-ui-created-today-exclude-journal nil) ; default: t #+end_src

** Previous Years Widget

#+begin_src emacs-lisp ;; How many years to look back (setq vulpea-journal-ui-previous-years-count 5) ; default: 5

;; Characters to show in preview (setq vulpea-journal-ui-previous-years-preview-chars 256)

;; Hide org drawers in preview (setq vulpea-journal-ui-previous-years-hide-drawers t) ; default: t

;; Start with previews expanded (setq vulpea-journal-ui-previous-years-expanded t) ; default: t #+end_src

** Widget Order Configuration

Customize where journal widgets appear relative to vulpea-ui widgets:

#+begin_src emacs-lisp (setq vulpea-journal-ui-widget-orders '((nav . 50) ; before stats (100) (calendar . 150) ; after stats, before outline (200) (created-today . 350) ; after backlinks (300) (previous-years . 360))) #+end_src

Example: Move calendar before stats:

#+begin_src emacs-lisp (use-package vulpea-journal :custom (vulpea-journal-ui-widget-orders '((nav . 50) (calendar . 90) ; now before stats (created-today . 350) (previous-years . 360)))) #+end_src

Reference orders for vulpea-ui widgets: stats=100, outline=200, backlinks=300, links=400.

• Commands

| Command | Description | |---------------------------+---------------------------------------------------------| | =vulpea-journal= | Open today's journal (or specify date programmatically) | | =vulpea-journal-today= | Open today's journal | | =vulpea-journal-date= | Prompt for a date and open its journal | | =vulpea-journal-next= | Go to next journal entry | | =vulpea-journal-previous= | Go to previous journal entry | | =vulpea-journal-setup= | Enable calendar/sidebar integration and register widgets |

• Sidebar Keybindings

When viewing a journal note, the sidebar provides quick navigation:

| Key | Action | |-----+--------------------------------| | =[= | Go to previous journal entry | | =]= | Go to next journal entry | | =t= | Go to today's journal | | =d= | Pick a date |

• Calendar Integration

After calling =vulpea-journal-setup=, the Emacs calendar gains journal superpowers via =vulpea-journal-calendar-mode=:

| Key | Action | |-----+--------------------------------| | =j= | Open journal for date at point | | =]= | Jump to next journal entry | | =[= | Jump to previous journal entry |

Days with journal entries are highlighted in the calendar.

The minor mode is automatically enabled in calendar buffers. You can toggle it with =M-x vulpea-journal-calendar-mode= if needed.

• Widgets Reference

** vulpea-journal-widget-nav

Shows the current journal date and navigation buttons:

[[file:images/vulpea-journal-ui-navigation.png]]

Clicking Prev/Next navigates by one calendar day (creating the entry if needed). Clicking Today jumps to today's journal.

Note: The sidebar keybindings =[= and =]= behave differently — they jump to the next/previous existing journal entry, skipping days without entries.

** vulpea-journal-widget-calendar

Interactive month calendar:

[[file:images/vulpea-journal-ui-calendar.png]]

• Bold = today
• Highlighted = selected date
• Dot (·) = has journal entry
• Click any date to open its journal

Click the =<= and =>= buttons to navigate months without changing the selected date.

** vulpea-journal-widget-created-today

Lists all notes created on the journal's date (from the CREATED property):

[[file:images/vulpea-journal-ui-created-today.png]]

Click a note to visit it. Times come from the CREATED property timestamp.

** vulpea-journal-widget-previous-years

Shows journal entries from the same date in previous years:

[[file:images/vulpea-journal-ui-previous-years.png]]

Click the date to visit that journal. Click =▸=/=▾= to expand/collapse the preview.

• Tips & Tricks

** Open journal on Emacs startup

#+begin_src emacs-lisp (add-hook 'emacs-startup-hook #'vulpea-journal) #+end_src

** Weekly review workflow

Use =vulpea-journal-dates-in-range= to query entries:

#+begin_src emacs-lisp (defun my/journal-this-week () "Get all journal dates from this week." (let* ((today (current-time)) (dow (string-to-number (format-time-string "%u" today))) (start (time-subtract today (days-to-time (1- dow)))) (end (time-add start (days-to-time 7)))) (vulpea-journal-dates-in-range start end))) #+end_src

** Custom journal tag

If you want a different tag than ="journal"=, set =vulpea-journal-tag=:

#+begin_src emacs-lisp (setq vulpea-journal-tag "daily-note") #+end_src

Template builders (=vulpea-journal-template-daily=, =vulpea-journal-template-monthly=) use =vulpea-journal-tag= as the default tag automatically. If you use a raw plist for =vulpea-journal-default-template=, make sure the first element of =:tags= matches =vulpea-journal-tag=.

• Troubleshooting

** Widgets don't appear in sidebar

1. Ensure =vulpea-journal-ui= is loaded (widgets auto-register on load)
2. Check that you're viewing a journal note (has the journal tag)
3. Try =M-x vulpea-ui-sidebar-refresh=

** Date extraction fails

vulpea-journal extracts dates from the CREATED property. Ensure your template includes:

#+begin_src emacs-lisp :head "#+created: %<[%Y-%m-%d]>" #+end_src

Supported formats:

• =[2025-12-08]=
• =[2025-12-08 08:54]=
• =2025-12-08=

** Calendar marks don't appear

Ensure =vulpea-journal-setup= is called in your config. This adds the necessary hooks:

#+begin_src emacs-lisp (add-hook 'calendar-today-visible-hook #'vulpea-journal-calendar-mark-entries) (add-hook 'calendar-today-invisible-hook #'vulpea-journal-calendar-mark-entries) #+end_src

** Calendar keybindings don't work

=vulpea-journal-setup= enables =vulpea-journal-calendar-mode= in calendar buffers. If keybindings aren't working:

1. Verify the minor mode is active by running =M-x vulpea-journal-calendar-mode= to toggle it
2. Ensure =vulpea-journal-setup= was called before opening the calendar

** Existing journal files not in database

If you have existing journal files that are not properly indexed in the vulpea database (e.g., manually created files, or files without an =:ID:= property), vulpea-journal will show an error when you try to navigate to that date. This is a safety measure to prevent accidentally overwriting your files.

To fix this, you have two options:

1. Add proper properties and sync: Ensure each file has an =:ID:= property in its property drawer, then run =M-x vulpea-db-sync-full-scan= to index them.

2. Delete and recreate: If the files don't contain important content, delete them and let vulpea-journal create new ones.

Additionally, if your notes lack the =CREATED= property, vulpea-journal won't find them for date-based queries (like "notes created today"). The note itself will work fine if opened directly.

** Migration script

If you have many existing journal files that need =:ID:=, =CREATED= properties, and the journal filetag, you can use this script to migrate them automatically.

WARNING: Back up your notes before running this script!

#+begin_src emacs-lisp (defun vulpea-journal-migrate-files (directory) "Migrate journal files in DIRECTORY to vulpea-journal format. Adds :ID: property if missing. Adds CREATED property if missing (inferred from filename or title). Adds journal filetag if missing (using `vulpea-journal-tag').

After running this, execute `vulpea-db-sync-full-scan' to index the files." (interactive "DJournal directory: ") (let* ((files (directory-files directory t "\.org$")) (count (length files)) (modified 0) (skipped 0)) (message "Processing %d files in %s..." count directory) (dolist (file files) (message " Processing %s..." (file-name-nondirectory file)) (with-current-buffer (find-file-noselect file) (let ((changed nil) (filename (file-name-base file))) ;; Check/add ID property (goto-char (point-min)) (unless (org-entry-get (point) "ID") (org-id-get-create) (setq changed t) (message " Added ID")) ;; Check/add CREATED property (goto-char (point-min)) (unless (org-entry-get (point) "CREATED") (when-let* ((date (vulpea-journal-migrate--infer-date file))) (org-set-property "CREATED" date) (setq changed t) (message " Added CREATED: %s" date))) ;; Check/add journal filetag (goto-char (point-min)) (unless (member vulpea-journal-tag (vulpea-buffer-tags-get)) (vulpea-buffer-tags-add (list vulpea-journal-tag)) (setq changed t) (message " Added filetag: %s" vulpea-journal-tag)) ;; Save if modified (if changed (progn (save-buffer) (setq modified (1+ modified))) (setq skipped (1+ skipped))) (kill-buffer)))) (message "Migration complete: %d modified, %d skipped" modified skipped) (message "Run M-x vulpea-db-sync-full-scan to index the migrated files.")))

(defun vulpea-journal-migrate--infer-date (file) "Infer date from FILE path or title. Returns date string in format [YYYY-MM-DD] or nil." (let ((filename (file-name-base file))) (cond ;; Try common filename patterns: YYYYMMDD, YYYY-MM-DD, YYYY_MM_DD ((string-match "\([0-9]\{4\}\)[-]?\([0-9]\{2\}\)[-]?\([0-9]\{2\}\)" filename) (format "[%s-%s-%s]" (match-string 1 filename) (match-string 2 filename) (match-string 3 filename))) ;; Try reading title from file (t (with-temp-buffer (insert-file-contents file) (goto-char (point-min)) (when (re-search-forward "^#\+title:[ \t]*\(.+\)" nil t) (let ((title (match-string 1))) (when (string-match "\([0-9]\{4\}\)[-]?\([0-9]\{2\}\)[-]?\([0-9]\{2\}\)" title) (format "[%s-%s-%s]" (match-string 1 title) (match-string 2 title) (match-string 3 title)))))))))) #+end_src

Usage:

1. Back up your journal directory
2. Evaluate the code above
3. Run =M-x vulpea-journal-migrate-files= and select your journal directory
4. Run =M-x vulpea-db-sync-full-scan= to index the migrated files

• API Reference

** Functions

#+begin_src emacs-lisp ;; Template builders (vulpea-journal-template-daily) ; Daily template (one file per day) (vulpea-journal-template-monthly) ; Monthly template (one file per month)

;; Note identification (vulpea-journal-note-p note) ; Is NOTE a journal note? (vulpea-journal-note-date note) ; Extract date from journal NOTE

;; Note retrieval (vulpea-journal-note date) ; Get/create journal for DATE (vulpea-journal-find-note date) ; Find existing journal (no create)

;; Queries (vulpea-journal-all-dates) ; All dates with journals (vulpea-journal-dates-in-month m y) ; Journals in month M of year Y (vulpea-journal-dates-in-range a b) ; Journals between dates A and B (vulpea-journal-notes-for-date-across-years date n) ; Same date in past N years #+end_src

** Faces

• =vulpea-journal-calendar-entry-face= - Calendar days with entries
• =vulpea-journal-ui-widget-title= - Widget headers
• =vulpea-journal-ui-calendar-date= - Regular calendar days
• =vulpea-journal-ui-calendar-today= - Today in calendar
• =vulpea-journal-ui-calendar-entry= - Days with entries in widget
• =vulpea-journal-ui-calendar-selected= - Selected day in widget

• Contributing

Contributions welcome! Please open issues and PRs on GitHub.

• License

GPLv3. See [[file:LICENSE][LICENSE]] for details.

• Support

If you enjoy this project, you can support its development via [[https://github.com/sponsors/d12frosted][GitHub Sponsors]] or [[https://www.patreon.com/d12frosted][Patreon]].