dotwee_obsidian-raindropio-plugin/README.md

# ![icon.svg](icon.svg) Raindrop.io Plugin for Obsidian

[![GitHub release (latest by date)](https://img.shields.io/github/v/release/dotWee/obsidian-raindropio-plugin?style=flat-square)](https://github.com/dotWee/obsidian-raindropio-plugin/releases)
[![GitHub License](https://img.shields.io/github/license/dotWee/obsidian-raindropio-plugin?style=flat-square)](LICENSE)
![Obsidian Downloads](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fobsidianmd%2Fobsidian-releases%2Fmaster%2Fcommunity-plugin-stats.json&query=%24%5B%22raindrop-io%22%5D.downloads&logo=obsidian&label=downloads&color=673ab7&link=https%3A%2F%2Fcommunity.obsidian.md%2Fplugins%2Fraindrop-io)
[![Build & Test](https://github.com/dotWee/obsidian-raindropio-plugin/actions/workflows/lint.yml/badge.svg)](https://github.com/dotWee/obsidian-raindropio-plugin/actions/workflows/lint.yml)
[![Code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://prettier.io)
[![Linting: ESLint](https://img.shields.io/badge/linting-eslint-4B3B6B.svg?style=flat-square)](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.

![Screenshot](./.github/assets/Screenshot.png)

## 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).