### Get Client

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Retrieves the singleton `obsidian.Client` instance. This function should be called after `setup()` has been successfully executed.

```APIDOC
## require("obsidian").get_client()

### Description
Returns the singleton `obsidian.Client` that was created by `setup()`. Raises an error if `setup()` has not been called. This is the primary handle for all programmatic interaction with obsidian.nvim from within other plugins or user scripts.

### Returns
- `obsidian.Client` - The client instance.

### Request Example
```lua
local client = require("obsidian").get_client()
print(client.dir)               -- absolute path to vault root, e.g. /home/user/vaults/personal
print(client.current_workspace.name)  -- "personal"
print(client:vault_name())      -- "personal"
```
```

--------------------------------

### Setup and Initialization

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

The `setup` function is the primary entry point for initializing obsidian.nvim. It configures the plugin with provided options and registers necessary commands and autocommands.

```APIDOC
## require("obsidian").setup(opts)

### Description
The single entry point that initialises obsidian.nvim for the current Neovim session. It creates the `obsidian.Client`, registers all `:Obsidian*` commands globally, optionally registers three nvim-cmp sources, and installs autocommands that fire on every `*.md` buffer enter/leave and pre-write event. Returns the created client. Should be called only once per Neovim session.

### Parameters
* `opts` (table) - Optional. Configuration options for obsidian.nvim. See the example for available options.

### Request Example
```lua
-- Minimal lazy.nvim spec — recommended installation pattern
return {
  "epwalsh/obsidian.nvim",
  version = "*",   -- always use latest tagged release
  lazy = true,
  ft = "markdown",
  dependencies = { "nvim-lua/plenary.nvim" },
  opts = {
    workspaces = {
      { name = "personal", path = "~/vaults/personal" },
      { name = "work",     path = "~/vaults/work",
        overrides = { notes_subdir = "notes" } },
    },
    notes_subdir        = "notes",
    new_notes_location  = "notes_subdir",  -- "current_dir" | "notes_subdir"
    preferred_link_style = "wiki",          -- "wiki" | "markdown"
    daily_notes = {
      folder       = "notes/dailies",
      date_format  = "%Y-%m-%d",
      alias_format = "%B %-d, %Y",
      default_tags = { "daily-notes" },
      template     = "daily.md",           -- template name, optional
    },
    completion = { nvim_cmp = true, min_chars = 2 },
    sort_by       = "modified",
    sort_reversed = true,
    search_max_lines = 1000,
    open_notes_in = "current",             -- "current" | "vsplit" | "hsplit"
    -- Custom note ID generator (Zettelkasten style)
    note_id_func = function(title)
      local suffix = title and title:gsub(" ", "-"):gsub("[^A-Za-z0-9-ről"]):lower() or
        string.format("%04d", math.random(1000, 9999))
      return tostring(os.time()) .. "-" .. suffix
    end,
    -- Custom frontmatter builder
    note_frontmatter_func = function(note)
      if note.title then note:add_alias(note.title) end
      local out = { id = note.id, aliases = note.aliases, tags = note.tags }
      if note.metadata and not vim.tbl_isempty(note.metadata) then
        for k, v in pairs(note.metadata) do out[k] = v end
      end
      return out
    end,
    callbacks = {
      post_setup         = function(client) vim.notify("obsidian ready: " .. client.dir) end,
      enter_note         = function(client, note) vim.notify("editing: " .. note:display_name()) end,
      pre_write_note     = function(client, note) note:add_tag("reviewed") end,
      post_set_workspace = function(client, ws)   vim.notify("workspace: " .. ws.name) end,
    },
  },
}
-- After setup, retrieve the client anywhere with:
-- local client = require("obsidian").get_client()
```
```

--------------------------------

### Setup obsidian.nvim with lazy.nvim

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

This is the recommended installation pattern using lazy.nvim. Ensure 'nvim-lua/plenary.nvim' is listed as a dependency. Configure workspace paths, note subdirectories, link styles, daily notes, completion settings, search parameters, and open behavior.

