plugins.obsidian.settings

Options provided to the require('obsidian').setup function.

Type: attribute set of anything

Default: { }

Example:

{
  completion = {
    min_chars = 2;
    nvim_cmp = true;
  };
  new_notes_location = "current_dir";
  workspaces = [
    {
      name = "work";
      path = "~/obsidian/work";
    }
    {
      name = "startup";
      path = "~/obsidian/startup";
    }
  ];
}

Declared by:

plugins.obsidian.settings.dir

Alternatively to workspaces - and for backwards compatibility - you can set dir to a single path instead of workspaces.

For example:

  dir = "~/vaults/work";

Type: null or string

Default: null

Declared by:

plugins.obsidian.settings.disable_frontmatter

Boolean or a function that takes a filename and returns a boolean. true indicates that you don’t want obsidian.nvim to manage frontmatter.

Default: false

Type: null or lua function string or boolean

Default: null

Declared by:

plugins.obsidian.settings.follow_url_func

By default when you use :ObsidianFollowLink on a link to an external URL it will be ignored but you can customize this behavior here.

Example:

  function(url)
    -- Open the URL in the default web browser.
    vim.fn.jobstart({"open", url})  -- Mac OS
    -- vim.fn.jobstart({"xdg-open", url})  -- linux
  end

Type: null or lua code string

Default: null

Declared by:

plugins.obsidian.settings.image_name_func

Customize the default name or prefix when pasting images via :ObsidianPasteImg.

Example:

  function()
    -- Prefix image names with timestamp.
    return string.format("%s-", os.time())
  end

Type: null or lua code string

Default: null

Declared by:

plugins.obsidian.settings.log_level

Set the log level for obsidian.nvim.

Type: null or unsigned integer, meaning >=0, or one of “off”, “error”, “warn”, “info”, “debug”, “trace”

Default: null

Plugin default: "info"

Declared by:

Customize how markdown links are formatted.

  ---@param opts {path: string, label: string, id: string|?}
  ---@return string links are formatted.

Example:

  function(opts)
    return string.format("[%s](%s)", opts.label, opts.path)
  end

Default: See source

Type: null or lua code string

Default: null

Declared by:

plugins.obsidian.settings.new_notes_location

Where to put new notes created from completion.

Valid options are

  • “current_dir” - put new notes in same directory as the current buffer.
  • “notes_subdir” - put new notes in the default notes subdirectory.

Type: null or one of “current_dir”, “notes_subdir” or raw lua code

Default: null

Plugin default: "current_dir"

Declared by:

plugins.obsidian.settings.note_frontmatter_func

You can customize the frontmatter data.

Example:

  function(note)
    -- Add the title of the note as an alias.
    if note.title then
      note:add_alias(note.title)
    end

    local out = { id = note.id, aliases = note.aliases, tags = note.tags }

    -- `note.metadata` contains any manually added fields in the frontmatter.
    -- So here we just make sure those fields are kept in the frontmatter.
    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

Type: null or lua code string

Default: null

Declared by:

plugins.obsidian.settings.note_id_func

Customize how names/IDs for new notes are created.

Example:

  function(title)
    -- Create note IDs in a Zettelkasten format with a timestamp and a suffix.
    -- In this case a note with the title 'My new note' will be given an ID that looks
    -- like '1657296016-my-new-note', and therefore the file name '1657296016-my-new-note.md'
    local suffix = ""
    if title ~= nil then
      -- If title is given, transform it into valid file name.
      suffix = title:gsub(" ", "-"):gsub("[^A-Za-z0-9-]", ""):lower()
    else
      -- If title is nil, just add 4 random uppercase letters to the suffix.
      for _ = 1, 4 do
        suffix = suffix .. string.char(math.random(65, 90))
      end
    end
    return tostring(os.time()) .. "-" .. suffix
  end

Type: null or lua code string

Default: null

Declared by:

plugins.obsidian.settings.note_path_func

Customize how note file names are generated given the ID, target directory, and title.

  ---@param spec { id: string, dir: obsidian.Path, title: string|? }
  ---@return string|obsidian.Path The full path to the new note.

Example:

  function(spec)
    -- This is equivalent to the default behavior.
    local path = spec.dir / tostring(spec.id)
    return path:with_suffix(".md")
  end

Type: null or lua code string

Default: null

Declared by:

plugins.obsidian.settings.notes_subdir

If you keep notes in a specific subdirectory of your vault.

Type: null or string or raw lua code

Default: null

Declared by:

plugins.obsidian.settings.open_app_foreground

Set to true to force :ObsidianOpen to bring the app to the foreground.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

plugins.obsidian.settings.open_notes_in

Determines how certain commands open notes.

The valid options are:

  • “current” (the default) - to always open in the current window
  • “vsplit” - to open in a vertical split if there’s not already a vertical split
  • “hsplit” - to open in a horizontal split if there’s not already a horizontal split

Type: null or one of “current”, “vsplit”, “hsplit” or raw lua code

Default: null

Plugin default: "current"

Declared by:

Either ‘wiki’ or ‘markdown’.

Type: null or one of “wiki”, “markdown” or raw lua code

Default: null

Plugin default: "wiki"

Declared by:

plugins.obsidian.settings.sort_by

Sort search results by “path”, “modified”, “accessed”, or “created”. The recommend value is “modified” and true for sortReversed, which means, for example, that :ObsidianQuickSwitch will show the notes sorted by latest modified time.

Type: null or one of “path”, “modified”, “accessed”, “created” or raw lua code

Default: null

Plugin default: "modified"

Declared by:

plugins.obsidian.settings.sort_reversed

Whether search results should be reversed.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.obsidian.settings.use_advanced_uri

Set to true to force ‘:ObsidianOpen’ to bring the app to the foreground.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

Customize how wiki links are formatted.

  ---@param opts {path: string, label: string, id: string|?}
  ---@return string

Example:

  function(opts)
    if opts.id == nil then
      return string.format("[[%s]]", opts.label)
    elseif opts.label ~= opts.id then
      return string.format("[[%s|%s]]", opts.id, opts.label)
    else
      return string.format("[[%s]]", opts.id)
    end
  end

Default: See source

Type: null or lua code string

Default: null

Declared by:

plugins.obsidian.settings.yaml_parser

Set the YAML parser to use.

The valid options are:

  • “native” - uses a pure Lua parser that’s fast but potentially misses some edge cases.
  • “yq” - uses the command-line tool yq (https://github.com/mikefarah/yq), which is more robust but much slower and needs to be installed separately.

In general you should be using the native parser unless you run into a bug with it, in which case you can temporarily switch to the “yq” parser until the bug is fixed.

Type: null or one of “native”, “yq” or raw lua code

Default: null

Plugin default: "native"

Declared by: