<div align="center">

.nvim

</div>

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, monthly, quarterly, and yearly 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.

<!-- FIXME: Make a GIF instead of lots of images-->

---

---

---

Contents

<!-- FIXME -->

• 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

<details> <summary>Packer.nvim</summary>

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

</details> <details> <summary>Lazy.nvim</summary>

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

</details> <details> <summary>Vim-plug</summary>

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

</details> <details> <summary>Vundle</summary>

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

</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 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
• md_toc: generate a table of contents for your markdown documents, better support for neovim/packer integration
• 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>

<details> <summary>Advanced use</summary> Each sub-command is implemented by a specific lua function. While high-level Telekasten commands can not accept arguments, you can also call directly the lua function with additional arguments. This is especially useful to craft some custom mappings.

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

</details>

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)
• goto_thismonth : Open this month's monthly note
• find_monthly_notes : Find monthly notes by title
• goto_thisquarter : Open this quarter's quarterly note
• find_quarterly_notes : Find quarterly notes by title
• goto_thisyear : Open this year's yearly note
• find_yearly_notes : Find yearly notes by title
• 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
• 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.

" 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 Zettel