```lua
-- Minimal lazy.nvim spec — recommended installation pattern
return {
  "epwalsh/obsidian.nvim",
  version = "*",   -- always use latest tagged release
  lazy = true,
  ft = "markdown",
  dependencies = { "nvim-lua/plenary.nvim" },
  opts = {
    workspaces = {
      { name = "personal", path = "~/vaults/personal" },
      { name = "work",     path = "~/vaults/work",
        overrides = { notes_subdir = "notes" } },
    },
    notes_subdir        = "notes",
    new_notes_location  = "notes_subdir",  -- "current_dir" | "notes_subdir"
    preferred_link_style = "wiki",          -- "wiki" | "markdown"
    daily_notes = {
      folder       = "notes/dailies",
      date_format  = "%Y-%m-%d",
      alias_format = "%B %-d, %Y",
      default_tags = { "daily-notes" },
      template     = "daily.md",           -- template name, optional
    },
    completion = { nvim_cmp = true, min_chars = 2 },
    sort_by       = "modified",
    sort_reversed = true,
    search_max_lines = 1000,
    open_notes_in = "current",             -- "current" | "vsplit" | "hsplit"
    -- Custom note ID generator (Zettelkasten style)
    note_id_func = function(title)
      local suffix = title and title:gsub(" ", "-"):gsub("[^A-Za-z0-9-]", ""):lower() or
        string.format("%04d", math.random(1000, 9999))
      return tostring(os.time()) .. "-" .. suffix
    end,
    -- Custom frontmatter builder
    note_frontmatter_func = function(note)
      if note.title then note:add_alias(note.title) end
      local out = { id = note.id, aliases = note.aliases, tags = note.tags }
      if note.metadata and not vim.tbl_isempty(note.metadata) then
        for k, v in pairs(note.metadata) do out[k] = v end
      end
      return out
    end,
    callbacks = {
      post_setup         = function(client) vim.notify("obsidian ready: " .. client.dir) end,
      enter_note         = function(client, note) vim.notify("editing: " .. note:display_name()) end,
      pre_write_note     = function(client, note) note:add_tag("reviewed") end,
      post_set_workspace = function(client, ws)   vim.notify("workspace: " .. ws.name) end,
    },
  },
}
-- After setup, retrieve the client anywhere with:
-- local client = require("obsidian").get_client()
```

--------------------------------

### Get obsidian.Client instance

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Retrieve the singleton obsidian.Client instance after setup. This client is the main interface for programmatic interactions with obsidian.nvim.

```lua
local client = require("obsidian").get_client()
print(client.dir)               -- absolute path to vault root, e.g. /home/user/vaults/personal
print(client.current_workspace.name)  -- "personal"
print(client:vault_name())      -- "personal"
```

--------------------------------

### Configure obsidian.nvim with Packer.nvim

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Example configuration for obsidian.nvim using the packer.nvim plugin manager. It sets up workspaces and specifies dependencies.

```lua
use({
  "epwalsh/obsidian.nvim",
  tag = "*",  -- recommended, use latest release instead of latest commit
  requires = {
    -- Required.
    "nvim-lua/plenary.nvim",

    -- see below for full list of optional dependencies 👇
  },
  config = function()
    require("obsidian").setup({
      workspaces = {
        {
          name = "personal",
          path = "~/vaults/personal",
        },

```

--------------------------------

### New Client from Directory

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Constructs a new `obsidian.Client` instance for a specified directory without requiring prior `setup()` execution. This is useful for scripting and testing.

```APIDOC
## require("obsidian").new_from_dir(dir)

### Description
Constructs a fresh `obsidian.Client` pointed at an arbitrary vault directory without calling `setup()`. Useful for scripting or testing outside of an interactive Neovim session.

### Parameters
* `dir` (string) - The path to the Obsidian vault directory.

### Returns
- `obsidian.Client` - A new client instance for the specified directory.

### Request Example
```lua
local obsidian = require "obsidian"
local client = obsidian.new_from_dir("~/vaults/work")
local note = client:create_note { title = "Meeting 2024-07-15", no_write = true }
print(note.id)   -- e.g. "1721040000-meeting-2024-07-15"
```
```

--------------------------------

### Configure obsidian.nvim with Lazy.nvim

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Example configuration for obsidian.nvim using the lazy.nvim plugin manager. It sets up workspaces and specifies dependencies.

```lua
return {
  "epwalsh/obsidian.nvim",
  version = "*",  -- recommended, use latest release instead of latest commit
  lazy = true,
  ft = "markdown",
  -- Replace the above line with this if you only want to load obsidian.nvim for markdown files in your vault:
  -- event = {
  --   -- If you want to use the home shortcut '~' here you need to call 'vim.fn.expand'.
  --   -- E.g. "BufReadPre " .. vim.fn.expand "~" .. "/my-vault/*.md"
  --   -- refer to `:h file-pattern` for more examples
  --   "BufReadPre path/to/my-vault/*.md",
  --   "BufNewFile path/to/my-vault/*.md",
  -- },
  dependencies = {
    -- Required.
    "nvim-lua/plenary.nvim",

    -- see below for full list of optional dependencies 👇
  },
  opts = {
    workspaces = {
      {
        name = "personal",
        path = "~/vaults/personal",
      },
      {
        name = "work",
        path = "~/vaults/work",
      },
    },

    -- see below for full list of options 👇
  },
}
```

--------------------------------

### Configure Obsidian.nvim Workspaces and Settings

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Set up your Obsidian vault paths, notes subdirectory, log level, and daily notes configuration. This example shows how to define multiple workspaces with optional overrides.

