A Neovim (lua) plugin for working with a text-based, markdown zettelkasten / wiki and mixing it with a journal, based on telescope.nvim.

Highlights

• Find notes by name, #tag or by searching within note text
• Find daily, weekly notes by date
• Vaults: Support for multiple separate note collections
• Place and follow links to your notes or create new ones, with templates
• Find notes that link back to your notes
• Find other notes that link to the same note as the link under the cursor
• Support for links to headings or specific paragraphs within specific notes or globally
• Alias link names to keep everything clean and tidy
• Toggle [ ] todo status
• Paste images from clipboard
• Insert links to images
• Image previews, via catimg, viu, or extension
• Calendar support

Search-based navigation

Every navigation action, like following a link, is centered around a Telescope picker. You can then decide to actually open the note or just read the content from the picker itself. Thanks to Telescope actions you can also just insert a link to the note or yank a link instead of opening the note.

Contents

• Requirements
• Getting started
  • Installation
  • Base setup
  • Suggested dependencies
• Usage
  • Commands
  • Command palette
• Customization
  • Highlights
  • Mappings
• Features
  • Link notation
  • Tag notation
  • Templates
  • Picker actions
  • Calendar
• Hard-coded stuff

Requirements

Telekasten requires Neovim v0.6.0 or higher. Besides that, its only mandatory dependency of is telescope.nvim, which acts as the backbone of this plugin.

Some features require external tools. For example, image pasting from the clipboard require a compatible clipboard manager such as xclip or wl-clipboard. Users are encouraged to read the requirements section of the documentation for a complete list of optional dependencies (:h telekasten.requirements).

Getting started

Installation

  use {
    'renerocksai/telekasten.nvim',
    requires = {'nvim-telescope/telescope.nvim'}
  }

  {
    'renerocksai/telekasten.nvim',
    dependencies = {'nvim-telescope/telescope.nvim'}
  },

  Plug 'nvim-telescope/telescope.nvim'
  Plug 'renerocksai/telekasten.nvim'

  Plugin 'nvim-telescope/telescope.nvim'
  Plugin 'renerocksai/telekasten.nvim'

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 create the defaults directories before first use.

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. 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
• catimg
• viu

Image pasting

• xclip
• 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 greatly improve the note-taking experience.

• telescope-bibtex.nvim: manage citations using bibtex
• telescope-symbols.nvim: telescope picker for symbols and emojis
• peek.nvim or markdown-preview.nvim: markdown previewer
• vim-markdown-toc: generate a table of contents for your markdown documents
• synctodo: bash script to sync todos among Telekasten, Mac and iPhone reminders.
• telescope-all-recent: shows files you have recently opened.

Usage

The simplest way to use the plugin is to call directly the related Telekasten command:

:Telekasten <sub-command>

:lua require('telekasten').search_notes()

Commands

The following sub-commands are defined:

• panel : brings up the 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)
• search_notes : Search (grep) in all notes
• insert_link : Insert a link to a note
• follow_link : Follow the link under the cursor
• goto_today : Open today's daily note
• new_note : Create a new note, prompts for title
• goto_thisweek : Open this week's weekly note
• find_weekly_notes : Find weekly notes by title (calendar week)
• yank_notelink : Yank a link to the currently open note
• new_templated_note : create a new note by template, prompts for title and template
• show_calendar : Show the calendar
• paste_img_and_link : Paste an image from the clipboard into a file and inserts a link to it
• toggle_todo : Toggle - [ ] todo status of a line
• show_backlinks : Show all notes linking to the current one
• find_friends : Show all notes linking to the link under the cursor
• insert_img_link : Browse images / media files and insert a link to the selected one
• preview_img : preview image under the cursor
• browse_media : Browse images / media files
• rename_note : Rename current note and update the links pointing to it
• switch_vault : switch the vault. Brings up a picker. See the vaults config option for more.

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 plugin, although limited to Telekasten.

You can call this panel using

: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

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

An additional CalNavi group is defined to tweak the appearance of the calendar navigation button.

