Hysidian

Couples a Hydrus Network library to an Obsidian vault: images live in Hydrus, your wiki lives in Obsidian, and this plugin joins them on the file hash.

Today it searches Hydrus and embeds images into notes, downloading each one into the vault so notes keep rendering when Hydrus is closed, offline, or off the tailnet. See ROADMAP.md for where it goes next: anchor pages per file, Hydrus notes mirrored into the vault, and tags in frontmatter.

What it does

• Search modal — tag search with autocomplete, a thumbnail grid, sort options and an images-only filter. Click to select, shift-click for a range, double-click to embed one immediately.
• Local caching — the selected file is written to your cache folder (hydrus/ by default) and the note gets a normal ![[image.jpg]] embed. A file already in the cache is never re-downloaded; a file you delete from the vault is fetched again on next use.
• Gallery blocks — a ```hysidian code block renders a live grid from a saved search, caching each image as it renders.
• Sidecar notes (optional) — a .md beside each image holding its hash, tags and source URLs.

Install

npm install
npm run build
npm run deploy -- /path/to/your/vault

Then enable Hysidian in Settings → Community plugins.

For development, npm run dev rebuilds main.js on change; re-run npm run deploy (or symlink the project into .obsidian/plugins/) to pick the build up.

Setup

1. In Hydrus: services → review services → client api, add an access key with search files and see file contents permissions, and make sure the API is running.
2. In Obsidian: Settings → Hysidian, paste the API URL and access key, then press Test. A tailnet or LAN address works as well as http://127.0.0.1:45869 — set allow non-local connections in Hydrus for anything but localhost.
3. Optionally press Load services from Hydrus to pick a file domain and tag domain.

Using it

Action	How
Search and embed	Ribbon icon, or the Search Hydrus and embed images command
Search	Type tags separated by commas, press Enter. Tab or ↑/↓ accepts a suggestion
Select	Click a thumbnail; shift-click extends; double-click embeds that one
Embed	The Embed button, or ⌘/Ctrl+Enter
Insert a gallery	The Insert Hydrus gallery block command

System predicates work as they do in Hydrus, e.g. system:archive, system:width > 1000, system:limit=50, and -tag to exclude.

Gallery blocks

```hysidian
tags: character:samus, system:archive
limit: 6
columns: 3
size: 220
```

Any line without a recognised key is treated as another predicate, so system:archive on its own line works too.

Cache behaviour

Cached files live in the folder named in settings and are named <title tag>-<hash prefix>.<ext> (or just the hash prefix, if you turn descriptive filenames off). The plugin keeps an index of hash → vault path in its own data.json; a cache entry counts only when the file is still in the vault, so nothing ever points at a missing image.

• Prune missing drops index entries whose files you deleted.
• Delete cached files moves every cached image to the vault trash and empties the index.

Development

npm test          # unit tests, plus a mock Hydrus server
npm run build     # typecheck and bundle

The live end-to-end tests run against a real client when you point them at one:

HYDRUS_API_URL=http://127.0.0.1:45869 HYDRUS_ACCESS_KEY=<key> npm test

The API client takes its transport as a parameter — Obsidian's requestUrl in the plugin (it bypasses CORS, which Hydrus does not set) and fetch in tests.

Licence

None. Personal project, all rights reserved — public so it can be read, not licensed for reuse.