```lua
{
  workspaces = {
    {
      name = "personal",
      path = "~/vaults/personal",
    },
    {
      name = "work",
      path = "~/vaults/work",
      overrides = {
        notes_subdir = "notes",
      },
    },
  },
  notes_subdir = "notes",
  log_level = vim.log.levels.INFO,
  daily_notes = {
    folder = "notes/dailies",
    date_format = "%Y-%m-%d",
    alias_format = "%B %-d, %Y",
    default_tags = { "daily-notes" },
    template = nil
  },
}
```

--------------------------------

### Create obsidian.Client from directory

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Construct a new obsidian.Client instance for a specified vault directory without calling setup(). This is useful for scripting or testing outside of Neovim.

```lua
local obsidian = require "obsidian"
local client = obsidian.new_from_dir("~/vaults/work")
local note = client:create_note { title = "Meeting 2024-07-15", no_write = true }
print(note.id)   -- e.g. "1721040000-meeting-2024-07-15"
```

--------------------------------

### Markdown Template Example

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Example of a markdown template file that uses substitutions like {{title}}, {{date}}.

```markdown
# {{title}}

Date created: {{date}}
```

--------------------------------

### Configure Default Mappings

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Set up custom key mappings for obsidian.nvim functionalities. This example shows how to override the 'gf' mapping for markdown/wiki links and a mapping to toggle checkboxes.

```lua
mappings = {
  -- Overrides the 'gf' mapping to work on markdown/wiki links within your vault.
  ["gf"] = {
    action = function()
      return require("obsidian").util.gf_passthrough()
    end,
    opts = { noremap = false, expr = true, buffer = true },
  },
  -- Toggle check-boxes.
  ["<leader>ch"] = {
    action = function()
      return require("obsidian").util.toggle_checkbox()
    end,
    opts = { buffer = true },
  },
}
```

--------------------------------

### Configure Obsidian.nvim Key Mappings

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Define custom key mappings for obsidian.nvim actions. This example includes mappings for 'gf' to follow links, toggling checkboxes, and a smart action for context-aware behavior.

```lua
mappings = {
  ["gf"] = {
    action = function()
      return require("obsidian").util.gf_passthrough()
    end,
    opts = { noremap = false, expr = true, buffer = true },
  },
  ["<leader>ch"] = {
    action = function()
      return require("obsidian").util.toggle_checkbox()
    end,
    opts = { buffer = true },
  },
  ["<cr>"] = {
    action = function()
      return require("obsidian").util.smart_action()
    end,
    opts = { buffer = true, expr = true },
  }
}
```

--------------------------------

### Configure Default Mappings in obsidian.nvim

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

These are the default buffer-local mappings for markdown files. They can be overridden by providing a custom `mappings` table in the `setup` function.

```lua
-- These are the defaults; override with opts.mappings = { ... }
mappings = {
  -- Follow link or open (gf passthrough)
  ["gf"] = {
    action = function() return require("obsidian").util.gf_passthrough() end,
    opts   = { noremap = false, expr = true, buffer = true },
  },
  -- Toggle checkbox state
  ["<leader>ch"] = {
    action = function() return require("obsidian").util.toggle_checkbox() end,
    opts   = { buffer = true },
  },
  -- Smart action: follow link if cursor is on one, else toggle checkbox
  ["<cr>"] = {
    action = function() return require("obsidian").util.smart_action() end,
    opts   = { buffer = true, expr = true },
  },
}

-- Disable all default mappings
require("obsidian").setup({ mappings = {} })
```

--------------------------------

### Example of Inserted Template Content

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Shows how a markdown template with substitutions is rendered when inserted into a note.

```markdown
# Configuring Neovim

Date created: 2023-03-01-Wed
```

--------------------------------

### Customize Note File Path Generation in Obsidian.nvim

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Define a custom function to determine the full path for new notes. This example replicates the default behavior by combining the directory, note ID, and adding a '.md' suffix.

```lua
note_path_func = function(spec)
  local path = spec.dir / tostring(spec.id)
  return path:with_suffix(".md")
end
```

--------------------------------

### Define Post-Setup Callback

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Define a callback function that runs at the end of `require("obsidian").setup()`. It receives the client object.

```lua
-- Optional, define your own callbacks to further customize behavior.
callbacks = {
  -- Runs at the end of `require("obsidian").setup()`.
  ---@param client obsidian.Client
  post_setup = function(client) end,
```

--------------------------------

### Path.parent

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Gets the logical parent of the path.

```APIDOC
## Path.parent

### Description
The logical parent of the path.

### Method
`Path.parent({self})

### Return
- `obsidian.Path`|`(optional)` - The parent path, or null if it's the root.
```

--------------------------------

### obsidian.Note.fname

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Gets the filename associated with the note.

```APIDOC
## obsidian.Note.fname

### Description
Get the filename associated with the note.

### Return
(string|) (optional)
```

--------------------------------

### Path.stat

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Gets the OS stat results for the path.

```APIDOC
## Path.stat

### Description
Get OS stat results.

### Method
`Path.stat({self})

### Return
- `(table|)` `(optional)` - The stat results table, or null if unavailable.
```

--------------------------------

