mirror of
https://github.com/Ascyii/telekasten.nvim.git
synced 2026-01-01 06:14:23 -05:00
413 lines
15 KiB
Markdown
413 lines
15 KiB
Markdown
<div align="center">
|
|
|
|
# .nvim
|
|
|
|
<!-- [](http://www.lua.org) -->
|
|
<!-- [](https://neovim.io) -->
|
|
[](http://www.lua.org)
|
|
[](https://neovim.io)
|
|
|
|
</div>
|
|
|
|
A Neovim (lua) plugin for working with a text-based, markdown [zettelkasten](https://takesmartnotes.com/) / wiki and
|
|
mixing it with a journal, based on [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim).
|
|
|
|
#### Highlights
|
|
|
|
- Find notes by name, #tag, and daily, weekly notes by date
|
|
- **Vaults**: Support for multiple separate note collections
|
|
- Search within all notes
|
|
- 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
|
|
- Calendar support
|
|
- Paste images from clipboard
|
|
- Toggle [ ] todo status
|
|
- Insert links to images
|
|
- Image previews, via `catimg`, `viu`, or extension
|
|
|
|
<div align="center">
|
|
|
|
#### New features are being announced in the [discussions](https://github.com/renerocksai/telekasten.nvim/discussions)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## Search-based navigation
|
|
|
|
Every navigation action, like following a link, is centered around a Telescope search: a Telescope search popup is
|
|
opened, and in the case of following a link, the search-text is pre-filled with the target. So, instead of opening the
|
|
linked note, you get a preview in Telescope and can decide if you actually want to go there. Since the search is often
|
|
likely to show up more than one result, you can preview related notes immediately.
|
|
|
|
### The preview is a powerful feature
|
|
|
|
Leaving the opening of the note to Telescope, you can decide with one key press whether you want to open the note in a
|
|
split or in the current window - or if you've seen enough.
|
|
|
|
I find that pressing the enter key to confirm the search does not interrupt my flow, and I really enjoy being able to
|
|
check the preview. I often get enough information from it alone so I don't actually have to "visit" every note in terms
|
|
of being able to edit it.
|
|
|
|
<!-- FIXME: Make a GIF instead of lots of images-->
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Contents
|
|
|
|
<!-- FIXME -->
|
|
- [Requirements](#requirements)
|
|
- [Getting started](#getting-started)
|
|
- [Installation](#installation)
|
|
- [Base setup](#base-setup)
|
|
- [Suggested dependencies](#suggested-dependencies)
|
|
- [Usage](#usage)
|
|
- [Commands](#commands)
|
|
- [Command palette](#command-palette)
|
|
- [Customization](#customization)
|
|
- [Highlights](#highlights)
|
|
- [Mappings](#mappings)
|
|
- [Features](#features)
|
|
- [Link notation](#link-notation)
|
|
- [Tag notation](#tag-notation)
|
|
- [Templates](#templates)
|
|
- [Picker actions](#picker-actions)
|
|
- [Calendar](#calendar)
|
|
- [Hard-coded stuff](#hard-coded-stuff)
|
|
|
|
## Requirements
|
|
Telekasten requires Neovim v0.6.0 or higher. Besides that, its only mandatory dependency of is
|
|
[telescope.nvim](https://github.com/nvim-telescope/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>
|
|
```lua
|
|
use {
|
|
'renerocksai/telekasten.nvim',
|
|
requires = {'nvim-telescope/telescope.nvim}
|
|
}
|
|
```
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Lazy.nvim</summary>
|
|
```lua
|
|
{
|
|
'renerocksai/telekasten.nvim',
|
|
dependencies = {'nvim-telescope/telescope.nvim}
|
|
},
|
|
```
|
|
</details>
|
|
|
|
|
|
<details>
|
|
<summary>Vim-plug</summary>
|
|
```vim
|
|
Plug 'nvim-telescope/telescope.nvim'
|
|
Plug 'renerocksai/telekasten.nvim'
|
|
```
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Vundle</summary>
|
|
```vim
|
|
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 create it for
|
|
you automatically.
|
|
|
|
```lua
|
|
require('telekasten').setup(
|
|
home = '~/zettelkasten', -- Put the name of your notes directory here
|
|
)
|
|
```
|
|
**NOTE:** For Windows users, please indicate the path as `C:/Users/username/zettelkasten/`.
|
|
|
|
### Suggested dependencies
|
|
|
|
#### Calendar
|
|
Telekasten interacts very nicely with [calendar-vim](https://github.com/renerocksai/calendar-vim). Installing this
|
|
plugin will allow you to create journal entries for the selected dates and highlight dates with attached entries.
|
|
Telekasten.nvim can optionally plug into [calendar-vim](https://github.com/renerocksai/calendar-vim): Selecting a day in
|
|
the calendar will open up a telescope search with preview that lets you open the daily note (or cancel out and keep
|
|
browsing your calendar). The daily note will be created if it doesn't exist. Days with daily notes get marked in the
|
|
calendar.
|
|
|
|
#### Image preview
|
|
Various plugins or external tools can be used as image previewers to help you pick the correct one for your note.
|
|
- [telescope-media-files.nvim](https://github.com/nvim-telescope/telescope-media-files.nvim)
|
|
- [catimg](https://github.com/posva/catimg)
|
|
- [viu](https://github.com/atanunq/viu)
|
|
|
|
#### Image pasting
|
|
- xclip
|
|
- [wl-clipboard](https://github.com/bugaevc/wl-clipboard)
|
|
|
|
**Note:** This is supported by default on MacOS, it is not necessary to install any other tool.
|
|
|
|
#### Other useful plugins
|
|
|
|
While they do not interact directly with Telekasten, the following plugins greatly improve the note-taking experience.
|
|
|
|
- [telescope-bibtex.nvim](https://github.com/nvim-telescope/telescope-bibtex.nvim)
|
|
- [telescope-symbols.nvim](https://github.com/nvim-telescope/telescope-symbols.nvim)
|
|
- [markdown-preview.nvim](https://github.com/iamcco/markdown-preview.nvim)
|
|
- [vim-markdown-toc](https://github.com/mzlogin/vim-markdown-toc)
|
|
|
|
|
|
## Usage
|
|
|
|
The simplest way to use the plugin is to call directly the related Telekasten command:
|
|
```vim
|
|
: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.
|
|
```vim
|
|
:lua require('telekasten').search_notes()
|
|
```
|
|
<!-- FIXME -->
|
|
This will be documented in a wiki entry later on.
|
|
</details>
|
|
|
|
### Commands
|
|
|
|
The following sub-commands are defined; check their corresponding [lua functions](#22-telekasten-lua-functions) below
|
|
the list for a more detailed description:
|
|
|
|
- `panel` : brings up the [command palette](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](https://github.com/folke/which-key.nvim) plugin, although
|
|
limited to Telekasten.
|
|
|
|
You can call this panel using
|
|
```vim
|
|
: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.
|
|
|
|
|
|
```vim
|
|
" 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 `Z`ettelkasten for instance).
|
|
|
|
|
|
```lua
|
|
-- Launch panel if nothing is typed after <leader>z
|
|
vim.keybind.set("n", "<leader>z", "<cmd>Telekasten panel<CR>")
|
|
|
|
-- Most used functions
|
|
vim.keybind.set("n", "<leader>zf", "<cmd>Telekasten find_notes<CR>")
|
|
vim.keybind.set("n", "<leader>zg", "<cmd>Telekasten search_notes<CR>")
|
|
vim.keybind.set("n", "<leader>zd", "<cmd>Telekasten goto_today<CR>")
|
|
vim.keybind.set("n", "<leader>zz", "<cmd>Telekasten follow_link<CR>")
|
|
vim.keybind.set("n", "<leader>zn", "<cmd>Telekasten new_note<CR>")
|
|
vim.keybind.set("n", "<leader>zc", "<cmd>Telekasten show_calendar<CR>")
|
|
vim.keybind.set("n", "<leader>zb", "<cmd>Telekasten show_backlinks<CR>")
|
|
vim.keybind.set("n", "<leader>zI", "<cmd>Telekasten insert_img_link<CR>")
|
|
|
|
-- Call insert link automatically when we start typing a link
|
|
vim.keybind.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.
|
|
|
|
**The documentation related to advanced mappings will be provided shortly.**
|
|
|
|
|
|
|
|
## 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:
|
|
|
|
```markdown
|
|
# 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.
|
|
-  ... links to the file `path/to/file`
|
|
```
|
|
|
|
See the documentation for more details regarding the different types of links (`:h telekaten.link_notation`).
|
|
|
|
|
|
### Tag notation
|
|
|
|
Telekasten supports the following tag notations:
|
|
|
|
1. `#tag`
|
|
2. `:tag:`
|
|
3. `yaml-bare`: bare tags in a tag collection in the yaml metadata:
|
|
|
|
|
|
See the documentation for more details regarding the tag syntax (`:h telekaten.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:
|
|
|
|
```markdown
|
|
---
|
|
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:
|
|
|
|
- <kbd>CTRL</kbd> + <kbd>i</kbd> : 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
|
|
- <kbd>CTRL</kbd> + <kbd>y</kbd> : yanks a link to the selected note / image, ready for <kbd>p</kbd>asting
|
|
- the option `close_after_yanking` defines whether the telescope window should be closed when the link has been
|
|
yanked
|
|
- <kbd>RETURN / ENTER</kbd> : 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:
|
|
|
|
```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](https://commons.wikimedia.org/wiki/Category:CC-BY-3.0)._
|