jonas/telekasten.nvim
1
0
Fork 0
mirror of https://github.com/Ascyii/telekasten.nvim.git synced 2026-01-01 14:14:24 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
f4f836d4b402ec45e21aaeb01c1966f3eb8a1461
telekasten.nvim/doc/telekasten.txt
Thomas Lambert ff85b22fb4 doc: improve link_notation for aliases
2022-11-14 20:44:35 +01:00

1049 lines
40 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.
For Windows users, many of the functions that require navigating file folders
do not work. This is due to how Telescope handles paths and the odd way that
Windows structures its paths. It is advised you don't use Windows.
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 Link Notation ............ |telekasten.link_notation|
3.2 Tag Notation ............. |telekasten.tag_notation|
3.3 Templates ................ |telekasten.templates|
3.4 Calendar ................. |telekasten.calendar|
3.5 Picker mappings .......... |telekasten.picker_mappings|
3.6 Mutliple home directories. |telekasten.switch_vaults|
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
-- image subdir for pasting
-- subdir name
-- or nil if pasted images shouldn't go into a special subdir
image_subdir = "img",
-- markdown file extension
extension = ".md",
-- Generate note filenames. One of:
-- "title" (default) - Use title if supplied, uuid otherwise
-- "uuid" - Use uuid
-- "uuid-title" - Prefix title by uuid
-- "title-uuid" - Suffix title with uuid
new_note_filename = "title",
-- file uuid type ("rand" or input for os.date such as "%Y%m%d%H%M")
uuid_type = "%Y%m%d%H%M",
-- UUID separator
uuid_sep = "-",
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
-- image link style",
-- wiki: ![[image name]]
-- markdown: ![](image_subdir/xxxxx.png)
image_link_style = "wiki",
-- default sort option: 'filename', 'modified'
sort = "filename",
-- specific note templates
-- set to `nil` or do not specify if you do not want a template
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'
},
-- make syntax available to markdown buffers and telescope previewers
install_syntax = true,
-- tag notation: '#tag', ':tag:', 'yaml-bare'
tag_notation = "#tag",
-- command palette theme: dropdown (window) or ivy (bottom panel)
command_palette_theme = "ivy",
-- tag list theme:
-- get_cursor: small tag list at cursor; ivy and dropdown like above
show_tags_theme = "ivy",
-- when linking to a note in subdir/, create a [[subdir/title]] link
-- instead of a [[title only]] link
subdirs_in_links = true,
vaults = {
personal = {
-- configuration for personal vault. E.g.:
-- home = "/home/user/vaults/personal",
}
},
-- how to preview media files
-- "telescope-media-files" if you have telescope-media-files.nvim installed
-- "catimg-previewer" if you have catimg installed
-- "viu-previewer" if you have viu installed
media_previewer = "telescope-media-files",
}
<
---------------------
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'
----------------------
Note to Windows users:
If you must use Windows, avoid using the drive path. You may use it,
but telekasten will ignore the drive name and create your main markdown
/ zettelkasten folder in the same drive that neovim executes from. This
is because of how Telescope handles files paths. Windows paths must be
stripped of the drive name or else the path will not be read correctly.
This is done automatically but is advised that you avoid adding it.
It is recommended that if your path is not the default to write it
like a Unix path with '/' instead of '\', or to escape the '\' as '\\'.
----------------------
*telekasten.settings.take_over_my_home*
take_over_my_home: ~
If set to `true`, telekasten.nvim will take over your home. Any notes
from the configured `home` directory will receive a `set`
`filetype=telekasten`, no matter if opened by telekasten or another
way.
Default: `true`
*telekasten.settings.auto_set_filetype*
auto_set_filetype: ~
If `false` (not recommended), the telekasten filetype will not be used
and the telekasten syntax not be loaded; markdown files will get the
markdown filetype.
Default: `true`
*telekasten.settings.daily*
daily: ~
Path to your daily notes, to separate them from 'normal' notes.
Accepts absolute path or sub-directory name.
Default: '~/zettelkasten/daily'
*telekasten.settings.weekly*
weekly: ~
Path to your weekly notes, to separate them from 'normal' notes.
Accepts absolute path or sub-directory name.
Default: '~/zettelkasten/weekly'
*telekasten.settings.templates*
templates: ~
Path to your note templates.
Accepts absolute path or sub-directory name.
Default: '~/zettelkasten/templates'
*telekasten.settings.extension*
extension: ~
Filename extension of your markdown note files.
Default: '.md'
*telekasten.settings.new_note_filename*
new_note_filename: ~
Configures the filenames of newly created notes. See |uuid_sep|
for 'uuid-title' and 'title-uuid' separator.
Valid options are:
- 'title' .. title only
- 'uuid' .. uuid only
- 'uuid-title' .. prefix title by uuid
- 'title-uuid' .. suffix title with uuid
Default: 'title'
*telekasten.settings.uuid_type*
uuid_type: ~
Type of UUID. Could be 'rand' for a random 6 character string, or a
time format to input in os.date() such as %Y%m%d%H%M.
Default: '%Y%m%d%H%M'
*telekasten.settings.uuid_sep*
uuid_sep: ~
Separator between UUID and title in filaneme.
Default: '-'
*telekasten.settings.image_subdir*
image_subdir: ~
Path to the directory where pasted images should go to. Accepts
absolute path or sub-directory name.Set to `nil` if images should not
go into a sub-directory.
Default: `nil`
*telekasten.settings.image_link_style*
image_link_style: ~
Style of links to insert when pasting an image.
Valid options are:
- 'wiki' .. places links like this: `![[image_name]]`
- 'markdown' .. `![](image_subdir/image_name)`
Default: 'markdown'
*telekasten.settings.sort*
sort: ~
Order the notes by the option.
Valid options are:
- 'filename'
- 'modified'
Default: 'filename'
*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. Set to `nil` if you don't want a
template.
Default: `nil`
Example: `'~/zettelkasten/templates/daily.md'`
*telekasten.settings.template_new_daily*
template_new_daily: ~
Markdown template for new daily notes. Set to `nil` if you don't want
a template.
Default: `nil`
Example: `'~/zettelkasten/templates/daily.md'`
*telekasten.settings.template_new_weekly*
template_new_weekly: ~
Markdown template for new weekly notes. Set to `nil` if you don't want
a template.
Default: `nil`
Example: `'~/zettelkasten/templates/daily.md'`
*telekasten.settings.install_syntax*
install_syntax:~
If `true`, telekasten's syntax for links, tags, etc. will be used for
markdown files, also in telescope previewers. Your configured markdown
syntax will be inherited, though.
Default: `true`
*telekasten.settings.tag_notation*
tag_notation:~
The tag style you want to use.
Valid options are:
- `'#tag'`
- `':tag:'`
- `'yaml-bare'`
Default: `#tag`
See |telekasten.tag_notation| for more information.
*telekasten.settings.subdirs_in_links*
subdirs_in_links:~
Include subdirs (if applicable) in generated (yanked, inserted) links.
Valid options are:
- `'tag'`
- `':tag:'`
- `'yaml-bare'`
Default: `true`
*telekasten.settings.template_handling*
template_handling:~
Strategy for telekasten to pick a template when a new note is created
via `new_note()`, or by `follow_link()` to a non-existing note.
Valid options are:
- `'smart'`: if day or week is detected in title, use daily / weekly
templates, else the new note template.
- `'prefer_new_note'`: use the new note template.
- `'always_ask'`: always ask for a template via template picker.
Default: `smart`
*telekasten.settings.new_note_location*
new_note_location:~
Path handling for `new_note()`, `new_templated_note()`, `follow_link()`
to non-existing note.
Valid options are:
- `'smart'`: put daily-looking (date as title) into the daily folder,
weekly-looking notes into the weekly folder, all other notes
into the home folder, except for notes with `sub/folders` in
the title.
- `'prefer_home'`: put all notes in home folder except for
`goto_today()` and `goto_thisweek()`, and notes with
`sub/folders` in the title.
- `'same_as_current'`: put all new notes in the directory of the
currently open note (where the cursor is) if
present or else into the home folder, except for
notes with `sub/folders` in the title.
Default: `smart`
*telekasten.settings.rename_update_links*
rename_update_links:~
If `true`, telekasten will automatically update the links after a file
has been renamed.
Default: `true`
*telekasten.settings.media_previewer*
media_previewer:~
Previewer used for viewing media / image files. There are two
options:
- `'telescope-media-files'` : use the telescope-media-files.nvim
plugin
- `'catimg-previewer'` : use the built-in `catimg` previewer.
Requires `catimg` to be installed.
- `'viu-previewer'` : use the built-in `viu` previewer.
Requires `viu` to be installed.
Default: `telescope-media-files`
*telekasten.settings.follow_url_fallback*
follow_url_fallback:~
A customizable fallback handler for urls.
When it set to nil, Telekasten will use `xdg-open` or `open`
Default: `nil`
Example: `"call jobstart('firefox --new-window {{url}}')"`
*telekasten.calendar_opts*
-----------------------------------
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)
- `tkTag` : well, tags
- `tkAliasedLink` : link with alias
- `tkHighlightedAliasedLink` : link with alias in `tkAliasedLink`
- `tkLinkAlias` : body of the link (left part of `[[aaa|bbb]]`)
- `tkLinkBody` : alias of the link (right part of `[[aaa|bbb]]`)
`tkHighlight`, has nothing to do with links but I added it anyway, since I like
highlighting text when taking notes.
Plugin supports wiki-link aliases: `[[value|alias]]`. These links will be
concealed to `[[alias]]` if `conceallevel=2`.
I also like the navigation buttons of the calendar to appear less prevalent, so
I redefine the `CalNavi` class as well.
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 guifg=blue gui=bold,underline
hi tkBrackets ctermfg=gray guifg=gray
" for gruvbox
hi tklink ctermfg=72 guifg=#689d6a cterm=bold,underline gui=bold,underline
hi tkBrackets ctermfg=gray guifg=gray
" real yellow
hi tkHighlight ctermbg=yellow ctermfg=darkred cterm=bold guibg=yellow guifg=darkred gui=bold
" gruvbox
"hi tkHighlight ctermbg=214 ctermfg=124 cterm=bold guibg=#fabd2f guifg=#9d0006 gui=bold
hi link CalNavi CalRuler
hi tkTagSep ctermfg=gray guifg=gray
hi tkTag ctermfg=175 guifg=#d3869B
<
================================================================================
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 name,
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
name, 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({opts})~
Select a note by title (file name), via Telescope, and place a `[[link]]` at
the current cursor position.
Valid keys for {opts}
i:~
If `true`, it will enter input mode by pressing the <A> key. This is useful
when being used in a simple `inoremap` key mapping like shown in
|telekasten.mappings|.
Default: `nil`
*telekasten.follow_link()*
telekasten.insert_link()~
Take the text between the brackets of a link pointing to a linked note, or
of a tag 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|
*telekasten.toggle_todo()*
telekasten.toggle_todo({opts})~
Turns a line into a `- [ ] ` todo line, or toggle between `- [ ]`, `- [x]`,
and `-` .
This can also be used in visual mode to toggle the status of multiple lines.
If using a keymapping to `toggle_todo` in visual mode, make sure the `rhs` is
`:Telekasten` `toggle_todo<CR>` instead of `<cmd>Telekasten` `toggle_todo<CR>`
to avoid neovim sending the wrong visual selection.
Valid keys for {opts}
i:~
If `true`, it will enter input mode by pressing the <A> key. This is useful
when being used in a simple `inoremap` key mapping like shown in
|telekasten.mappings|.
Default: `nil`
onlyTodo:
If true, it will avoid circling back to a regular list - when toggle_todo
is called on - [x] items.
Default: nil
*telekasten.show_backlinks()*
telekasten.show_backlinks()~
Opens a telescope search for notes that `[[link]]` back to the current note.
*telekasten.find_friends()*
telekasten.find_friends()~
Opens a telescope search for notes that also `[[link]]` to the link under the
cursor.
*telekasten.insert_img_link()*
telekasten.insert_img_link({opts})~
Opens a telescope search for all media (PDFs, images, videos (MP4, webm)) and
places a markdown image link to the picked one at the cursor position.
Note:~
If the `telescope-media-files.nvim` plugin is installed, a preview of
images / media files will be given during the search.
Valid keys for {opts}
i:~
If `true`, it will enter input mode by pressing the <A> key. This is useful
for being able to continue typing after the link has been inserted.
See also: |telekasten.mappings|
Default: `nil`
*telekasten.preview_img()*
telekasten.preview_img()~
Uses the `telescope-media-files.nvim` extension to preview the image / media
file under the cursor of a markdown image link: `![](path/to/img.png)`. The
cursor must be between `(the two parenthesis)`.
Note:~
This requires the `telescope-media-files.nvim` plugin to be installed.
*telekasten.browse_media()*
telekasten.browse_media()~
Uses the `telescope-media-files.nvim` extension to preview the image / media
file under the cursor.
Note:~
This requires the `telescope-media-files.nvim` plugin to be installed.
--------------------------------------------------------------------------------
Section 3.1: Link notation *telekasten.link_notation*
The following links are supported:
Note links~
`[[A cool title]]` ................. links to the note named 'A cool title'
`[[A cool title#Heading 27]]` ...... links to the heading 'Heading 27' within
the note named 'A cool title'
`[[A cool title#^xxxxxxxx]]` ....... links to the paragraph with id ^xxxxxxxx
within the note named 'A cool title'
`[[201705061300|A cool title]]` ..... links to the note named `201705061300` but
shows the link as `A cool title` if
`conceallevel=2`
`[[A cool title|xxxxxxxx]]` ........ links note 'A cool title' with using
name.
`[[#Heading 27]]` .................. links to the heading 'Heading 27' within
all notes
`[[#^xxxxxxxx]]` ................... links to the paragraph with id ^xxxxxxxx
within all notes
Optionally, notes can live in specific sub-directories:
`[[some/subdirectory/A cool title]]`: links to note named 'A cool title'
in some/subdirectory
`[[some/subdirectory/A cool title#Heading 27]]`: links to the heading
'Heading 27' within the note named
'A cool title' in some/subdirectory
`[[some/subdirectory/A cool title#^xxxxxxxx]]` : links to the paragraph
with id ^xxxxxxxx within the note named
'A cool title' in some/subdirectory
Note that notes linked to with headings or paragraph IDs **will not be created
automatically**. Non-existing notes will be ignored in this case, a global
telescope search wil be performed instead.
Media links~
Use these for images, PDF files, videos. If telescope-media-files is installed,
these can be previewed.
`![optional title](path/to/file)` ... links to the file `path/to/file`
--------------------------------------------------------------------------------
Section 3.2: Tag Notation *telekasten.tag_notation*
Telekasten supports the following tag notations:
1. `#tag`
2. `:tag:`
3. bare tags in a tag collection in the yaml metadata:
>
--- title: My awesome note
date: 2021-12-06
tags: [ example, note-taking, foo, bar ]
---
<
Tag syntax:~
Spaces are not allowed in tags. So, to differentiate two or more words in a
tag, use one of the following formats:
- camelCase: `#noteTaking`
- PascalCase: `#NoteTaking`
- snake_case: `#note_taking`
- kebab-case: `#note-taking`
The only symbols allowed are:
- underscore : `_`
- dash : `-`
- forward slash : `/`
Numbers are allowed in tags, as long as a tag is not purely numeric. For
example, #1984 is not a valid tag, but `#y1984` is.
Note:~
For proper highlighting, the `auto_set_filetype` option is set to `true` by
default. This automatically sets the to `telekasten`, and also registers the
syntax with telescope previewers for `.md` files.
Note:
When using the `#tag` notation, telekasten will try to differentiate an
actual tag from an hexadecimal code (e.g. `#FF0000`) to prevent false
matches. This is achieved by using the `--pcre2` flag of `ripgrep`. However,
some linux distribution (mostly the ones based on Debian) do not compile
ripgrep with this flag by default, making it impossible to use. If this is
the case, the tag functions of telekasten will not be able to differentiate
color codes from actual tags and will return everything. A workaround is to
either use the `:tag:` notation or to recompile ripgrep locally with the
appropriate flag (see issues # 115 and #145).
--------------------------------------------------------------------------------
Section 3.3: 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 |
| `{{shorttitle}} | the short title of the note | dir/dir/My Note -> My Note |
| `{{uuid}}` | UUID of the note | 202201271129 |
| `{{date}}` | date in iso format | 2021-11-21 |
| `{{prevday}}` | previous day, iso | 2021-11-20 |
| `{{nextday}}` | next day, iso | 2021-11-22 |
| `{{hdate}}` | date in long format | Sunday, November 21st, 2021 |
| `{{rfc3339}}` | date in RFC3339 format | 2021-11-21T14:30Z+01:00 |
| `{{week}}` | week of the year | 46 |
| `{{prevweek}}` | previous week | 45 |
| `{{nextweek}}` | next week | 47 |
| `{{isoweek}}` | week in iso format | 2021-46 |
| `{{isoprevweek}}` | last week, iso | 2021-45 |
| `{{isonextweek}}` | next week, iso | 2021-47 |
| `{{year}}` | year | 2021 |
| `{{monday}}` | Monday, iso | 2021-11-15 |
| `{{tuesday}}` | Tuesday, iso | 2021-11-16 |
| `{{wednesday}}` | Wednesday, iso | 2021-11-17 |
| `{{thursday}}` | Thursday, iso | 2021-11-18 |
| `{{friday}}` | Friday, iso | 2021-11-19 |
| `{{saturday}}` | Saturday, iso | 2021-11-20 |
| `{{sunday}}` | Sunday, iso (see note)| 2021-11-21 |
+-----------------+-----------------------+-----------------------------+
Note: Sunday is adjusted to match the user's `calendar_monday` preference.
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.4: 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.
If you want to see a big calendar showing the current month that fills your
entire window, you can issue the following command in vim:
>
:CalendarT
<
Note:~
Calendar functions are only available if you have the plugin `calendar-vim`
installed, which you can find at https://github.com/renerocksai/calendar-vim
--------------------------------------------------------------------------------
Section 3.5: Picker mappings *telekasten.picker_mappings*
When you are prompted with a telescope picker to select a note or media file,
the following mappings apply:
<CTRL> + <i>
Inserts a link to the selected note / image.
The option `insert_after_inserting` defines if insert mode will be entered
after the link is pasted into your current buffer.
<CTRL> + <y>
Yanks a link to the selected note / image, ready for <p>asting.
The option `close_after_yanking` defines whether the telescope window should
be closed when the link has been yanked.
<RETURN> / <ENTER>
Usually opens the selected note or performs the action defined by the called
function. E.g. `insert_img_link()`'s action is to insert a link to the
selected image.
--------------------------------------------------------------------------------
Section 3.6 Mutliple home directories *telekasten.switch_vaults*
You can have multiple home directories setup in telekasten. The configuration
for each vault is stored as a map in telekasten. You can use `switch_vaults
to launch a picker to choose the vaults.
================================================================================
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').goto_thisweek()<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>
nnoremap <leader>zC :CalendarT<CR>
nnoremap <leader>zi :lua require('telekasten').paste_img_and_link()<CR>
nnoremap <leader>zt :lua require('telekasten').toggle_todo()<CR>
nnoremap <leader>zb :lua require('telekasten').show_backlinks()<CR>
nnoremap <leader>zF :lua require('telekasten').find_friends()<CR>
nnoremap <leader>zI :lua require('telekasten').insert_img_link({ i=true })<CR>
nnoremap <leader>zp :lua require('telekasten').preview_img()<CR>
nnoremap <leader>zm :lua require('telekasten').browse_media()<CR>
nnoremap <leader># :lua require('telekasten').show_tags()<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({ i=true })<CR>
inoremap <leader>zt <ESC>:lua require('telekasten').toggle_todo({ i=true })<CR>
inoremap <leader># <cmd>lua require('telekasten').show_tags({i = true})<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 guifg=#689d6a cterm=bold,underline gui=bold,underline
hi tkBrackets ctermfg=gray guifg=gray
" real yellow
hi tkHighlight ctermbg=yellow ctermfg=darkred cterm=bold guibg=yellow guifg=darkred gui=bold
" gruvbox
"hi tkHighlight ctermbg=214 ctermfg=124 cterm=bold guibg=#fabd2f guifg=#9d0006 gui=bold
hi link CalNavi CalRuler
hi tkTagSep ctermfg=gray guifg=gray
hi tkTag ctermfg=175 guifg=#d3869B
<
================================================================================
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} aka {teej_dv} aka {TJDeVries} 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