zettelkasten.nvim/README.md

# Zettelkasten.nvim

To develop / debug:

start neovim with  `nvim --cmd "set rtp+=$(pwd)" .` to automatically load the files in project dir as if they were on path

next up:
[ ] fix link following:
  * [x] empty space (e.g. in link text, or link itself) disrupts link regex search
  * [x] line-end following breaks if cursor is in the MIDDLE of the link
  * [x] extract anchor from link/string (anchor.lua)
    * [x] probably stop hardcoding anchor regex, make an option
    * [ ] implement custom anchor creation function to go with custom regex
  * [ ] opening zettel should use generated link table for full filename anchor search
    * [x] need a default zettel directory to look in
  * [ ] link following order should be:
    * [x] look up & follow anchor
    * [ ] look for filename in current dir (or relative/absolute link loc)
    * [ ] implement fallback to filename in any of zettel subdirs

## TODO: needed functionality

* [ ] note creation (new anchor)
  * [x] create anchor
    * [ ] *unique* anchor creation
  * [x] create link (md / wiki)
* [ ] note listing (anchors / titles, no anchor)
  * [ ] list anchors
  * [ ] list filenames
* [ ] link following (to existing anchor)
  * [ ] fallback to filename if anchor invalid / not found
* [ ] link creation (to existing note)
  * [ ] list existing
  * [ ] create link (md / wiki)
* [ ] link switching (point to another existing note)
* [ ] note search (title / full-text)
* [ ] jump to zettel (open existing anchor)
  * [ ] select by anchor
  * [ ] select by (fuzzy) title match
* [ ] options
 * [x] zettel anchor separator
 * [x] zettel extension
 * [x] link style (wiki/markdown)
  * [ ] custom link style?
 * [x] link detection/following (under word, next on line)
 * [ ] recursive dir lookup for zettel
 * [ ] zettel anchor regex

## TODO: nice-to-haves

* [ ] refactor parsers (md/wiki) to be tables of functions/regex in options, so e.g. valid link detection can call `options.parser.isValidLink(link)` or transformation `options.parser.styleLink(anchor, text)`
  * [ ] use unified parser model (e.g. containing `turn-to-link()`, `parse-link()`) function
  * [ ] enable custom parser supply
* [ ] completion engine (e.g. for `completion-nvim`, look in completion_buffers/completion-tags for reference)
* [ ] zettel caching for big directories
* [ ] backlinks (via rg for filename anchor?)
  * [ ] keep tree of notes cached?
* [ ] zettel maintenance
  * [ ] fix malformed anchors
    * [ ] fix-link function which looks for most similar file to be found and renames file/link automatically (after confirmation)
  * [ ] add missing anchors
  * [ ] 'rename' anchor (goes against stability?)
  * [ ] recognize duplicate anchors (in directory, when listing, etc)
    * [ ] provide option to rename and automatically change backlinks
* [ ] zettel 'lens' (preview first headline + content of linked zettel through floating window etc, on keypress)
* [ ] support *both* md-style and wiki-style links at the same time
* [ ] file/directory exception list for gathering files, which will be ignored
* [ ] 'strict' mode *only* matching and following valid anchor links

## TODO: maintenance

* [ ] remove hard-coding of option vimnames in tests, now that we can dynamically change this through a single table

* anchor creation
  * *must* be unique
  * default: 10 digits, usually current date+time (YYMMDDHHmm)
  * but, if multiple links created within one minute (or other circumstances), this would duplicate
  * thus, duplicate-check before creating a new anchor
  * if duplicated, generate first *non*-duplicated link (recursive?)
  * try to move *backwards* through minutes not forward
    * i.e. if 2030101200 exists move to 2030101159, 2030101158, ...
    * if moving backwards, we do not take away id space from *future* note creation
    * if moving forwards, every zettel created within a minute would delay next zettel creation *another* minute
* to decide: should zettel creation create a zettel in current working dir or at zettel root dir? or set by option?

* [ ] (CODE) switch -- comments to --- doc comments for function descriptions etc

## Options

atm:
```
anchor_separator = vim.g["zettel_anchor_separator"] or vim.b["zettel_anchor_separator"] or "_",
zettel_extension = vim.g["zettel_extension"] or vim.b["zettel_extension"] or ".md",
zettel_root = vim.g["zettel_root"] or vim.b["zettel_root"] or "~/documents/notes",
```
Initial commit 2020-10-26 14:55:40 +00:00			`# Zettelkasten.nvim`

Add Datestamp and Link creation functionality 2020-10-26 18:32:27 +00:00			`To develop / debug:`

			start neovim with `nvim --cmd "set rtp+=$(pwd)" .` to automatically load the files in project dir as if they were on path

