Notes on configuration - obsidian-nvim/obsidian.nvim GitHub Wiki

For most Obsidian users, each workspace you configure in your obsidian.nvim config should correspond to a unique Obsidian vault, in which case the path of each workspace should be set to the corresponding vault root path.

For example, suppose you have an Obsidian vault at ~/vaults/personal, then the workspaces field in your config would look like this:

config = {
  workspaces = {
    {
      name = "personal",
      path = "~/vaults/personal",
    },
  },
}

However obsidian.nvim's concept of workspaces is a little more general than that of vaults, since it's also valid to configure a workspace that doesn't correspond to a vault, or to configure multiple workspaces for a single vault. The latter case can be useful if you want to segment a single vault into multiple directories with different settings applied to each directory. For example:

config = {
  workspaces = {
    {
      name = "project-1",
      path = "~/vaults/personal/project-1",
      -- `strict=true` here tells obsidian to use the `path` as the workspace/vault root,
      -- even though the actual Obsidian vault root may be `~/vaults/personal/`.
      strict = true,
      overrides = {
        -- ...
      },
    },
    {
      name = "project-2",
      path = "~/vaults/personal/project-2",
      strict = true,
      overrides = {
        -- ...
      },
    },
  },
}

obsidian.nvim also supports "dynamic" workspaces. These are simply workspaces where the path is set to a Lua function (that returns a path) instead of a hard-coded path. This can be useful in several scenarios, such as when you want a workspace whose path is always set to the parent directory of the current buffer:

config = {
  workspaces = {
    {
      name = "buf-parent",
      path = function()
        return assert(vim.fs.dirname(vim.api.nvim_buf_get_name(0)))
      end,
    },
  },
}

Dynamic workspaces are also useful when you want to use a subset of this plugin's functionality on markdown files outside of your "fixed" vaults. See using obsidian.nvim outside of a workspace / Obsidian vault.

obsidian.nvim supports nvim_cmp and blink.cmp completion plugins.

obsidian.nvim will set itself up automatically when you enter a markdown buffer within your vault directory, you do not need to specify this plugin as a cmp source manually.

Note that in order to trigger completion for tags within YAML frontmatter you still need to type the "#" at the start of the tag. obsidian.nvim will remove the "#" when you hit enter on the tag completion item.

If you're using nvim-treesitter you're configuration should include both "markdown" and "markdown_inline" sources:

require("nvim-treesitter.configs").setup {
  ensure_installed = { "markdown", "markdown_inline", ... },
  highlight = {
    enable = true,
    additional_vim_regex_highlighting = { "markdown" }, -- for the obsidian style %% comments
  },
}

If you use vim-markdown you'll probably want to disable its frontmatter syntax highlighting (vim.g.vim_markdown_frontmatter = 1) which I've found doesn't work very well.

If you wish to use the formatting concealment features, you will need to have conceallevel set to a value that allows it (either 1 or 2), for example: set conceallevel=1 in viml or vim.opt.conceallevel = 1 in a lua config.

The notes_subdir and note_id_func options are not mutually exclusive. You can use them both. For example, using a combination of both of the above settings, a new note called "My new note" will assigned a path like notes/1657296016-my-new-note.md.

If you want the gf passthrough functionality but you've already overridden the gf keybinding, just change your gf mapping definition to something like this:

vim.keymap.set("n", "gf", function()
  if require("obsidian").util.cursor_on_markdown_link() then
    return "<cmd>ObsidianFollowLink<CR>"
  else
    return "gf"
  end
end, { noremap = false, expr = true })

Then make sure to comment out the gf keybinding in your obsidian.nvim config:

mappings = {
  -- ["gf"] = ...
},

Or alternatively you could map obsidian.nvim's follow functionality to a different key:

mappings = {
  ["fo"] = {
    action = function()
      return require("obsidian").util.gf_passthrough()
    end,
    opts = { noremap = false, expr = true, buffer = true },
  },
},