obsidian.nvim

A community fork of epwalsh/obsidian.nvim, neovim plugin for Obsidian vaults.

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.

🍴 About the fork

The original project has not been actively maintained for quite a while and 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
To migrate from original repo or older releases, see Breaking changes
See the documentation:
- obsidian.nvim documentation for documentation of the latest release.
- :Obsidian help or :Obsidian helpgrep for documentation update to date with your current installation.
- :h obsidian-api for API reference.

⭐ Features

▶️ Completion: Ultra-fast, asynchronous autocompletion for note references and tags via in-process LSP (triggered by typing [[ for wiki and markdown links, # for tags, [^ for footnotes). Use [[##query to search headings across the vault. For blocks, use [[^query for the current note, [[note^query or [[note#^query for a named note, and [[^^query across the vault; unlabeled blocks receive an ID when selected.

Vault-wide block candidates are indexed in memory on first use and updated per note when watched files change. The index starts warming at [[^^; completion items appear once the block query reaches completion.min_chars (set it to 0 to show candidates for a bare prefix).

🏃 Navigation: Navigate throughout your vault via links, backlinks, tags and etc.

📷 Images: Paste images into notes.

📎 Embeds: Render Markdown notes, headings, and blocks inline, with paged whole-note previews. See Embeds.

📈 Status: See note status in footer like obsidian app.

🔄 Sync: Sync support for Obsidian Sync.

Keymaps

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, see Checkbox.create_new.
- If cursor is on a heading, cycle the fold of that heading, see Folding to set this up.
nav_link, bind to [o and ]o will navigate cursor to next valid link in the buffer.

For other available actions and remapping default ones, see Keymaps

Commands

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.

[!Warning] Note subcommands related to refactoring, like rename and template And all the visual mode commands, will be moved to code actions in 3.17.0.

Top level commands

:Obsidian check - check for common issues in your vault and plugin setup
: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 help - find files in the plugin help docs
:Obsidian helpgrep - grep files in the plugin help docs
: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 properties [KEY] [VALUE] - get a picker list of frontmatter properties across the vault
- with no arguments, opens a three-stage picker: property keys, then values for the chosen key, then notes carrying that key/value pair
- KEY alone skips to the values stage; KEY VALUE skips straight to matching notes
:Obsidian today [OFFSET_OR_DATE] - open/create a new daily note
- offset is in days, e.g. use :Obsidian today -1 to go to yesterday's note.
- you can also give an argument like 3-1/2026-3-1, it will parse common date formats and open daily for that specific date.
- 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 rebuild_cache - force a full cache rescan and flush
:Obsidian search [QUERY] - search for (or create) notes in your vault using ripgrep with your preferred picker
:Obsidian sync [SUBCMD] - use obsidian-headless to access official obsidian sync service. Default off, enable with opts.sync.enabled = true, for more see Sync.
:Obsidian tags [TAG ...] - get a picker list of all occurrences of the given tags
:Obsidian unique_note [TITLE] - create a new note with a unique, timestamp-based ID
:Obsidian workspace [NAME] - switch to another workspace

Note commands

: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
- If the link does not exist, you will be prompted to create it. If you choose to create it, the link in the buffer will be automatically updated with the new note's ID and alias.
:Obsidian toc - get a picker list of table of contents for current note
:Obsidian footnotes - get a select list of all footnotes in current note, with preview
: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
- Attachment options
: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 loads every note with backlinks into your buffer-list
- after renaming you need to do :wa again for changes to take effect
- alternatively, call vim.lsp.buf.rename or use grn
:Obsidian toggle_checkbox - cycle through checkbox options

Visual mode commands

:Obsidian extract_note [TITLE] - extract the visually selected text into a new note and link to it
:Obsidian link [QUERY] - 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, selected text is used

LSP code actions

Use gra or :=vim.lsp.buf.code_action() to trigger note specific actions.
See LSP code actions and Actions for more info.

📝 Requirements

System requirements

Neovim >= 0.11.0
For completion and search features: ripgrep
Additional system dependencies:
- Windows WSL users need wsl-open for :Obsidian open.
- MacOS users need pngpaste (brew install pngpaste) for :Obsidian paste_img. ImageMagick is optional and corrects macOS paste gamma when installed (brew install imagemagick).
- Linux users need xclip (X11) or wl-clipboard (Wayland) for :Obsidian paste_img.

Plugin dependencies

There's no required dependency, but there are a number of optional dependencies that enhance the obsidian.nvim experience.

Pickers:

To use a specific picker, set picker.name in your config, e.g.:

require("obsidian").setup {
  picker = {
    name = "snacks.picker", -- use snacks picker
    -- name = "telescope.nvim",   -- or telescope
    -- name = "fzf-lua",     -- or fzf-lua
    -- name = "mini.pick",   -- or mini.pick
  },
}

Image viewing:
- snacks.image
- See Images for configuration.
Completion
- See Completion

📥 Installation

[!WARNING] For stability you may want to use latest release, be aware that the README on main may reference features that haven't been released yet.

So view 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, run nvim -u minimal.lua in the installed root to try in a clean environment

Using `lazy.nvim`

return {
  "obsidian-nvim/obsidian.nvim",
  version = "*", -- use latest release, remove to use latest commit
  ---@module 'obsidian'
  ---@type obsidian.config
  opts = {
    legacy_commands = false, -- this will be removed in 4.0.0
    workspaces = {
      {
        name = "personal",
        path = "~/vaults/personal",
      },
      {
        name = "work",
        path = "~/vaults/work",
      },
    },
  },
}

Using `rocks.nvim`

:Rocks install obsidian.nvim

Using `vim.pack` (nvim-0.12+)

vim.pack.add {
  {
    src = "https://github.com/obsidian-nvim/obsidian.nvim",
    version = vim.version.range "*", -- use latest release, remove to use latest commit
  },
}

require("obsidian").setup {
  legacy_commands = false, -- this will be removed in 4.0.0
  workspaces = {
    {
      name = "personal",
      path = "~/vaults/personal",
    },
    {
      name = "work",
      path = "~/vaults/work",
    },
  },
}

⚙️ Configuration

To configure obsidian.nvim, pass your custom options that are different from default options to require"obsidian".setup().

🤝 Contributing

Please read the CONTRIBUTING guide before submitting a pull request.

_neo451 💻	_{Stefan Otte} 💻	_guspix 💻	_ffricken 💻	_{Erlan Rangel} 💻	_bosvik 💻	_{Jost Alemann} 📖
_{Luis Garcia} 💻	_Joe 💻	_{Horia Gug} 💻	_{Aquiles Gomez} 💻	_{Alvaro Sevilla} 💻	_{Sebastian Stark} 💻	_{Jumpei Yamakawa} 💻
_marcocofano 💻	_Jaehaks 💻	_Magnus 💻	_{Noam Stolero} 💻	_aileot 💻	_{Rico Sta. Cruz} 📖	_{KIM Hyunjae} 💻
_{Ben Burgess} 💻	_{Sebastian Szyller} 💻	_nobe4 💻	_Anaritus 💻	_{Michael Davis} 💻	_{Brian Rodriguez} 💻	_carschandler 📖
_{Aki Sasaki} 💻	_{Reinaldo Molina} 💻	_{Stuart Rackham} 💻	_{Ahmed Mughal} 💻	_{trash-panda-v91-beta} 💻	_{Jakob Westhoff} 💻	_{Christian Johansen} 💻
_{Volodymyr Kot} 💻	_{Jorge Villalobos} 💻	_Tak 💻	_{Emilio Marin} 💻	_{Vladimir Gusev} 💻	_{FirelightFlagboy} 💻	_{Cameron Ring} 💻
_{Miklós Balázs} 💻	_{Clément Vannicatte} 📖	_Anatoliy 💻	_acidsugarx 💻	_{João Sampaio} 💻	_{Sundar Gurumurthy} 💻	_apalermo01 💻
_S1RENS 💻	_CaeChao 💻	_{Kahlil Hodgson} 💻	_{Frederik Roland Christiansen} 💻	_{Lucky Laughing} 💻	_{Jorg Jenni} 💻	_zzhirong 💻
_{Franco Ruggeri} 💻	_{John T. Kelly} 💻	_antinomie8 💻	_Todd 📖	_beekeepeer 💻	_{tdashelby-cmyk} 📖	_{Giovanni Smith-Alvarez} 💻
_Christo 💻	_{Rich Snapp} 💻	_{Neil Syiemlieh} 💻	_{Anshu Gahire} 💻	_{Maciej Gajewski} 💻	_{Xiangnong Wu} 💻	_{MoltenMonster} 💻
_{Samuel Huang} 💻	_{Johannes Schmölder} 💻	_berce 💻	_{Diogo Pombeiro} 💻	_sean0407 💻