Usage#

Profiles#

Harang Immich can talk to more than one Immich server through profiles. Each profile bundles a server address, an API key, and a default album, and gets its own name so you can tell them apart (e.g. “Home server”, “Work server”).

Open Settings → Harang Immich to manage profiles:

Active profile

The profile this device currently uses to browse and upload images. This choice is stored locally on the device (not in the vault), so desktop and mobile can each use a different profile — or the same one — without fighting over a shared setting when the vault syncs.

Profiles

One section per profile, each with:

Profile name: A label of your choosing, shown in the active-profile picker and the insert-image gallery. It’s also embedded in every image link you insert from this profile (see “The link syntax” below) — renaming a profile breaks images already inserted under its old name, so treat the name as semi-permanent once you’ve started using it.
Immich server URL: The base URL of that profile’s Immich server, e.g. https://immich.example.com.
Immich API key: The API key generated in that Immich account (see Prerequisites). It is stored using Obsidian’s SecretStorage, not as plain text in the vault, and each profile has its own key.
Immich album selection / Create a new album: Same as before, scoped to this profile’s server.

A trash-can button next to each profile’s heading deletes it. Deleting a profile does not touch anything on the Immich server itself — it only removes the local connection details. Images already inserted from that profile keep pointing at it (see below); once the profile is gone, they show a “profile not found” error instead of the image.

Add profile

Adds a new, empty profile to configure.

Cache management

Thumbnails fetched from any profile’s server are cached locally (inside the plugin’s own .cache folder in the vault) so repeated views don’t re-download them. This section shows current cache usage and lets you clear it with Clear cache.

If you’re upgrading from a version of the plugin that only supported a single server, your existing connection is migrated automatically into one profile the first time the plugin loads on the new version, and any images you’d already inserted keep working without changes.

The four core features#

1. Insert an image from Immich#

In editing mode, run the command Insert Immich Image (via the command palette, or bind it to a hotkey). A gallery dialog opens showing thumbnails from your active profile’s default album (or all photos). If you have more than one profile configured, a Active profile dropdown at the top lets you switch profiles for this pick; an Album dropdown lets you switch to any other album on that profile’s server — neither changes your saved settings. Click a photo to insert it at the cursor using Harang Immich’s link syntax.

2. Editing-mode preview#

While editing (Live Preview), any Harang Immich link in the note is rendered inline as an image. Move your cursor onto the link’s text and it temporarily reveals the raw syntax so you can edit it; move away and it renders again.

3. Reading-mode preview#

In Reading view, Harang Immich links are rendered as images the same way, without needing to switch to editing mode first.

4. Paste or drag images to upload#

In editing mode, pasting an image from the clipboard or dragging one in from outside Obsidian uploads it to your active profile’s server automatically. A temporary “Uploading…” placeholder is inserted and replaced with the real link once the upload finishes. If the upload fails, the placeholder is removed and an error notice is shown. If an album is selected for that profile, uploaded images are added to that album automatically.

The link syntax#

Harang Immich images use a dedicated syntax rather than standard Markdown image links, so Obsidian’s default renderer leaves them untouched until the plugin replaces them with the actual image:

![immich:profile name/ASSET_ID]
![immich:profile name/ASSET_ID|alt text]

The profile name pins the link to the server it came from, so switching your active profile later never breaks images you already inserted — as long as the profile keeps its name. Renaming a profile breaks every image already inserted under its old name, since the link can no longer find a profile by that name (see Troubleshooting & FAQ for what that looks like). Links created before profiles existed (![immich:ASSET_ID], with no profile) still work — they resolve to the profile your old single-server setup was migrated into, as long as you haven’t renamed that one either.

You normally never type this by hand — it’s inserted for you by the gallery command or by pasting/dragging an image.

Keeping Immich in sync when you delete images#

Harang Immich keeps track of which Immich asset IDs each note references (along with which profile each one belongs to). When a link disappears from a note — because you deleted the link, edited the note, deleted the whole note, or renamed it — the plugin notices and asks what to do with the now-unreferenced Immich asset(s). If a note references assets from more than one profile, each asset is deleted from the server it actually belongs to:

Move to trash — soft-deletes the asset(s) in Immich.
Permanently delete — deletes the asset(s) immediately.
Cancel — leaves the asset(s) untouched in Immich.

Deleting or renaming a note is detected immediately; editing a note’s content is checked after you stop typing (a short debounce), so the prompt does not interrupt you mid-edit.

Usage

Contents