mirror of
https://github.com/Ascyii/telekasten.nvim.git
synced 2026-01-01 14:14:24 -05:00
doc: reformat README
This commit is contained in:
Thomas Lambert
210
README.md
210
README.md
@@ -2,54 +2,40 @@
|
|||||||
|
|
||||||
# .nvim
|
# .nvim
|
||||||
|
|
||||||
<!-- [](http://www.lua.org) -->
|
|
||||||
<!-- [](https://neovim.io) -->
|
|
||||||
[](http://www.lua.org)
|
[](http://www.lua.org)
|
||||||
[](https://neovim.io)
|
[](https://neovim.io)
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
A Neovim (lua) plugin for working with a text-based, markdown [zettelkasten](https://takesmartnotes.com/) / wiki and
|
A Neovim (lua) plugin for working with a text-based, markdown
|
||||||
mixing it with a journal, based on [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim).
|
[zettelkasten](https://takesmartnotes.com/) / wiki and mixing it with a journal,
|
||||||
|
based on [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim).
|
||||||
|
|
||||||
#### Highlights
|
#### Highlights
|
||||||
|
|
||||||
- Find notes by name, #tag, and daily, weekly notes by date
|
- Find notes by name, #tag or by searching within note text
|
||||||
|
- Find daily, weekly notes by date
|
||||||
- **Vaults**: Support for multiple separate note collections
|
- **Vaults**: Support for multiple separate note collections
|
||||||
- Search within all notes
|
|
||||||
- Place and follow links to your notes or create new ones, with templates
|
- Place and follow links to your notes or create new ones, with templates
|
||||||
- Find notes that link back to your notes
|
- Find notes that link back to your notes
|
||||||
- Find other notes that link to the same note as the link under the cursor
|
- 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
|
- Support for links to headings or specific paragraphs within specific notes or
|
||||||
- Calendar support
|
globally
|
||||||
- Paste images from clipboard
|
- Alias link names to keep everything clean and tidy
|
||||||
- Toggle [ ] todo status
|
- Toggle [ ] todo status
|
||||||
|
- Paste images from clipboard
|
||||||
- Insert links to images
|
- Insert links to images
|
||||||
- Image previews, via `catimg`, `viu`, or extension
|
- Image previews, via `catimg`, `viu`, or extension
|
||||||
|
- Calendar support
|
||||||
<div align="center">
|
|
||||||
|
|
||||||
#### New features are being announced in the [discussions](https://github.com/renerocksai/telekasten.nvim/discussions)
|
|
||||||
|
|
||||||
</div>
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Search-based navigation
|
## Search-based navigation
|
||||||
|
|
||||||
Every navigation action, like following a link, is centered around a Telescope search: a Telescope search popup is
|
Every navigation action, like following a link, is centered around a Telescope
|
||||||
opened, and in the case of following a link, the search-text is pre-filled with the target. So, instead of opening the
|
picker. You can then decide to actually open the note or just read the content
|
||||||
linked note, you get a preview in Telescope and can decide if you actually want to go there. Since the search is often
|
from the picker itself. Thanks to [Telescope actions](#picker-actions) you can
|
||||||
likely to show up more than one result, you can preview related notes immediately.
|
also just insert a link to the note or yank a link instead of opening the note.
|
||||||
|
|
||||||
### 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-->
|
<!-- FIXME: Make a GIF instead of lots of images-->
|
||||||
|
|
||||||
@@ -90,12 +76,16 @@ of being able to edit it.
|
|||||||
- [Hard-coded stuff](#hard-coded-stuff)
|
- [Hard-coded stuff](#hard-coded-stuff)
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
Telekasten requires Neovim v0.6.0 or higher. Besides that, its only mandatory dependency of is
|
Telekasten requires Neovim v0.6.0 or higher. Besides that, its only mandatory
|
||||||
[telescope.nvim](https://github.com/nvim-telescope/telescope.nvim), which acts as the backbone of this plugin.
|
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
|
Some features require external tools. For example, image pasting from the
|
||||||
manager such as `xclip` or `wl-clipboard`. Users are encouraged to read the requirements section of the documentation
|
clipboard require a compatible clipboard manager such as `xclip` or
|
||||||
for a complete list of optional dependencies (`:h telekasten.requirements`).
|
`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
|
## Getting started
|
||||||
|
|
||||||
@@ -148,61 +138,72 @@ for a complete list of optional dependencies (`:h telekasten.requirements`).
|
|||||||
|
|
||||||
|
|
||||||
### Base setup
|
### Base setup
|
||||||
In order to use Telekasten, you need to first require its setup function somewhere in your `init.lua`. Take this
|
In order to use Telekasten, you need to first require its setup function
|
||||||
opportunity to indicate the path for your notes directory. If you do not specify anything, the plugin will create it for
|
somewhere in your `init.lua`. Take this opportunity to indicate the path for
|
||||||
you automatically.
|
your notes directory. If you do not specify anything, the plugin will ask you to
|
||||||
|
create the defaults directories before first use.
|
||||||
|
|
||||||
```lua
|
```lua
|
||||||
require('telekasten').setup(
|
require('telekasten').setup(
|
||||||
home = '~/zettelkasten', -- Put the name of your notes directory here
|
home = '~/zettelkasten', -- Put the name of your notes directory here
|
||||||
)
|
)
|
||||||
```
|
```
|
||||||
**NOTE:** For Windows users, please indicate the path as `C:/Users/username/zettelkasten/`.
|
**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
|
### Suggested dependencies
|
||||||
|
|
||||||
#### Calendar
|
#### Calendar
|
||||||
Telekasten interacts very nicely with [calendar-vim](https://github.com/renerocksai/calendar-vim). Installing this
|
Telekasten interacts very nicely with
|
||||||
plugin will allow you to create journal entries for the selected dates and highlight dates with attached entries.
|
[calendar-vim](https://github.com/renerocksai/calendar-vim). Installing this
|
||||||
Telekasten.nvim can optionally plug into [calendar-vim](https://github.com/renerocksai/calendar-vim): Selecting a day in
|
plugin will allow you to create journal entries for the selected dates and
|
||||||
the calendar will open up a telescope search with preview that lets you open the daily note (or cancel out and keep
|
highlight dates with attached entries.
|
||||||
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
|
#### Image preview
|
||||||
Various plugins or external tools can be used as image previewers to help you pick the correct one for your note.
|
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](https://github.com/nvim-telescope/telescope-media-files.nvim)
|
- [telescope-media-files.nvim](https://github.com/nvim-telescope/telescope-media-files.nvim)
|
||||||
- [catimg](https://github.com/posva/catimg)
|
- [catimg](https://github.com/posva/catimg)
|
||||||
- [viu](https://github.com/atanunq/viu)
|
- [viu](https://github.com/atanunq/viu)
|
||||||
|
|
||||||
#### Image pasting
|
#### Image pasting
|
||||||
- xclip
|
- [xclip](https://github.com/astrand/xclip)
|
||||||
- [wl-clipboard](https://github.com/bugaevc/wl-clipboard)
|
- [wl-clipboard](https://github.com/bugaevc/wl-clipboard)
|
||||||
|
|
||||||
_Image pasting is supported by default on MacOS, it is not necessary to install any other tool._
|
_Image pasting is supported by default on MacOS, it is not necessary to install
|
||||||
|
any other tool._
|
||||||
|
|
||||||
|
|
||||||
#### Other useful plugins
|
#### Other useful plugins
|
||||||
|
|
||||||
While they do not interact directly with Telekasten, the following plugins greatly improve the note-taking experience.
|
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-bibtex.nvim](https://github.com/nvim-telescope/telescope-bibtex.nvim):
|
||||||
- [telescope-symbols.nvim](https://github.com/nvim-telescope/telescope-symbols.nvim)
|
manage citations using bibtex
|
||||||
- [peek.nvim](https://github.com/toppair/peek.nvim) or [markdown-preview.nvim](https://github.com/iamcco/markdown-preview.nvim)
|
- [telescope-symbols.nvim](https://github.com/nvim-telescope/telescope-symbols.nvim):
|
||||||
- [vim-markdown-toc](https://github.com/mzlogin/vim-markdown-toc)
|
telescope picker for symbols and emojis
|
||||||
|
- [peek.nvim](https://github.com/toppair/peek.nvim) or
|
||||||
|
[markdown-preview.nvim](https://github.com/iamcco/markdown-preview.nvim):
|
||||||
|
markdown previewer
|
||||||
|
- [vim-markdown-toc](https://github.com/mzlogin/vim-markdown-toc):
|
||||||
|
generate a table of contents for your markdown documents
|
||||||
|
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
The simplest way to use the plugin is to call directly the related Telekasten command:
|
The simplest way to use the plugin is to call directly the related Telekasten
|
||||||
|
command:
|
||||||
```vim
|
```vim
|
||||||
:Telekasten <sub-command>
|
:Telekasten <sub-command>
|
||||||
```
|
```
|
||||||
<details>
|
<details>
|
||||||
<summary>Advanced use</summary>
|
<summary>Advanced use</summary>
|
||||||
Each sub-command is implemented by a specific lua function. While high-level Telekasten commands can not accept
|
Each sub-command is implemented by a specific lua function. While high-level
|
||||||
arguments, you can also call directly the lua function with additional arguments. This is especially useful to craft
|
Telekasten commands can not accept arguments, you can also call directly the lua
|
||||||
some custom mappings.
|
function with additional arguments. This is especially useful to craft some
|
||||||
|
custom mappings.
|
||||||
```vim
|
```vim
|
||||||
:lua require('telekasten').search_notes()
|
:lua require('telekasten').search_notes()
|
||||||
```
|
```
|
||||||
@@ -212,8 +213,7 @@ This will be documented in a wiki entry later on.
|
|||||||
|
|
||||||
### Commands
|
### Commands
|
||||||
|
|
||||||
The following sub-commands are defined; check their corresponding [lua functions](#22-telekasten-lua-functions) below
|
The following sub-commands are defined:
|
||||||
the list for a more detailed description:
|
|
||||||
|
|
||||||
- `panel` : brings up the [command palette](command-palette)
|
- `panel` : brings up the [command palette](command-palette)
|
||||||
- `find_notes` : Find notes by title (filename)
|
- `find_notes` : Find notes by title (filename)
|
||||||
@@ -243,30 +243,34 @@ the list for a more detailed description:
|
|||||||
|
|
||||||
### Command palette
|
### Command palette
|
||||||
|
|
||||||
Telekasten comes with a small helper command palette that let the user browse the different commands available.
|
Telekasten comes with a small helper command palette that let the user browse
|
||||||
This feature is quite similar to the excellent [which-key.nvim](https://github.com/folke/which-key.nvim) plugin, although
|
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.
|
limited to Telekasten.
|
||||||
|
|
||||||
You can call this panel using
|
You can call this panel using
|
||||||
```vim
|
```vim
|
||||||
:Telekasten panel
|
:Telekasten panel
|
||||||
```
|
```
|
||||||
This can be especially useful if all your Telekasten mappings start with the same prefix. In that case, bind the command
|
This can be especially useful if all your Telekasten mappings start with the
|
||||||
panel to the prefix only and it will pop-up when you hesitate to complete the mapping.
|
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
|
## Customization
|
||||||
|
|
||||||
### Highlights
|
### Highlights
|
||||||
|
|
||||||
Telekasten.nvim allows you to color your `[[links]]` and `#tags` by providing the following syntax groups:
|
Telekasten.nvim allows you to color your `[[links]]` and `#tags` by providing
|
||||||
|
the following syntax groups:
|
||||||
|
|
||||||
- `tkLink` : the link title inside the brackets
|
- `tkLink` : the link title inside the brackets
|
||||||
- `tkBrackets` : the brackets surrounding the link title
|
- `tkBrackets` : the brackets surrounding the link title
|
||||||
- `tkHighlight` : ==highlighted== text (non-standard markdown)
|
- `tkHighlight` : ==highlighted== text (non-standard markdown)
|
||||||
- `tkTag` : well, tags
|
- `tkTag` : well, tags
|
||||||
|
|
||||||
An additional `CalNavi` group is defined to tweak the appearance of the calendar navigation button.
|
An additional `CalNavi` group is defined to tweak the appearance of the calendar
|
||||||
|
navigation button.
|
||||||
|
|
||||||
|
|
||||||
```vim
|
```vim
|
||||||
@@ -277,9 +281,10 @@ hi tkBrackets ctermfg=gray guifg=gray
|
|||||||
|
|
||||||
### Mappings
|
### Mappings
|
||||||
|
|
||||||
The real power of Telekasten lays in defining sensible mappings to make your workflow even smoother.
|
The real power of Telekasten lays in defining sensible mappings to make your
|
||||||
A good idea is to take advantage of the [command palette][#command-palette] and start all your mappings with the same
|
workflow even smoother. A good idea is to take advantage of the [command
|
||||||
prefix (`<leader>z`, for `Z`ettelkasten for instance).
|
palette][#command-palette] and start all your mappings with the same prefix
|
||||||
|
(`<leader>z`, for `Z`ettelkasten for instance).
|
||||||
|
|
||||||
|
|
||||||
```lua
|
```lua
|
||||||
@@ -303,18 +308,19 @@ vim.keybind.set("i", "[[", "<cmd>Telekasten insert_link<CR>")
|
|||||||
|
|
||||||
|
|
||||||
#### Advanced mappings
|
#### Advanced mappings
|
||||||
Each Telekasten command is bound to a specific lua function. As lua functions can accept arguments, it is possible to
|
Each Telekasten command is bound to a specific lua function. As lua functions
|
||||||
craft special mappings to tailor the execution of a function to your specific need.
|
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.**
|
**The documentation related to advanced mappings will be provided shortly.**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
### Vaults
|
### Vaults
|
||||||
Telekasten allows the user to have completely separated note collections and switch between them easily.
|
Telekasten allows the user to have completely separated note collections and
|
||||||
Simply add data to the `vaults` table in the configuration and configure each vault as you wish.
|
switch between them easily. Simply add data to the `vaults` table in the
|
||||||
|
configuration and configure each vault as you wish.
|
||||||
|
|
||||||
### Link notation
|
### Link notation
|
||||||
|
|
||||||
@@ -344,7 +350,8 @@ be previewed.
|
|||||||
-  ... links to the file `path/to/file`
|
-  ... links to the file `path/to/file`
|
||||||
```
|
```
|
||||||
|
|
||||||
See the documentation for more details regarding the different types of links (`:h telekaten.link_notation`).
|
See the documentation for more details regarding the different types of links
|
||||||
|
(`:h telekaten.link_notation`).
|
||||||
|
|
||||||
|
|
||||||
### Tag notation
|
### Tag notation
|
||||||
@@ -356,12 +363,14 @@ Telekasten supports the following tag notations:
|
|||||||
3. `yaml-bare`: bare tags in a tag collection in the yaml metadata:
|
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`).
|
See the documentation for more details regarding the tag syntax (`:h
|
||||||
|
telekaten.tag_notation`).
|
||||||
|
|
||||||
### Templates
|
### Templates
|
||||||
|
|
||||||
To streamline your workflow, it is possible to create various note templates and call them upon note creation.
|
To streamline your workflow, it is possible to create various note templates and
|
||||||
These templates will substitute various terms (date, times, file names, uuid, etc).
|
call them upon note creation. These templates will substitute various terms
|
||||||
|
(date, times, file names, UUID, etc).
|
||||||
|
|
||||||
A simple template can be:
|
A simple template can be:
|
||||||
|
|
||||||
@@ -375,32 +384,39 @@ date: {{date}}
|
|||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
A complete list of substitutions can be found in the documentation (`:h telekasten.template_files`).
|
A complete list of substitutions can be found in the documentation (`:h
|
||||||
|
telekasten.template_files`).
|
||||||
|
|
||||||
### Picker actions
|
### Picker actions
|
||||||
|
|
||||||
When you are prompted with a telescope picker to select a note or media file, the following mappings apply:
|
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
|
- <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
|
- the option `insert_after_inserting` defines if insert mode will be entered
|
||||||
current buffer
|
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
|
- <kbd>CTRL</kbd> + <kbd>y</kbd> : yanks a link to the selected note / image,
|
||||||
- the option `close_after_yanking` defines whether the telescope window should be closed when the link has been
|
ready for <kbd>p</kbd>asting
|
||||||
yanked
|
- the option `close_after_yanking` defines whether the telescope window should
|
||||||
- <kbd>RETURN / ENTER</kbd> : usually opens the selected note or performs the action defined by the called function
|
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.
|
- e.g. `insert_img_link()`'s action is to insert a link to the selected image.
|
||||||
|
|
||||||
### Calendar
|
### Calendar
|
||||||
|
|
||||||
When invoking `show_calendar()`, a calendar showing the previous, current, and next month is shown at the right side of
|
When invoking `show_calendar()`, a calendar showing the previous, current, and
|
||||||
vim.
|
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
|
- days that have a daily note associated with them are marked with a + sign and
|
||||||
- pressing enter on a day will open up a telescope finder with the associated daily note selected and previewed. The
|
a different color
|
||||||
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
|
- pressing enter on a day will open up a telescope finder with the associated
|
||||||
you can preview other notes.
|
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
|
If you want to see a big calendar showing the current month that fills your
|
||||||
command in vim:
|
entire window, you can issue the following command in vim:
|
||||||
|
|
||||||
```vim
|
```vim
|
||||||
:CalendarT
|
:CalendarT
|
||||||
@@ -408,13 +424,17 @@ command in vim:
|
|||||||
|
|
||||||
## Hard-coded stuff
|
## Hard-coded stuff
|
||||||
|
|
||||||
Some (minor) stuff are currently still hard-coded. We will eventually change this to allow more flexibility at one point.
|
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:
|
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 daily note files: `YYYY-MM-DD.ext` (e.g.
|
||||||
- the file naming format for weekly note files: `YYYY-Www.ext` (e.g. `2021-W46.md`)
|
`2021-11-21.md`)
|
||||||
- the file naming format for pasted images: `pasted_img_YYYYMMDDhhmmss.png` (e.g. `pasted_img_20211126041108.png`)
|
- 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,
|
_The Telekasten logo is based on the neovim logo attributed to Jason Long, neovim,
|
||||||
|
|||||||
Reference in New Issue
Block a user