Add zettel link following style option `g:zettel_link_following` can be set to `cursor` or `line` to change the way zk detect the closest link to follow to (or create a new link for). Setting it to `cursor` will look for the current word under the cursor and decide if it is a followable link. `line` will look from the current cursor position to the end of the line instead. 2020-11-01 21:18:40 +00:00			`next up:`
Remove hardcoded options, do repo house-cleaning Update readme and tmux.session file. Remove unused tests, update option calling. 2020-11-04 21:27:30 +00:00			`[ ] fix link following:`
			`* [x] empty space (e.g. in link text, or link itself) disrupts link regex search`
			`* [x] line-end following breaks if cursor is in the MIDDLE of the link`
Add anchor extraction function `anchor.extract(string, anchor)` will find and extract a zettel anchor from any string passed in. It can be given an optional anchor regex which will supersede any regex set in the plugin options. 2020-11-06 14:47:33 +00:00			`* [x] extract anchor from link/string (anchor.lua)`
			`* [x] probably stop hardcoding anchor regex, make an option`
			`* [ ] implement custom anchor creation function to go with custom regex`
Remove hardcoded options, do repo house-cleaning Update readme and tmux.session file. Remove unused tests, update option calling. 2020-11-04 21:27:30 +00:00			`* [ ] opening zettel should use generated link table for full filename anchor search`
Add configurable zettel root directory Plugin will by default recursively look in this directory for any zettel. 2020-11-06 15:35:36 +00:00			`* [x] need a default zettel directory to look in`
Update readme and debug mappings 2021-04-30 11:28:39 +00:00			`* [ ] link following order should be:`
			`* [x] look up & follow anchor`
			`* [ ] look for filename in current dir (or relative/absolute link loc)`
			`* [ ] implement fallback to filename in any of zettel subdirs`
Add zettel link following style option `g:zettel_link_following` can be set to `cursor` or `line` to change the way zk detect the closest link to follow to (or create a new link for). Setting it to `cursor` will look for the current word under the cursor and decide if it is a followable link. `line` will look from the current cursor position to the end of the line instead. 2020-11-01 21:18:40 +00:00
Move anchor prepend function to anchor module 2020-10-31 10:01:53 +00:00			`## TODO: needed functionality`
Initial commit 2020-10-26 14:55:40 +00:00
Move intended features to README 2020-10-29 17:31:08 +00:00			`* [ ] note creation (new anchor)`
			`* [x] create anchor`
			`* [ ] unique anchor creation`
Move anchor prepend function to anchor module 2020-10-31 10:01:53 +00:00			`* [x] create link (md / wiki)`
Refactor anchor and link functions into files 2020-10-30 15:30:37 +00:00			`* [ ] note listing (anchors / titles, no anchor)`
			`* [ ] list anchors`
			`* [ ] list filenames`
			`* [ ] link following (to existing anchor)`
Add function to search for next link on line By choosing 'line' in the `zettel_link_following` option, the link to be opened will be searched for on the complete rest of the line, meaning from the cursor to the newline symbol onwards. 2020-11-02 20:51:14 +00:00			`* [ ] fallback to filename if anchor invalid / not found`
Move intended features to README 2020-10-29 17:31:08 +00:00			`* [ ] link creation (to existing note)`
			`* [ ] list existing`
			`* [ ] create link (md / wiki)`
Add function to search for next link on line By choosing 'line' in the `zettel_link_following` option, the link to be opened will be searched for on the complete rest of the line, meaning from the cursor to the newline symbol onwards. 2020-11-02 20:51:14 +00:00			`* [ ] link switching (point to another existing note)`
Move intended features to README 2020-10-29 17:31:08 +00:00			`* [ ] note search (title / full-text)`
			`* [ ] jump to zettel (open existing anchor)`
			`* [ ] select by anchor`
			`* [ ] select by (fuzzy) title match`
			`* [ ] options`
			`* [x] zettel anchor separator`
Refactor anchor and link functions into files 2020-10-30 15:30:37 +00:00			`* [x] zettel extension`
Move anchor prepend function to anchor module 2020-10-31 10:01:53 +00:00			`* [x] link style (wiki/markdown)`
			`* [ ] custom link style?`
Add function to search for next link on line By choosing 'line' in the `zettel_link_following` option, the link to be opened will be searched for on the complete rest of the line, meaning from the cursor to the newline symbol onwards. 2020-11-02 20:51:14 +00:00			`* [x] link detection/following (under word, next on line)`
Move anchor prepend function to anchor module 2020-10-31 10:01:53 +00:00			`* [ ] recursive dir lookup for zettel`
Move intended features to README 2020-10-29 17:31:08 +00:00			`* [ ] zettel anchor regex`
Move anchor prepend function to anchor module 2020-10-31 10:01:53 +00:00
			`## TODO: nice-to-haves`