### Path.parents

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Gets a list of the parent directories of the path.

```APIDOC
## Path.parents

### Description
Get a list of the parent directories.

### Method
`Path.parents({self})

### Return
- `obsidian.Path[]` - An array of parent paths.
```

--------------------------------

### obsidian.Path.cwd

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Gets a path corresponding to the current working directory.

```APIDOC
## obsidian.Path.cwd

### Description
Get a path corresponding to the current working directory as given by `vim.loop.cwd()`.

### Return
- **path** (obsidian.Path) - The current working directory Path object.
```

--------------------------------

### obsidian.Path.temp

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Gets a temporary path with a unique name. Optional options can be provided.

```APIDOC
## obsidian.Path.temp

### Description
Get a temporary path with a unique name.

### Parameters
#### Path Parameters
- **opts** ({ suffix: (string|?) }|?) - Optional - Options for the temporary path, such as a suffix.

### Return
- **path** (obsidian.Path) - The temporary Path object.
```

--------------------------------

### Client.find_tags

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Finds all tags within notes that start with the provided search term(s).

```APIDOC
## Client.find_tags

### Description
Finds all tags within notes that start with the provided search term(s).

### Method
`Client.find_tags({self}, {term}, {opts})`

### Parameters
- **term** (`string|string[]`): The search term(s) for tags.
- **opts** (`{ search: obsidian.SearchOpts|?, timeout: integer|? }|?`): Optional search options and timeout.

### Return
- `obsidian.TagLocation[]`: An array of tag locations found.
```

--------------------------------

### Path.touch

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Creates a file at the given path.

```APIDOC
## Path.touch

### Description
Create a file at this given path.

### Method
`Path.touch({self}, {opts})

### Parameters
- **opts** { `mode`: `(integer|?,)` `exist_ok`: `boolean`|? }|? - Optional options for file creation. `mode` specifies permissions, and `exist_ok` prevents an error if the file already exists.
```

--------------------------------

### find_vault_root

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Finds the root directory of an Obsidian vault starting from a given base directory.

```APIDOC
## find_vault_root

### Description
Find the vault root from a given directory. This will traverse the directory tree upwards until a '.obsidian/' folder is found to indicate the root of a vault, otherwise the given directory is used as-is.

### Parameters
#### Path Parameters
- **base_dir** (string|obsidian.Path) - The directory to start searching from.

### Return
- **obsidian.Path** (optional) - The path to the vault root, if found.
```

--------------------------------

### Template Configuration

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Sets up template functionality, specifying the template folder, date and time formats, and custom variable substitutions.

```lua
-- Optional, for templates (see below).
templates = {
  folder = "templates",
  date_format = "%Y-%m-%d",
  time_format = "%H:%M",
  -- A map for custom variables, the key should be the variable and the value a function
  substitutions = {},
}
```

--------------------------------

### Client.find_tags_async

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Asynchronously finds all tags within notes that start with the provided search term(s).

```APIDOC
## Client.find_tags_async

### Description
Asynchronously finds all tags within notes that start with the provided search term(s).

### Method
`Client.find_tags_async({self}, {term}, {callback}, {opts})`

### Parameters
- **term** (`string|string[]`): The search term(s) for tags.
- **callback** (`fun(tags: obsidian.TagLocation[])`): The function to call with the found tags.
- **opts** (`{ search: obsidian.SearchOpts }|?`): Optional search options.
```

--------------------------------

### Force Open App Foreground

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Set to true to force ':ObsidianOpen' to bring the application to the foreground.

```lua
-- Optional, set to true to force ':ObsidianOpen' to bring the app to the foreground.
open_app_foreground = false,
```

--------------------------------

### Follow Link Asynchronously

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Handles various link types (wiki, markdown, URL, image) and prompts to create notes if they don't exist. Opens a picker if multiple matches are found. Use `open_strategy` to control how the link is opened.

```lua
local client = require("obsidian").get_client()

-- Follow the link currently under the cursor (typical keymap usage)
vim.keymap.set("n", "gf", function()
  client:follow_link_async(nil, { open_strategy = "vsplit" })
end, { buffer = true })

-- Follow a specific link programmatically
client:follow_link_async("[[" .. "Project Alpha Kickoff" .. "]]")
```

--------------------------------

### obsidian.Path.buffer

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Gets a path corresponding to a buffer. If no buffer number is provided, it defaults to the current buffer.

```APIDOC
## obsidian.Path.buffer

### Description
Get a path corresponding to a buffer.

### Parameters
#### Path Parameters
- **bufnr** (integer|?) - Optional - The buffer number or 0/nil for the current buffer.

### Return
- **path** (obsidian.Path) - The Path object for the buffer.
```

--------------------------------

### client:switch_workspace(workspace) / client:set_workspace(workspace)

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Allows switching between configured workspaces at runtime, with options to lock the workspace.

