TODO | proj:vim-roam status:pending

• Adaptively listing files with tags or other metadata (i.e. recreating outlook)
• Add visual graph support (hard) with many different graph types!
• Figure out how to create a new page without hitting enter to serve as backlink store
• Figure out tagging (alignment with Pelican) and search within Vimwiki (how to replicate Notion fields?)
• Add collection support, greater than just a backlink reference; mimics Wikipedia style
• Implement visual counterpart to Vim writing (e.g. simple local web server for converted HTML or PDF files)
• Generate random system lines for naive SRS
• Implement linking functionality to unlinked references (hard)
• Implement full file content search (instead of just lines)
• Add image link shortcut
• Move bl buffer autocmd for wiki root only
• Improve backlinks
  • Allow arbitrary block references across system (Roam-like)
  • Fix backlink scan w/o quitting vim
  • Prevent redundant content copying for list items
  • Add special reference grouping (e.g. log entries, thoughts, etc)
  • Read backlinks for links split across lines
  • Edit backlink content in backlink buffer (hard)
• Consolidate plugin
  • Make FZF shortcuts internal (fzf optional dependency)
  • Make templates internal (Ultisnips optional dependency)
  • Make task support internal (Taskwiki optional dependency)
  • Make Markdown syntax settings internal (Vim-markdown optional dependency)
  • Add preferred (overwritten) wiki.vim settings to plugin file

Current Bugs

• There appear to be occasional weird issues with the realpath modification I’ve made. This could be a result of passing weird, buggy paths into and getting funky results, but clearly there’s something wrong behind the scenes.
  • Just removed the use of realpath for a more native fnamemodify option. Obvious in hindsight I should’ve used this from the beginning.
• Links broken across lines (maybe look at Vim’s breakat option?)
• File renaming method is totally messed up. I believe the intention is to only rename links in open buffers (which is stupid), and on top of that I wouldn’t be surprised if it was botching relative links in some way or another.
• Not sure who’s fault it is (Markdown conceal most likely), but after adding links a single space will be highlighted instead of the usual 2. This is weird. (fixed)
• Backlink buffer calculation is incredibly inefficient since each file with matching links must actually be opened in a buffer.
  • Fixing this: the way this can be sped up is by operating entirely on the file text (like every other part of the link reading process), instead of having to actually open that file up. The main hang up here is getting the entire text for list items, which is being handled by the list_bounds() method. However, the opening of new buffers is done by the outer backlink_buffer() method, just before list_bounds() is invoked. This all happens because the li text object has a few lines of parsing that require moving around in the file, instead of acting on lines read from the file. So in order to fix this, we need to redefine a version of wiki#list#get(), who moves to cater to the internal functions it calls. This roots down to the parse_list_to_items() method in this list/item.vim file, who sets a line position to do a search. This single operation can be replaced to use a known location in a file, instead of taking the current position as the target location. Redefining the parse_list_to_items() function, which can then be called by a redefined wiki#list#get() function, which can then be called the list_bounds() method, which can then be called by the gather_nodes() method to get each link’s surrounding list context without actually visiting that file. The file reference will have to be passed down that entire chain of functions, so it can be read at the right location at the very bottom. The backlink_buffer() function will then no longer need to store the current position and open new buffers for each link encountered. This will fix the problem, and I think it is likely the simplest way toward a working solution.

Features to consider

