neovimcraft

plugins configs about

note-taking

1,223

CREATED

2021-11-21

UPDATED

3 days ago

.nvim

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.

Requirements
Getting started
Usage
- Commands
- Command palette
Customization
- Highlights
- Mappings
Features
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.

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.

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

#tag
@tag
:tag:
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.

neovimcraft

neovimcraft

renerocksai/telekasten.nvim

CREATED

2021-11-21

UPDATED

3 days ago

.nvim

Highlights

Search-based navigation

Contents

Requirements

Getting started

Installation

Base setup

Suggested dependencies

Calendar

Image preview

Image pasting

Other useful resources/plugins

Usage

Commands

Command palette

Customization

Highlights

Mappings

Advanced mappings

Features

Vaults

Link notation

Tag notation

Templates

Picker actions

Calendar

Hard-coded stuff