Obsidian.nvim

<h1 align="center">obsidian.nvim</h1> <div><h4 align="center"><a href="#setup">Setup</a> · <a href="#configuration-options">Configure</a> · <a href="#contributing">Contribute</a> · <a href="https://github.com/epwalsh/obsidian.nvim/discussions">Discuss</a></h4></div> <div align="center"><a href="https://github.com/epwalsh/obsidian.nvim/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/epwalsh/obsidian.nvim?style=for-the-badge&logo=starship&logoColor=D9E0EE&labelColor=302D41&&color=d9b3ff&include_prerelease&sort=semver" /></a> <a href="https://github.com/epwalsh/obsidian.nvim/pulse"><img alt="Last commit" src="https://img.shields.io/github/last-commit/epwalsh/obsidian.nvim?style=for-the-badge&logo=github&logoColor=D9E0EE&labelColor=302D41&color=9fdf9f"/></a> <a href="https://github.com/neovim/neovim/releases/latest"><img alt="Latest Neovim" src="https://img.shields.io/github/v/release/neovim/neovim?style=for-the-badge&logo=neovim&logoColor=D9E0EE&label=Neovim&labelColor=302D41&color=99d6ff&sort=semver" /></a> <a href="http://www.lua.org/"><img alt="Made with Lua" src="https://img.shields.io/badge/Built%20with%20Lua-grey?style=for-the-badge&logo=lua&logoColor=D9E0EE&label=Lua&labelColor=302D41&color=b3b3ff"></a> <a href="https://www.buymeacoffee.com/epwalsh"><img alt="Buy me a coffee" src="https://img.shields.io/badge/Buy%20me%20a%20coffee-grey?style=for-the-badge&logo=buymeacoffee&logoColor=D9E0EE&label=Sponsor&labelColor=302D41&color=ffff99" /></a></div> <hr>

A Neovim plugin for writing and navigating Obsidian vaults, written in Lua.

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.

If you're new to Obsidian I highly recommend watching this excellent YouTube video for a great overview.

Keep in mind this plugin is not meant to replace Obsidian, but to complement it. The Obsidian app is very powerful in its own way; it 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.

Table of contents

• 👉 Features
  • Commands
  • Demo
• ⚙️ Setup
  • System requirements
  • Install and configure
  • Plugin dependencies
  • Configuration options
  • Notes on configuration
  • Using templates
  • Usage outside of a workspace or vault
• ➕ Contributing

Features

▶️ Completion: Ultra-fast, asynchronous autocompletion for note references and tags via nvim-cmp (triggered by typing [[ for wiki links, [ for markdown links, or # for tags), powered by ripgrep.

🏃 Navigation: Navigate throughout your vault by typing gf on any link to another note.

📷 Images: Paste images into notes.

💅 Syntax: Additional markdown syntax highlighting, concealing, and extmarks for references, tags, and check-boxes.

Commands

• :ObsidianOpen [QUERY] to open a note in the Obsidian app. This command has one optional argument: a query used to resolve the note to open by ID, path, or alias. If not given, the note corresponding to the current buffer is opened.

• :ObsidianNew [TITLE] to create a new note. This command has one optional argument: the title of the new note.

• :ObsidianQuickSwitch to quickly switch to (or open) another note in your vault, searching by its name using ripgrep with your preferred picker (see plugin dependencies below).

• :ObsidianFollowLink [vsplit|hsplit] to follow a note reference under the cursor, optionally opening it in a vertical or horizontal split.

• :ObsidianBacklinks for getting a picker list of references to the current buffer.

• :ObsidianTags [TAG ...] for getting a picker list of all occurrences of the given tags.

• :ObsidianToday [OFFSET] to open/create a new daily note. This command also takes an optional offset in days, e.g. use :ObsidianToday -1 to go to yesterday's note. Unlike :ObsidianYesterday and :ObsidianTomorrow this command does not differentiate between weekdays and weekends.

• :ObsidianYesterday to open/create the daily note for the previous working day.

• :ObsidianTomorrow to open/create the daily note for the next working day.

• :ObsidianDailies [OFFSET ...] to open a picker list of daily notes. For example, :ObsidianDailies -2 1 to list daily notes from 2 days ago until tomorrow.

• :ObsidianTemplate [NAME] to insert a template from the templates folder, selecting from a list using your preferred picker. See "using templates" for more information.

• :ObsidianSearch [QUERY] to search for (or create) notes in your vault using ripgrep with your preferred picker.

• :ObsidianLink [QUERY] to link an inline visual selection of text to a note. This command has one optional argument: a query that will be used to resolve the note by ID, path, or alias. If not given, the selected text will be used as the query.

• :ObsidianLinkNew [TITLE] to create a new note and link it to an inline visual selection of text. This command has one optional argument: the title of the new note. If not given, the selected text will be used as the title.

• :ObsidianLinks to collect all links within the current buffer into a picker window.

• :ObsidianExtractNote [TITLE] to extract the visually selected text into a new note and link to it.

• :ObsidianWorkspace [NAME] to switch to another workspace.

• :ObsidianPasteImg [IMGNAME] to 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. You can configure the default folder to save images to with the attachments.img_folder option.

• :ObsidianRename [NEWNAME] [--dry-run] to rename the note of the current buffer or reference under the cursor, updating all backlinks across the vault. Since this command is still relatively new and could potentially write a lot of changes to your vault, I highly recommend committing the current state of your vault (if you're using version control) before running it, or doing a dry-run first by appending "--dry-run" to the command, e.g. :ObsidianRename new-id --dry-run.

• :ObsidianToggleCheckbox to cycle through checkbox options.

• :ObsidianNewFromTemplate [TITLE] to create a new note from a template in the templates folder. Selecting from a list using your preferred picker. This command has one optional argument: the title of the new note.

• :ObsidianTOC to load the table of contents of the current note into a picker list.

Demo

Setup

System requirements

• NeoVim >= 0.8.0 (this plugin uses vim.fs which was only added in 0.8).
• If you want completion and search features (recommended) you'll need ripgrep to be installed and on your $PATH. See ripgrep#installation for install options.

Specific operating systems also require additional dependencies in order to use all of obsidian.nvim's functionality:

• Windows WSL users need wsl-open for the :ObsidianOpen command.
• MacOS users need pngpaste (brew install pngpaste) for the :ObsidianPasteImg command.
• Linux users need xclip (X11) or wl-clipboard (Wayland) for the :ObsidianPasteImg command.

Search functionality (e.g. via the :ObsidianSearch and :ObsidianQuickSwitch commands) also requires a picker such telescope.nvim (see plugin dependencies below).

Install and configure

To configure obsidian.nvim you just need to call require("obsidian").setup({ ... }) with the desired options. Here are some examples using different plugin managers. The full set of plugin dependencies and configuration options are listed below.

⚠️ 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.

Using lazy.nvim

return {
  "epwalsh/obsidian.nvim",
  version = "*",  -- recommended, use latest release instead of latest commit
  lazy = true,
  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.expan