" Example
hi tkLink ctermfg=Blue cterm=bold,underline guifg=blue gui=bold,underline
hi tkBrackets ctermfg=gray guifg=gray

Mappings

The real power of Telekasten lays in defining sensible mappings to make your 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 Zettelkasten for instance).

-- Launch panel if nothing is typed after <leader>z
vim.keymap.set("n", "<leader>z", "<cmd>Telekasten panel<CR>")

-- Most used functions
vim.keymap.set("n", "<leader>zf", "<cmd>Telekasten find_notes<CR>")
vim.keymap.set("n", "<leader>zg", "<cmd>Telekasten search_notes<CR>")
vim.keymap.set("n", "<leader>zd", "<cmd>Telekasten goto_today<CR>")
vim.keymap.set("n", "<leader>zz", "<cmd>Telekasten follow_link<CR>")
vim.keymap.set("n", "<leader>zn", "<cmd>Telekasten new_note<CR>")
vim.keymap.set("n", "<leader>zc", "<cmd>Telekasten show_calendar<CR>")
vim.keymap.set("n", "<leader>zb", "<cmd>Telekasten show_backlinks<CR>")
vim.keymap.set("n", "<leader>zI", "<cmd>Telekasten insert_img_link<CR>")

-- Call insert link automatically when we start typing a link
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 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.

Link notation

The following links are supported:

# Note links
- [[A cool title]]  ................. links to the note named 'A cool title'
- [[A cool title#Heading 27]]  ...... links to the heading 'Heading 27' within the note
                                      named 'A cool title'
- [[A cool title#^xxxxxxxx]]  ....... links to the paragraph with id ^xxxxxxxx within the note
                                      named 'A cool title'
- [[201705061300|A cool title]] ..... links to the note named `201705061300` but shows the link as
                                      `A cool title` if `conceallevel=2`
- [[#Heading 27]]  .................. links to the heading 'Heading 27' within all notes
- [[#^xxxxxxxx]]  ................... links to the paragraph with id ^xxxxxxxx within all notes

## Optionally, notes can live in specific sub-directories
- [[some/subdirectory/A cool title]]
- [[some/subdirectory/A cool title#Heading 27]]
- [[some/subdirectory/A cool title#^xxxxxxxx]]


# Media links
Use these for images, PDF files, videos. If telescope-media-files is installed,
these can be previewed.
- ![optional title](path/to/file) ... links to the file `path/to/file`

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. :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).

Templates

To streamline your workflow, it is possible to create various note templates and call them upon note creation. These templates will substitute various terms (date, times, file names, UUID, etc).

A simple template can be:

---
uuid: {{uuid}}
date:  {{date}}
---

# {{shorttitle}}

A complete list of substitutions can be found in the documentation (:h telekasten.template_files).

Picker actions

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

• CTRL + i : inserts a link to the selected note / image
  • the option insert_after_inserting defines if insert mode will be entered after the link is pasted into your current buffer
• CTRL + y : yanks a link to the selected note / image, ready for pasting
  • the option close_after_yanking defines whether the telescope window should be closed when the link has been yanked
• RETURN / ENTER : usually opens the selected note or performs the action defined by the called function
  • e.g. insert_img_link()'s action is to insert a link to the selected image.

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.

If you want to see a big calendar showing the current month that fills your entire window, you can issue the following command in vim:

:CalendarT

Hard-coded stuff

Some (minor) stuff are currently still hard-coded. We will eventually change this to allow more flexibility at one point.

Currently, the following things are hardcoded:

• the file naming format for daily note files: YYYY-MM-DD.ext (e.g. 2021-11-21.md)
• the file naming format for weekly note files: YYYY-Www.ext (e.g. 2021-W46.md)
• the file naming format for pasted images: pasted_img_YYYYMMDDhhmmss.png (e.g. pasted_img_20211126041108.png)

The Telekasten logo is based on the neovim logo attributed to Jason Long, neovim, CC-BY-3.0.