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 wiki 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)

🏃 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.

🔄 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 help wiki
• :Obsidian helpgrep - grep files in the help wiki
• :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_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 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 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 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.10.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.
  • 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:
  • telescope.nvim
  • fzf-lua
  • mini.pick
  • snacks.picker

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

❤️ Acknowledgement

We would like to thank epwalsh for creating this beautiful plugin. If you're feeling especially generous, he still appreciates some coffee funds!.