mirror of
https://github.com/Ascyii/telekasten.nvim.git
synced 2026-01-01 06:14:23 -05:00
first cut of help file
This commit is contained in:
Rene Schallner
518
doc/telekasten.txt
Normal file
518
doc/telekasten.txt
Normal file
@@ -0,0 +1,518 @@
|
||||
================================================================================
|
||||
*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
Block a user