Paths

The ssglib.paths module provides file path conversion utilities and filesystem operations.

local paths = require "ssglib.paths"

posix_path(s)

Convert a system path to POSIX format by replacing the system separator with /. On POSIX systems, this is a no-op.

paths.posix_path("articles\\hello.md")  -- "articles/hello.md"

system_path(s)

Convert a POSIX path to the system-native separator format.

paths.system_path("articles/hello.md")  -- "articles\\hello.md" (on Windows)

stem(path)

Get the stem of a POSIX file path (filename without extension or directory).

paths.stem("articles/Hello World.md")  -- "Hello World"

is_local_path(url)

Check whether a URL is a local vault path. URLs with a scheme (http://, file://, etc.) or host prefix (//) are not local.

paths.is_local_path("Hello World")       -- true
paths.is_local_path("https://example.com")  -- false
paths.is_local_path("//cdn.example.com")    -- false

file_mtime(path)

Return the modification time of a file as an ISO 8601 string. Returns "" if the file does not exist.

paths.file_mtime("vault/index.md")  -- "2025-01-15T10:30:00Z"

walk_tree(root, fn, include_hidden)

Recursively walk a directory tree, calling fn(path) for each file. Files and directories starting with . are skipped unless include_hidden is true.

paths.walk_tree("vault", function(path)
  print(path)
end)

-- Include dotfiles:
paths.walk_tree("output", function(path)
  print(path)
end, true)

remove_empty_dirs(root)

Recursively remove empty directories under root (depth-first). Directories that become empty after their children are removed are also removed.

paths.remove_empty_dirs("output")