Skip to content
Skills Library
Programming · Tool integration

obsidian-nvim

/obsidian-nvim

Guide for implementing obsidian.nvim - a Neovim plugin for Obsidian vault management. Use when configuring, troubleshooting, or extending obsidian.nvim features including workspace setup, daily notes, templates, completion, pickers, and UI customization.

Licence
MIT
Last repository change
14.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Guide for implementing obsidian.nvim - a Neovim plugin for Obsidian vault management. Use when configuring, troubleshooting, or extending obsidian.nvim features including workspace setup, daily notes, templates, completion, pickers, and UI customization.

Original author description

Guide for implementing obsidian.nvim - a Neovim plugin for Obsidian vault management. Use when configuring, troubleshooting, or extending obsidian.nvim features including workspace setup, daily notes, templates, completion, pickers, and UI customization.

How it works

  1. Quick Start
  2. Configuration
  3. Commands
  4. Keymaps
  5. Picker Integration
  6. Completion Integration
  7. Templates
  8. Frontmatter Management
  9. Troubleshooting
  10. Examples
Original SKILL.md headings · 276 lines, 930 words
SKILL.md preview
---
name: obsidian-nvim
description: Guide for implementing obsidian.nvim - a Neovim plugin for Obsidian vault management. Use when configuring, troubleshooting, or extending obsidian.nvim features including workspace setup, daily notes, templates, completion, pickers, and UI customization.
---

# obsidian.nvim Skill

A comprehensive guide for implementing and configuring obsidian.nvim - the Neovim plugin for managing Obsidian vaults.

## Quick Start

### Minimal Installation (lazy.nvim)

```lua
return {
  "obsidian-nvim/obsidian.nvim",
  version = "*",
  ft = "markdown",
  opts = {
    workspaces = {
      { name = "personal", path = "~/vaults/personal" },
    },
  },
}
```

### System Requirements

- **Neovim**: >= 0.10.0
- **ripgrep**: Required for completion and search (`brew install ripgrep`)
- **pngpaste** (macOS): For image pasting (`brew install pngpaste`)
- **xclip/wl-clipboard** (Linux): For image pasting

## Configuration

See [references/configuration.md](references/configuration.md) for complete configuration options.

### Essential Configuration Options

```lua
require("obsidian").setup({
  -- Workspace configuration (required)
  workspaces = {
    { name = "personal", path = "~/vaults/personal" },
    { name = "work", path = "~/vaults/work" },
  },

  -- Daily notes
  daily_notes = {
    folder = "daily",
    date_format = "%Y-%m-%d",
    alias_format = "%B %-d, %Y",
    default_tags = { "daily-notes" },
  },

  -- Templates
  templates = {
    folder = "templates",
    date_format = "%Y-%m-%d",
    time_format = "%H:%M",
  },

  -- Note ID generation (Zettelkasten-style by default)
  note_id_func = function(title)
    local suffix = ""
    if title ~= nil then
      suffix = title:gsub(" ", "-"):gsub("[^A-Za-z0-9-]", ""):lower()
    else
      for _ = 1, 4 do
        suffix = suffix .. string.char(math.random(65, 90))
      end
    end
    return tostring(os.time()) .. "-" .. suffix
  end,

  -- Completion settings
  completion = {
    nvim_cmp = true,  -- or blink = true for blink.cmp
    min_chars = 2,
  },

  -- UI customization
  ui = {
    enable = true,
    checkboxes = {
      [" "] = { char = "󰄱", hl_group = "ObsidianTodo" },
      ["x"] = { char = "", hl_group = "ObsidianDone" },
    },
  },
})
```

## Commands

See [references/commands.md](references/commands.md) for complete command reference.

### Primary Commands

| Command | Description |
|---------|-------------|
| `:Obsidian` | Open command picker |
| `:Obsidian today [OFFSET]` | Open/create daily note |
| `:Obsidian new [TITLE]` | Create new note |
| `:Obsidian search [QUERY]` | Search vault with ripgrep |
| `:Obsidian quick_switch` | Fuzzy find notes |
| `:Obsidian backlinks` | Show references to current note |
| `:Obsidian template [NAME]` | Insert template |
| `:Obsidian workspace [NAME]` | Switch workspace |

### Visual Mode Commands

| Command | Description |
|---------|-------------|
| `:Obsidian link [QUERY]` | Link selection to existing note |
| `:Obsidian link_new [TITLE]` | Create note and link selection |
| `:Obsidian extract_note [TITLE]` | Extract selection to new note |

## Keymaps

### Smart Action (Recommended: `<CR>`)

```lua
vim.keymap.set("n", "<CR>", function()
  if require("obsidian").util.cursor_on_markdown_link() then
    return "<cmd>Obsidian follow_link<CR>"
  else
    return "<CR>"
  end
end, { expr = true })
```

### Navigation Links

```lua
vim.keymap.set("n", "[o", function()
  require("obsidian").util.nav_link("prev")
end, { buffer = true, desc = "Previous link" })

vim.keymap.set("n", "]o", function()
  require("obsidian").util.nav_link("next")
end, { buffer = true, desc = "Next link" })
```

## Picker Integration

Configure your preferred picker:

```lua
picker = {
  name = "telescope",  -- or "fzf-lua", "mini.pick", "snacks.picker"
  note_mappings = {
    new = "<C-x>",
    insert_link = "<C-l>",
  },
  tag_mappings = {
    tag_note = "<C-x>",
    insert_tag = "<C-l>",
  },
},
```

## Completion Integration

### With blink.cmp

```lua
completion = {
  blink = true,
  nvim_cmp = false,
  min_chars = 2,
},
```

### With nvim-cmp

```lua
completion = {
  nvim_cmp = true,
  blink = false,
  min_chars = 2,
},
```

**Triggers:**
- `[[` - Wiki link completion
- `[` - Markdown link completion
- `#` - Tag completion

## Templates

### Template Variables

| Variable | Description |
|----------|-------------|
| `{{title}}` | Note title |
| `{{date}}` | Current date |
| `{{time}}` | Current time |
| `{{id}}` | Note ID |

### Custom Substitutions

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

## Frontmatter Management

```lua
frontmatter = {
  enabled = true,
  func = function(note)
    local out = { id = note.id, aliases = note.aliases, tags = note.tags }
    if note.metadata ~= nil and not vim.tbl_isempty(note.metadata) then
      for k, v in pairs(note.metadata) do
        out[k] = v
      end
    end
    return out
  end,
  sort = { "id", "aliases", "tags" },
},
```

## Troubleshooting

See [references/troubleshooting.md](references/troubleshooting.md) for comprehensive troubleshooting.

### Health Check

```vim
:checkhealth obsidian
```

### Quick Fixes

| Issue | Solution |
|-------|----------|
| Completion not working | Install ripgrep: `brew install ripgrep` |
| Picker not opening | Verify picker name matches installed plugin |
| Images not pasting | macOS: `brew install pngpaste` |
| Links not following | Ensure cursor is on `[[link]]` or `[text](link)` |
| Checkboxes not rendering | Set `:set conceallevel=2` |
| Workspace not found | Verify path exists and file is inside vault |

### Debug Mode

```lua
log_level = vim.log.levels.DEBUG,
```

## Examples

See [references/examples.md](references/examples.md) for practical configuration examples.

## Resources

- [GitHub Repository](https://github.com/obsidian-nvim/obsidian.nvim)
- [Wiki Documentation](https://github.com/obsidian-nvim/obsidian.nvim/wiki)
- [Breaking Changes](https://github.com/obsidian-nvim/obsidian.nvim/wiki/Breaking-Changes)

---

## Gotchas

- **The plugin requires Obsidian to be running for live updates** — vault changes from Neovim don't propagate to Obsidian's index until the app is open AND has focused the vault.
- **Completion source ordering conflicts with `cmp-buffer`** — LSP completion may not show note suggestions if buffer source ranks higher; explicit `sorting.priority_weight` adjustment needed.
- **Daily-note template paths use Lua's `os.date` format**, not Obsidian's natural-language date format — `%Y-%m-%d` in nvim, `YYYY-MM-DD` in Obsidian.
- **`require("obsidian").get_client():resolve_link()` returns nil for an unindexed file** — even if the file exists. Force a `:ObsidianRefresh` after creating notes outside the plugin.
- **lazy.nvim lazy-loading on `BufRead`: the first vault file you open before plugin spec evaluation doesn't get note features** — set `lazy=false` for obsidian.nvim or use a `VeryLazy` event.
Files in this package (5)
  • SKILL.md 7 KB
  • references/commands.md 9 KB
  • references/configuration.md 11 KB
  • references/examples.md 13 KB
  • references/troubleshooting.md 9 KB

Versions

The database has no other skills named obsidian-nvim.

Database snapshot: 13.11.2026 · package version 5a75cd739c7d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100nvim-code-review
    Read and answer code review comments a human left in Neovim (code-review.nvim). Use when the user says "check comments", "address my review comments", or mentions code-review threads.
  • 100nvim-install
    Install Neovim and stand up the nvim-fredrik config in the Claude Code web sandbox (the cloud environment), where no Neovim exists. Use this before testing any Neovim config change in a web session, e.g. checking out a PR branch that touches nvim-fredrik and observing its…
  • 100neovim-configuration
    Modern Neovim configuration expertise including Lua scripting, plugin management with lazy.nvim, LSP setup with Mason, AI integration with claudecode.nvim/opencode.nvim, and workflow optimization. Covers keymaps, autocommands, and treesitter configuration. Use when user mentions…
  • 100lazy-nvim-optimization
    Profiles Neovim startup performance and optimizes lazy.nvim plugin loading with targeted lazy-loading specs, priorities, and event triggers. Contains profiling workflow and bottleneck checklists. Make sure to use this skill whenever the user mentions slow neovim startup, neovim…
  • 100neovim
    Comprehensive guide for this Neovim configuration - a modular, performance-optimized Lua-based IDE. Use when configuring plugins, adding keybindings, setting up LSP servers, debugging, or extending the configuration. Covers lazy.nvim, 82+ plugins across 9 categories, DAP…
  • 100neovim
    Maintain the Stow-managed Neovim config in ~/.dotfiles/home/.config/nvim for Neovim 0.12+, lazy.nvim, vim.lsp.config, and nvim-treesitter main. Use to validate or repair Neovim, change plugins, diagnose measured startup regressions, or fix keymaps and LSP. Route whole-dotfiles…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.