Add zettel link following style option `g:zettel_link_following` can be set to `cursor` or `line` to change the way zk detect the closest link to follow to (or create a new link for). Setting it to `cursor` will look for the current word under the cursor and decide if it is a followable link. `line` will look from the current cursor position to the end of the line instead. 2020-11-01 21:18:40 +00:00			* [ ] refactor parsers (md/wiki) to be tables of functions/regex in options, so e.g. valid link detection can call `options.parser.isValidLink(link)` or transformation `options.parser.styleLink(anchor, text)`
Remove hardcoded options, do repo house-cleaning Update readme and tmux.session file. Remove unused tests, update option calling. 2020-11-04 21:27:30 +00:00			* [ ] use unified parser model (e.g. containing `turn-to-link()`, `parse-link()`) function
Add function to search for next link on line By choosing 'line' in the `zettel_link_following` option, the link to be opened will be searched for on the complete rest of the line, meaning from the cursor to the newline symbol onwards. 2020-11-02 20:51:14 +00:00			`* [ ] enable custom parser supply`
Move intended features to README 2020-10-29 17:31:08 +00:00			* [ ] completion engine (e.g. for `completion-nvim`, look in completion_buffers/completion-tags for reference)
			`* [ ] zettel caching for big directories`
Move anchor prepend function to anchor module 2020-10-31 10:01:53 +00:00			`* [ ] backlinks (via rg for filename anchor?)`
			`* [ ] keep tree of notes cached?`
Move intended features to README 2020-10-29 17:31:08 +00:00			`* [ ] zettel maintenance`
			`* [ ] fix malformed anchors`
Update readme and debug mappings 2021-04-30 11:28:39 +00:00			`* [ ] fix-link function which looks for most similar file to be found and renames file/link automatically (after confirmation)`
Move intended features to README 2020-10-29 17:31:08 +00:00			`* [ ] add missing anchors`
			`* [ ] 'rename' anchor (goes against stability?)`
			`* [ ] recognize duplicate anchors (in directory, when listing, etc)`
			`* [ ] provide option to rename and automatically change backlinks`
Move anchor prepend function to anchor module 2020-10-31 10:01:53 +00:00			`* [ ] zettel 'lens' (preview first headline + content of linked zettel through floating window etc, on keypress)`
Refactor file listing and zettel picking 2021-04-30 13:07:36 +00:00			`* [ ] support both md-style and wiki-style links at the same time`
			`* [ ] file/directory exception list for gathering files, which will be ignored`
Fix function formatting getting zettel from dir 2021-04-30 13:26:32 +00:00			`* [ ] 'strict' mode only matching and following valid anchor links`
Initial commit 2020-10-26 14:55:40 +00:00
Remove hardcoded options, do repo house-cleaning Update readme and tmux.session file. Remove unused tests, update option calling. 2020-11-04 21:27:30 +00:00			`## TODO: maintenance`

			`* [ ] remove hard-coding of option vimnames in tests, now that we can dynamically change this through a single table`

Move intended features to README 2020-10-29 17:31:08 +00:00			`* anchor creation`
Initial commit 2020-10-26 14:55:40 +00:00			`* must be unique`
Move intended features to README 2020-10-29 17:31:08 +00:00			`* default: 10 digits, usually current date+time (YYMMDDHHmm)`
Initial commit 2020-10-26 14:55:40 +00:00			`* but, if multiple links created within one minute (or other circumstances), this would duplicate`
			`* thus, duplicate-check before creating a new anchor`
			`* if duplicated, generate first non-duplicated link (recursive?)`
Move intended features to README 2020-10-29 17:31:08 +00:00			`* try to move backwards through minutes not forward`
			`* i.e. if 2030101200 exists move to 2030101159, 2030101158, ...`
			`* if moving backwards, we do not take away id space from future note creation`
			`* if moving forwards, every zettel created within a minute would delay next zettel creation another minute`
Add opening zettel by reference if no anchor found Opens zettel by linked value, most often a direct path link, but will also look through the root dir to find a(n exactly) matching basename to open. If nothing is found in the root dir will open a new file to write with the corresponding name. Careful, if the reference is a full path definition, and the file does not exist, it will still open the corresponding file at the correct location but when attempting to save will generally complain if parts of the path are missing. They have to be created manually or in some other place, this is outside the scope of this plugin. 2021-04-30 14:28:22 +00:00			`* to decide: should zettel creation create a zettel in current working dir or at zettel root dir? or set by option?`
Move intended features to README 2020-10-29 17:31:08 +00:00
Add Zettel ref getting defaulting to root dir 2021-04-30 14:10:16 +00:00			`* [ ] (CODE) switch -- comments to --- doc comments for function descriptions etc`

Move intended features to README 2020-10-29 17:31:08 +00:00			`## Options`

			`atm:`
			```
			`anchor_separator = vim.g["zettel_anchor_separator"] or vim.b["zettel_anchor_separator"] or "_",`
			`zettel_extension = vim.g["zettel_extension"] or vim.b["zettel_extension"] or ".md",`
			`zettel_root = vim.g["zettel_root"] or vim.b["zettel_root"] or "~/documents/notes",`
			```