obsidian-nvim

obsidian.nvim 技能

用于实现和配置 obsidian.nvim 的综合指南——这款用于管理 Obsidian 知识库的 Neovim 插件。

快速开始

最简安装（lazy.nvim）

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

系统要求

• Neovim：>= 0.10.0
• ripgrep：补全和搜索所需（brew install ripgrep）
• pngpaste（macOS）：用于粘贴图像（brew install pngpaste）
• xclip/wl-clipboard（Linux）：用于粘贴图像

配置

完整配置选项请参阅 references/configuration.md。

基本配置选项

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" },
    },
  },
})

命令

完整命令参考请参阅 references/commands.md。

主要命令

命令	描述
:Obsidian	打开命令选择器
:Obsidian today [OFFSET]	打开/创建每日笔记
:Obsidian new [TITLE]	创建新笔记
:Obsidian search [QUERY]	使用 ripgrep 搜索知识库
:Obsidian quick_switch	模糊查找笔记
:Obsidian backlinks	显示指向当前笔记的引用
:Obsidian template [NAME]	插入模板
:Obsidian workspace [NAME]	切换工作区

可视模式命令

命令	描述
:Obsidian link [QUERY]	将选中内容链接到现有笔记
:Obsidian link_new [TITLE]	创建笔记并链接选中内容
:Obsidian extract_note [TITLE]	将选中内容提取到新笔记

键位映射

智能操作（推荐：<CR>）

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 })

导航链接

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 = {
  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>",
  },
},

补全集成

使用 blink.cmp

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

使用 nvim-cmp

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

触发符号：

• [[ - Wiki 链接补全
• [ - Markdown 链接补全
• # - 标签补全

模板

模板变量

变量	描述
{{title}}	笔记标题
{{date}}	当前日期
{{time}}	当前时间
{{id}}	笔记 ID

自定义替换

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 管理

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" },
},

故障排除

全面的故障排除指南请参阅 references/troubleshooting.md。

健康检查

:checkhealth obsidian

快速修复

问题	解决方案
补全无法使用	安装 ripgrep：brew install ripgrep
选择器无法打开	确认选择器名称与已安装的插件匹配
无法粘贴图像	macOS：brew install pngpaste
链接无法跳转	确保光标位于 [[link]] 或 [text](link) 上
复选框未渲染	设置 :set conceallevel=2
找不到工作区	确认路径存在，且文件位于知识库内

调试模式

log_level = vim.log.levels.DEBUG,

示例

实用配置示例请参阅 references/examples.md。

资源

• GitHub 仓库
• Wiki 文档
• 破坏性变更

---

注意事项

• 该插件需要 Obsidian 正在运行才能实时更新——Neovim 中的 vault 更改不会同步到 Obsidian 的索引，除非应用已打开且当前聚焦于该 vault。
• 补全源排序与 cmp-buffer 冲突——如果缓冲区源的优先级更高，LSP 补全可能不会显示笔记建议；需要显式调整 sorting.priority_weight。
• 每日笔记模板路径使用 Lua 的 os.date 格式，而不是 Obsidian 的自然语言日期格式——nvim 中使用 %Y-%m-%d，Obsidian 中使用 YYYY-MM-DD。
• 对于未编入索引的文件，require("obsidian").get_client():resolve_link() 会返回 nil——即使文件确实存在。在插件外创建笔记后，请强制执行 :ObsidianRefresh。
• lazy.nvim 在 BufRead 时延迟加载：在插件配置求值前打开的第一个 vault 文件不会启用笔记功能——将 obsidian.nvim 设置为 lazy=false，或使用 VeryLazy 事件。