From fcc5a76500a89ecf8489aa322f2cc769824cee88 Mon Sep 17 00:00:00 2001 From: Rene Schallner Date: Wed, 24 Nov 2021 23:06:42 +0100 Subject: [PATCH] first cut of help file --- doc/telekasten.txt | 518 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 518 insertions(+) create mode 100644 doc/telekasten.txt diff --git a/doc/telekasten.txt b/doc/telekasten.txt new file mode 100644 index 0000000..e6dc320 --- /dev/null +++ b/doc/telekasten.txt @@ -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 zf :lua require('telekasten').find_notes() + nnoremap zd :lua require('telekasten').find_daily_notes() + nnoremap zg :lua require('telekasten').search_notes() + nnoremap zz :lua require('telekasten').follow_link() + nnoremap zt :lua require('telekasten').goto_today() + nnoremap zw :lua require('telekasten').find_weekly_notes() + nnoremap zn :lua require('telekasten').new_note() + nnoremap zN :lua require('telekasten').new_templated_note() + nnoremap zy :lua require('telekasten').yank_notelink() + nnoremap zc :lua require('telekasten').show_calendar() + + " we could define [[ in **insert mode** to call insert link + " inoremap [[ :lua require('telekasten').insert_link() + " alternatively: leader [ + inoremap [ :lua require('telekasten').insert_link() + + + " 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: