Merge pull request #329 from TheTaoOfSu/refact

Merge latest main developments into refact, before pursuing the refactoring effort.
nvim-telekasten · May 6, 2024 · 7b22b78 · 7b22b78
2 parents 81cb818 + 09b5692
commit 7b22b78
Show file tree

Hide file tree

Showing 8 changed files with 1,405 additions and 1,136 deletions.
diff --git a/README.md b/README.md
@@ -52,7 +52,6 @@ also just insert a link to the note or yank a link instead of opening the note.
 
 ![](img/tags-linkcounts.png)
 
-
 ## Contents
 
 <!-- FIXME -->
@@ -76,6 +75,7 @@ also just insert a link to the note or yank a link instead of opening the note.
 - [Hard-coded stuff](#hard-coded-stuff)
 
 ## Requirements
+
 Telekasten requires Neovim v0.6.0 or higher. Besides that, its only mandatory
 dependency of is
 [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim), which acts
@@ -115,7 +115,6 @@ telekasten.requirements`).
 
 </details>
 
-
 <details>
 <summary>Vim-plug</summary>
 
@@ -136,8 +135,8 @@ telekasten.requirements`).
 
 </details>
 
-
 ### Base setup
+
 In order to use Telekasten, you need to first require its setup function
 somewhere in your `init.lua`. Take this opportunity to indicate the path for
 your notes directory. If you do not specify anything, the plugin will ask you to
@@ -148,33 +147,37 @@ require('telekasten').setup({
   home = vim.fn.expand("~/zettelkasten"), -- Put the name of your notes directory here
 })
 ```
+
 **NOTE:** For Windows users, please indicate the path as
 `C:/Users/username/zettelkasten/`. See `:h telekasten.windows` for more details
 about the specificities for Windows.
 
 ### Suggested dependencies
 
 #### Calendar
+
 Telekasten interacts very nicely with
 [calendar-vim](https://github.com/renerocksai/calendar-vim). Installing this
 plugin will allow you to create journal entries for the selected dates and
 highlight dates with attached entries.
 
 #### Image preview
+
 Various plugins or external tools can be used as image previewers to help you
 pick the correct illustrations for your note.
+
 - [telescope-media-files.nvim](https://github.com/nvim-telescope/telescope-media-files.nvim)
 - [catimg](https://github.com/posva/catimg)
 - [viu](https://github.com/atanunq/viu)
 
 #### Image pasting
+
 - [xclip](https://github.com/astrand/xclip)
 - [wl-clipboard](https://github.com/bugaevc/wl-clipboard)
 
 _Image pasting is supported by default on MacOS, it is not necessary to install
 any other tool._
 
-
 #### Other useful resources/plugins
 
 While they do not interact directly with Telekasten, the following plugins
@@ -191,15 +194,18 @@ greatly improve the note-taking experience.
   generate a table of contents for your markdown documents
 - [synctodo](https://github.com/cnshsliu/synctodo): bash script to sync todos
   among Telekasten, Mac and iPhone reminders.
-
+- [telescope-all-recent](https://github.com/prochri/telescope-all-recent.nvim):
+  shows files you have recently opened.
 
 ## Usage
 
 The simplest way to use the plugin is to call directly the related Telekasten
 command:
+
 ```vim
 :Telekasten <sub-command>
 ```
+
 <details>
 <summary>Advanced use</summary>
 Each sub-command is implemented by a specific lua function. While high-level
@@ -211,14 +217,13 @@ custom mappings.
 :lua require('telekasten').search_notes()
 ```
 
