# Alphabetical Neighbors — Obsidian Plugin Spec ## Problem New files are created in a single inbox folder and filed into subfolders after being fleshed out. When a similarly named file already exists elsewhere in the vault, there's no easy way to notice the overlap — the filed-away file is out of sight. ## Solution On hovering a file in the file explorer, show a tooltip displaying the vault-wide alphabetical neighbors: the file immediately before and immediately after, regardless of folder location. This gives instant context for whether a near-duplicate already exists. ## Core Behavior 1. **Build a sorted index** of all vault filenames (basename only, no path), updated on file create/rename/delete events. 2. **On hover** over a file in the file explorer sidebar, find the hovered file's position in the sorted index via binary search. 3. **Display a tooltip** showing the previous and next filenames alphabetically, with their parent folder as context. ### Example Hovering `Change management` in the inbox folder shows: ``` ← Challenges of tool adoption (Notes/PM/) → Change management (ITSM) (Notes/ITSM/) ``` ## Data Model ### Sorted File Index - **Source:** `app.vault.getFiles()` filtered to markdown files (or all files — configurable). - **Shape:** Array of `{ basename: string, path: string }` sorted case-insensitively by `basename`. - **Lookup:** Binary search for the hovered file's basename to find index position, then read `[i-1]` and `[i+1]`. ### Initialization and Updates - Build the full sorted array on plugin load. - Register event listeners to keep it current: - `vault.on('create')` — insert into sorted position. - `vault.on('rename')` — remove old entry, insert new. - `vault.on('delete')` — remove entry. - Insertions/removals into a sorted array are `O(n)` but the vault size (~8,000 files) makes this negligible. ## UI ### Tooltip - Attach `mouseenter`/`mouseleave` listeners to `.nav-file-title` elements in the file explorer. - On `mouseenter`, look up neighbors and show a tooltip near the hovered item. - Use Obsidian's native tooltip API if available (`setTooltip` or similar), otherwise create a lightweight custom tooltip element. - Tooltip appears after a short delay (~300ms) to avoid flickering on casual mouse movement. ### Tooltip Content Format ``` ← {prev_basename} ({prev_parent_folder}/) → {next_basename} ({next_parent_folder}/) ``` - If the hovered file is first alphabetically, omit the `←` line. - If the hovered file is last alphabetically, omit the `→` line. - Parent folder is the immediate parent only (e.g., `Notes/ITSM/` not full vault path) unless disambiguation is needed. ### Clickability (Optional Enhancement) - Clicking a neighbor name in the tooltip opens that file, for quick inspection. ## Settings |Setting|Default|Description| |---|---|---| |File types|Markdown only|Whether to index all files or just `.md`| |Show folder path|Immediate parent|`immediate parent`, `full path`, or `none`| |Hover delay (ms)|300|Delay before tooltip appears| |Case-sensitive sort|Off|Whether sorting is case-sensitive| ## Technical Notes ### DOM Interaction The file explorer is not well-supported by Obsidian's public API. This plugin will need to: - Use `MutationObserver` or re-register listeners when the file explorer re-renders (e.g., on folder collapse/expand, search, or vault changes). - Query `.nav-file-title` elements and read the file path from the associated data attribute or by resolving the text content against the vault. This is the same DOM-boundary approach used in Alias on Create — functional but potentially fragile across Obsidian updates. ### Edge Cases - **Duplicate basenames in different folders:** Multiple files can share a basename. The sorted index should include all of them. When displaying neighbors, all entries at the neighboring position should be shown if names collide. - **Empty vault / single file:** Handle gracefully — tooltip says "No neighbors" or simply doesn't appear. - **Non-markdown files:** Respect the file type setting; don't index what the user has excluded. - **File explorer panels:** If the user has multiple file explorer panes open, listeners should be attached to all of them. ## Future Enhancements These are out of scope for v1 but worth keeping in mind architecturally: - **Fuzzy / similarity matching:** Instead of strict alphabetical neighbors, show the N most similar filenames by edit distance. Would require swapping binary search for a different lookup strategy. - **Configurable neighbor count:** Show more than 1 neighbor in each direction. - **Integration with quick switcher:** Surface neighbor info in the quick switcher modal too. - **Highlight potential duplicates:** Flag neighbors with very high similarity (e.g., edit distance < 3) with a warning color.