# Joplin Explorer

A unified sidebar plugin for [Joplin](https://joplinapp.org/) that displays notebooks and notes together in a single tree view — like a file explorer.

[中文说明](README-CN.md)

![Joplin Explorer sidebar](https://raw.githubusercontent.com/lim0513/joplin-explorer/HEAD/assets/1.png)

| Hover preview | Context menu | Settings |
| :---: | :---: | :---: |
| ![Hover preview](https://raw.githubusercontent.com/lim0513/joplin-explorer/HEAD/assets/2.png) | ![Context menu](https://raw.githubusercontent.com/lim0513/joplin-explorer/HEAD/assets/3.png) | ![Settings](https://raw.githubusercontent.com/lim0513/joplin-explorer/HEAD/assets/4.png) |

## Features

- **Unified Tree View** — Notebooks and notes displayed in one collapsible panel
- **Custom Icons** — Shows emoji icons set in notebook settings; customize folder and pinned section icons via settings (emoji / image URL / data URI / local file path)
- **Toggle Arrow Visibility** — Hide expand/collapse arrows for a cleaner look
- **Live Updates** — Notes refresh in-place when their title or todo state changes
- **Favorites (Pin)** — Pin notes and notebooks to a collapsible section at the top of the tree; drag items to the pinned section to pin, drag within to reorder; persists across restarts
- **Enhanced Search** — Search notes, notebooks, and tags simultaneously with keyword highlighting; results grouped in collapsible sections; local title substring matching for partial queries (e.g. "8121R" finds "KY8121R")
- **Sort** — Toggle between sorting by update time or title (ascending/descending)
- **Context Menus**
  - Notebooks: pin/unpin, new note, new to-do, new sub-notebook, rename, export, delete
  - Notes: pin/unpin, open, open in new window, copy Markdown link, duplicate, switch note/to-do type, toggle completed, rename, view properties, delete
- **Drag & Drop** — Move notes between notebooks, reorganize folder hierarchy; drag to empty area to create a new notebook; drag to pinned section to pin
- **Sync Button** — Trigger synchronization with status feedback (syncing → done)
- **Auto Expand** — Automatically expands to the currently selected note on startup
- **Collapse All** — One-click collapse all notebooks
- **Scroll Position** — Preserved when navigating between notes
- **i18n** — Supports English, Simplified Chinese, Traditional Chinese, Japanese, and Russian (follows Joplin's locale setting)

## Install

### From File

1. Download `joplin-explorer.jpl` from the [latest release](https://github.com/lim0513/joplin-explorer/releases/latest)
2. In Joplin, go to **Tools → Options → Plugins**
3. Click the gear icon and select **Install from file**
4. Choose the downloaded `.jpl` file
5. Restart Joplin

## Usage

After installation, the Explorer panel appears on the side of the editor. You can:

- **Click** a notebook to expand/collapse it
- **Click** a note to open it
- **Right-click** for context menu actions (including pin/unpin)
- **Drag** notes or notebooks to reorganize; drag to the bottom zone to create a new notebook; drag to the pinned section to pin
- Use the **toolbar** at the top for quick actions (new notebook/note/to-do, sort, collapse all)
- Use the **search bar** to search notes, notebooks, and tags
- Click **Sync** at the bottom to trigger synchronization

## Development

```bash
# Install dependencies
npm install

# Build
npm run dist

# Watch mode
npm run dev
```

The built plugin is output to the `publish/` directory. To test locally, set `plugins.devPluginPaths` in Joplin's settings to point to the `publish/` directory.

## Acknowledgements

Special thanks to [@CJeffyB](https://github.com/CJeffyB), whose steady stream of thoughtful bug reports and feature ideas shaped much of v1.5–v1.6 — and who generously bought the project a coffee on Ko-fi. ☕

Thanks also to [@bwat47](https://github.com/bwat47) for PR [#30](https://github.com/lim0513/joplin-explorer/pull/30) and several sharp-eyed reports.

## License

MIT