# Note Attachment Sorter

[한국어 설명](README.ko.md)

**Note Attachment Sorter** groups attachments immediately beneath the related Markdown note in Obsidian's File Explorer. It changes **display order only**: it does not rename, move, copy, or delete files.

> **Status:** Public beta · `0.2.0` · Desktop-only · Developed by **Poro**.
> The plugin currently patches an **undocumented File Explorer API**. Compatibility with future Obsidian releases is not guaranteed. Use a test vault and back up important vaults before trying it.

## What it looks like

Files actually stored together in one folder:

```text
Notes/
  Household budget.md
  @Household budget.png
  @Household budget-01.png
  Source data.pdf
  Another note.md
```

When `Household budget.md` links to `Source data.pdf`, the File Explorer shows:

```text
Household budget
  @Household budget.png
  @Household budget-01.png
  Source data.pdf
Another note
```

The indentation above is **illustrative**: the files remain siblings in the same folder, not physical children of the note.

## Features

- Group attachments using a configurable filename prefix (default `@`).
- Group files with unrelated names when a Markdown note links to them.
- Display numbered attachments in natural order (`-01`, `-02`, `-10`).
- Use English or Korean for the settings labels.
- Keep different folders independent, including identically named files in different folders.
- Leave unattached or ambiguously linked files ungrouped at the end of the current folder's files.
- Never rename, move, duplicate, or delete vault files.
- No YAML, `sortspec.md`, or Bookmarks required.

### Filename matching

The note `Household budget.md` matches `@Household budget.png` and `@Household budget-01.png` when the attachment prefix is `@`.

For automatic attachment renaming, you may separately install **Paste Image Rename** and use its filename pattern `@{{fileName}}`. This plugin itself does **not** rename files; Paste Image Rename is optional.

### Link matching

In `Household budget.md`:

```markdown
[[Source data.pdf]]
```

If `Source data.pdf` is in **the same folder**, the plugin can group it beneath the note even though the filename is different. Wiki links and embeds that Obsidian resolves are supported through its metadata cache.

## Installation

### Manual installation (before community directory listing)

1. Obtain `main.js` and `manifest.json` from a GitHub Release for the **same version**. If there is no release yet, see **Build from source** below.
2. In your test vault create `.obsidian/plugins/note-attachment-sorter/`.
3. Copy both files into that folder.
4. Restart Obsidian and enable **Note Attachment Sorter** under **Settings → Community plugins**.

### Build from source

Requirements: Node.js, npm, and a desktop Obsidian installation.

```bash
npm install
npm run build
```

Then copy the generated `main.js` along with `manifest.json` to `.obsidian/plugins/note-attachment-sorter/` in your vault. For development, use `npm run dev` (watch mode).

> You do not need Git installed to build: you may download the source ZIP and open its folder in VS Code.

## Settings

| Setting | Default | Purpose |
| --- | --- | --- |
| Display language | English | English or Korean interface |
| Enable automatic sorting | On | Toggle grouping in the File Explorer |
| Attachment prefix | `@` | Filename prefix used for matching |

The command palette includes **Refresh attachment sorting**.

## Important limitations

- **Desktop only.** Mobile is not yet supported or verified.
- **Non-public API:** The implementation wraps Obsidian's internal `getSortedFolderItems()` method and calls `requestSort()`. This may change without notice.
- **Same-folder scope:** An attachment referenced from another folder is **not** moved or grouped into the note's folder.
- **Shared files:** When multiple notes in the same folder link to the same attachment, the file remains ungrouped unless the explicit filename prefix identifies its owner. It is never displayed twice in the same folder.
- **Unsupported extensions:** Some file types, such as `.xlsx`, might not be indexed or shown by Obsidian without additional support. The sorter does not add support for file types.
- **Other sort plugins:** Disable other plugins that override File Explorer sorting while testing this plugin.
- **File name changes:** The plugin does not automatically rename source files. Link resolution depends on Obsidian's index being up to date.

## Development and releases

Source: `src/main.ts`. Build command: `npm run build`.

For version `0.2.0`, GitHub Release tag must be **`0.2.0`** (without `v`); upload **`main.js` and `manifest.json`** as separate release assets. See [Publishing guide](PUBLISHING.ko.md).

GitHub source availability is **not** the same as being approved for Obsidian's Community Plugin directory.

## Privacy

This plugin processes file paths and Obsidian metadata **locally**. Its source contains no telemetry, external requests, or account integration.

## License

MIT License · © 2026 Poro. Third-party dependency: [`monkey-around`](https://www.npmjs.com/package/monkey-around), ISC license.

## Contact

For questions, feedback, or bug reports, you can contact **Poro** at [captivemg@gmail.com](mailto:captivemg@gmail.com).

## Reporting issues

Please include the Obsidian version, OS, steps to reproduce, relevant filenames (redact private information), and the developer console error if available.