jonas/telekasten.nvim
1
0
Fork 0
mirror of https://github.com/Ascyii/telekasten.nvim.git synced 2026-01-01 06:14:23 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
694683df4b6a4ee075cbfcddfb60da2cb4c9ff5d
telekasten.nvim/doc/telekasten.txt
Rene Schallner 694683df4b u h
2021-11-24 23:24:29 +01:00

520 lines
19 KiB
Plaintext
Raw Blame History

================================================================================
*telekasten.nvim*
Telekasten.nvim is a plugin that lets you work with a folder of Markdown files
and use it as a 'Zettelkasten' or a Wiki plus journal.
Find notes by name, daily and weekly notes by date, search within all notes,
place and follow links to your notes or create new ones, with templates.
Current daily and weekly notes can be created if not present when searching
for dailies or weeklies. Following a link to a non-existing note can also
create the missing note (optional).
Telekasten can optionally plug into `calendar-vim`: Selecting a day in the
calendar will open up a telescope search with preview that lets you open the
daily note (or cancel out and keep browsing your calendar). The daily note
will be created if it doesn't exist. Days with daily notes get marked in the
calendar.
To find out more:
https://github.com/renerocksai/telekasten.nvim
================================================================================
*telekasten.contents*
CONTENTS
0. Note file naming .............. |telekasten.note_naming|
1. Setup ......................... |telekasten.setup|
2. Colors ........................ |telekasten.colors|
3. Usage ......................... |telekasten.usage|
3.1 Templates ................ |telekasten.templates|
3.2 Calendar ................. |telekasten.calendar|
4. Suggested mappings ............ |telekasten.mappings|
5. Credits ....................... |telekasten.credits|
================================================================================
Section 0: Note file naming *telekasten.note_naming*
Please Note:~
Currently, the following file naming conventions are hard-coded:
- daily note files : `YYYY-MM-DD.ext` (e.g. `2021-11-21.md`)
- weekly note files: `YYYY-Www.ext` (e.g. `2021-W46.md`)
================================================================================
Section 1: Setup *telekasten.setup()*
telekasten.setup({opts})
Setup function to be run by user. Configures the defaults, markdown
directories, templates, and optional calendar integration of telekasten.
Usage:
>
require("telekasten").setup({
home = '/path/to/directory', -- path to main markdown folder
daily = '/path/to/directory', -- path to daily notes
weekly = '/path/to/directory', -- path to weekly notes
templates = '/path/to/directory', -- path to templates
extension = '.file extension', -- file extension of note files
-- flags for creating non-existing notes
follow_creates_nonexisting = true, -- create non-existing on follow
dailies_create_nonexisting = true, -- create non-existing dailies
weeklies_create_nonexisting = true, -- create non-existing weeklies
-- specific note templates
template_new_note = '/path/to/file', -- template for new notes
template_new_daily = '/path/to/file', -- template for new daily notes
template_new_weekly = '/path/to/file', -- template for new weekly notes
-- calendar integration
plug_into_calendar = true, -- use calendar integration
calendar_opts = {
weeknm = 4, -- calendar week display mode:
-- 1 .. 'WK01'
-- 2 .. 'WK 1'
-- 3 .. 'KW01'
-- 4 .. 'KW 1'
-- 5 .. '1'
calendar_monday = 1, -- use monday as first day of week:
-- 1 .. true
-- 0 .. false
calendar_mark = 'left-fit', -- calendar mark placement
-- where to put mark for marked days:
-- 'left'
-- 'right'
-- 'left-fit'
}
<
Valid keys for {opts}
*telekasten.settings.home*
home: ~
Path to your main markdown / zettelkasten folder. This is where all
your notes will be stored.
Default: '~/zettelkasten'
*telekasten.settings.daily*
daily: ~
Path to your daily notes, to separate them from 'normal' notes.
Default: '~/zettelkasten/daily'
*telekasten.settings.weekly*
weekly: ~
Path to your weekly notes, to separate them from 'normal' notes.
Default: '~/zettelkasten/weekly'
*telekasten.settings.templates*
templates: ~
Path to your note templates.
Default: '~/zettelkasten/templates'
*telekasten.settings.extension*
extension: ~
Filename extension of your markdown note files.
Default: '.md'
*telekasten.settings.follow_create_nonexisting*
follow_creates_nonexisting: ~
Flag that determines whether non-existing notes should be created when
following a link to them.
Default: true
*telekasten.settings.dailies_create_nonexisting*
dailies_create_nonexisting: ~
Flag that determines whether today's note should always be created if
not present. Also, whether daily notes should be created when opening
them via the calendar.
Default: true
*telekasten.settings.weeklies_create_nonexisting*
weekliesdailies_create_nonexisting: ~
Flag that determines whether this week's note should always be created
if not present. Also, whether weekly notes should be created when
opening them via the calendar.
Default: true
*telekasten.settings.template_new_note*
template_new_note: ~
Markdown template for new notes.
Default: '~/zettelkasten/templates/new_note.md'
*telekasten.settings.template_new_daily*
template_new_daily: ~
Markdown template for new daily notes.
Default: '~/zettelkasten/templates/daily.md'
*telekasten.settings.template_new_weekly*
template_new_weekly: ~
Markdown template for new weekly notes.
Default: '~/zettelkasten/templates/daily.md'
Valid keys for {opts.calendar_opts}
*telekasten.calendar_opts.weeknm*
weeknm: ~
Integer that defines the format of how calendar weeks should be
labeled.
Valid values are:
- 1 -> `WK01`
- 2 -> `WK 1`
- 3 -> `KW01`
- 4 -> `KW 1`
- 5 -> `1`
Default: 4
*telekasten.calendar_opts.calendar_monday*
calendar_monday: ~
Set this to 1 if you want weeks to start on Mondays.
Valid values are:
- 0 -> weeks start on Sundays
- 1 -> weeks start on Mondays
Default: 1
*telekasten.calendar_opts.calendar_mark*
calendar_mark: ~
Where to place marks such as `+` and `*`, relative to the day.
Valid values are:
- 'left' -> ugly
- 'right' -> right to the day
- 'left-fit' -> left of the day
Default: 'left-fit'
--------------------------------------------------------------------------------
Section 2: Colors *telekasten.colors*
Telekasten.nvim allows you to color your `[[links]]` by providing two syntax
groups:
- `tkLink` : the link title inside the brackets
- `tkBrackets` : the brackets surrounding the link title
- `tkHighlight` : ==highlighted== text (non-standard markdown)
The last one, `tkHighlight`, has nothing to do with links but I added it
anyway, since I like highlighting text when taking notes.
You can assign colors to the new syntax groups in your `init.vim`:
>
" just blue and gray links
hi tkLink ctermfg=Blue cterm=bold,underline
hi tkBrackets ctermfg=gray
" for gruvbox
hi tkLink ctermfg=72 cterm=bold,underline
hi tkBrackets ctermfg=gray
" highlight ==highlighted== text
hi tkHighlight ctermbg=yellow ctermfg=darkred cterm=bold
<
================================================================================
Section 3: Usage *telekasten.usage*
Telekasten.nvim is used by calling the following lua functions without
parameters:
*telekasten.new_note()*
telekasten.new_note()~
Promts for a title and creates a new note by the `new_note` template, then
shows it in Telescope.
See also:~
- |telekasten.settings.template_new_note|
- |telekasten.templates|
- |telekasten.template_files|
*telekasten.new_templated_note()*
telekasten.new_templated_note()~
Promts for a title and then uses Telescope for choosing a template. When a
template is selected, a new note is created with it and opened.
Should the note already exist before running `new_templated_note()`, it is
opened immediately.
See also:~
- |telekasten.template_files|
*telekasten.find_notes()*
telekasten.find_notes()~
Opens a Telescope file finder and lets you pick a note by title (file name).
*telekasten.find_daily_notes()*
telekasten.find_daily_notes()~
Find daily notes by date, via Telescope. File names are sorted by file
creation time, most recent file first.
If today's daily note is not present, will be created if
`dailies_create_nonexisting` is set to `true`.
See also:~
- |telekasten.settings.dailies_create_nonexisting|
New daily notes are created with the template specified in the
`template_new_daily` setting.
See also:~
- |telekasten.settings.template_new_daily|
- |telekasten.templates|
- |telekasten.template_files|
*telekasten.goto_today()*
telekasten.goto_today()~
Pops up a Telescope finder with today's daily note pre-selected.
If today's daily note is not present, will be created if
`dailies_create_nonexisting` is set to `true`.
See also:~
- |telekasten.settings.dailies_create_nonexisting|
New daily notes are created with the template specified in the
`template_new_daily` setting.
See also:~
- |telekasten.settings.template_new_daily|
- |telekasten.templates|
- |telekasten.template_files|
*telekasten.find_weekly_notes()*
telekasten.find_weekly_notes()~
Find weekly notes by week, via Telescope. File names are sorted by file
creation time, most recent file first.
If this week's daily note is not present, will be created if
`weeklies_create_nonexisting` is set to `true`.
See also:~
- |telekasten.settings.weeklies_create_nonexisting|
New weekly notes are created with the template specified in the
`template_new_weekly` setting.
See also:~
- |telekasten.settings.template_new_weekly|
- |telekasten.templates|
- |telekasten.template_files|
*telekasten.goto_thisweek()*
telekasten.goto_thisweek()~
Pops up a Telescope finder with this week's daily note pre-selected.
If this week's daily note is not present, will be created if
`weeklies_create_nonexisting` is set to `true`.
See also:~
- |telekasten.settings.weeklies_create_nonexisting|
New weekly notes are created with the template specified in the
`template_new_weekly` setting.
See also:~
- |telekasten.settings.template_new_weekly|
- |telekasten.templates|
- |telekasten.template_files|
*telekasten.search_notes()*
telekasten.search_notes()~
Search through all notes via Telescope live grep, initialized with the word
under the cursor.
*telekasten.insert_link()*
telekasten.insert_link()~
Select a note by title (file name), via Telescope, and place a `[[link]]` at
the current cursor position.
*telekasten.follow_link()*
telekasten.insert_link()~
Take the text between the brackets of a link, pointing to a linked note, and
open a Telescope file finder with it.
If the linked note does not exist and the setting
`follow_creates_nonexisting` is set to `true`, a new note will be created
using the `new_note` template before invoking Telescope.
See also:~
- |telekasten.settings.follow_creates_nonexisting|
- |telekasten.settings.template_new_note|
- |telekasten.template_files|
*telekasten.yank_notelink()*
telekasten.yank_notelink()~
Yank a link to the current note, ready to paste.
*telekasten.show_calendar()*
telekasten.show_calendar()~
Opens up the calendar in a properly-sized vertical split at the very right,
showing the previous, current, and next month.
See also:~
- |telekasten.calendar|
--------------------------------------------------------------------------------
Section 3.1: Templates *telekasten.templates*
Telekasten.nvim can create non-existing notes, providing this is enabled in
the settings - which it is by default. Auto-creation of notes is useful when
you jump to today's or this week's note, or when you typed a
`[[link to a new note]]` and jump to it.
The specific templates and settings used are:
For daily notes:~
- |telekasten.settings.template_new_daily|
- |telekasten.settings.dailies_create_nonexisting|
For weekly notes:~
- |telekasten.settings.template_new_weekly|
- |telekasten.settings.weeklies_create_nonexisting|
For all other notes:~
- |telekasten.settings.template_new_note|
- |telekasten.settings.follow_creates_nonexisting|
See also |telekasten.template_files| below for more on the specific templates.
The following table shows you what action creates what kind of non-existing
note:
+----------------------------------+--------------------------------+
| ACTION | KIND OF NOTE |
+----------------------------------+--------------------------------+
| `goto_today()` | today's daily note |
| [ENTER] on a day in the calendar | selected day's daily note |
| `find_daily_notes()` | today's daily note |
| `goto_thisweek()` | this week's weekly note |
| `find_weekly_notes()` | this week's weekly note |
| `follow_link()` | new note |
| `new_note()` | new note |
| `new_templated_note()` | new note |
+----------------------------------+--------------------------------+
*telekasten.template_files*
Template Files~
The options `template_new_note`, `template_new_daily`, and
`template_new_weekly` are used to specify the paths to template text files
that are used for creating new notes.
The following substitutions will be made during new note creation:
+-------------+-----------------------+-----------------------------+
| specifier | | |
| in template | expands to | example |
+-------------+-----------------------+-----------------------------+
| `{{title}}` | the title of the note | My new note |
| `{{date}}` | date in iso format | 2021-11-21 |
| `{{hdate}}` | date in long format | Sunday, November 21st, 2021 |
| `{{week}}` | week of the year | 46 |
| `{{year}}` | year | 2021 |
+-------------+-----------------------+-----------------------------+
As an example, this is my template for new notes:
>
---
title: {{title}}
date: {{date}}
---
<
I use this one for daily notes:
>
---
title: {{hdate}}
---
<
And finally, what a template for weekly notes could look like:
>
---
title: {{year}}-W{{week}}
date: {{hdate}}
---
# Review Week {{week}} / {{year}}
<
--------------------------------------------------------------------------------
Section 3.2: Calendar *telekasten.calendar*
When invoking `show_calendar()`, a calendar showing the previous, current, and
next month is shown at the right side of vim.
- days that have a daily note associated with them are marked with a + sign
and a different color
- pressing [ENTER] on a day will open up a telescope finder with the
associated daily note selected and previewed. The daily note will be created
if it doesn't exist. If you choose to not open the note, you will return to
the calender so you can preview other notes.
================================================================================
Section 4: Suggested Mappings *telekasten.mappings*
Telekasten.nvim does not come with pre-defined mappings.
However, here are some suggestions:
>
nnoremap <leader>zf :lua require('telekasten').find_notes()<CR>
nnoremap <leader>zd :lua require('telekasten').find_daily_notes()<CR>
nnoremap <leader>zg :lua require('telekasten').search_notes()<CR>
nnoremap <leader>zz :lua require('telekasten').follow_link()<CR>
nnoremap <leader>zt :lua require('telekasten').goto_today()<CR>
nnoremap <leader>zw :lua require('telekasten').find_weekly_notes()<CR>
nnoremap <leader>zn :lua require('telekasten').new_note()<CR>
nnoremap <leader>zN :lua require('telekasten').new_templated_note()<CR>
nnoremap <leader>zy :lua require('telekasten').yank_notelink()<CR>
nnoremap <leader>zc :lua require('telekasten').show_calendar()<CR>
" we could define [[ in **insert mode** to call insert link
" inoremap [[ <ESC>:lua require('telekasten').insert_link()<CR>
" alternatively: leader [
inoremap <leader>[ <ESC>:lua require('telekasten').insert_link()<CR>
" the following are for syntax-coloring [[links]] and ==highlighted text==
" (see the section about coloring in README.md)
" colors suitable for gruvbox color scheme
hi tkLink ctermfg=72 cterm=bold,underline
hi tkBrackets ctermfg=gray
" highlight ==highlighted== text
hi tkHighlight ctermbg=yellow ctermfg=darkred cterm=bold
<
================================================================================
Section 5: Credits *telekasten.credits*
Credits go to:
* {Conni2461} on GitHub for the awesome pull request and support!
* {NeoVim} and its awesome community
* {Telescope.nvim} and its awesome community
* {ThePrimeagen} and {TJ} of twitch (and vimconf and...) fame for being awesome
and inspiring!
vim:tw=78:ts=8:ft=help:norl:
Reference in New Issue View Git Blame Copy Permalink