IlyasYOY/obs.nvim

github

note-taking

90

0

1

5

CREATED

2023-03-05

UPDATED

2026-06-02

---

obs.nvim

obs.nvim is a WIP Neovim plugin for Obsidian-like Markdown notes.

It is built around a local note vault and small Neovim commands for common note workflows:

• write notes without leaving Neovim
• follow [[wiki links]]
• create daily and weekly journal notes
• insert Markdown templates
• rename, move, and inspect backlinks for notes
• copy wiki or Obsidian links for the current note

Installation

Example installation with folke/lazy.nvim:

return {
    {
        "IlyasYOY/obs.nvim",
    },
}

Example installation with Neovim's built-in vim.pack:

vim.pack.add {
    { src = "https://github.com/IlyasYOY/obs.nvim" },
}

Requirements and health

obs.nvim uses Neovim user commands, vim.ui.select, and vim.ui.open. A clipboard provider is needed for the link-copy commands. Wiki link completion requires Neovim 0.12 or newer; on older versions the rest of the plugin can still be configured, but completion is left disabled.

After setup, run:

:checkhealth obs

The health check verifies that the plugin loads, obs.setup() has run, expected commands are registered, the required Neovim APIs and clipboard support are available, and the configured vault, templates, journal directories, and note, daily, or weekly templates are visible.

Configuration

My configuration is here.

Example configuration:

local obs = require "obs"

obs.setup {
    vault_home = "~/Notes",
    vault_name = "Notes",
    journal = {
        daily_template_name = "daily",
        weekly_template_name = "weekly",
    },
    templater = {
        home = "~/Notes/meta/templates",
        note_template_name = "note",
        extra_providers = {
            {
                name = "descr",
                func = function()
                    return vim.fn.input "Enter description: "
                end,
            },
        },
    },
}

vim.keymap.set("n", "<leader>nn", "<cmd>ObsNvimFollowLink<cr>")
vim.keymap.set("n", "<leader>nr", "<cmd>ObsNvimRandomNote<cr>")
vim.keymap.set("n", "<leader>nN", "<cmd>ObsNvimNewNote<cr>")
vim.keymap.set("n", "<leader>ny", "<cmd>ObsNvimCopyObsidianLinkToNote<cr>")
vim.keymap.set("n", "<leader>nY", "<cmd>ObsNvimCopyWikiLinkToNote<cr>")
vim.keymap.set("n", "<leader>no", "<cmd>ObsNvimOpenInObsidian<cr>")
vim.keymap.set("n", "<leader>nd", "<cmd>ObsNvimDailyNote<cr>")
vim.keymap.set("n", "<leader>nw", "<cmd>ObsNvimWeeklyNote<cr>")
vim.keymap.set("n", "<leader>nrn", "<cmd>ObsNvimRename<cr>")
vim.keymap.set("n", "<leader>nT", "<cmd>ObsNvimTemplate<cr>")
vim.keymap.set("n", "<leader>nM", "<cmd>ObsNvimMove<cr>")
vim.keymap.set("n", "<leader>nb", "<cmd>ObsNvimBacklinks<cr>")
vim.keymap.set("n", "<leader>nt", "<cmd>ObsNvimTags<cr>")
vim.keymap.set("n", "<leader>ng", "<cmd>ObsNvimTag<cr>")
vim.keymap.set("n", "]l", function()
    vim.cmd(vim.v.count1 .. "ObsNvimNextLink")
end)
vim.keymap.set("n", "[l", function()
    vim.cmd(vim.v.count1 .. "ObsNvimPrevLink")
end)

obs.setup() accepts obs.VaultOpts, defined in lua/obs/vault.lua.

The most useful options are:

Regular notes created with :ObsNvimNewNote use templater.note_template_name. Daily notes use journal.daily_template_name. Weekly notes use journal.weekly_template_name. The older journal.template_name option still works as a deprecated alias for the daily template.

Wiki link completion requires Neovim 0.12 or newer and is enabled by default for Markdown notes inside the vault. It completes note names inside [[...]] with Neovim's built-in completion:

• use CTRL-X CTRL-U to trigger it manually
• set vim.opt.autocomplete = true in your config for Neovim's built-in automatic popup
• set completion = { enabled = false } in obs.setup() to disable it

Templates are Markdown files in templater.home. The default template variables are:

You can add custom variables with templater.extra_providers, or set templater.include_default_providers = false to disable the built-in variables.

Commands

Most commands that act on the current buffer require the file to be a Markdown note inside the configured vault.

:ObsNvimNextLink wraps at file boundaries. The example ]l and [l mappings preserve counts, so 3]l moves three wiki links forward and 2[l moves two wiki links backward. Use :ObsNvimNextLink! or :ObsNvimPrevLink! when you want Markdown links like [label](target.md) and bare links like https://example.com included too.

Normal-mode mappings like <cmd>ObsNvimDailyNote<cr> do not automatically pass vim.v.count. Use a function mapping if you want 10<leader>nd to call :10ObsNvimDailyNote. Using both a count and date text shows a warning and does nothing.

The daily-note calendar popup shows one month at a time with ISO week numbers. Existing daily notes are marked with * on day cells, and existing weekly notes are marked with * next to the week number. Use h/l for previous/next day, k/j for previous/next week, K/J for previous/next month, <CR> to open the selected date, w to open the selected row's weekly note, q or <Esc> to close, and ? to toggle mapping help.

Tips

• Useful LuaSnip snippets for Obsidian are here.