YAML Breadcrumb for Nvim

3 months ago 2

A Neovim plugin that provides YAML breadcrumb navigation, showing the hierarchical path to your current position in YAML files.

🍞 Visual breadcrumb display - Shows the current YAML path as virtual text
📍 Auto-update on cursor movement - Breadcrumb updates as you navigate through the file
🔢 Array index tracking - Handles YAML arrays with proper indexing ([0], [1], etc.)
🎯 Line number integration - Optional display of line numbers in breadcrumb
⌨️ Customizable keymaps - Default keybindings with full customization support
🎨 Configurable appearance - Custom separators, highlight groups, and formatting
🔧 Statusline integration - Export breadcrumb to your statusline
🩺 Health check support - Built-in health check command

{ "vasuadari/yaml-breadcrumb.nvim", ft = { "yaml", "yml" }, config = function() require("yaml-breadcrumb").setup({ -- your configuration here }) end, }

use { "vasuadari/yaml-breadcrumb.nvim", ft = { "yaml", "yml" }, config = function() require("yaml-breadcrumb").setup() end }

Plug 'vasuadari/yaml-breadcrumb.nvim'

require("yaml-breadcrumb").setup({ enabled = true, -- Enable/disable the plugin show_on_cursor_move = true, -- Auto-update breadcrumb on cursor movement virtual_text = true, -- Show breadcrumb as virtual text separator = " -> ", -- Separator between breadcrumb items show_line_numbers = false, -- Show line numbers in breadcrumb highlight_group = "Comment", -- Highlight group for virtual text })

Option Type Default Description

enabled	boolean	true	Enable or disable the plugin
show_on_cursor_move	boolean	true	Automatically update breadcrumb when cursor moves
virtual_text	boolean	true	Display breadcrumb as virtual text at end of line
separator	string	" -> "	String used to separate breadcrumb components
show_line_numbers	boolean	false	Include line numbers in breadcrumb display
highlight_group	string	"Comment"	Neovim highlight group for virtual text styling

The plugin provides the following commands:

:YamlBreadcrumb - Show breadcrumb for current line in a notification
:YamlBreadcrumbToggle - Toggle the plugin on/off
:YamlBreadcrumbHealth - Run health check to verify plugin status

Key Mode Action

<leader>yb	Normal	Show YAML breadcrumb
<leader>yt	Normal	Toggle YAML breadcrumb

You can set up your own keymaps:

vim.keymap.set("n", "<your-key>", function() require("yaml-breadcrumb").show_breadcrumb() end, { desc = "Show YAML breadcrumb" }) vim.keymap.set("n", "<your-key>", function() require("yaml-breadcrumb").toggle() end, { desc = "Toggle YAML breadcrumb" })

For this YAML file:

apiVersion: v1 kind: ConfigMap metadata: name: my-config namespace: default data: config.yaml: | database: host: localhost port: 5432

When your cursor is on the port: 5432 line, the breadcrumb would show:

🍞 apiVersion > kind > metadata > data > config.yaml > database > port

For this YAML file:

users: - name: john email: [email protected] roles: - admin - user - name: jane email: [email protected]

When your cursor is on email: [email protected], the breadcrumb would show:

With Line Numbers Enabled

With show_line_numbers = true, the same breadcrumb would show:

🍞 users (L1) > [1] (L8) > email (L9)

You can integrate the breadcrumb into your statusline:

require('lualine').setup { sections = { lualine_c = { 'filename', function() return require('yaml-breadcrumb').get_current_breadcrumb() end } } }

vim.o.statusline = vim.o.statusline .. '%{luaeval("require(\'yaml-breadcrumb\').get_current_breadcrumb()")}'

Create custom highlight groups for better visual integration:

-- Define custom highlight vim.api.nvim_set_hl(0, "YamlBreadcrumb", { fg = "#61AFEF", bg = "NONE", italic = true }) -- Use in configuration require("yaml-breadcrumb").setup({ highlight_group = "YamlBreadcrumb", })

Enable only for specific file patterns:

require("yaml-breadcrumb").setup({ enabled = vim.fn.expand("%:t"):match(".*%.ya?ml$") ~= nil, })

Run the health check to diagnose issues:

Breadcrumb not showing: Ensure you're in a YAML file (.yaml or .yml extension)
Virtual text not appearing: Check that virtual_text = true in your configuration
Incorrect indentation detection: The plugin uses space-based indentation detection

Enable debug notifications to see what the plugin detects:

-- The plugin includes debug output in the show_breadcrumb() function -- Use :YamlBreadcrumb to see debug information