Obsidian Ranger

A Ranger-like file explorer for Obsidian with a three-column layout and vim keybindings.

Recent Changes

Navigation Improvements

• 'l' key behavior change: The l key now only navigates into folders and no longer opens files. This makes navigation more predictable and consistent with Ranger.
• Enter key: Press Enter (↵) to open files in the editor. Enter also works for navigating into folders.
• Arrow key support: Full arrow key support added:
  • ↑ = k (move up)
  • ↓ = j (move down)
  • ← = h (go to parent directory)
  • → = l (enter folder)
• Menu improvements: All action menus (marks, action pane, undo, sort) now show "SPACE to cancel" in their headers for clarity. SPACE can be used to close any overlay except fuzzy finder and filter modes (where it's needed for typing).
• Help overlay enhancement: The help popup (?) has been enlarged for better readability with more comprehensive keybinding documentation.

Features

• Three-column Miller columns layout - Parent directory, current directory, and preview pane
• Vim-style navigation - Navigate with h, j, k, l keys
• Fuzzy finder - Search across entire vault for files and folders with intelligent matching
• Directory marks/bookmarks - Save and jump to frequently used locations
• File filtering - Filter current directory or toggle file type visibility
• Markdown preview - Rendered markdown preview for files
• File operations - Copy, cut, paste, rename, and delete files/folders
• Multi-file selection - Select multiple files for batch operations
• Sorting options - Sort by name, date added, date modified, or size
• System trash integration - Deleted files go to system trash (recoverable)

Opening Ranger

Use the command palette (Ctrl/Cmd + P) and search for "Ranger: Open file explorer"

You can also assign a custom hotkey in Obsidian Settings > Hotkeys.

Keybindings

Navigation

Key	Action
j / ↓	Move down in file list
k / ↑	Move up in file list
h / ←	Go to parent directory
l / →	Enter directory (folders only)
Enter	Open file in editor / Enter directory
gg	Go to first item
G	Go to last item
gh	Go to vault root

Search & Filter

Key	Action
f	Filter current directory (type to filter, Enter/Esc to exit)
/	Open fuzzy finder (search entire vault for files and folders)

Fuzzy Finder Controls

Key	Action
Enter	Open selected file or navigate to selected folder
Esc	Close fuzzy finder
↓ / Ctrl+n / Ctrl+j	Move selection down
↑ / Ctrl+p / Ctrl+k	Move selection up

The fuzzy finder searches both files and folders in your vault. When you select:

• A file: It opens in the editor and closes the ranger modal
• A folder: It navigates to that folder in the ranger view (modal stays open)

Marks (Bookmarks)

Key	Action
m + [a-z]	Set mark at current directory (e.g., ma sets mark 'a')
' + [a-z]	Jump to mark (e.g., 'a jumps to mark 'a')
''	Jump to previous directory
Esc or Space	Close marks panel (when open)

When you press m or ', a marks panel appears at the bottom showing:

• All your saved marks with their paths
• Special '' mark showing the previous directory
• Marks panel size adjusts to the number of marks created

Marks are persisted across sessions using localStorage.

File Visibility

Key	Action
zh	Toggle file visibility filter

By default, only common file types are shown: .md, .png, .jpg, .jpeg, .pdf

Press zh to toggle showing all files in the vault.

File Selection

Key	Action
Space	Toggle selection on current file and move down
v	Select all files in current directory

Selected files are highlighted with an accent border. Use selection for batch copy, cut, or trash operations.

Copy, Cut & Paste

Key	Action
yy	Copy selected/current file(s) to clipboard
dd	Cut selected/current file(s) to clipboard (via action pane)
pp	Paste files from clipboard to current directory

• Copied files remain in clipboard after paste
• Cut files are removed from clipboard after paste (move operation)
• Cut files appear dimmed with strikethrough until pasted
• Status bar shows clipboard contents (e.g., "Cut: 3" or "Copied: 2")

File Operations (Action Pane)

Press d to open the action pane with available operations:

Key	Action
d	Open action pane
t	Move to system trash (~/.local/share/Trash/)
d	Cut file(s) to clipboard
m	Clear all marks (with confirmation)
Esc or Space	Close action pane

System Trash

Files moved to trash are placed in ~/.local/share/Trash/files/ with corresponding .trashinfo files in ~/.local/share/Trash/info/. This allows recovery using your system's trash manager.

Undo Operations

Press u to open the undo pane:

Key	Action
u	Open undo pane
v	Undo selection (clear all selected files)
d	Undo cut (clear clipboard if in cut mode)
Esc or Space	Close undo pane

Sorting

Press o to open the sort pane:

