A community fork of the Neovim plugin for writing and navigating Obsidian vaults, written in Lua, created by epwalsh.
Built for people who love the concept of Obsidian -- a simple, markdown-based notes app -- but love Neovim too much to stand typing characters into anything else.
This plugin is not meant to replace Obsidian, but to complement it. The Obsidian app comes with a mobile app and has a lot of functionality that's not feasible to implement in Neovim, such as the graph explorer view. That said, this plugin stands on its own as well. You don't necessarily need to use it alongside the Obsidian app.
The original project has not been actively maintained for quite a while and with the ever-changing Neovim ecosystem, new widely used tools such as blink.cmp or snacks.picker were not supported.
With bugs, issues and pull requests piling up, people from the community decided to fork and maintain the project.
- Discussions are happening in GitHub Discussions
- Sponsor the project at Open Collective
[[ for wiki links, [ for markdown links, or # for tags)
🏃 Navigation: Navigate throughout your vault via links, backlinks, tags and etc.
📷 Images: Paste images into notes.
📈 Status: See note status in footer like obsidian app.
smart_action, bind to<CR>will:- If cursor is on a link, follow the link.
- If cursor is on a tag, show all notes with that tag in a picker.
- If cursor is on a checkbox, toggle the checkbox.
- If cursor is on a heading, cycle the fold of that heading, see Folding to set this up.
nav_link, bind to[oand]owill navigate cursor to next valid link in the buffer.
For other available actions and remapping default ones, see Keymaps
There's one entry point user command for this plugin: Obsidian
Obsidian<CR>(<enter>) to select sub commands.Obsidian <Tab>to get completion for sub commands.- Sub commands are context sensitive, meaning some actions will only appear when:
- you are in a note.
- you are in visual mode.
- See Commands for more info.
| name | description | info |
|---|---|---|
:Obsidian dailies [OFFSET ...] |
open a picker list of daily notes | :Obsidian dailies -2 1 to list daily notes from 2 days ago until tomorrow |
:Obsidian new [TITLE] |
create a new note | |
:Obsidian open [QUERY] |
open a note in the Obsidian app | query is used to resolve the note to open by ID, path, or alias, else use current note |
:Obsidian today [OFFSET] |
open/create a new daily note | offset is in days, e.g. use :Obsidian today -1 to go to yesterday's note. Unlike :Obsidian yesterday and :Obsidian tomorrow this command does not differentiate between weekdays and weekends |
:Obsidian tomorrow |
open/create the daily note for the next working day | |
:Obsidian yesterday |
open/create the daily note for the previous working day | |
:Obsidian new_from_template [TITLE] [TEMPLATE] |
create a new note with TITLE from a template with the name TEMPLATE |
both arguments are optional. If not given, the template will be selected from a list using your preferred picker |
:Obsidian quick_switch |
switch to another note in your vault, searching by its name with a picker | |
:Obsidian search [QUERY] |
search for (or create) notes in your vault using ripgrep with your preferred picker |
|
:Obsidian tags [TAG ...] |
for getting a picker list of all occurrences of the given tags | |
:Obsidian workspace [NAME] |
switch to another workspace |
| name | description | info |
|---|---|---|
:Obsidian backlinks |
get a picker list of references to the current note | grr/vim.lsp.buf.references to see references in quickfix list |
:Obsidian follow_link [STRATEGY] |
follow a note reference under the cursor | available strategies: vsplit, hsplit, vsplit_force, hsplit_force |
:Obsidian toc |
get a picker list of table of contents for current note | |
:Obsidian template [NAME] |
insert a template from the templates folder, selecting from a list using your preferred picker | Template |
:Obsidian links |
get a picker list of all links in current note | |
:Obsidian paste_img [IMGNAME] |
paste an image from the clipboard into the note at the cursor position by saving it to the vault and adding a markdown image link | Images |
:Obsidian rename [NEWNAME] |
rename the note of the current buffer or reference under the cursor, updating all backlinks across the vault | runs :wa before renaming, and load every note with backlinks into your buffer-list, after renaming you need to do :wa after for changes to take effect. Alternatively, call vim.lsp.buf.rename or use grn |
:Obsidian toggle_checkbox |
to cycle through checkbox options |
| name | description | info |
|---|---|---|
:Obsidian extract_note [TITLE] |
extract the visually selected text into a new note and link to it | |
:Obsidian link [QUERY] |
to link an inline visual selection of text to a note. | query will be used to resolve the note by ID, path, or alias, else query is selected text |
:Obsidian link_new [TITLE] |
create a new note and link it to an inline visual selection of text | if title is not given, else selected text is used |
-
Neovim >= 0.10.0
-
For completion and search features:
- Backend: ripgrep, see ripgrep#installation
- Frontend: a picker, see Plugin dependencies
-
Additional system dependencies:
There's no required dependency, but there are a number of optional dependencies that enhance the obsidian.nvim experience.
Completion:
Pickers:
Image viewing:
- snacks.image
- See Images for configuration.
Syntax highlighting:
See syntax highlighting for more details.
- For base syntax highlighting:
- For additional syntax features:
Warning
If you install from the latest release (recommended for stability) instead of main, be aware that the README on main may reference features that haven't been released yet. For that reason I recommend viewing the README on the tag for the latest release instead of main.
Tip
To see your installation status, run :checkhealth obsidian
To try out or debug this plugin, use minimal.lua in the repo to run a clean instance of obsidian.nvim
Using lazy.nvim
Click for install snippet
return {
"obsidian-nvim/obsidian.nvim",
version = "*", -- recommended, use latest release instead of latest commit
ft = "markdown",
-- Replace the above line with this if you only want to load obsidian.nvim for markdown files in your vault:
-- event = {
-- -- If you want to use the home shortcut '~' here you need to call 'vim.fn.expand'.
-- -- E.g. "BufReadPre " .. vim.fn.expand "~" .. "/my-vault/*.md"
-- -- refer to `:h file-pattern` for more examples
-- "BufReadPre path/to/my-vault/*.md",
-- "BufNewFile path/to/my-vault/*.md",
-- },
---@module 'obsidian'
---@type obsidian.config
opts = {
workspaces = {
{
name = "personal",
path = "~/vaults/personal",
},
{
name = "work",
path = "~/vaults/work",
},
},
-- see below for full list of options 👇
},
}Using rocks.nvim
Click for install snippet
:Rocks install obsidian.nvimTo configure obsidian.nvim, pass your custom options that are different from default options to require"obsidian".setup().
See the obsidian.nvim wiki
Please read the CONTRIBUTING guide before submitting a pull request.
We would like to thank epwalsh for creating this beautiful plugin. If you're feeling especially generous, he still appreciates some coffee funds!.
![@allcontributors[bot]](https://avatars.githubusercontent.com/in/23186?s=64&v=4){kind=small}
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
