A journaling interface for vulpea that integrates seamlessly with vulpea-ui sidebar.
vulpea-journal brings the power of journaling to your vulpea-based note system. Think of it as 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
vulpea-journal requires:
(package-install 'vulpea-journal)(straight-use-package 'vulpea-journal)(elpaca vulpea-journal)In packages.el:
(package! vulpea-journal)In config.el:
(use-package! vulpea-journal
:after (vulpea vulpea-ui)
:config
(vulpea-journal-setup))(use-package vulpea-journal
:after (vulpea vulpea-ui)
:config
(vulpea-journal-setup))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) |
| journal-created-today | 350 | After backlinks |
| journal-previous-years | 360 | After journal-created-today |
| links | 400 | (vulpea-ui) |
To customize the order, see Widget Order Configuration below.
(global-set-key (kbd "C-c j") #'vulpea-journal)Press C-c j to open today’s journal. The sidebar will show journal-specific widgets.
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:
- Finds or creates the note for that date
- Opens it in your main window (for monthly, navigates to the heading)
- Shows the vulpea-ui sidebar with journal widgets
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.
Customize how journal notes are created. Use the template builder functions for convenience:
(setq vulpea-journal-default-template
(vulpea-journal-template-daily))This is equivalent to the default behavior. You can override any parameter:
(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"))(setq vulpea-journal-default-template
(vulpea-journal-template-monthly))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:
(setq vulpea-journal-default-template
(vulpea-journal-template-monthly
:file-name "journal/%Y/%m.org"
:entry-title "%d %A"))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 (derived when :entry-groups is set) |
:entry-title | %d %A | strftime format for heading |
:entry-groups | nil | Optional grouping headings (see below) |
:entry-order | oldest-first | Direction of day entries in the file (see below) |
:aliases | nil | Per-entry aliases, computed or static (see below) |
:tags | ("journal") | Tags (first one identifies journals) |
For monthly templates, :body, :properties, :context, and :aliases apply to each daily entry, while :head seeds the monthly file (the container). :meta is file-level only: monthly heading entries do not carry metadata, because vulpea-create stores metadata on file-level notes only.
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:
(setq vulpea-journal-default-template
(vulpea-journal-template-monthly
:entry-title "%d %A"
:entry-groups '("week %V")
:body "*** Tasks\n\n*** Notes\n"))Each element of :entry-groups adds one heading level between the file and the daily entry. An element is either a strftime format string (expanded for the entry’s date) or a function of one argument (the date) returning the heading title. A single spec may be given without wrapping it in a list. Group headings are created on demand and reused across days that resolve to the same title, and :entry-level is derived as 1 + (length entry-groups) so lookup and creation stay in sync. The template above produces:
#+title: 2026-06 #+filetags: :journal: * week 24 ** 08 Monday *** Tasks *** Notes ** 09 Tuesday *** Tasks *** Notes * week 25 ** 15 Monday *** Tasks *** Notes
Because :body is inserted verbatim at fixed heading levels, nest its subheadings one level below the entry (*** for entries at level 2, as above).
By default the monthly file reads chronologically: the oldest day sits at the top and new days are added at the bottom. Set :entry-order to newest-first to keep the most recent day at the top instead. This is useful on mobile, where reaching today’s entry otherwise means scrolling through the whole month:
(setq vulpea-journal-default-template
(vulpea-journal-template-monthly
:entry-order 'newest-first))#+title: 2026-07 #+filetags: :journal: * 23 Thursday * 18 Saturday * 10 Friday
Insertion is date-aware in both directions: creating an entry for a past date (say, visiting July 15 with the file above) places it between its date neighbors instead of at the edge of the file. Only the day headings are ordered this way; whatever you add inside a day keeps its usual order (for captures, org-capture’s :prepend flag controls that).
With :entry-groups, newly created group headings follow the same direction. Group headings carry no date, so their placement is positional: a group created for a back-dated entry is prepended (or appended) rather than sorted.
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.
(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")))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.
You can also provide a raw plist directly:
(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 bodyImportant: 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 %<format> syntax and are expanded at creation time.
For more control, use a function:
(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")))));; Start week on Sunday (0) or Monday (1, default)
(setq vulpea-journal-ui-calendar-week-start 1);; Include journal notes in the "created today" list
(setq vulpea-journal-ui-created-today-exclude-journal nil) ; default: t;; 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: tCustomize where journal widgets appear relative to vulpea-ui widgets:
(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)))Note that vulpea-journal-ui-widget-orders uses short keys (nav, calendar, created-today, previous-years), and it is read once, when the widgets are registered. So set it before calling vulpea-journal-setup (e.g. via :custom in use-package).
Example: Move calendar before stats:
(use-package vulpea-journal
:custom
(vulpea-journal-ui-widget-orders
'((nav . 50)
(calendar . 90) ; now before stats
(created-today . 350)
(previous-years . 360))))Reference orders for vulpea-ui widgets: stats=100, outline=200, backlinks=300, links=400.
If you want to change the order after the widgets are already registered, use vulpea-ui-widget-set instead. It operates on vulpea-ui’s widget registry, where journal widgets are registered under their full names: journal-nav, journal-calendar, journal-created-today, journal-previous-years.
(vulpea-ui-widget-set 'journal-calendar :order 90) ; now before stats| 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 |
Note: When using vulpea-journal-date to input a date, you can leverage standard Org-mode keybindings for navigating between days (refer to the org-read-date documentation for details). Additionally, M-<left> and M-<right> allow you to move specifically through days that already have journal entries.
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 |
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.
Sometimes you just want to jot something into today’s note without the sidebar and its widgets popping up. vulpea-journal-capture-target is an org-capture target function for exactly that. It creates today’s note on demand (so the first capture of the day also registers it in the vulpea database) and moves point into place. It never touches the vulpea-ui sidebar.
Add a capture template that uses it as a (function ...) target:
(add-to-list 'org-capture-templates
'("j" "Journal" entry
(function vulpea-journal-capture-target)
"* %<%H:%M> %?"))The same template works for both daily and monthly journals: the target reads your vulpea-journal-default-template and positions point accordingly. The heading is prefixed with just the time (%<%H:%M>) because the date is already implied by the file (daily) or the day heading (monthly), so a full timestamp would be redundant.
For a daily template (one file per day), an entry capture is appended as a new top-level heading at the end of today’s file:
#+title: 2026-07-23 Thursday #+filetags: :journal: * 08:15 Morning thought * 21:40 Evening thought
For a monthly template (one file per month, days as headings), the entry nests as a child of today’s day heading, so you do not need to narrow to it yourself:
#+title: 2026-07 #+filetags: :journal: * 23 Thursday ** 09:12 First quick note ** 14:30 Second quick note
The function only positions point, so the capture type (entry, item, plain, …) and the content come entirely from your template. It also accepts an optional DATE argument if you want to capture into a specific day instead of today.
If you would rather just visit today’s note and write in it directly (no capture buffer, still no sidebar), skip the template and call:
(vulpea-visit (vulpea-journal-note (current-time)))Shows the current journal date and navigation buttons:
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.
Interactive month calendar:
- 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.
Lists all notes created on the journal’s date (from the CREATED property):
Click a note to visit it. Times come from the CREATED property timestamp.
Shows journal entries from the same date in previous years:
Click the date to visit that journal. Click ▸=/=▾ to expand/collapse the preview.
(add-hook 'emacs-startup-hook #'vulpea-journal)Use vulpea-journal-dates-in-range to query entries:
(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)))If you want a different tag than "journal", set vulpea-journal-tag:
(setq vulpea-journal-tag "daily-note")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.
- Ensure
vulpea-journal-uiis loaded (widgets auto-register on load) - Check that you’re viewing a journal note (has the journal tag)
- Try
M-x vulpea-ui-sidebar-refresh
vulpea-journal extracts dates from the CREATED property. Ensure your template includes:
:head "#+created: %<[%Y-%m-%d]>"Supported formats:
[2025-12-08][2025-12-08 08:54]2025-12-08
Ensure vulpea-journal-setup is called in your config. This adds the necessary hooks:
(add-hook 'calendar-today-visible-hook #'vulpea-journal-calendar-mark-entries)
(add-hook 'calendar-today-invisible-hook #'vulpea-journal-calendar-mark-entries)vulpea-journal-setup enables vulpea-journal-calendar-mode in calendar buffers. If keybindings aren’t working:
- Verify the minor mode is active by running
M-x vulpea-journal-calendar-modeto toggle it - Ensure
vulpea-journal-setupwas called before opening the calendar
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:
- Add proper properties and sync: Ensure each file has an
:ID:property in its property drawer, then runM-x vulpea-db-sync-full-scanto index them. - 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.
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!
(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))))))))))Usage:
- Back up your journal directory
- Evaluate the code above
- Run
M-x vulpea-journal-migrate-filesand select your journal directory - Run
M-x vulpea-db-sync-full-scanto index the migrated files
;; 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)
;; Capture
(vulpea-journal-capture-target) ; `org-capture' target: point in today's note
;; 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 yearsvulpea-journal-calendar-entry-face- Calendar days with entriesvulpea-journal-ui-widget-title- Widget headersvulpea-journal-ui-calendar-date- Regular calendar daysvulpea-journal-ui-calendar-today- Today in calendarvulpea-journal-ui-calendar-entry- Days with entries in widgetvulpea-journal-ui-calendar-selected- Selected day in widget
Contributions welcome! Please open issues and PRs on GitHub.
GPLv3. See LICENSE for details.
If you enjoy this project, you can support its development via GitHub Sponsors or Patreon.