! experimental and unstable see BUGS
a diary plugin for vim
ephemeris is a diary and calendar plugin for vim. It provides a collection of functions and commands that can be used to create, edit, and curate diary/log entries.
The diary is defined by the directories and files found recursively under the
directory set in the global variable g:ephemeris_diary. ephemeris does not
rely on any external programs and does not interfere with any external
program, such as cal, etc. This plugin works best when the directory structure
of g:ephemeris_diary is YYYY/MM/DD.md, as follows:
├── 2019
│ └── 09
│ ├── 16.md
│ └── 12
│ └── 20.md
├── 2020
│ └── 05
│ ├── 01.md
│ ├── 04.mdThis tree structure is provided by default by ephemeris functions. This plugin will only provide limited functionality if the directory structure does not include a date-aligned directory structure as outlined above.
see doc/ephemeris.txt for additional user help
see CONTRIBUTING for contributor guidelines
see vader tests for testing
documentation
version information available at vim.org
- [🌕] create/goto index/today
- [🌖] checkbox list item management
- [🌕] filter/toggle/archive/count
- [🌕] copy last set of tasks
- [ ]to current day's diary entry
- [🌗] print day's agenda
- [🌖] list-appropriate code folding
Add Plug 'HP4k1h5/ephemeris' to your .vimrc and run
:source $MYVIMRC | PlugInstallGenerally, ephemeris may work for those who like to keep a daily journal or log and a todo list and other note, task, and reminder related items in the same place. As functionalities grow, the principle of moving data from one place to another efficiently will be prioritised.
- Add the only required setting to your
.vimrc, with e.g.:let g:ephemeris_diary = '~/diary' - Either create a new entry with
:EphemerisGotoToday, or copy over todos from the last entry with:EphemerisCopyTodosif you already have entries that containg:ephemeris_todosmarkers. - If you use task lists,
:EphemerisToggleTaskcan create task items and toggle task items between by default,- [ ], for incomplete, and- [x]for complete tasks.:EphemerisFilterTaskswill move to archive or delete completed tasks and their associated subblocks. :EphemerisPrintAgendawill grep all diary entries for date tags of the date provided, e.g.(YYYY/MM/DD)or today, if no date is provided.
g:ephemeris_diary (!!required)
set the root directory for your diary entries g:ephemeris_diary, i.e. in your
.vimrc:
let g:ephemeris_diary = '~/diary'g:ephemeris_todos
Set the string for EphemerisCopyTodos, to look for. Everything below the
marker in the most recent diary entry is copied and appended into the current
day's entry. You can change it by setting it, i.e. in your .vimrc. See
EphemerisCopyTodos.
Default: TODOs
Example:
let g:ephemeris_todos = '=== TASK LIST ==='g:ephemeris_toggle_list
String list of characters to be used in checkbox items.
Default: ' x', rendering as - [ ] and - [x]
Example:
let g:ephemeris_toggle_list = '🌑🌘🌗🌖🌕'a checkbox will look like - [🌖] and the last item in the list will be the
completed item.
see doc/ephemeris.txt for additional help
:EphemerisCreateIndex
Create markdown diary index of all '.md' files found under the
|g:ephemeris_diary| directory, and go to vertical split. Calls
|ephemeris#ind#create_index()|
:EphemerisGotoIndex
Open diary index in a vertical split or focus diary index buffer. Index is
found at |g:ephemeris_diary|/index.md. Calls |ephemeris#ind#goto_index()|
:EphemerisGotoToday
Open a split with today's diary entry. Index is found at
|g:ephemeris_diary|/index.md.
:EphemerisCopyTodos
Copy TODOs from last set of TODOs going back up to 10 years. Your
@setting(g:ephemeris_diary) directory must be organized in a
.../YYYY/MM/DD.md hierarchy, in order for this function to know which set
of TODOs are_most recent_. TODOs are defined by the string set in
@setting(g:ephemeris_todos). Default is 'TODOs'. Everything below that
marker, until 2 consecutive newlines, an incomplete task, or a subsequent
g:ephemeris_todos marker, is copied to the current day's diary entry. It will
open today's diary entry in a split. Calls
@function(ephemeris#lst#copy_todos)
:EphemerisToggleTask
Toggle state of task item under cursor through items provided in
g:ephemeris_toggle_list. The last character in the string is the "completed"
item, used by e.g. EphemerisFilterTasks. If no task item is present a new
one will be created, using the left-most item in the
g:ephemeris_toggle_list.
:EphemerisPrintAgenda
Print [date]'s agenda composed of grepped lines found in files found in
g:ephemeris_diary tagged with (YYYY/MM/DD) date-formatted markers. If no
date is provided, today's date is used. If g:ephemeris_todos exists agenda
items will be printed below that, otherwise at the top of the buffer.
Ex: :EphemerisPrintAgenda '2020/07/04', yields in the current buffer
# TODOs
## 2020/07/04 AGENDA
filename1 :: agenda item 1 due on... (2020/07/04)
filename2 :: agenda item 2 (2020/07/04)
filename3 :: agenda item 3 (2020/07/04):EphemerisFilterTasks
@usage [archive] [summary]
Delete or move completed tasks, e.g. list items containing - [x], and all
associated subblocks until the next incomplete task
@setting(g:ephemeris_todos) marker, 2 newlines, or EOF. See example in
@function(ephemeris#lst#filter_tasks). The first argument [archive] is a
boolean which determines whether the filtered tasks are moved to
'g:ephemeris_diary'/.cache/archive.md. Default is 0. The second argument
[summary] is a boolean. If true this function will print a summary of
filtered/remaining tasks at the bottom of the buffer. Default is 0.
Ex: :EphemerisFilterTasks 1 1 " filters tasks, moves completed tasks to
*------------------------------------*
| TODOs (before) |
|- [x] complete task 1 |
|- [ ] incomplete task 2 |
| - [x] complete task 2a |
| - additional info that is not a | run in command-line mode
| task will be preserved if the | *---------------------*
| task is incomplete |--|:EphemerisFilterTasks|
|- [x] complete task 3 | *---------------------*
| - [ ] incomplete task 3a | |
|- [x] complete task 4 | |
| - but removed otherwise | |
| - [ ] incomplete task 4a also | |
| this will get preserved | |
*------------------------------------* V
*----------------------------------------------*
| TODOs (after) |
|- [ ] incomplete task 2 |
| - [ ] incomplete task 3a |
| - [ ] incomplete task 4a also |
| this will get preserved |
*----------------------------------------------*:EphemerisFold
Fold file by line-separated paragraphs, works well with lists if you leave a
" space between list blocks. Set 'foldlevel' to 0 or type zM to fold all,
type " zR to open all folds.
In the top left image, an unfolded list of items. As these grow, navigating
them and getting a high-level overview can be difficult. In the top right
image, EphemerisFold has been applied and all blocks have been closed zM.
Blocks of newline-spaced list items are folded and visually condensed to their
parent headers. In the bottom image, one fold has been opened zo.
nmap <leader>eci :EphemerisCreateIndex<CR>
nmap <leader>egt :EphemerisGotoToday<CR>
nmap <leader>ect :EphemerisCopyTodos<CR>
nmap <leader>epa :EphemerisPrintAgenda<CR>
nmap <leader>ef :EphemerisFold<CR>
nmap <leader>eft :EphemerisFilterTasks 1 1<CR>
" 1 = archive, 0 = delete ---^ ^---- 1 = summary, 0 = no summary
nmap <leader>et :EphemerisToggleTask<CR>- v0.9 bugfixes, agenda
- v0.8 folding, checkbox options