-See the [wiki](https://github.com/renerocksai/telekasten.nvim/wiki/Mappings#advanced-key-mappings) for more details regarding advanced usage.
 </details>
 
 ### Commands
 
 The following sub-commands are defined:
 
-- `panel` : brings up the [command palette](command-palette)
+- `panel` : brings up the [command palette](#command-palette)
 - `find_notes` : Find notes by title (filename)
 - `show_tags` : brings up the tag list. From there you can select a tag to search for tagged notes - or yank or insert the tag
 - `find_daily_notes` : Find daily notes by title (date)
@@ -243,23 +248,23 @@ The following sub-commands are defined:
 - `switch_vault` : switch the vault. Brings up a picker. See the `vaults` config
   option for more.
 
-
-###  Command palette
+### Command palette
 
 Telekasten comes with a small helper command palette that let the user browse
 the different commands available. This feature is quite similar to the excellent
 [which-key.nvim](https://github.com/folke/which-key.nvim) plugin, although
 limited to Telekasten.
 
 You can call this panel using
+
 ```vim
 :Telekasten panel
 ```
+
 This can be especially useful if all your Telekasten mappings start with the
 same prefix. In that case, bind the command panel to the prefix only and it will
 pop-up when you hesitate to complete the mapping.
 
-
 ## Customization
 
 ### Highlights
@@ -268,14 +273,14 @@ Telekasten.nvim allows you to color your `[[links]]` and `#tags` by providing
 the following syntax groups:
 
 - `tkLink` : the link title inside the brackets
+- `tkAliasedLink` : the concealed portion of `[[concealed link|link alias]]`
 - `tkBrackets` : the brackets surrounding the link title
 - `tkHighlight` : ==highlighted== text (non-standard markdown)
 - `tkTag` :  well, tags
 
 An additional `CalNavi` group is defined to tweak the appearance of the calendar
 navigation button.
 
-
 ```vim
 " Example
 hi tkLink ctermfg=Blue cterm=bold,underline guifg=blue gui=bold,underline
@@ -289,7 +294,6 @@ workflow even smoother. A good idea is to take advantage of the [command
 palette][#command-palette] and start all your mappings with the same prefix
 (`<leader>z`, for `Z`ettelkasten for instance).
 
-
 ```lua
 -- Launch panel if nothing is typed after <leader>z
 vim.keymap.set("n", "<leader>z", "<cmd>Telekasten panel<CR>")
@@ -309,18 +313,16 @@ vim.keymap.set("i", "[[", "<cmd>Telekasten insert_link<CR>")
 
 ```
 
-
 #### Advanced mappings
+
 Each Telekasten command is bound to a specific lua function. As lua functions
 can accept arguments, it is possible to craft special mappings to tailor the
 execution of a function to your specific need.
 
-See the [wiki](https://github.com/renerocksai/telekasten.nvim/wiki/Mappings#advanced-key-mappings) for more details regarding advanced key mappings.
-
-
 ## Features
 
 ### Vaults
+
 Telekasten allows the user to have completely separated note collections and
 switch between them easily. Simply add data to the `vaults` table in the
     configuration and configure each vault as you wish.
@@ -356,15 +358,14 @@ these can be previewed.
 See the documentation for more details regarding the different types of links
 (`:h telekasten.link_notation`).
 
-
 ### Tag notation
 
 Telekasten supports the following tag notations:
 
 1. `#tag`
-2. `:tag:`
-3. `yaml-bare`: bare tags in a tag collection in the yaml metadata:
-
+2. `@tag`
+3. `:tag:`
+4. `yaml-bare`: bare tags in a tag collection in the yaml metadata:
 
 See the documentation for more details regarding the tag syntax (`:h
 telekasten.tag_notation`).

diff --git a/doc/telekasten.txt b/doc/telekasten.txt
@@ -69,8 +69,8 @@ telekasten.setup({opts})
 
       -- Main paths
       home = '/path/to/directory',        -- path to main notes folder
-      daily = '/path/to/directory',       -- path to daily notes
-      weekly = '/path/to/directory',      -- path to weekly notes
+      dailies = '/path/to/directory',       -- path to daily notes
+      weeklies = '/path/to/directory',      -- path to weekly notes
       templates = '/path/to/directory',   -- path to templates
 
       -- Specific note templates
@@ -103,6 +103,9 @@ telekasten.setup({opts})
       dailies_create_nonexisting = true,    -- create non-existing dailies
       weeklies_create_nonexisting = true,   -- create non-existing weeklies
 
+      -- skip telescope prompt for goto_today and goto_thisweek
+      journal_auto_open = false,
+
       -- Image link style",
         -- wiki:     ![[image name]]
         -- markdown: ![](image_subdir/xxxxx.png)
@@ -114,7 +117,7 @@ telekasten.setup({opts})
       -- Make syntax available to markdown buffers and telescope previewers
       install_syntax = true,
 
-      -- Tag notation: '#tag', ':tag:', 'yaml-bare'
+      -- Tag notation: '#tag', '@tag', ':tag:', 'yaml-bare'
       tag_notation = "#tag",
 
       -- When linking to a note in subdir/, create a [[subdir/title]] link
@@ -125,7 +128,9 @@ telekasten.setup({opts})
       command_palette_theme = "ivy",
 
       -- Tag list theme:
-        -- get_cursor: small tag list at cursor; ivy and dropdown like above
+        -- get_cursor (small tag list at cursor)
+        -- dropdown (window)
+        -- ivy (bottom panel)
       show_tags_theme = "ivy",
 
       -- Previewer for media files (images mostly)
@@ -134,6 +139,20 @@ telekasten.setup({opts})
         -- "viu-previewer" if you have viu installed
       media_previewer = "telescope-media-files",
 
+      -- Customize insert image and preview image files list. This is useful
+      -- to add optional filetypes into filtered list (for example
+      -- telescope-media-files optionally supporting svg preview)
+      media_extensions = {
+        ".png",
+        ".jpg",
+        ".bmp",
+        ".gif",
+        ".pdf",
+        ".mp4",
+        ".webm",
+        ".webp",
+      },
+
       -- Calendar integration
       plug_into_calendar = true,         -- use calendar integration
       calendar_opts = {
@@ -162,6 +181,8 @@ telekasten.setup({opts})
         }
       },
 
+      -- Specify a clipboard program to use
+      clipboard_program = "", -- xsel, xclip, wl-paste, osascript
     }
 <
 
@@ -331,6 +352,14 @@ telekasten.setup({opts})
 
         Default: true
 
+                         *telekasten.settings.journal_auto_open*
+    journal_auto_open: ~
+        Flag that determines whether the telescope picker should be used when
+        opening the daily and weekly notes, or if they should be directly
+        created/opened.
+
+        Default: false
+
                                    *telekasten.settings.template_new_note*
     template_new_note: ~
         Markdown template for new notes. Set to `nil` if you don't want a
@@ -369,6 +398,7 @@ telekasten.setup({opts})
 
         Valid options are:
         - `'#tag'`
+        - `'@tag'`
         - `':tag:'`
         - `'yaml-bare'`
 
@@ -428,7 +458,7 @@ telekasten.setup({opts})
 
                                        *telekasten.settings.media_previewer*
     media_previewer:~
-        Previewer used for viewing media / image files. There are two
+        Previewer used for viewing media / image files. There are three
         options:
         - `'telescope-media-files'` : use the telescope-media-files.nvim
           plugin
@@ -446,6 +476,14 @@ telekasten.setup({opts})
 
         Default: `nil`
         Example: `"call jobstart('firefox --new-window {{url}}')"`
+
+                                  *telekasten.settings.enable_create_new*
+    enable_create_new: ~
+        Flag that determines if creating new notes with <C-n> in enabled when
+        using the `find_notes` picker.
+
+        Default: true
+
                                                *telekasten.calendar_opts*
     -----------------------------------
     Valid keys for {opts.calendar_opts}
@@ -496,10 +534,7 @@ groups:
 - `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]]`)
