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

⭐ 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.
  • 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

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

Note commands

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

Visual mode commands

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

📝 Requirements

System requirements

• Neovim >= 0.10.0

• For completion and search features:

  • Backend: ripgrep, see ripgrep#installation
  • Frontend: a picker, see Plugin dependencies

• 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] 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

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

:Rocks install 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.

❤️ Acknowledgement

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