```APIDOC
## `client:switch_workspace(workspace)` / `client:set_workspace(workspace)`

### Description
Switches the active workspace at runtime. Accepts either a workspace name string or an `obsidian.Workspace` object. Reinitialises the vault directory, reloads config overrides, and re-runs the UI setup. `set_workspace` also accepts `{ lock = true }` to prevent automatic workspace switching when entering markdown buffers.

### Parameters
#### Path Parameters
- `workspace` (string | obsidian.Workspace) - Required - The name of the workspace or the workspace object to switch to.
#### Options (`opts`)
- `lock` (boolean) - Optional - If true, prevents automatic workspace switching.

### Request Example
```lua
local client    = require("obsidian").get_client()
local Workspace = require("obsidian").Workspace

-- Switch by name (must be listed in `workspaces` config)
client:switch_workspace("work")

-- Switch to an ad-hoc workspace
local tmp_ws = Workspace.new("~/notes/tmp", { name = "tmp" })
client:set_workspace(tmp_ws, { lock = true })
```
```

--------------------------------

### Configure Template Folder and Date/Time Formats

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Set the folder for your templates and define custom date and time formats for substitutions.

```lua
{
  -- other fields ...

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

--------------------------------

### obsidian.Path.buf_dir

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Gets a path corresponding to the parent directory of a buffer. If no buffer number is provided, it defaults to the current buffer.

```APIDOC
## obsidian.Path.buf_dir

### Description
Get a path corresponding to the parent of a buffer.

### Parameters
#### Path Parameters
- **bufnr** (integer|?) - Optional - The buffer number or 0/nil for the current buffer.

### Return
- **path** (obsidian.Path) - The Path object for the buffer's parent directory.
```

--------------------------------

### Note.from_file(path, opts) / Note.from_file_async(path, opts)

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Loads a note by parsing its YAML frontmatter and first-level header from a file. The async variant requires a plenary async context.

```APIDOC
## Note.from_file(path, opts) / Note.from_file_async(path, opts) → obsidian.Note

### Description
Loads a note by reading and parsing its YAML frontmatter and first-level `#` header from a file on disk. The async variant must be called inside a plenary async context. Both accept `LoadOpts` to control how many lines are read and whether to collect anchor links or block IDs.

### Parameters
- **path** (string) - Required - The path to the note file.
- **opts** (table) - Optional - Options for loading the note.
  - **max_lines** (number) - Optional - The maximum number of lines to read from the file.
  - **collect_anchor_links** (boolean) - Optional - Whether to collect anchor links.
  - **collect_blocks** (boolean) - Optional - Whether to collect block IDs.

### Example
```lua
local Note = require("obsidian").Note

-- Synchronous load
local note = Note.from_file("~/vaults/personal/notes/alpha.md", {
  max_lines            = 200,
  collect_anchor_links = true,
  collect_blocks       = true,
})
print(note.id)            -- e.g. "1721040000-project-alpha-kickoff"
print(#note.aliases)      -- 2
print(note.has_frontmatter) -- true

-- Resolve a header anchor
local anchor = note:resolve_anchor_link("#Goals")
if anchor then
  print("Goals section at line", anchor.line)
end
```
```

--------------------------------

### obsidian.Note.reference_ids

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Gets a list of all unique strings that can identify this note via references, including the ID, aliases, and filename.

```APIDOC
## obsidian.Note.reference_ids

### Description
Get a list of all of the different string that can identify this note via references, including the ID, aliases, and filename.

### Parameters
* **opts** { lowercase: (boolean|?) }|?

### Return
(string[])
```

--------------------------------

### Workspace.new_from_buf

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Initializes a Workspace object from the parent directory of the specified buffer.

```APIDOC
## Workspace.new_from_buf

### Description
Initialize a 'Workspace' object from the parent directory of the current buffer.

### Parameters
#### Path Parameters
- **bufnr** (integer|?) - The buffer number. Optional.
- **opts** (obsidian.workspace.WorkspaceOpts|?) - Optional workspace options.

### Return
- **obsidian.Workspace** - The initialized Workspace object.
```

--------------------------------

### Define Enter Note Callback

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Define a callback function that runs anytime you enter the buffer for a note. It receives the client and note objects.

```lua
  -- Runs anytime you enter the buffer for a note.
  ---@param client obsidian.Client
  ---@param note obsidian.Note
  enter_note = function(client, note) end,
