org-journal
Adapted from https://www.emacswiki.org/emacs/PersonalDiary
Functions to maintain a simple personal diary / journal using in Emacs.
Feel free to use, modify and improve the code! — mtvoid, bastibe
Synopsis
org-journal
maintains a set of files, where each file represents a day. Convenient
bindings allow the creation of journal records in the current daily file and search within
all records or specified time intervals. All records can be browsed and searched from the
Emacs Calendar for convenience. All entries in a specified TODO state will be carried over
to the next day. Optionally, the journal can also be encrypted.
An example of a daily file (it will actually look a lot nicer, depending on your org-mode settings):
* Tuesday, 06/04/13 ** 10:28 Company meeting Endless discussions about projects. Not much progress ** 11:33 Work on org-journal :org-journal: For the longest time, I wanted to have a cool diary app on my computer. However, I simply lacked the right tool for that job. After many hours of searching, I finally found PersonalDiary on EmacsWiki. PersonalDiary is a very simple diary system based on the emacs calendar. It works pretty well, but I don't really like that it only uses unstructured text. Thus, I spent the last two hours making that diary use org-mode and represent every entry as an org-mode headline. Very cool! ** 15:33 Work on org-journal :org-journal: Now my journal automatically creates the right headlines (adds the current time stamp if on the current day, does not add a time stamp for any other day). Additionally, it automatically collapses the headlines in the org-file to the right level (shows everything if in view mode, shows only headlines in new-entry-mode). Emacs and elisp are really cool! ** 16:40 Work on org-journal :org-journal: I uploaded my journal mode to marmalade and Github! Awesome! ** TODO teach org-journal how to brew coffee :org-journal:
Installation
org-journal
is available through marmalade, melpa and melpa-stable. So installation
should be trivial:
M-x package-install org-journal
Then add (require 'org-journal)
to your .emacs
.
Quickstart
Doing M-x org-journal-new-entry
(or C-c C-j
) will immediately create a journal
directory in the default path (customized using the org-journal-dir
variable), open or
create a file in org-journal-mode
, and insert a template for a new journal entry.
The same command with a prefix argument (C-u C-c C-j
) will do everything mentioned while
skipping entry creation, which is useful for looking at the current journal file.
Basic Usage
Bindings available in org-journal-mode
:
C-c C-f
- go to the next journal file.C-c C-b
- go to the previous journal file.C-c C-j
- insert a new entry into the current journal file (creates the file if not present).C-c C-s
- search the journal for a string.
All journal entries are registered in the Emacs Calendar. To see available journal
entries do M-x calendar
. Bindings available in the calendar-mode
:
j
- view an entry in a new buffer.C-j
- view an entry but do not switch to it.i j
- add a new entry into the day’s file (creates the file if not present).f w
- search in all entries of the current week.f m
- search in all entries of the current month.f y
- search in all entries of the current year.f f
- search in all entries of all time.f F
- search in all entries in the future.[
- go to previous day with journal entries.]
- go to next day with journal entries.
Advanced Usage and Customization
Journal Directory and Files
Customization options related to journal directory and files:
org-journal-dir
- the journal path. Tweaking this variable will also updateauto-mode-alist
to ensure journal files are opened inorg-journal-mode
.org-journal-file-format
- format string for journal file names (may contain directories relative toorg-journal-dir
).org-journal-find-file
- a function to use when opening a journal file. By default it opens a window usingfind-file-other-window
. Set this tofind-file
if you don’t want org-journal to split your window.org-extend-today-until
- a number that indicates the hour of your end of the day. If you create a new entry withorg-journal-new-entry
earlier than this time, the journal entry will go into the previous day’s journal.
Journal File Content
Customization options related to the journal file contents:
org-journal-date-format
- date format formatorg-journal
uses when showing a date within a journal and search results page. If set to a function, it is evaluated and inserted.org-journal-date-prefix
- this string will prefix the date at the top of a journal file.org-journal-time-format
- a timestamp format that will prefix every entry within a daily journal file.org-journal-time-prefix
- a string that will prefix every entry within a daily journal file.
Searching the Journal
org-journal
has two searching options: the usual org-mode
agenda search and the
built-in plain text search. The former can become slow with bigger journals, so the
built-in search is a recommended option.
To use the agenda search, you can add all journal entries to your org-agenda by adding
org-journal-dir
to org-agenda-files
and setting org-agenda-file-regexp
to include
files matching your org-journal-file-pattern
(=\`[^.].*\.org\’\|\`[0-9]+\’= for
the default all-numeric file format).
However, this can become very slow if you have many journal entries. As a compromize,
you can set org-journal-enable-agenda-integration
to t
, which automatically adds the
current and all future journal entries to the agenda. This is enough to get an overview
over current and future tasks.
The built-in search is available through the following function: org-journal-search
(C-c C-s
in org-journal-mode
). By default, it will ask for the time interval to search
within (accepting the org-read-date
format such as “-1y” or “-1m”) and the string to
search for. Given a prefix argument (C-u org-journal-search
), it will go through the
whole journal.
The order of the search results (ascending or descending by date) can be customized using
the org-journal-search-results-order-by
variable.
Search is also available through the Emacs Calendar as described in “Basic Usage”.
Carry Over
By default, org-journal
will try to carry over previous day TODO-marked items whenever
a new journal file is created. The older journal entry will be moved (i.e., deleted and
reinserted) to the current day’s file.
This feature is controlled through the org-journal-carryover-items
variable. Set this to
nil
to disable this feature, or to any agenda tags view match string for a set of
matching tags, properties, and todo states. By default, this is TODO=”TODO”
, which will
match TODO items.
Encryption
The journal can be encrypted using org-crypt
when org-journal-enable-encryption
is non-nil.
Agenda and Scheduling
An easy way of keeping track of appointments or future TODOs is to simply create a journal entry in the future. Such entries will automatically get a timestamp and show up in the current day’s journal entry once you reach that day.
- if
org-journal-enable-agenda-integration
ist
, org-journal will automatically add the current and all future journal entries toorg-agenda-files
.
There are a few helper functions to deal with such scheduled entries:
org-journal-new-scheduled-entry
- prompts for a date, and creates a new journal entry on that date with its timestamp set to the date. By default, this is a TODO entry. Set the prefix to avoid the TODO.org-journal-schedule-view
- creates a read-only overview of scheduled entries.
iCalendar export
You can export your scheduled entries to an iCalendar file, and subscribe to that file in your calendar application. You need to enable the agenda integration for this to work. I also recommend you set the following values before exporting:
(setq org-journal-enable-agenda-integration t
org-icalendar-store-UID t
org-icalendar-include-todo "all"
org-icalendar-combined-agenda-file "~/path/to/org-journal.ics")
With this done, you can export your agenda, including your scheduled entries, with (org-icalendar-combine-agenda-files)
.
Journal Capture Template
You can configure a capture template in order to integrate org-journal
with org-capture
,
as in the following example:
(defun org-journal-find-location ()
;; Open today's journal, but specify a non-nil prefix argument in order to
;; inhibit inserting the heading; org-capture will insert the heading.
(org-journal-new-entry t)
;; Position point on the journal's top-level heading so that org-capture
;; will add the new entry as a child entry.
(goto-char (point-min)))
(setq org-capture-templates '(("j" "Journal entry" entry (function org-journal-find-location)
"* %(format-time-string org-journal-time-format)%^{Title}\n%i%?")))
FAQ
Can I use monthly/weekly journal entries instead of daily ones?
org-journal
currently only supports daily entries.
Can I have multiple journals?
At the moment, this is not possible. But it should be possible to switch the value of
org-journal-directory
using a custom function or directory local variables.
Can I use org-journal with Spacemacs?
To use org-journal
with Spacemacs, you can:
git clone https://github.com/borgnix/spacemacs-journal.git ~/.emacs.d/private/journal
- add it to your
~/.spacemacs
. You will need to addjournal
to the existingdotspacemacs-configuration-layers
list in this file.
The manual of the journal layer can be found at https://github.com/borgnix/spacemacs-journal
Some key-bindings in org-journal overwrite org-mode key bindings
Major modes are supposed to only use key bindings of the form C-c C-?
, where ?
can be any letter. With org-mode already using most interesting keys, collisions are inevitable. Currently, org-journal overwrites
C-c C-s
(org-schedule
) withorg-journal-search
C-c C-f
(org-forward-heading-same-level
) withorg-journal-open-next-entry
C-c C-b
(org-backward-heading-same-level
) withorg-journal-open-previous-entry
C-c C-j
(org-goto
) withorg-journal-new-entry
However, this is Emacs, and if you don’t like a key binding, change it!
Opening journal entries from the calendar are not editable
Old entries are opened in view-mode
, which has convenient key bindings for browsing files. Most notably, you can quickly close view-mode
buffers with q
, scroll them with the SPC
and DEL
, or quit view-mode
with e
.
Contributors
See CONTRIBUTORS.
Changelog
See CHANGELOG.