Key	Action
o	Open sort pane
a	Sort by time added (creation time, newest first)
c	Sort by time changed (modification time, newest first)
b	Sort alphabetically by name (default)
s	Sort by file size (largest first)
Esc or Space	Close sort pane

The current sort mode is displayed in the status bar. Folders are always sorted first, then files according to the selected sort mode.

Rename

Key	Action
F2	Rename current file or folder
Enter	Confirm rename
Esc	Cancel rename

The rename dialog pre-fills with the current name. For files, the name (without extension) is pre-selected for easy editing.

Command Console

Key	Action
:	Open command console (similar to Ranger/vim)

Available Commands

Command	Action
touch {filename}	Create a new file in current directory (adds .md if no extension)
mkdir {foldername}	Create a new folder in current directory

Close

Key	Action
?	Show keyboard shortcuts help overlay
q	Close Ranger
Esc	Close any open panel/overlay and return to main view, or clear selection
Space	Close overlays (help, marks, action/undo/sort panes) - does not work in fuzzy/filter modes

Space Key Behavior:

• In normal mode: Toggles selection on current file
• In overlay panes (help ?, marks m/', action d, undo u, sort o): Closes the overlay
• In fuzzy finder / and filter f: Space is used for typing (does not close)

Help

Key	Action
?	Toggle keyboard shortcuts help overlay

Press ? at any time to display a centered help overlay showing all available keyboard shortcuts organized by category. The overlay can be closed by pressing ?, Space, Esc, or q.

Interface

┌─────────────────────────────────────────────────────────────┐
│ Breadcrumb: / > folder > subfolder                          │
├─────────────────────────────────────────────────────────────┤
│ Parent Dir  │ Current Dir     │ Preview                     │
│             │                 │                             │
│ folder1     │ > file1.md      │ # File Content              │
│ folder2     │   file2.md      │                             │
│ [current]   │   subfolder/    │ This is the preview of      │
│ folder4     │   image.png     │ the selected file...        │
│             │                 │                             │
├─────────────────────────────────────────────────────────────┤
│ Status: 15 items | 3/15 | [2 selected] | Cut: 1 | Sort: name│
├─────────────────────────────────────────────────────────────┤
│ Marks/Sort/Undo Panel: (context-sensitive, shown when       │
│ m, ', o, u, or d is pressed)                                │
└─────────────────────────────────────────────────────────────┘

Columns

• Left column (25%) - Parent directory contents, highlights current folder. When at root, shows "Obsidian Vault" as the vault root indicator.
• Middle column (30%) - Current directory contents with selection
• Right column (45%) - Preview of selected item:
  • Files: Rendered content (markdown rendered, images displayed, text shown)
  • Folders: List of contents

Visual Indicators

• Selected item - Highlighted with accent color
• Multi-selected items - Left border accent indicator
• Cut files - Dimmed with strikethrough
• Folders - Show item count in parentheses
• Status bar - Shows item count, position, selection count, clipboard status, and sort mode

Quick Reference Card

Category	Keys	Action
Move	j/k or ↓/↑	Down/Up
Move	h/←	Parent
Move	l/→	Enter folder
Move	Enter	Open file/folder
Move	gg/G	First/Last
Search	/	Fuzzy find
Filter	f	Filter directory
Marks	m[a-z]	Set mark
Marks	'[a-z]	Jump to mark
Select	Space	Toggle selection
Select	v	Select all
Copy	yy	Copy to clipboard
Cut	d → d	Cut to clipboard
Paste	pp	Paste from clipboard
Trash	d → t	Move to system trash
Rename	F2	Rename file/folder
Sort	o[a/c/b/s]	Change sort order
Undo	u[v/d]	Undo selection/cut
Create	:touch	New file
Create	:mkdir	New folder
Help	?	Show shortcuts
Toggle	zh	Show/hide all files
Exit	q	Close Ranger
Close Panes	Space	Close overlays

Performance

• Fuzzy search - Debounced input (150ms) with pre-computed lowercase caching
• Large files - Files over 5MB show "File too large to preview" instead of loading
• Race conditions - Async rendering tracked to prevent stale previews

Installation

Manual Installation

1. Create folder: .obsidian/plugins/obsidian-ranger/
2. Copy main.js, manifest.json, and styles.css to the folder
3. Reload Obsidian
4. Enable "Ranger" in Settings > Community Plugins

Development

# Install dependencies
npm install

# Development mode (watch for changes)
npm run dev

# Production build
npm run build

Files

File	Description
main.ts	Plugin source code
main.js	Compiled plugin (generated)
manifest.json	Plugin metadata
styles.css	UI styling
package.json	NPM dependencies
tsconfig.json	TypeScript configuration
esbuild.config.mjs	Build configuration

License

MIT