spelunk.nvim
A Neovim plugin for managing bookmarks as navigable stacks with a configurable UI and optional persistence.
What is spelunk.nvim?
spelunk.nvim is a Neovim plugin that reimagines bookmark management by organizing locations into related stacks, aligning with the layered nature of code navigation. It provides an intuitive, opinionated UI out of the box while remaining configurable for advanced users.
Neovim users who frequently navigate between related code locations and want a more structured bookmarking system than native marks. It's particularly useful for developers working on codebases with layered functionality or complex navigation patterns.
Developers choose spelunk.nvim for its stack-based bookmark organization that mirrors how code is naturally layered, combined with a ready-to-use experience including default keymaps and UI. Unlike API-centric alternatives, it provides immediate functionality while still offering deep customization through its internal API.
Overview
Create and manage bookmarks as stacks in Neovim with a friendly UI.
Use Cases
Best For
- Managing related code locations as navigable stacks instead of isolated bookmarks
- Neovim users who want persistent bookmarks scoped to specific directories or Git branches
- Developers who prefer opinionated plugins with complete default keymaps and UI out of the box
- Teams needing consistent bookmark management across projects with configurable persistence
- Advanced Neovim users who want deep customization through an internal API while having sensible defaults
- Users who want fuzzy search integration with Telescope, snacks.nvim, fzf-lua, or native vim.ui.select
Not Ideal For
- Users who need simple, isolated bookmarks without stack-based organization
- Teams requiring guaranteed API stability for deep integration or custom scripting
- Neovim setups on versions older than 0.11.0 or using unstable builds
- Developers who prefer lightweight plugins with zero UI or minimal dependencies
Pros & Cons
Pros
Groups bookmarks into related stacks, aligning with layered code navigation for intuitive management of complex locations, as highlighted in the design goals.
Provides full default keymaps and a toggleable UI out of the box, reducing setup time compared to API-centric plugins, per the philosophy section.
Offers opt-in per-directory bookmark persistence with optional Git branch restriction, allowing flexible state management for project-specific contexts.
Supports fuzzy search via multiple providers like Telescope and fzf-lua, plus statusline display with lualine.nvim, enhancing workflow compatibility.
Cons
The internal API is not guaranteed to be stable, as admitted in the README, which can break custom integrations or scripts in future updates.
Advanced features like enhanced fuzzy search or Treesitter context require optional dependencies, adding setup complexity and potential bloat.
Only works with Neovim stable versions 0.11.0 and above, excluding users on older releases or nightly builds, as specified in requirements.
Frequently Asked Questions
Related Projects
harpoonHarpoon is a Neovim plugin designed to solve the repetitive navigation problem in software development. It allows users to mark frequently accessed files and terminals within a project, providing quick keyboard-driven access to reduce context switching and boost productivity. ## Key Features - **Persistent File Marks** — Mark important files per-project with positions that auto-update as you edit. - **Quick Navigation Menu** — Toggle a menu to view, reorder, or jump to marked files instantly. - **Terminal Management** — Create, navigate between, and send commands to multiple persistent terminal sessions. - **Tmux Integration** — Seamlessly control tmux windows and panes directly from Neovim. - **Telescope Extension** — Browse and select marks using the popular Telescope fuzzy finder. - **Customizable Configuration** — Adjust settings like save behavior, excluded filetypes, and menu appearance. ## Philosophy Harpoon emphasizes minimal keystrokes and persistent, project-aware navigation, treating files and terminals as equally important resources in a developer's workflow.
marks.nvimA better user experience for viewing and interacting with Vim marks.
arrow.nvimBookmark your files, separated by project, and quickly navigate through them.
grapple.nvimNeovim plugin for tagging important files
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.