# Attachments Cache
[](https://opensource.org/licenses/gpl-3)
If you search help about the **Settings** you can check the [documentation](./docs/settings.md).
## Summary
This plugin for Obsidian, stores remote attachments (currently only images) locally inside the vault.
The note is **NOT** modified, this way even outside of the vault the attachments keep working with the remotes URL.
When the attachment is rendered in a note, the local version is used instead of the remote working as a local cache.
> The cached attachments can be deleted any time to free up disk space.
In detail, during the Obsidian render process, when an `img` is found:
1. The plugin checks if the image is cached/should be cached.
2. Download the image into a vault folder if is not cached.
3. Modify the `img` element to use the cached file inside the vault.
## Features
- [x] Exposed API for thrid-party integration.
- [x] Whitelist/blacklist vault vault paths to perform caching.
- [x] Whitelist/blacklist vault remote URLs to perform caching.
- [x] For listed Vault paths define where to store the attachments.
- [x] Allows override of rules on individual notes or remotes.
---
## Instalation
### From within Obsidian
> I'm working ⚒️ on making this posible.
From Obsidian v1.8+, you can activate this plugin within Obsidian by doing the following:
- Open Settings > Third-party plugin
- Make sure Safe mode is **off**
- Click Browse community plugins
- Search for "Attachments Cache"
- Click Install
- Once installed, enable the plugin
- Then select "Attachments Cache" settings
- Configure the vault paths and URL remotes that should be cached
### From source
You can activate this plugin, building from source by doing the following:
- Clone the repository
- Install the dependencies
- Run `pnpm build:dist`
- Copy the content of the repository `dist` folder to your vault, the path should look like `your-vault/.obsidian/plugins/attachments-cache`
- Open your vault in _Obsidian_ and activate the newly installed plugin
---
## Pricing
This plugin is provided to everyone for free, however if you would like to
say thanks or help support continued development, feel free to send a little
through the following method:
[
](https://www.buymeacoffee.com/luisbs)
## Notes
The plugin is not on active development, new features or changes are developed when there is an oportunity. But issues and bugs will have especial priority.
### Thrid-party Integration
An API `AttachmentsCache` is exposed globally for easy integration.
For usage inside a plugin the methods `isPluginEnabled` and `getAPI` are exposed from an npm package named `@luis.bs/obsidian-attachments-cache`
```sh
pnpm add @luis.bs/obsidian-attachments-cache
```
On other environments where the package can not be used as a dependency, the API is attach to the global `window` object. The next declare can be used for development:
```ts
declare namespace AttachmentsCache {
/** Test whether the attachments should be cached. */
function mayCache(notepath: string, remote: string): boolean
/** Test whether a remote file is already cached. */
function isCached(notepath: string, remote: string): Promise
/** Tries to map a remote url into a Vault resourcePath. */
function resource(notepath: string, remote: string): Promise
/** Tries to map a remote url into a Vault filePath. */
function resolve(notepath: string, remote: string): Promise
/** Tries to cache a file locally and returns a Vault resourcePath. */
function cache(notepath: string, remote: string): Promise
}
```
## Troubleshooting
### An image rendered by another plugin is not been cached?
Plugins use [Markdown post processing](https://docs.obsidian.md/Plugins/Editor/Markdown+post+processing) to change the rendered view of the note.
By default any image rendered by a plugin may be cached, dependening on the [Cache priority](./docs/settings.md#cache-priority).
But if the plugin uses _**async functions**_ the order defined by **Cache priority** is not enforced, in that situations this plugin runs before the thrid-party plugin has ended and the added images avoid been cached.
To prevent that situation on `'NORMAL'` priority 2 second is awaited before the cache is executed.
On `'HIGHER'` priority 10 seconds are awaited.