CSS Resource Variables

Map a file already in your vault to a CSS custom property, so any theme or snippet whose CSS reads that variable name picks up your file automatically.

The problem this solves

Obsidian's theme and snippet CSS gets injected as raw text into the app, with no folder context of its own. A relative path like url("images/backdrop.jpg") can't resolve to a real file, and file:///app://local/ URLs are blocked by the app for security. The only way to get a real, loadable URL for a local file is Obsidian's own plugin API (getResourcePath()), which only a plugin can call. If a theme or snippet author wants to let you plug in your own local image, font, or other asset, this is that missing piece.

This plugin does one thing: pick a file, name a CSS variable, done. Every theme's own CSS decides what to do with that variable; this plugin has no opinion about styling.

How to use it

1. Open Settings -> CSS Resource Variables.
2. Click Add mapping, and pick a file from your vault.
3. Type a variable name (no leading --, that gets added automatically). Use whatever name the consuming theme or snippet's CSS already expects; check its own docs for the exact name it reads.
4. Any CSS anywhere in your vault that reads var(--your-name) now resolves to your file. This is re-resolved automatically every time Obsidian loads, and it follows the file if you rename or move it.

What you can do with it

Give a theme a custom background image, if that theme exposes a variable for it:

/* in the theme's own CSS */
.some-note-type .markdown-preview-view {
  background-image: var(--my-backdrop);
}

Map any image in your vault to my-backdrop, and that note type now shows your photo as its background, offline, no bundled default, no network call.

Use your own font in a theme or snippet, without base64-encoding it yourself:

@font-face {
  font-family: "My Custom Font";
  src: var(--my-font-file);
}

Map a .ttf/.otf/.woff2 file in your vault to my-font-file, and that @font-face rule picks it up.

Anything else that takes a url(...) value. The plugin always wraps the resolved path in url("...") for you, so any CSS property that accepts a URL works the same way.

Settings reference

Setting	What it does
Add mapping	Opens a file picker; after you choose a file, type its CSS variable name in the new field that appears
File icon (per mapping)	Change which file this mapping points to
Trash icon (per mapping)	Remove the mapping and clear its CSS variable immediately

Good to know

• Only the vault-relative file path is stored, never a resolved URL. Resolved URLs are session-specific in Obsidian and would break on the next launch if cached, so this plugin re-resolves on every load instead.
• No network calls, no telemetry. This plugin reads file paths and resolves them through Obsidian's own API, nothing else.
• Removing a mapping clears its CSS variable immediately, so a deleted mapping doesn't leave a stale value behind.
• Two mappings can't usefully share the same variable name; the plugin warns you if you pick one that's already in use, but doesn't block it, in case that's genuinely what you want.

Contributing

Issues and pull requests are welcome.

Support

If this plugin is useful to you, you can buy me a coffee.

License

MIT