Vault

The ssglib.vault module reads an Obsidian vault directory and provides access to vault files.

local vault = require "ssglib.vault"

Vault.new(dir, prefix)

Create a vault by scanning dir. The optional prefix sets the URL path prefix (default "/"); it must start and end with "/".

local v = vault.Vault.new("/path/to/vault")
local v = vault.Vault.new("/path/to/vault", "/blog/")

Fields

• dir -- Root directory path of the vault
• prefix -- URL path prefix (e.g., "/" or "/blog/")
• notes -- pandoc.List of vault-relative POSIX paths for all .md files

Vault:system_path(path)

Get the full filesystem path for a vault-relative POSIX path.

v:system_path("articles/Hello World.md")

Vault:resolve(target, source)

Resolve a link target to a vault-relative POSIX path. The .md extension is optional for notes. Returns nil if the target is not found in the vault.

v:resolve("Hello World", "articles/other.md")  -- "Hello World.md"
v:resolve("images/photo.jpg", "articles/other.md")

Vault:url(path)

Get the URL for a vault-relative POSIX path. If the file's front matter includes a permalink property, that value is used. Otherwise, the URL is derived from the path with spaces replaced by hyphens.

-- With permalink: "hello/"
v:url("articles/Hello World.md")  -- "/hello/"

-- Without permalink
v:url("articles/Hello World.md")  -- "/articles/Hello-World/"

Vault:doc(path)

Parse a note file and return a pandoc.Doc. Obsidian-style image wikilinks (![[image.png]]) are converted to standard Pandoc Image elements.

local doc = v:doc("articles/Hello World.md")

format_date(fmt, date)

Format an ISO 8601 date string using os.date format specifiers.

vault.format_date("%B %Y", "2025-03-15")  -- "March 2025"