• Could add a local header context in the backlink page (perhaps next to the file: [# Log] or something) so we can tell under what heading a line is located. Could be useful for grouping or indentifying key headers (like the Log or Thoughts) even when they are technically not within the context scope.
• Note that backlink links from within context snippets will be broken. This is no one’s fault other than I just don’t re-process these links after cutting them out of their files.
• Backlink page should use paragraph text objects instead of just pulling lines. This would resolve (I think) all current oppositions to hard line breaks. Additionally, if a link is used as a header, the backlinks buffer should show the entire text underneath that header. Here we can potentially use text objects from the Vim-markdown plugin for header navigation.
• When appropriate, complete the correct filetype in the link (e.g. if I’m completing a link to a PDF, it should use the file scheme). Of course, this may be hard given how links are meant to be handled with the HTML build process. Perhaps Pandoc would have a method of controlling how different kinds of links are rendered.

Implemented features extending wiki.vim

• Save on navigate: when following a link or going backward in the file stack, save the current file if edits have been made (instead of showing an annoying warning). Optional extension, enable with the g:write_on_follow option.
• Improved relative link, just smoothing out some bugs. This is mostly not a problem with a flat file hierarchy.
• Improved backlinks: make backlinks more readable by transposing the actual content into a “backlink buffer”, splitting the screen. This is (in my opinion) a much better option than a location list, which doesn’t really prioritize the content underneath the link.
  • Implemented a simple QOL improvement, bundling same-page results under the same file header in the buffer.
• Utilized the wikivim option g:wiki_map_create_page to also modify link target files. So when pages are created directly, the name is modified according to this function, but in the case that link name schemes in-document want to be more “prose-like”, this ensures that names also get modified in this way when they are visited. If the proper file name was used in the link, and the naming scheme is consistent with how that file was created, this will have no effect and work as normal.
• Allow journal name to be empty, creating journal entries in root wiki directory.

The following is text typed up but never submitted in an issue to wikivim regarding prose-like links. This should be revisited and updated to match the actual state of the wiki.vim fork and Vim-roam today.

Relevant tools

• Roam research
• Vimwiki
• Taskwiki
• Taskwarrior
• Vimscript
• fzf
• ripgrep
• bat
• vim
• Bash

Relevant Sources

• Evil Mode Or, How I Learned to Stop Worrying and Love Emacs
• The ZettelKasten Method
• The New System
• How To Take Smart Notes
• Building a Second Brain
• Building a Second Brain in Roam
• How To Take Smart Notes With Org mode

Documentation

Standards

• Following most systematic choices from Wikipedia
• File names mostly have a capitalized first word, with lowercase additional words (if it applies). Spaces are replaced with dashes, and dots with underscores. This restricts some flexibility, but it’s hard to include slashes, dots, spaces, and colons in the filename itself.
  • Note that commas are the only valid “special” characters allowed (specifically apostrophes, question marks, etc do not work)
• Single level hierarchy only; can be justified by custom templates, can be created immediately based on location

Logging

• Something to try: I think I should try logging projects through the daily and using the Log page when I have better backlinks. This way, the log is much more organic and doesn’t have to take up space in the actual project page, extending forever, but rather gets dated and is nicely separated in each of the daily notes that I take down what I did. Then when it comes to rendering the backlinks (either in Vim or on the web), those listed under the log page can be treated specifically as the project log.

Vim Configuration

All configuration details pertaining to the wiki. This includes any external plugins I’m relying on, .vimrc choices, line breaking decisions, everything. Outside of Vim, this is the target destination for documentation about my vim setup for the wiki.

Links

Links are central to maintain a wiki, and are really at the core of what makes tools like Roam research powerful. wikivim offers a solid link core for handling links of all types.

• Link types
  • Internal (wiki) links: [<link>](<link>) style or regular Markdown style.
  • Files: open a file the way the OS wants to handle it
  • Other link specs

Creating links and files

The plugin aims to offer convenient link and file creation schemes. For creating files directly, there is the native wikivim function WikiOpen (which can be mapped to a shortcut) to create new files. Using the g:wiki_map_create_page option, a function to transfer the user input filename to the actual filename. This can be helpful for automatically converting spaces to underscores, for example, for more friendly filenames.

There are many ways to create a wikilink:

• When typing \[\[, fzf can be used to automatically complete the link for existing files. With the fzf prompt open, one can also write a link to a new file, and have the link syntax wrapped automatically. Visiting this link will allow you to create the new file, making it easy to quickly add files organically while writing.
• Hitting <CR> on a work or highlighted phrase will wrap the text in the link syntax. This makes it easy to create new links from existing text. Note that the wikivim provides the ability to transform text when creating a link (similar to the function for transforming new pages) using the g:wiki_map_link_create. For example, if replacing spaces with dashes was the desired effect, then creating a link from the text “some text” would produce the link “some-text|some text”. This is helpful for turning prose into an expected file naming scheme.

An additional option introduced in the vim-roam plugin is the ability to transform the target filename when visiting a link. For example, if I had the link some file, but wanted to ensure all filenames had underscores instead of spaces, I could specify a function that followed the given link to “some_file.md”. This, together with direct page creation and link transformations, allows us to fully abstract away an underlying filename scheme (like turning spaces to underscores and removing special characters) from direct links written in simple prose. This way, not even a cleaned “display text” using “|” needs to be used when creating links, keeping redundant character count to a minimum.

Link and page transformation settings

There are current three different customizable maps that are used to transform page names and links:

• wiki_map_create_page: a setting from the original wikivim plugin, used to transform text provided to WikiOpen for creating new pages from scratch. This transformation is pretty telling about how the user would like to turn arbitrary prose into filenames, so it’s used anywhere else for this purpose (instead of, say, defining a new option for each new use case). An example here is for the link visit mapping (i.e. enabling prose links); if enabled, we know the user would like to turn prose-like links into filenames using this same map.
• wiki_map_link_create: a setting from original wikivim plugin, not very useful to
  1. Defines a simple transform from prose-like text to link names. With prose-like link transformations enabled, this is completely unnecessary.
• wiki_map_file_to_title: new setting, holds a function that is meant to reverse the transformation applied in wiki_map_create_page. This is used in places where we want to show filenames in a prose-like manner (as used in backlink page headers), or pop out prose-like links from the filenames themselves (like in link completion with fzf).

Renaming files

Worth noting that renaming files is a bit complicated given prose-like links. Here I’ve modified the wiki.vim fork (so outside the vim-roam scope) to look for links with transformed text, as well as set the new links to transformed text of the old and new filenames, respectively. This transformation is done by the wiki_map_file_to_title function if the prose_links options is also enabled. This seems to actual have worked well with some initial tests. Note that, as a result, you must provide the exact filename you’d like the file to be renamed to (instead relying on a prose-to-filename transformation like when regularly creating files).

• Not actually sure this last point is true now that I think about it. You could run the prose-to-fname conversion, get the new filename, then transform that back into prose for the links. I think my initial thought was just you wouldn’t be able to tell if the user supplied prose or actual text, and then wouldn’t know whether or not to use it for links as-is or not. But this is not a roadblock more than it is just a dumb thing to think would be necessary. Note: this is not yet implemented, for now you need to provide an exact new filename.

Thesis

Vim-roam is a core plugin building on wiki.vim. It offers increased backlink functionality, link flexibility, and other setup options. More than this, it embraces a configuration of multiple separate external tools which enhance the wiki experience. This includes a task management framework in pure markdown, bullets.vim support, Ultisnips for templates, custom Markdown syntax highlighting, fzf for efficient searching. Also supporting external conversions like building a linked site based on a theme, Anki/notecard support, writing stat tracking, etc.