obsidian.nvim

---

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.

🍴 About the fork

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
• See Breaking changes to migrate from original repo or older releases

⭐ Features

▶️ Completion: Ultra-fast, asynchronous autocompletion for note references and tags via nvim-cmp or blink.cmp (triggered by typing [[ 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.

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.

Top level commands

• :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 ...] - get a picker list of all occurrences of the given tags
• :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
• :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

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

Completion:

• blink.cmp
• nvim-cmp

Pickers:

• telescope.nvim
• fzf-lua
• mini.pick
• snacks.picker

Image viewing:

• snacks.image
• See Images for configuration.

Syntax highlighting:

See syntax highlighting for more details.

• For base syntax highlighting:
  • nvim-treesitter
  • vim-markdown
• For additional syntax features:
  • render-markdown.nvim
  • markview.nvim

📥 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 = "*", -- recommended, use latest release instead of latest commit
  ft = "markdown",
  ---@module 'obsidian'
  ---@type obsidian.config
  opts = {
    legacy_commands = false, -- this will be removed in the next major release
    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 { "obsidian-nvim/obsidian.nvim" }

⚙️ Configuration

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

📖 Documentation

See the obsidian.nvim wiki

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

❤️ Acknowledgement

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