knot.nvim

Neovim plugin for the knot dotfiles manager.

Features

• Automatic filetype detection for files named exactly Knotfile
• 🪢 Devicon registration for nvim-web-devicons (shown in statuslines, file trees, tablines)
• YAML-based syntax highlighting with Knotfile-specific keyword groups:
  • packages — highlighted as a structure keyword
  • source, target, ignore, condition — highlighted as identifiers
  • os — highlighted as a special keyword
  • darwin, linux, windows, freebsd — highlighted as constants
• Buffer-local settings (tabstop=2, shiftwidth=2, commentstring=# %s)
• Optional yaml-language-server schema auto-configuration for inline validation and completions
• Treesitter YAML parser override for enhanced syntax and text-objects (Neovim 0.9+)

Requirements

• Neovim 0.10+
• Optional: nvim-lspconfig + yaml-language-server for schema validation and completions
• Optional: nvim-treesitter with yaml parser (Neovim 0.9+) for enhanced highlighting

Installation

lazy.nvim

{
  "oxGrad/knot.nvim",
  main = "knot",   -- tells lazy.nvim to call require("knot").setup(opts)
  lazy = false,    -- must load at startup so the devicon is registered before file trees render
  opts = {
    auto_configure_yamlls = true,
  },
},

Why lazy = false? The devicon must be registered before plugins like nvim-tree or neo-tree first render. With ft = "knotfile" the plugin would only load after you open a Knotfile, so the icon would show the default until then.

Why main = "knot"? Without it, lazy.nvim derives the module name from the repo name (knot.nvim) and calls require("knot.nvim").setup(opts), which fails.

packer.nvim

use {
  -- Path to the neovim plugin directory inside the knot repo
  -- (packer does not expand ~, so vim.fn.expand is required):
  vim.fn.expand("~/path/to/knot/editors/neovim"),
  -- Once published as a standalone plugin, replace with:
  -- "oxGrad/knot.nvim",
  ft = { "knotfile" },
  config = function()
    require("knot").setup({
      auto_configure_yamlls = true,
    })
  end,
}

Manual (no plugin manager)

Add the plugin directory to your runtime path in init.lua:

vim.opt.runtimepath:append(vim.fn.expand("~/path/to/knot/editors/neovim"))
require("knot").setup()

Or in init.vim:

set runtimepath+=~/path/to/knot/editors/neovim
lua require("knot").setup()

Configuration

require("knot").setup({
  -- Set to false if you manage yamlls schemas yourself.
  auto_configure_yamlls = true,
})

Option	Type	Default	Description
auto_configure_yamlls	boolean	true	Automatically notify the active yaml-language-server client to use the Knotfile JSON Schema for all Knotfile buffers.

Manual yaml-language-server schema association

If you prefer to configure yamlls yourself, add this to your lspconfig setup:

require("lspconfig").yamlls.setup({
  settings = {
    yaml = {
      schemas = {
        ["https://raw.githubusercontent.com/oxGrad/knot/main/schema/knotfile.schema.json"] = "**/Knotfile",
      },
    },
  },
})

Or add this modeline as the first line of any Knotfile:

# yaml-language-server: $schema=https://raw.githubusercontent.com/oxGrad/knot/main/schema/knotfile.schema.json
packages:
  nvim:
    source: ./nvim
    target: ~/.config/nvim

Schema

The official JSON Schema is published at:

https://raw.githubusercontent.com/oxGrad/knot/main/schema/knotfile.schema.json

See ../../schema/knotfile.schema.json for the full definition.