mirror of
https://github.com/dotwee/obsidian-raindropio-plugin.git
synced 2026-07-22 06:50:29 +00:00
173 lines
7.4 KiB
Markdown
173 lines
7.4 KiB
Markdown
#  Raindrop.io Plugin for Obsidian
|
|
|
|
[](https://github.com/dotWee/obsidian-raindropio-plugin/releases)
|
|
[](LICENSE)
|
|
|
|
[](https://github.com/dotWee/obsidian-raindropio-plugin/actions/workflows/lint.yml)
|
|
[](https://prettier.io)
|
|
[](https://eslint.org)
|
|
|
|
Browse Raindrop.io links in notes with note-aware and configurable search filters.
|
|
|
|
The plugin uses a Raindrop.io access token and the official Raindrop.io REST API. OAuth is planned for a later release.
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- **Raindrop.io explorer**: Browse saved bookmarks from the configured collection in a side pane.
|
|
- **Note-aware filtering**: Let the explorer follow the active note by turning note tags and external links into a Raindrop.io search term.
|
|
- **Manual search**: Search Raindrop.io directly with keywords, `#tag` filters, exact phrases, or operators such as `type:article`, `notag:true`, and `created:2024-01`.
|
|
- **Note blocks**: Render saved Raindrop.io links inline from fenced `raindrop` code blocks.
|
|
- **Configurable tag clicks**: Choose whether tags on rendered Raindrop.io items search Obsidian notes, filter the explorer, or do nothing.
|
|
- **Native Obsidian UI**: Uses Obsidian commands, a ribbon icon, theme-friendly styling, and no hidden telemetry.
|
|
|
|
## Setup
|
|
|
|
1. Create or copy a Raindrop.io access token.
|
|
2. Open **Settings → Community plugins**, then select **Raindrop.io**.
|
|
3. Paste the token into **Access token**.
|
|
4. Use **Open explorer** from the command palette or ribbon icon.
|
|
5. Optionally add a `raindrop` block to a note for inline results.
|
|
|
|
The access token is stored in Obsidian plugin data and sent only to the Raindrop.io REST API.
|
|
|
|
## Explorer
|
|
|
|
The side pane opens as **Raindrop.io explorer**. It can browse all saved links from the configured collection, run manual searches, and load more paginated results.
|
|
|
|
Controls:
|
|
|
|
- **Search**: Runs the query in the search field against Raindrop.io.
|
|
- **Use note filter**: Rebuilds the search term from the active note.
|
|
- **Browse all**: Clears the query and shows the configured collection.
|
|
- **Refresh**: Reloads the current explorer state.
|
|
- **Load more**: Requests the next page of results when more are available.
|
|
|
|
When the explorer follows a note, it uses:
|
|
|
|
- Obsidian tags from the active note as Raindrop.io tag filters, for example `#project`.
|
|
- External `http` and `https` links as exact phrase searches.
|
|
- `match:OR` when multiple note-derived filters are present, so a bookmark can match any note tag or link.
|
|
|
|
Opening and interacting with the explorer preserves the last active note as context, so the note filter remains stable while you browse.
|
|
|
|
## Note blocks
|
|
|
|
Add a fenced code block to any note:
|
|
|
|
````markdown
|
|
```raindrop
|
|
collection: 0
|
|
tag: project-x
|
|
search: important
|
|
sort: -created
|
|
limit: 20
|
|
```
|
|
````
|
|
|
|
Options:
|
|
|
|
- `collection`: Raindrop.io collection ID. Use `0` for all collections. Defaults to **Default collection**.
|
|
- `tag`: Raindrop.io tag to include in the search. Multi-word tags are quoted automatically, for example `#"coffee beans"`.
|
|
- `search`: Raindrop.io search term. This is passed through to Raindrop.io.
|
|
- `sort`: Raindrop.io sort value, for example `-created`. Defaults to **Default sort**.
|
|
- `limit`: Number of links to request, clamped between 1 and 100. Defaults to **Default limit**.
|
|
- `show`: Comma-separated fields to show in addition to the **Result display** settings.
|
|
- `hide`: Comma-separated fields to hide, applied after `show`.
|
|
|
|
Valid field names for `show` and `hide`: `cover`, `domain`, `created`, `excerpt`, `tags`, `collection`. Unknown names produce a warning above the results. For example:
|
|
|
|
````markdown
|
|
```raindrop
|
|
tag: obsidian
|
|
hide: excerpt, tags
|
|
show: collection
|
|
```
|
|
````
|
|
|
|
You can combine `tag` and `search`; the plugin joins them into one Raindrop.io search term.
|
|
|
|
## Settings
|
|
|
|
- **Access token**: Token used for Raindrop.io API requests.
|
|
- **Default collection**: Collection ID used by the explorer and note blocks unless a block overrides it. Use `0` for all collections.
|
|
- **Default limit**: Number of links requested per page or block render. Values are clamped between 1 and 100.
|
|
- **Default sort**: Sort value passed to Raindrop.io, such as `-created`.
|
|
- **Tag click behavior**: Controls clicks on tags shown on Raindrop.io items.
|
|
|
|
Result display toggles control which fields each result shows. They apply to the explorer and act as the default for note blocks:
|
|
|
|
- **Show cover**: Bookmark cover image. Off by default.
|
|
- **Show domain**: Bookmark domain, for example `obsidian.md`.
|
|
- **Show created date**: Date the bookmark was saved.
|
|
- **Show excerpt**: Bookmark description.
|
|
- **Show tags**: Bookmark tags.
|
|
- **Show collection**: Collection the bookmark belongs to. Off by default; when enabled, the plugin lazily fetches the collection list from Raindrop.io once and caches it.
|
|
|
|
Tag click behavior options:
|
|
|
|
- **Search notes for the tag**: Opens Obsidian search for the clicked tag.
|
|
- **Filter explorer by the tag**: Opens the explorer and applies the clicked tag as a Raindrop.io filter.
|
|
- **Do nothing**: Leaves tag clicks inactive.
|
|
|
|
## Commands
|
|
|
|
- **Open explorer**: Opens the Raindrop.io explorer side pane.
|
|
- **Refresh explorer**: Reloads open explorer panes.
|
|
|
|
## Search syntax
|
|
|
|
The plugin passes search text through to Raindrop.io. Useful examples:
|
|
|
|
- `#project-x`: Bookmarks tagged `project-x`.
|
|
- `#"coffee beans"`: Bookmarks with a multi-word tag.
|
|
- `"exact phrase"`: Exact phrase match.
|
|
- `type:article`: Article bookmarks.
|
|
- `notag:true`: Bookmarks without tags.
|
|
- `created:2024-01`: Bookmarks created in January 2024.
|
|
- `#work #research match:OR`: Bookmarks matching either tag.
|
|
|
|
## Privacy and network access
|
|
|
|
- The plugin only makes network requests to `https://api.raindrop.io`.
|
|
- The access token is stored locally in Obsidian plugin data.
|
|
- Note-aware filtering sends the generated Raindrop.io search term to Raindrop.io. If the active note contains external links, those URLs can be included in the search term.
|
|
- The plugin does not collect analytics or use hidden telemetry.
|
|
|
|
## Release files
|
|
|
|
Obsidian release assets are built at the repository root:
|
|
|
|
- `main.js`
|
|
- `manifest.json`
|
|
- `styles.css`
|
|
|
|
Do not commit generated `main.js`; attach it to GitHub releases together with `manifest.json` and `styles.css`.
|
|
|
|
## Development
|
|
|
|
Install dependencies and build the plugin:
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
For watch mode:
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Quality checks:
|
|
|
|
```bash
|
|
npm run lint
|
|
```
|
|
|
|
## License
|
|
|
|
Copyright (C) 2026 Lukas '@dotWee' Wolfsteiner <lukas@wolfsteiner.media>
|
|
|
|
Licensed under the _Do What The Fuck You Want To_ public license (see [LICENSE](./LICENSE) file).
|