```

--------------------------------

### Get Default Search Options

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Retrieve the default configuration for search operations. This can be used as a base for custom search queries.

```lua
client:search_defaults()
```

--------------------------------

### Configure Dynamic Workspace for Individual Files

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Set up a dynamic workspace to handle markdown files outside of a traditional Obsidian vault.

```lua
{
  workspaces = {
     {
       name = "personal",
       path = "~/vaults/personal",
     },
     ...
    {
      name = "no-vault",
      path = function()
        -- alternatively use the CWD:
        -- return assert(vim.fn.getcwd())
        return assert(vim.fs.dirname(vim.api.nvim_buf_get_name(0)))
      end,
      overrides = {
        notes_subdir = vim.NIL,  -- have to use 'vim.NIL' instead of 'nil'
        new_notes_location = "current_dir",
        templates = {
          folder = vim.NIL,
        },
        disable_frontmatter = true,
      },
    },
  },
   ...
}
```

--------------------------------

### Configure Obsidian Template Folder and Date/Time Formats

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Set up the template folder, date format, and time format for Obsidian templates. This configuration affects how dates and times are substituted into templates.

```lua
{
  -- other fields ...

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

```

--------------------------------

### Custom Image Following Function

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Defines how image links are handled when using `:ObsidianFollowLink`, with examples for macOS quick look preview.

```lua
-- Optional, by default when you use `:ObsidianFollowLink` on a link to an image
-- file it will be ignored but you can customize this behavior here.
---@param img string
follow_img_func = function(img)
  vim.fn.jobstart { "qlmanage", "-p", img }  -- Mac OS quick look preview
  -- vim.fn.jobstart({"xdg-open", url})  -- linux
  -- vim.cmd(':silent exec "!start ' .. url .. '"') -- Windows
end
```

--------------------------------

### Configure Picker Settings

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Configure picker settings, including the preferred picker name and key mappings for notes and tags.

```lua
picker = {
  -- Set your preferred picker. Can be one of 'telescope.nvim', 'fzf-lua', or 'mini.pick'.
  name = "telescope.nvim",
  -- Optional, configure key mappings for the picker. These are the defaults.
  -- Not all pickers support all mappings.
  note_mappings = {
    -- Create a new note from your query.
    new = "<C-x>",
    -- Insert a link to the selected note.
    insert_link = "<C-l>",
  },
  tag_mappings = {
    -- Add tag(s) to current note.
    tag_note = "<C-x>",
    -- Insert a tag at the current location.
    insert_tag = "<C-l>",
  },
},
```

--------------------------------

### Configure Note Picker

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Specify the preferred note picker plugin and configure key mappings for note-related actions like creating new notes or inserting links.

```lua
picker = {
  name = "telescope.nvim",
  note_mappings = {
    new = "<C-x>",
    insert_link = "<C-l>",
  },
  tag_mappings = {
    tag_note = "<C-x>",
    insert_tag = "<C-l>",
  },
}
```

--------------------------------

### Configure Daily Notes Folder

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Specify a folder for daily notes and customize their date format, alias format, default tags, and template.

```lua
daily_notes = {
  -- Optional, if you keep daily notes in a separate directory.
  folder = "notes/dailies",
  -- Optional, if you want to change the date format for the ID of daily notes.
  date_format = "%Y-%m-%d",
  -- Optional, if you want to change the date format of the default alias of daily notes.
  alias_format = "%B %-d, %Y",
  -- Optional, default tags to add to each new daily note created.
  default_tags = { "daily-notes" },
  -- Optional, if you want to automatically insert a template from your template directory like 'daily.md'
  template = nil
}
```

--------------------------------

### Get Workspace for Directory

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Resolves the configured workspace for a given directory. Useful for internal logic like automatic workspace switching based on the current buffer's location.

```lua
local Workspace = require("obsidian").Workspace
local client    = require("obsidian").get_client()

local ws = Workspace.get_workspace_for_dir(
  vim.fn.expand("~/vaults/work/projects"),
  client.opts.workspaces
)
if ws then
  print("Belongs to workspace:", ws.name)
end
```

--------------------------------

### client:open_note(note_or_path, opts)

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Opens a note or a given path in a Neovim buffer. Supports specifying an open strategy and jumping to a specific line and column.

```APIDOC
## `client:open_note(note_or_path, opts)`

### Description
Opens a note (or arbitrary path) in a Neovim buffer using the configured `open_notes_in` strategy, or the strategy passed in `opts.open_strategy`. Optionally jumps to a specific line and column after opening.

### Parameters
#### Path Parameters
- `note_or_path` (obsidian.Note | string) - Required - The note object or path to open.
#### Options (`opts`)
- `line` (number) - Optional - The line number to jump to.
- `column` (number) - Optional - The column number to jump to.
- `open_strategy` (string) - Optional - The strategy to use for opening the note (e.g., "current", "vsplit", "hsplit"). Defaults to the configured `open_notes_in` strategy.

### Request Example
```lua
local client = require("obsidian").get_client()
local notes  = client:find_notes("alpha kickoff")
if #notes > 0 then
  client:open_note(notes[1], {
    line          = 10,
    open_strategy = "hsplit",    -- "current" | "vsplit" | "hsplit"
  })
end
```
```

--------------------------------

### Configure Note Opening Behavior

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Define how notes are opened using the `open_notes_in` option, choosing between 'current', 'vsplit', or 'hsplit'.

```lua
open_notes_in = "current",
```

--------------------------------

### Note.from_file

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Initializes an Obsidian note from a given file path. Supports optional loading options.

```APIDOC
## Note.from_file

### Description
Initializes a note from a file.

### Method
`Note.from_file({path}, {opts})`

### Parameters
#### Path Parameters
- **path** (string|obsidian.Path) - Required - The path to the file.
- **opts** (obsidian.note.LoadOpts|?) - Optional - Loading options.

### Return
- **obsidian.Note** - The initialized note object.
```

--------------------------------

### Configure Obsidian.nvim Completion Settings

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Enable or disable wiki link, local markdown link, and tag completion using nvim-cmp. Set the minimum characters required to trigger completion.

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

--------------------------------

### Format Link String

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Generates a formatted wiki or markdown link string for a given note. Supports `link_style`, `wiki_link_func`, `markdown_link_func`, and anchor/block suffixes. Use `resolve_anchor_link` to get an anchor for a header.

```lua
local client = require("obsidian").get_client()
local notes  = client:find_notes("alpha kickoff")
local note   = notes[1]

-- Default (wiki) link
print(client:format_link(note))
-- => [[1721040000-project-alpha-kickoff|Project Alpha Kickoff]]

-- Markdown link
print(client:format_link(note, { link_style = "markdown" }))
-- => [Project Alpha Kickoff](projects/1721040000-project-alpha-kickoff.md)

-- Link to a specific header anchor
local anchor = note:resolve_anchor_link("#Goals")
print(client:format_link(note, { anchor = anchor }))
-- => [[1721040000-project-alpha-kickoff#Goals|Project Alpha Kickoff]]
```

--------------------------------

### Customize Note ID Generation in Obsidian.nvim

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Define a custom function to generate unique note IDs. This example creates Zettelkasten-style IDs with a timestamp and a title-based suffix, or random characters if no title is provided.

```lua
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
```

--------------------------------

### Configure Attachment Settings

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Set up how images and other attachments are handled. Specify the default folder for pasted images and customize naming functions.

```lua
attachments = {
        -- The default folder to place images in via ":ObsidianPasteImg`.
        -- If this is a relative path it will be interpreted as relative to the vault root.
        -- You can always override this per image by passing a full path to the command instead of just a filename.
        img_folder = "assets/imgs",  -- This is the default

        -- Optional, customize the default name or prefix when pasting images via ":ObsidianPasteImg`.
        ---@return string
        img_name_func = function()
          -- Prefix image names with timestamp.
          return string.format("%s-", os.time())
        end,

        -- A function that determines the text to insert in the note when pasting an image.
        -- It takes two arguments, the `obsidian.Client` and an `obsidian.Path` to the image file.
        -- This is the default implementation.
        ---@param client obsidian.Client
        ---@param path obsidian.Path the absolute path to the image file
        ---@return string
        img_text_func = function(client, path)
          path = client:vault_relative_path(path) or path
          return string.format("!%s](%s)", path.name, path)
        end,
      }
```

--------------------------------

### Switch Workspace

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Switches the active workspace at runtime by name or `Workspace` object. Reinitializes the vault, reloads config, and re-runs UI setup. `set_workspace` can optionally lock the workspace to prevent automatic switching.

```lua
local client    = require("obsidian").get_client()
local Workspace = require("obsidian").Workspace

-- Switch by name (must be listed in `workspaces` config)
client:switch_workspace("work")

-- Switch to an ad-hoc workspace
local tmp_ws = Workspace.new("~/notes/tmp", { name = "tmp" })
client:set_workspace(tmp_ws, { lock = true })
```

--------------------------------

### Configure Template Settings

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Configure template settings, including the folder, date format, time format, and custom variable substitutions.

```lua
-- Optional, for templates (see below).
templates = {
  folder = "templates",
  date_format = "%Y-%m-%d",
  time_format = "%H:%M",
  -- A map for custom variables, the key should be the variable and the value a function
  substitutions = {},
},
```

--------------------------------

### Path.mkdir

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Creates a new directory at the given path.

```APIDOC
## Path.mkdir

### Description
Create a new directory at the given path.

### Method
`Path.mkdir({self}, {opts})

### Parameters
- **opts** { `mode`: `(integer|?,)` `parents`: `boolean`|?, `exist_ok`: `boolean`|? }|? - Optional options for directory creation. `mode` specifies permissions, `parents` creates parent directories if they don't exist, and `exist_ok` prevents an error if the directory already exists.
```

--------------------------------

### Configure Completion Settings

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian.txt

Enable or disable completion for wiki links, local markdown links, and tags using nvim-cmp. Set the minimum characters required to trigger completion.

```lua
completion = {
  -- Set to false to disable completion.
  nvim_cmp = true,
  -- Trigger completion at 2 chars.
  min_chars = 2,
}
```

--------------------------------

### client:follow_link_async(link, opts)

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Follows a specified link or the link under the cursor. It handles various link types and provides options for creating new notes or selecting from multiple matches.

```APIDOC
## `client:follow_link_async(link, opts)`

### Description
Follows a link string (or the link under the cursor when `link` is `nil`). Handles wiki links, markdown links, external URLs, image paths, and empty locations (TOC entries). When a wiki link target does not exist it prompts the user to create a new note. When multiple matches are found it opens a picker.

### Parameters
#### Path Parameters
- `link` (string | nil) - Optional - The link to follow. If nil, the link under the cursor is used.
#### Options (`opts`)
- `open_strategy` (string) - Optional - The strategy to use for opening the link (e.g., "vsplit", "hsplit", "current").

### Request Example
```lua
local client = require("obsidian").get_client()

-- Follow the link currently under the cursor (typical keymap usage)
vim.keymap.set("n", "gf", function()
  client:follow_link_async(nil, { open_strategy = "vsplit" })
end, { buffer = true })

-- Follow a specific link programmatically
client:follow_link_async("[[Project Alpha Kickoff]]")
```
```

--------------------------------

### Load Obsidian Note from File

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Loads a note by parsing its YAML frontmatter and header from a file. The `from_file_async` variant requires a plenary async context. Options control line reading and link/block collection.

```lua
local Note = require("obsidian").Note

-- Synchronous load
local note = Note.from_file("~/vaults/personal/notes/alpha.md", {
  max_lines            = 200,
  collect_anchor_links = true,
  collect_blocks       = true,
})
print(note.id)            -- e.g. "1721040000-project-alpha-kickoff"
print(#note.aliases)      -- 2
print(note.has_frontmatter) -- true

-- Resolve a header anchor
local anchor = note:resolve_anchor_link("#Goals")
if anchor then
  print("Goals section at line", anchor.line)
end
```

--------------------------------

### Create and Write a New Note

Source: https://context7.com/epwalsh/obsidian.nvim/llms.txt

Use `create_note` to generate a new note object. By default, it writes the note to disk. You can specify a title, aliases, tags, a destination directory, and a template. Use `no_write = true` to create an in-memory note that can be written later.

```lua
local client = require("obsidian").get_client()

-- Create and write a note with tags and a template
local note = client:create_note {
  title    = "Project Alpha Kickoff",
  aliases  = { "alpha kickoff", "project-alpha" },
  tags     = { "project", "meeting" },
  dir      = "projects",          -- relative to vault root
  template = "meeting-notes.md",  -- name inside templates folder
}
-- note.id    => "1721040000-project-alpha-kickoff"
-- note.path  => obsidian.Path("~/vaults/personal/projects/1721040000-project-alpha-kickoff.md")

-- Create a note in-memory only (no file written)
local draft = client:create_note { title = "Draft Idea", no_write = true }
-- Manually write later:
client:write_note(draft)
```

--------------------------------

### Configure Basic Workspace

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Define a workspace corresponding to an Obsidian vault path. This is the most common configuration for users.

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

--------------------------------

### Configure Dynamic Workspace (Buffer Parent)

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/README.md

Set up a dynamic workspace where the path is determined by a Lua function, such as the parent directory of the current buffer. Useful for applying plugin functionality to markdown files outside fixed vaults.

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

--------------------------------

### Workspace.new

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Creates a new Workspace object, assuming the workspace directory already exists on the filesystem.

```APIDOC
## Workspace.new

### Description
Create a new 'Workspace' object. This assumes the workspace already exists on the filesystem.

### Parameters
#### Path Parameters
- **path** (string|obsidian.Path) - Workspace path.
- **opts** (obsidian.workspace.WorkspaceOpts|?) - Optional workspace options.

### Return
- **obsidian.Workspace** - The newly created Workspace object.
```

--------------------------------

### Client.create_note

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Creates a new note with specified options, including title, ID, directory, aliases, tags, and more.

```APIDOC
## Client.create_note

### Description
Create a new note with the following options.

### Parameters
- **opts** obsidian.CreateNoteOpts|? Options.

### Options
- `title`: A title to assign the note.
- `id`: An ID to assign the note. If not specified one will be generated.
- `dir`: An optional directory to place the note in. Relative paths will be interpreted
  relative to the workspace / vault root.
- `aliases`: Additional aliases to assign to the note.
- `tags`: Tags to assign to the note.
- `no_write`: If true, the note will not be written to disk.
- `template`: A template to use for the note.
```

--------------------------------

### Client.apply_async_raw

Source: https://github.com/epwalsh/obsidian.nvim/blob/main/doc/obsidian_api.txt

Similar to `apply_async`, but the callback function receives the note's path instead of a note instance.

```APIDOC
## Client.apply_async_raw

### Description
Like apply, but the callback takes a path instead of a note instance.

### Parameters
- **on_path** (fun(path: string))
- **opts** { on_done: (fun()|?,) timeout: integer|?, pattern: string|? }|?

### Options
- `on_done`: A function to call when all paths have been processed.
- `timeout`: An optional timeout.
- `pattern`: A Lua search pattern. Defaults to ".*%.md".
```