search

nvim-telekasten / telekasten.nvim

A Neovim (lua) plugin for working with a markdown zettelkasten / wiki and mixing it with a journal, based on telescope.nvim
MIT License
1.29k stars 83 forks source link
lua neovim nvim

readme

# ![](img/telekasten-logo-gray-270x87.png).nvim [![Lua](https://img.shields.io/badge/Lua-blue.svg?style=plastic&logo=lua)](http://www.lua.org) [![Neovim](https://img.shields.io/badge/Neovim%200.6+-green.svg?style=plastic&logo=neovim)](https://neovim.io)

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

Highlights

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.

image

image

Contents

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

Packer.nvim ```lua use { 'renerocksai/telekasten.nvim', requires = {'nvim-telescope/telescope.nvim'} } ```
Lazy.nvim ```lua { 'renerocksai/telekasten.nvim', dependencies = {'nvim-telescope/telescope.nvim'} }, ```
Vim-plug ```vim Plug 'nvim-telescope/telescope.nvim' Plug 'renerocksai/telekasten.nvim' ```
Vundle ```vim 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.

Image pasting

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.

Usage

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

:Telekasten <sub-command>
Advanced use 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. ```vim :lua require('telekasten').search_notes() ```

Commands

The following sub-commands are defined:

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:

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.

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:

Calendar

When invoking show_calendar(), a calendar showing the previous, current, and next month is shown at the right side of vim.

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 Telekasten logo is based on the neovim logo attributed to Jason Long, neovim, CC-BY-3.0.