+- `tkAliasedLink` : the concealed part of the link (left part of `[[aaa|bbb]]`)
 
 `tkHighlight`, has nothing to do with links but I added it anyway, since I like
 highlighting text when taking notes.
@@ -530,6 +565,12 @@ You can assign colors to the new syntax groups in your `init.vim`:
   hi tkTag ctermfg=175 guifg=#d3869B
 <
 
+NOTE: Users configuring the following highlight groups prior to 09/2023, be aware they are deprecated:
+- `tkHighlightedAliasLink`: this syntax group is now covered by `tkHighlight`
+- `tkLinkBody`: this syntax group is renamed to `tkAliasedLink`
+- `tkAliasedLink`: this group used to cover the whole link, it is now equivalent to the former `tkLinkBody`
+- `tkLinkAlias`: this rule is deprecated
+
 ================================================================================
 Section 3: Usage                                              *telekasten.usage*
 
@@ -666,7 +707,7 @@ telekasten.insert_link({opts})~
     Default: `nil`
 
                                                    *telekasten.follow_link()*
-telekasten.insert_link()~
+telekasten.follow_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.
 
@@ -817,8 +858,9 @@ 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:
+2. `@tag`
+3. `:tag:`
+4. bare tags in a tag collection in the yaml metadata:
 >
   ---
   title: My awesome note