Skip to content

FAQ

Philosophy

Can I create folders?

No. This is intentional. Classification is tags only (plus one level of tag groups).

A folder forces you to pick one place, which creates indecision. Tags let you apply everything that fits — when in doubt, apply them all.

Things that genuinely need a hierarchy (source code, a website's file tree) are better left to Git and other tools.

Not as in-text syntax. Melanite's links are references between item IDs managed in the database, created from the Inspector's link field.

In exchange, any file kinds can link to each other (image → PDF, etc.). → Linking Items

Can I edit with a live preview?

No. Split previews and WYSIWYG are deliberately not built. Editing is always plain text; the formatted view is the read-only overlay on Cmd+E.

By design. Full-text search covers note (.md) text only.

Full-text search of PDFs, images (OCR), and Office files was implemented once and withdrawn because extraction quality couldn't be trusted. A search that silently misses is worse than no search.

Find PDFs by file name, tags, and memos. The Inspector's memo field is covered by full-text search, so writing keywords there works well.

Also by design. Text files can be edited in the built-in editor and show a preview on the card, but their text is not indexed (they match by name only).

Save things you want text-searchable as .md.

Single-character searches don't match

The search box's full-text search covers terms of 3 or more characters (an index-format limitation). With 2 or fewer, only file names and memos are searched.

To find by file name, use Quick Open (Cmd+P / Ctrl+P) — it doesn't use the index and works from a single character.

Can I search for two words at once?

Yes. Separate them with spaces and only items matching all of them remain (order doesn't matter).

Typing meeting quote narrows to items containing both. Each word may match in a different place, so it also finds a note whose file name contains "meeting" and whose body contains "quote". The search box, Quick Open, and the link field all behave the same way → Finding Items

There is no phrase search that requires the words in that exact order.

Can't I search by tag?

Tags are not part of the search box's scope. Click tags in the Sidebar to filter; that combines with the search box as AND.

Files

Can I delete the original files after importing?

Yes. Files are copied into the library on import, so moving or deleting the originals has no effect.

Can I put files into the library folder directly?

Please don't. A file placed into files/ by hand is not registered in the database, so it never appears in the list or search. Always import through the app.

What happens to my files if Melanite goes away?

They come right out. Files are stored at <library>.melanite/files/<ULID>/<original name>, in their original format. Nothing is converted.

Does renaming change the actual file name?

Yes. The actual file follows for every kind (the extension never changes).

Libraries

How do I back up?

Just copy the .melanite folder. Close the app first.

Separately, Melanite automatically keeps snapshots of the database that holds your tags, links and memos in backups/ inside the library (once a day, 5 generations, by default). Since they live inside the library folder, losing the disk loses them too — they are not a substitute for copying the whole folder. → Libraries

I got "Couldn't open the database"

The database (melanite.db) is damaged. Your files are fine — they are still in files/ in their original format, so what's affected is metadata: tags, links, memos.

The recovery dialog that appears lets you pick a point to go back to, and reopens the library from that generation. The database being replaced is kept as melanite.db.replaced-<timestamp>, so you can try a different one. → Libraries

Can I keep it in Dropbox or iCloud?

Yes, but with care. Melanite assumes single-process access; opening the library from two machines at once can corrupt the database.

Only one machine at a time, and always close the app before switching. → Libraries

There's no .lock in my library folder

That's normal. .lock exists only while the app has the library open and is deleted on close. It is also a hidden dotfile, so it usually doesn't show in Finder / File Explorer.

What's always there: melanite.json (the library marker), melanite.db, and the files/ thumbs/ trash/ folders. → Libraries

It says "May be open on another machine"

A record of another machine opening the library is still in .lock. The app cannot tell whether that machine still has it open or whether a crash simply left the record behind, so it asks. Confirm it is closed on the other machine, then choose "Open anyway". → Libraries

It says "opened by another process"

Melanite is running twice on the same machine — use the other window. A .lock left behind by a crash is reclaimed automatically, so manual deletion is normally unnecessary.

Can I open multiple libraries at once?

No, one at a time. The intended usage is one big library (the design targets 100,000 items).

How do I move to another machine?

Copy the .melanite folder and open it. Note that settings are per-device — the theme and per-extension open rules don't travel.

Display & behavior

Thumbnails don't appear

Depends on the kind.

  • PDF / images / videos (macOS) — generated; they fill in shortly after import
  • Videos (Windows) — icon only
  • Office files and others — icon only

If the kind should have a thumbnail but doesn't, select the items and right-click → "Regenerate Thumbnails" (works on a multi-selection). → Regenerating thumbnails

The integrity check only generates thumbnails that are missing. Ones that failed before (password-protected PDFs and the like) are not retried automatically — use "Regenerate Thumbnails" for those.

To rebuild the whole library, thumbs/ is a disposable cache: delete the entire folder, then run the integrity check.

A video won't play

Quick Preview playback is limited to codecs the OS WebView supports. If it won't play, press Enter to open it in an external app (which is also the default action).

Does it work offline?

Yes. The only three things that need a network are the map background tiles, the map's place search (both OpenStreetMap), and importing from URLs. Offline, only the map background is missing; pins and the rest of the app are unaffected. Map areas you have already viewed are cached, so they still render offline. → Location and maps / Privacy

Is the "Updates" statistic the number of imports?

No. It counts items per month by file modification time. A batch import of old files distributes across their original modification months, not the import month. → Statistics