obsidian.nvim

obsidian.nvim is a Neovim plugin for writing and navigating Obsidian vaults using Lua. Key features include:

• Completion: Asynchronous autocompletion for note references ([[) and tags (#) via nvim-cmp and ripgrep.
• Navigation: Use gf on any link to navigate to the referenced note.
• Images: Support for pasting images from the clipboard into notes.
• Syntax: Enhanced markdown syntax highlighting, concealing, and extmarks for references, tags, and checkboxes.

To install obsidian.nvim, use your preferred plugin manager. It is recommended to use the latest release (version = "*" or tag = "*") rather than the main branch for stability.

Required Dependency:

• nvim-lua/plenary.nvim

Setup: Call require("obsidian").setup({ ... }) with your desired configuration. You can define multiple workspaces to manage different Obsidian vaults.

-- Example using lazy.nvim
return {
  "epwalsh/obsidian.nvim",
  version = "*",
  lazy = true,
  ft = "markdown",
  dependencies = {
    "nvim-lua/plenary.nvim",
  },
  opts = {
    workspaces = {
      {
        name = "personal",
        path = "~/vaults/personal",
      },
    },
  },
}

Core Requirements

• NeoVim: >= 0.8.0
• ripgrep: Required for completion and search features.

OS-Specific Dependencies

Certain commands require external tools:

• Windows WSL: wsl-open (for :ObsidianOpen)
• MacOS: pngpaste (for :ObsidianPasteImg)
• Linux: xclip (X11) or wl-clipboard (Wayland) (for :ObsidianPasteImg)

Use :ObsidianTemplate to insert a template or :ObsidianNewFromTemplate to create a new note from one.

Built-in substitutions: {{id}}, {{title}}, {{path}}, {{date}}, and {{time}}.

Custom substitutions: Define functions in templates.substitutions to add custom variables.

templates = {
  folder = "my-templates-folder",
  substitutions = {
    yesterday = function() 
      return os.date("%Y-%m-%d", os.time() - 86400) 
    end
  }
}

Manage how images and other attachments are handled when using :ObsidianPasteImg.

• attachments.img_folder: The directory where images are stored (relative to vault root).
• attachments.img_name_func: Function to generate the filename (e.g., adding a timestamp).
• attachments.img_text_func: Function to define the markdown syntax used to insert the image.

attachments = {
  img_folder = "assets/imgs",
  img_name_func = function() 
    return string.format("%s-", os.time()) 
  end,
}

Customize how daily notes are handled via the daily_notes table in your setup:

• folder: Subdirectory for daily notes.
• date_format: Date format for the note ID.
• alias_format: Date format for the default alias.
• default_tags: Tags to add to new daily notes.
• template: Path to a template file to insert upon creation.

daily_notes = {
  folder = "notes/dailies",
  date_format = "%Y-%m-%d",
  alias_format = "%B %-d, %Y",
  default_tags = { "daily-notes" },
  template = "daily.md"
}

To enable advanced UI features (like checkbox icons and link concealment), set conceallevel to 1 or 2 in Neovim.

Key UI settings:

• ui.enable: Enable/disable UI features.
• ui.checkboxes: Map characters (e.g., " ", "x") to specific highlight groups.
• ui.hl_groups: Define custom highlight groups using vim.api.nvim_set_hl().

-- Required for UI features
-- set conceallevel=1

ui = {
  enable = true,
  checkboxes = {
    [" "] = { char = "󰄱", hl_group = "ObsidianTodo" },
    ["x"] = { char = "", hl_group = "ObsidianDone" },
  },
}

Workspaces define your Obsidian vaults. You can configure multiple workspaces, and obsidian.nvim will automatically select the one whose path is a parent of the current file.

• Fixed Workspaces: Provide a name and a path (string).
• Strict Mode: Setting strict = true forces the path to be treated as the workspace root, even if the actual Obsidian vault root is higher up.
• Dynamic Workspaces: Provide a Lua function for the path field. This is useful for working with markdown files outside of fixed vaults (e.g., using the current buffer's parent directory).

workspaces = {
  { 
    name = "personal", 
    path = "~/vaults/personal" 
  },
  { 
    name = "dynamic-vault", 
    path = function() 
      return assert(vim.fs.dirname(vim.api.nvim_buf_get_name(0))) 
    end 
  }
}

To programmatically interact with obsidian.nvim features in Lua, obtain the main client instance using require("obsidian").get_client(). The client provides access to workspaces, notes, searching, and link resolution.

local client = require("obsidian").get_client()