initial support for tags: we start with: syntax

2026-01-01 06:14:23 -05:00 · 2021-12-08 19:04:01 +01:00
parent ddfc7a3ac9
commit e710d725fe
8 changed files with 165 additions and 28 deletions
--- a/.luacheckrc
+++ b/.luacheckrc
@@ -14,6 +14,7 @@ ignore = {

 globals = {
  "_",
+  "vim",
  "TelescopeGlobalState",
  "_TelescopeConfigurationValues",
  "_TelescopeConfigurationPickers",
--- a/BACKLOG.md
+++ b/BACKLOG.md
@@ -1,5 +1,7 @@
 # Backlog

+- [ ] maybe a virtual line in the 1st line that shows number of backlinks and maybe other interesting stuff
+    - or put it as an extmark at the end of the first line, meh.
 - [ ] some support for #tags
 - [ ] some cool buffer showing backlinks (and stuff?)
    - maybe another one where we dot-render a graph of linked notes and 
@@ -11,6 +13,8 @@
 - [ ] yt video

 ## Dones
+- [x] syntax for tags, incl. plenary filetype
+    - for proper display, needed to define 'telekasten' syntax
 - [x] browse_media()
 - [x] action mappings for notes: yanking and link inserting
 - [x] document and suggest colors for Calendar nav buttons, they look weird in gruvbox
--- a/README.md
+++ b/README.md
@@ -81,10 +81,11 @@ of being able to edit it.
 * [1. Get Help](#1-get-help)
 * [2. Use it](#2-use-it)
    * [2.0 Link notation](#20-link-notation)
-    * [2.1 Note templates](#21-note-templates)
-        * [2.1.1 Template files](#211-template-files)
-    * [2.2 Using the calendar](#22-using-the-calendar)
-    * [2.3 Using the telescope pickers](#23-using-the-telescope-pickers)
+    * [2.1 Tag notation](#21-tag-notation)
+    * [2.2 Note templates](#22-note-templates)
+        * [2.2.1 Template files](#221-template-files)
+    * [2.3 Using the calendar](#23-using-the-calendar)
+    * [2.4 Using the telescope pickers](#24-using-the-telescope-pickers)
 * [3. Bind it](#3-bind-it)
 * [4. The hardcoded stuff](#4-the-hardcoded-stuff)

@@ -254,6 +255,8 @@ END
 | `calendar_opts` | options for calendar, see below | see below |
 | `close_after_yanking` | close telescope preview after yanking via <kbd>ctrl</kbd><kbd>y</kbd>| false |
 | `insert_after_inserting` | enter insert mode after inserting a link from a telescope picker via <kbd>ctrl</kbd><kbd>i</kbd>| true |
+| `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. | true |
+

 **Please note:** If you do not want to use a template, set its associated option to `nil` or remove it from your config.
 ```lua
@@ -280,13 +283,14 @@ The calendar support has its own options, contained in `calendar_opts`:


 ### 0.3 Configure your own colors
-Telekasten.nvim allows you to color your `[[links]]` by providing two syntax groups:
+Telekasten.nvim allows you to color your `[[links]]` and `#tags` by providing the following 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

-The last one, `tkHighlight`, has nothing to do with links but I added it anyway, since I like highlighting text when
+`tkHighlight`, has nothing to do with links but I added it anyway, since I like highlighting text when
 taking notes 😄.

 I also like the navigation buttons of the calendar to appear less prevalent, so I also redefine the `CalNavi` class.
@@ -308,8 +312,15 @@ hi tkHighlight ctermbg=yellow ctermfg=darkred cterm=bold

 " for calendar, I prefer less prevalent navigation buttons
 hi link CalNavi CalRuler
+
+" colors for tags:
+hi tkTag ctermfg=175
+" tag separator is only relevant in the following syntax:
+" tags: [ tag1, tag2, tag3 ] 
+hi tkTagSep ctermfg=gray
 ```

+
 ## 1. Get Help
 Telekasten.nvim now comes with its own help file. So you can always:

@@ -438,7 +449,40 @@ Regarding linking to paragraphs: The `^blockid` notation is supported by more an
  Here goes the next paragraph.
  ```

-### 2.1 Note templates
+### 2.1 Tag notation
+
+Telekasten supports the following tag notations:
+
+1. `#tag`
+2. `:tag:`
+3. bare tags in a tag collection in the yaml metadata:
+
+```yaml
+---
+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.
+
+### 2.2 Note templates

 The functions `goto_today`, `goto_thisweek`, `find_daily_notes`, `find_weekly_notes`, and `follow_link` can create
 non-existing notes. This allows you to 'go to today' without having to create today's note beforehand. When you just
@@ -459,7 +503,7 @@ The following table shows what action creates what kind of non-existing note:

 If the associated option is `true`, non-existing notes will be created.

-#### 2.1.1 Template files
+#### 2.2.1 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.
@@ -516,7 +560,7 @@ date:  {{hdate}}
 ## Sunday link
 ```

-### 2.2 Using the calendar
+### 2.3 Using the calendar

 When invoking `show_calendar()`, a calendar showing the previous, current, and next month is shown at the right side of
 vim.
@@ -534,7 +578,7 @@ command in vim:
 ```


-### 2.3 Using the telescope pickers
+### 2.4 Using the telescope pickers

 When you are prompted with a telescope picker to select a note or media file, the following mappings apply:

@@ -591,6 +635,12 @@ hi tkHighlight ctermbg=yellow ctermfg=darkred cterm=bold

 " for calendar, I prefer less prevalent navigation buttons
 hi link CalNavi CalRuler
+
+" colors for tags:
+hi tkTag ctermfg=175
+" tag separator is only relevant in the following syntax:
+" tags: [ tag1, tag2, tag3 ] 
+hi tkTagSep ctermfg=gray
 ```

 ## 4. The hardcoded stuff
--- a/data/plenary/filetypes/telekasten.lua
+++ b/data/plenary/filetypes/telekasten.lua
@@ -0,0 +1,5 @@
+return {
+    extension = {
+        ['md'] = 'telekasten'
+    }
+}
--- a/doc/telekasten.txt
+++ b/doc/telekasten.txt
@@ -29,9 +29,10 @@ CONTENTS
    2. Colors ........................ |telekasten.colors|
    3. Usage ......................... |telekasten.usage|
        3.1 Link Notation ............ |telekasten.link_notation|
-        3.2 Templates ................ |telekasten.templates|
-        3.3 Calendar ................. |telekasten.calendar|
-        3.4 Picker mappings .......... |telekasten.picker_mappings|
+        3.2 Tag Notation ............. |telekasten.tag_notation|
+        3.3 Templates ................ |telekasten.templates|
+        3.4 Calendar ................. |telekasten.calendar|
+        3.5 Picker mappings .......... |telekasten.picker_mappings|
    4. Suggested mappings ............ |telekasten.mappings|
    5. Credits ....................... |telekasten.credits|

@@ -516,7 +517,39 @@ Note that notes linked to with headings or paragraph IDs **will not be created
 automatically**. 

 --------------------------------------------------------------------------------
-Section 3.2: Templates                                    *telekasten.templates*
+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.
+
+--------------------------------------------------------------------------------
+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
@@ -601,7 +634,7 @@ And finally, what a template for weekly notes could look like:
 <

 --------------------------------------------------------------------------------
-Section 3.3: Calendar                                    *telekasten.calendar*
+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.
@@ -623,7 +656,7 @@ Note:~
  installed, which you can find at https://github.com/renerocksai/calendar-vim 

 --------------------------------------------------------------------------------
-Section 3.4: Picker mappings                      *telekasten.picker_mappings*
+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:
@@ -688,6 +721,12 @@ However, here are some suggestions:

 " for calendar, I prefer less prevalent navigation buttons
 hi link CalNavi CalRuler
+
+ " colors for tags:
+ hi tkTag ctermfg=175
+ " tag separator is only relevant in the following syntax:
+ " tags: [ tag1, tag2, tag3 ] 
+ hi tkTagSep ctermfg=gray
 <

 ================================================================================
--- a/lua/telekasten.lua
+++ b/lua/telekasten.lua
@@ -9,6 +9,7 @@ local utils = require("telescope.utils")
 local previewers = require("telescope.previewers")
 local make_entry = require("telescope.make_entry")
 local debug_utils = require("plenary.debug_utils")
+local filetype = require("plenary.filetype")

 -- declare locals for the nvim api stuff to avoid more lsp warnings
 local vim = vim
@@ -60,6 +61,7 @@ M.Cfg = {
    },
    close_after_yanking = false,
    insert_after_inserting = true,
+    install_syntax = true
 }

 local function file_exists(fname)
@@ -1481,6 +1483,14 @@ local function Setup(cfg)
        weekly = M.Cfg.template_new_weekly,
    }

+    if M.Cfg.install_syntax then
+        -- for previewers to pick up our syntax, we need to tell plenary to override `.md` with our syntax
+        filetype.add_file("telekasten")
+
+        -- now activate our syntax also for all markdown files
+        vim.cmd("autocmd filetype markdown set syntax=telekasten")
+    end
+
    if debug then
        print("Resulting config:")
        print("-----------------")
--- a/syntax/markdown.vim
+++ b/syntax/markdown.vim
@@ -1,25 +1,25 @@
-syntax region tkLink matchgroup=tkBrackets start=/\[\[/ end=/\]\]/ display oneline 
-syntax region tkHighlight matchgroup=tkBrackets start=/==/ end=/==/ display oneline 
+"syn region Comment matchgroup=mkdDelimiter start="\%^---$" end="^\(---\|\.\.\.\)$"  contains=tkTag keepend
+
+syntax region tkLink matchgroup=tkBrackets start=/\[\[/ end=/\]\]/ display oneline
+syntax region tkHighlight matchgroup=tkBrackets start=/==/ end=/==/ display oneline

 syntax match tkTag "\v#[a-zA-Z]+[a-zA-Z0-9/-_]*"
 syntax match tkTag "\v:[a-zA-Z]+[a-zA-Z0-9/-_]*:"

 syntax match tkTagSep "\v\s*,\s*" contained
-syntax region tkTag matchgroup=tkBrackets start=/^\s*tags:\s*\[\s*/ end=/\s*\]\s*$/ contains=tkTagSep display oneline
+syntax region tkTag matchgroup=tkBrackets start=/^tags\s*:\s*\[\s*/ end=/\s*\]\s*$/ contains=tkTagSep display oneline

-hi tkTagSep ctermfg=gray
-hi tkTag ctermfg=magenta
-
-echomsg "loaded"
-
-" just blue
+" " just blue
 "     hi tklink ctermfg=Blue cterm=bold,underline
 "     hi tkBrackets ctermfg=gray

-
-" for gruvbox
+" " for gruvbox
 "     hi tklink ctermfg=72 cterm=bold,underline
 "     hi tkBrackets ctermfg=gray

-" Highlight ==highlighted== text 
+" " Highlight ==highlighted== text 
 "     hi tkHighlight ctermbg=yellow ctermfg=darkred cterm=bold
+"
+" " Tags
+" hi tkTagSep ctermfg=gray
+" hi tkTag ctermfg=magenta
--- a/syntax/telekasten.vim
+++ b/syntax/telekasten.vim
@@ -0,0 +1,28 @@
+"syn region Comment matchgroup=mkdDelimiter start="\%^---$" end="^\(---\|\.\.\.\)$"  contains=tkTag keepend
+runtime! syntax/markdown.vim
+"unlet b:current_syntax
+
+syntax region tkLink matchgroup=tkBrackets start=/\[\[/ end=/\]\]/ display oneline
+syntax region tkHighlight matchgroup=tkBrackets start=/==/ end=/==/ display oneline
+
+syntax match tkTag "\v#[a-zA-Z]+[a-zA-Z0-9/-_]*"
+syntax match tkTag "\v:[a-zA-Z]+[a-zA-Z0-9/-_]*:"
+
+syntax match tkTagSep "\v\s*,\s*" contained
+syntax region tkTag matchgroup=tkBrackets start=/^tags\s*:\s*\[\s*/ end=/\s*\]\s*$/ contains=tkTagSep display oneline
+
+
+" " just blue
+"     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
+"
+" " Tags
+" hi tkTagSep ctermfg=gray
+" hi tkTag ctermfg=magenta