Sidebar Keyboard Navigation

Obsidian Sidebar Keyboard Navigation

Obsidian plugin to enable keyboard based workflow(Vim-like) in the native File Explorer.

For Vim users, Obsidian currently supports using Vim-mode in the Editor (enabled in Settings), but not in other tool windows, like File Explorer. The goal of this plugin is to fill this gap for users who rely on a keyboard-based workflow.

Features

• Use keyboard to perform common actions in the File Explorer
• Option to disable certain keys, if they interfere with your workflow (or other plugins)
• Minimal invasion to the native app behavior (and your note-taking workflow)
• Changes(improvements) to the native app features
  • Avoid duplicating opened files: if trying to open an already opened file - focus it, instead of opening a duplicate tab (enabled/disabled in Settings).
  • Background opening: for most file-opening actions, there is an alternative action to allow you to open files "in background", while keep the focus on the File Explorer.
  • Deselect all items: new action.
  • After deleting a node in the File Explorer, automatically focus next/prev node, instead of loosing focus.

Showcase

Installation

Install Latest Git Version via BRAT

Refer to the BRAT documentation for detailed instructions.

Manual Installation

1. Download assets (main.js, manifest.json, styles.css) from the releases page
2. Create plugin folder in VAULT_DIR/.obsidian/plugins/sidebar-keyboard-navigation
3. Put downloaded assets into the plugin folder

Usage

1. (Optional) Consider reviewing/setting the following key bindings provided by Obsidian, so you can use the File Explorer more efficiently:
   • Files: Show file explorer: focus the File Explorer (e.g. Alt+P)
   • Toggle left sidebar: toggle the File Explorer (e.g. Alt+Shift+P)
   • Files: Reveal current file in navigation: (e.g. Alt+F1, similar to one in Intellij IDEA)
   • Focus on tab group to the right/lef/below/above: to switch between opened splits (e.g. Ctrl- L/H/J/K). You can also use Esc to switch from the File Explorer to the most recent Split.
2. (Optional) Open and review plugin settings.
3. Focus the File Explorer using Files: Show file explorer or File: Reveal current file in navigation command ( shortcut or from the Command Palette).
4. Use supported key bindings to navigate and interact with nodes.
   • For new users it's suggested to start with the most basic commands - j/k/h/k/n/f, and introduce more advanced actions gradually.

If, after some operation (e.g. after deleting a note via default mapping - Ctrl-Shift-D), you see that no nodes focused(focus lost) - just press j or k to get focus back.

Search Toolbar

When you open the Search toolbar, the keyboard focus initially placed on the input element. After you entered the search term, you can unfocus the search input by pressing Tab, and then start navigating by moving focus to the first entry (j).

After you open a file from the search results (by pressing l or Enter), you can quickly move focus back to the same position in the search results by pressing Shift + Tab. It's the native app's behavior and will work only if you have a single editor opened (no splits).

Available Actions

[!NOTE]

• All key bindings currently limited to use only a single key press, and Ctrl/Alt modifiers are not used, as these > are likely to interfere with the native key bindings.
• Node - an entry in a sidebar toolbar (file or folder for File Explorer)
• Focused node - a node with the cursor(focus) positioned on it
• Selected node - a node selected via selection
• Background-opening - opening a file without switching focus to the Editor
• Mappings for some destructive actions (e.g. delete note/folder) are disabled by default in Settings, so you don't accidentally damage your precious stuff while exploring the plugin for the first time.

How It Works

When one of supported leafs (tool windows) (e.g. File Explorer) is focused, the plugin is starting listening for keydown events to invoke appropriate actions. To implement actions logic, where possible, the plugin tries to use the most abstract native(obsidian/browser) functions (e.g. onKeyArrowDown, setFocusedItem) to minimize any conflicts/bugs. For some actions, it's necessary to mimic the logic from internal functions and apply some changes.

APIs used by the plugin:

• DOM: mostly for reading the state (except for rendering the help modal, and highlighting focused tab)
• Event: dispatching events to mimic native app behavior
• Obsidian: using internal (non-sensitive) functions like getMostRecentLeaf, crate leaf, tree.setFocusedItem

No runtime dependencies.

Not Implemented (Yet) Features and Their Drawbacks

• Configurable key mappings
  • Adds substantial complexity to the codebase
  • Requires handling of different keyboard layouts (should map key codes with key symbols for UI)
  • Adding new keys requires more careful consideration
• File Explorer
  • Copy/Cut/Paste: pretty hard to mimic the native Clipboard event (perhaps due to the security model of Electron/Browser JS). And another solution - overwriting the native functions(handleCut/handleCopy/handlePaste) seems to not be so safe for edit-actions.
  • scrolloff/zz/zt/zb: there is no ready-to-use internal structure to list currently visible entries in the FileExplorer, so a potential implementation will require a complex path traversal logic
• Other tool windows
  • Planned to add support for other (sidebar) tool windows - bookmarks, outline.

Known Bugs and Current Limitations

• This plugin is indented to be used with the core File Explorer plugin. So it might break the functionality of your other plugins if they change the behaviour of the File Explorer.
• While current keyboard shortcuts have been thoroughly designed and made to be future-proof, they are subject to change (though unlikely).
• Key mappings (in the docs and in-app) reflect characters produced by en_US QWERTY keyboard layout
• Background-opening
  • The position of a new tab/split will depend on to the most recently focused split(or tab group)
  • If you background-open a file, and then switch focus to it - the focus is not set properly. Steps to reproduce:
    • Empty Editor (no opened tabs)
    • Focus File Explorer and background-open a file using T
    • Focus Editor using Escape
    • Now, some native key bindings (e.g. scroll via ArrowDown/ArrowUp/Page Down/Page Up) will not work until you click on Editor, or enter the source mode
  • This feature may introduce unnecessary complexity to your workflow, if you try to build a workspace layout with 3+ splits using these actions. So consider using it sparingly.

Contributing

I prefer to host my open-source projects on Codeberg, but in order to publish the plugin to the community store it has to be hosted on GitHub.

If you prefer to contribute on Codeberg – you can find the mirror repository here.

Issues

If you are sure that you have found a bug - please open an issue. For any clarifications regarding plugin's functionality, please ask questions on the forum.

Feedback

Please leave any feedback in the plugin's topic on the Obsidian official forum.

Similar Projects

• NERDTree - A tree explorer plugin for Vim.
• Neo-tree - Neovim plugin to manage the file system and other tree. like structures.

License

MIT