obsidian.nvim

When a recording is completed, the following lifecycle occurs:

1. The audio is written to a temporary .wav file (using WAV/PCM as CLI tools do not reliably encode .m4a without extra codecs).
2. The file is copied into your configured attachments folder using obsidian.attachment.add().
3. The file is named using the pattern: Recording YYYYMMDDHHMMSS.wav.
4. The temporary file is deleted by default after attachment.

obsidian.nvim logs both the temporary path and the final attachment path during this process.

When selecting a bookmark, the plugin handles different types of Obsidian bookmarks with specific behaviors:

• file: Opens the specific note and jumps to the stored block or heading subpath.
• folder: Opens the directory using vim.cmd.edit.
• url: Opens the link using vim.ui.open.
• search: Executes a search using picker.grep with the stored query string.
• group: Recursively enters the nested bookmark list.

Limitations:

• The graph type is not supported (as Obsidian does not bookmark graph views).
• The search type is currently partial; it passes the raw query string to grep and does not yet implement the full Obsidian search-term parser.

The cache stays synchronized through several mechanisms:

• Startup: The plugin checks the vault for supported Markdown files and updates entries if the file size or modification time (including nanoseconds) has changed.
• File Saves: LSP textDocument/didSave notifications refresh notes immediately upon saving.
• Plugin Actions: Moves, renames, and deletes initiated by the plugin update the cache directly.
• External Changes: File watch events cover changes made outside of Neovim.

Note: Persisted entries are not exposed to queries until the validation process finishes. The cache respects your existing file.ignore_filters settings.

obsidian.nvim can be understood through two different mental models depending on your workflow:

1. For Obsidian users: It is an implementation of Obsidian's core capabilities within Neovim using Neovim's API. This includes support for links, backlinks, tags, header links, and block links (excluding GUI-specific features like Graph View or Canvas).

2. For Neovim users: It acts as a Markdown LSP (Language Server Protocol) implementation. In this model, an Obsidian 'vault' is treated as a project (a directory of markdown files), providing features like completions, finding references, and hover documentation.

Resolvers are user-provided functions used to choose or acquire input before an action continues. Unlike callbacks, which observe lifecycle events and emit autocmds, resolvers are not hooks. They receive a context object and must call a done() callback with normalized data to proceed with the running action.

Resolvers can be synchronous or asynchronous. To handle the done callback:

• Success: Call done({ data }) with the normalized result.
• Cancel: Call done(nil) to cancel the action.
• Failure: Call done(nil, "error message") to fail with a specific message.

require("obsidian").setup {
  resolvers = {
    attachment = function(ctx, done)
      done { path = "/tmp/image.png" }
    end,

    date = function(ctx, done)
      done { timestamp = os.time(), precision = "day" }
    end,
  },
}

The plugin reads YAML frontmatter located between --- lines at the top of a note. It specifically validates and manages a small set of special keys used for plugin functionality, while leaving all other fields untouched as metadata.

Supported special keys:

• id: string or number
• aliases: string or list of strings
• tags: string or list of strings

Note: Invalid types for these keys are ignored and will trigger a warning.

To perform tasks like transcription or summarization after a recording is finished, hook into the attachment pipeline. You can use either the callbacks.add_attachment configuration option or the ObsidianAttachmentAdded user autocmd.

When using callbacks.add_attachment, check the ctx.scope to ensure you are only running logic on audio recordings.

A dynamic workspace is defined by providing a Lua function to the path field instead of a static string. The function must return a path string.

This is useful for:

1. Automatically setting the workspace root to the parent directory of the current buffer.
2. Using plugin functionality on markdown files located outside of your fixed Obsidian vaults.

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

To ensure compatibility between GitHub Wiki and Obsidian, follow these linking conventions:

• Files: Use media wiki links: [[file]].
• Anchors/Headings: Use standard markdown links: [heading](#anchor).

The cache stores derived metadata used to build :Obsidian quick_switch entries, including:

• note path
• aliases
• tags
• frontmatter properties
• outgoing links
• tasks
• file modification time and size

Because the cache is derived data, it can be safely deleted at any time; obsidian.nvim will rebuild it on the next startup or file change.