doc: update readme

Add a custom snippet for markdown to insert a YAML metadata block
This is a highly targeted snippet as it works for my blog template only.

There is some work to do on neatening this snippet up

lazy-lock.json

@@ -1,25 +1,33 @@
 {
-  "LuaSnip": { "branch": "master", "commit": "3732756842a2f7e0e76a7b0487e9692072857277" },
+  "LuaSnip": { "branch": "master", "commit": "a62e1083a3cfe8b6b206e7d3d33a51091df25357" },
   "cmp-nerdfont": { "branch": "main", "commit": "e97482344ebed29093015a18c155057adf5c842b" },
   "cmp-nvim-lsp": { "branch": "main", "commit": "cbc7b02bb99fae35cb42f514762b89b5126651ef" },
   "cmp_luasnip": { "branch": "master", "commit": "98d9cb5c2c38532bd9bdb481067b20fea8f32e90" },
-  "friendly-snippets": { "branch": "main", "commit": "572f5660cf05f8cd8834e096d7b4c921ba18e175" },
+  "friendly-snippets": { "branch": "main", "commit": "6cd7280adead7f586db6fccbd15d2cac7e2188b9" },
-  "gruvbox.nvim": { "branch": "main", "commit": "5e0a460d8e0f7f669c158dedd5f9ae2bcac31437" },
+  "gruvbox.nvim": { "branch": "main", "commit": "334d5fd49fc8033f26408425366c66c6390c57bb" },
   "lazy.nvim": { "branch": "main", "commit": "306a05526ada86a7b30af95c5cc81ffba93fef97" },
-  "lazydev.nvim": { "branch": "main", "commit": "5231c62aa83c2f8dc8e7ba957aa77098cda1257d" },
+  "lazydev.nvim": { "branch": "main", "commit": "ff2cbcba459b637ec3fd165a2be59b7bbaeedf0d" },
-  "lspkind.nvim": { "branch": "master", "commit": "3ddd1b4edefa425fda5a9f95a4f25578727c0bb3" },
+  "lspkind.nvim": { "branch": "master", "commit": "c7274c48137396526b59d86232eabcdc7fed8a32" },
   "lualine-spell-status": { "branch": "main", "commit": "aa81c2c9a71e3ed3552c6cd75e150414ff9ac664" },
-  "lualine.nvim": { "branch": "master", "commit": "47f91c416daef12db467145e16bed5bbfe00add8" },
+  "lualine.nvim": { "branch": "master", "commit": "f5d2a8570f8b736ddb9bb4be504355bcd6e15ec8" },
-  "mason-lspconfig.nvim": { "branch": "main", "commit": "4cfe411526a7a99c18281135e8b4765ae6330d15" },
+  "mason-lspconfig.nvim": { "branch": "main", "commit": "63a3c6a80538de1003373a619e29aeda27809ad3" },
-  "mason.nvim": { "branch": "main", "commit": "44d1e90e1f66e077268191e3ee9d2ac97cc18e65" },
+  "mason.nvim": { "branch": "main", "commit": "b03fb0f20bc1d43daf558cda981a2be22e73ac42" },
-  "neo-tree.nvim": { "branch": "v3.x", "commit": "f3df514fff2bdd4318127c40470984137f87b62e" },
+  "neo-tree.nvim": { "branch": "v3.x", "commit": "84c75e7a7e443586f60508d12fc50f90d9aee14e" },
   "nui.nvim": { "branch": "main", "commit": "de740991c12411b663994b2860f1a4fd0937c130" },
-  "nvim-autopairs": { "branch": "master", "commit": "c2a0dd0d931d0fb07665e1fedb1ea688da3b80b4" },
+  "nvim-autopairs": { "branch": "master", "commit": "59bce2eef357189c3305e25bc6dd2d138c1683f5" },
-  "nvim-cmp": { "branch": "main", "commit": "85bbfad83f804f11688d1ab9486b459e699292d6" },
+  "nvim-cmp": { "branch": "main", "commit": "a1d504892f2bc56c2e79b65c6faded2fd21f3eca" },
-  "nvim-lspconfig": { "branch": "master", "commit": "5a82e10b2df0ed31bec642c1c0344baee7c458b6" },
+  "nvim-lspconfig": { "branch": "master", "commit": "c588db330592fa477a70d2fee6ba20a57194bdc3" },
-  "nvim-treesitter": { "branch": "main", "commit": "de878155ca66c49b027b1380e4e60a6c665b2630" },
+  "nvim-treesitter": { "branch": "main", "commit": "4916d6592ede8c07973490d9322f187e07dfefac" },
-  "nvim-treesitter-context": { "branch": "master", "commit": "64dd4cf3f6fd0ab17622c5ce15c91fc539c3f24a" },
+  "nvim-treesitter-context": { "branch": "master", "commit": "b0c45cefe2c8f7b55fc46f34e563bc428ef99636" },
-  "nvim-web-devicons": { "branch": "master", "commit": "6788013bb9cb784e606ada44206b0e755e4323d7" },
+  "nvim-web-devicons": { "branch": "master", "commit": "c72328a5494b4502947a022fe69c0c47e53b6aa6" },
-  "plenary.nvim": { "branch": "master", "commit": "b9fd5226c2f76c951fc8ed5923d85e4de065e509" },
+  "plenary.nvim": { "branch": "master", "commit": "fcb3e9ac127d178b4c189088396165b3facc219e" },
+  "snacks.nvim": { "branch": "main", "commit": "ad9ede6a9cddf16cedbd31b8932d6dcdee9b716e" },
+  "telescope-fzf-native.nvim": { "branch": "main", "commit": "6fea601bd2b694c6f2ae08a6c6fab14930c60e2c" },
+  "telescope.nvim": { "branch": "master", "commit": "5255aa27c422de944791318024167ad5d40aad20" },
+  "todo-comments.nvim": { "branch": "main", "commit": "31e3c38ce9b29781e4422fc0322eb0a21f4e8668" },
+  "toggleterm.nvim": { "branch": "main", "commit": "50ea089fc548917cc3cc16b46a8211833b9e3c7c" },
+  "treesitter-modules.nvim": { "branch": "main", "commit": "34e50df1c49376592788dcb245683e2f43444444" },
+  "trouble.nvim": { "branch": "main", "commit": "bd67efe408d4816e25e8491cc5ad4088e708a69a" },
+  "vimtex": { "branch": "master", "commit": "9306903316c3ddd250676b7cf97c84a84c9c8f99" },
   "which-key.nvim": { "branch": "main", "commit": "3aab2147e74890957785941f0c1ad87d0a44c15a" }
 }

lua/core/init.lua

@@ -6,10 +6,15 @@ M.setup = function()
 	require("core.filetypes")
 	require("plugins.lazy")
 
-	-- Load this after loading plugins to ensure default lspconfig is there
+	-- Load this after loading plugins to ensure default lsp-config is there
 	require("core.lspconfig")
 	require("core.treesitter")
 
+	-- Load this after loading everything else
+	-- to ensure we are ready for them.
+	require("core.keybinds")
+
+	-- Finally set the colorscheme
 	vim.cmd.colorscheme("gruvbox")
 end
 

lua/core/keybinds.lua

@@ -0,0 +1,51 @@
+-- NOTE: MOST PLUGIN KEY-BINDS ARE LOCATED IN THE PLUGINS SPEC
+-- As a general rule of thumb: 
+--	* if the key-bind requires a given plugin be loaded 
+--	* or is/can be used to lazy-load a plugin
+-- It doesn't belong here
+
+-- NOTE: I am not using any convenience function here.
+-- Instead I am using the `vim.keymap.set` function bare.
+-- This is to make it easier to know what this is doing 
+-- if I come back to edit a binding later.
+
+
+-- ! Use native tree-sitter incremental highlighting when possible.
+if vim.fn.has('nvim-0.12') == 1 then
+	vim.keymap.set({'n','x'}, '<TAB>',
+		function ()
+			require('vim.treesitter._select')
+			.select_next(vim.v.count1)
+		end,
+		{
+			desc = 'Select next Treesitter Node'
+		}
+	)
+	vim.keymap.set({'n','x'}, '<S-TAB>',
+		function ()
+			require('vim.treesitter._select')
+			.select_prev(vim.v.count1)
+		end,
+		{
+			desc = 'Select previous Treesitter Node'
+		}
+	)
+	vim.keymap.set({'n','x'}, '<CR>',
+		function ()
+			require('vim.treesitter._select')
+			.select_parent(vim.v.count1)
+		end,
+		{
+			desc = 'Select parent TS node'
+		}
+	)
+	vim.keymap.set({'n','x'}, '<S-CR>',
+		function ()
+			require('vim.treesitter._select')
+			.select_child(vim.v.count1)
+		end,
+		{
+			desc = 'Select child TS node'
+		}
+	)
+end

lua/core/lspconfig.lua

@@ -26,3 +26,5 @@ vim.lsp.config("termux_language_server", {
 	},
 })
 vim.lsp.enable("termux_language_server") -- not enabled by default for some reason
+
+vim.lsp.inlay_hint.enable(true,nil)

lua/plugins/lazy/init.lua

@@ -1,23 +1,89 @@
+-- Boostrap Lazy plugin manager
 local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
+
+-- It is possible to install this config via tarball,
+-- or inherit it when copying my user config to a new machine.
+-- 
+-- It is also possible that git can be installed but not in $PATH
+-- especially when linux DE's are started via `exec env`
+-- 
+-- as such the system installing it may not have git avaialable
+-- This is a failure condition as we cannot bootstrap,
+-- nor manage plugins without it.
+if vim.fn.executable("git") == 0 then
+	vim.api.nvim_echo(
+		{
+			{ "git is not installed, will be unable to use Lazy\n", "ErrorMsg"},
+			{ "your PATH is: ", "WarningMsg" },
+			{ vim.env.PATH, "WarningMsg"}, -- output path for debugging purposes
+			{ "\nPress any key to exit..."}
+		}, true, {} )
+	vim.fn.getchar()
+	os.exit(1)
+end
+
+
+-- Standard bootstrapping process.
 if not (vim.uv or vim.loop).fs_stat(lazypath) then
 	local lazyrepo = "https://github.com/folke/lazy.nvim.git"
+
+
 	local out = vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath })
 	if vim.v.shell_error ~= 0 then
 		vim.api.nvim_echo({
 			{ "Failed to clone lazy.nvim:\n", "ErrorMsg" },
 			{ out, "WarningMsg" },
 			{ "\nPress any key to exit..." },
-		}, true, {})
+		}, true, {} )
 		vim.fn.getchar()
 		os.exit(1)
 	end
 end
 vim.opt.rtp:prepend(lazypath)
 
+-- Check for internet, if we have curl..
+-- This check is intentionally placed after the bootstrapping
+-- as bootstrapping will fail if we don't have internet anyway.
+-- and outside of that it is not a failure condition
+if vim.fn.executable("curl") == 1 then
+	local out = vim.fn.system({
+		"curl",
+		"-sS" , -- only output errors
+		"--head", -- only get headers
+		"www.google.com",
+		"-o", -- send any output to /dev/null
+		"/dev/null"
+	})
+
+	if vim.v.shell_error ~= 0 then
+		vim.api.nvim_echo({
+			{ "We can't connect to the internet\n", "WarningMsg"},
+			{ "This is what curl said: ", "WarningMsg" },
+			{ out, "WarningMsg" },
+			{ "Packages can load, but we cannot install/update\n" },
+			{ "Press any key to continue...\n" }
+		}, true, {})
+	end
+end
+
+-- Actually load Lazy and get it going
 require("lazy").setup({
 	spec = {
 		{ import = "plugins.spec" },
 	},
 
 	checker = { enabled = true },
+
+	performance = {
+		rtp = {
+			disabled_plugins ={
+				"netrwPlugin",
+				"gzip",
+				"tarPlugin",
+				"tohtml",
+				"tutor",
+				"zipPlugin"
+			}
+		}
+	}
 })

lua/plugins/spec/builtin.lua

@@ -0,0 +1,26 @@
+---@module 'lazy'
+---@type LazySpec
+return{
+	{
+		name = 'nohlsearch',
+		virtual = true,
+		dir = 'nohlsearch',
+		enabled = function ()
+			return vim.fn.has('nvim-0.12') == 1
+		end,
+		init = function()
+			vim.cmd([[packadd nohlsearch]])
+		end
+	},
+	{
+		name = 'nvim.undotree',
+		virtual = true,
+		dir = 'nvim.undotree',
+		enabled = function ()
+			return vim.fn.has('nvim-0.12') == 1
+		end,
+		init = function()
+			vim.cmd([[packadd nvim.undotree]])
+		end
+	}
+}

lua/plugins/spec/completion.lua

@@ -1,17 +1,31 @@
-require("lazy.types")
+---@module "lazy"
----@type LazySpec[]
+---@type LazySpec
 return {
-	{
+	{	"L3MON4D3/LuaSnip",
-		"L3MON4D3/LuaSnip",
 		dependencies = {
 			"rafamadriz/friendly-snippets",
 		},
 		config = function()
 			local lua_snippets = vim.fn.stdpath("config") .. "/luasnip"
 			local vscode_snippets = vim.fn.stdpath("config") .. "/snippets"
+			local types = require("luasnip.util.types")
 			require("luasnip.loaders.from_vscode").lazy_load()
 			require("luasnip.loaders.from_vscode").lazy_load({ paths = { vscode_snippets } })
 			require("luasnip.loaders.from_lua").lazy_load({ paths = { lua_snippets } })
+			require("luasnip").config.setup({
+				ext_opts = {
+					[types.choiceNode] = {
+						active = {
+							virt_text = {{"", "GruvboxOrange"}}
+						}
+					},
+					[types.insertNode] = {
+						active = {
+							virt_text = {{"", "GruvboxBlue"}}
+						}
+					}
+				}
+			})
 		end,
 		lazy = true,
 	},
@@ -32,9 +46,16 @@ return {
 			"chrisgrieser/cmp-nerdfont",
 		},
 		opts = function()
+			vim.lsp.config("*", {capabilities = require("cmp_nvim_lsp").default_capabilities()})
+
 			local cmp = require("cmp")
 			local luasnip = require("luasnip")
 			local lspkind = require("lspkind")
+			local cmp_autopairs = require("nvim-autopairs.completion.cmp")
+			cmp.event:on(
+				'confirm_done',
+				cmp_autopairs.on_confirm_done()
+			)
 			---@type cmp.ConfigSchema
 			return {
 				enabled = function()
@@ -66,6 +87,20 @@ return {
 							fallback()
 						end
 					end, { "i", "s" }),
+					["x"] = cmp.mapping(function (fallback)
+						if luasnip.choice_active() then
+							luasnip.change_choice(1)
+						else
+							fallback()
+						end
+					end),
+					["z"] = cmp.mapping(function (fallback)
+						if luasnip.choice_active() then
+							luasnip.change_choice(-1)
+						else
+							fallback()
+						end
+					end),
 					["<S-Tab>"] = cmp.mapping(function(fallback)
 						if cmp.visible() then
 							cmp.select_prev_item()
@@ -92,9 +127,16 @@ return {
 							select = false,
 						}),
 					}),
-					["<C-F>"] = cmp.mapping(function(fallback)
+					["<C-F>"] = cmp.mapping(function(_)
 						cmp.complete()
 					end),
+					["<C-A>"] = cmp.mapping(function (fallback)
+						if cmp.visible() then
+							cmp.close()
+						else
+							fallback()
+						end
+					end)
 				},
 				sources = cmp.config.sources({
 					{ name = "lazydev" },
@@ -122,3 +164,4 @@ return {
 		end,
 	},
 }
+-- vim: fdl=2

lua/plugins/spec/gruvbox.lua

@@ -1,3 +1,5 @@
+---@module 'lazy.nvim'
+---@type LazySpec
 return {
 	{
 		"ellisonleao/gruvbox.nvim",

lua/plugins/spec/lsp.lua

@@ -1,3 +1,5 @@
+---@module "lazy.nvim"
+---@type LazySpec[]
 return {
 	{
 		"mason-org/mason-lspconfig.nvim",
@@ -7,7 +9,9 @@ return {
 			},
 		},
 		dependencies = {
-			{ "mason-org/mason.nvim", opts = {} },
+			{
+				"mason-org/mason.nvim", opts = {}
+			},
 			"neovim/nvim-lspconfig",
 		},
 	},
@@ -20,4 +24,69 @@ return {
 			},
 		},
 	},
+	{
+		"folke/trouble.nvim",
+		opts = {},
+		cmd = "Trouble",
+		keys = function (_, _)
+			local tr = require("trouble")
+
+			---@type LazyKeysSpec[]
+			return {
+
+				{"<leader>xx",
+					function ()
+						tr.toggle(
+						---@diagnostic disable-next-line: missing-fields
+							{
+								mode = "diagnostics",
+								focus = false}
+						)
+					end,
+					desc = "Trouble Diagnostics",
+					mode = "n"
+				},
+				{"<leader>xX",
+					function ()
+						tr.toggle(
+						---@diagnostic disable-next-line: missing-fields
+							{
+								mode = "diagnostics",
+								filter = {
+									buf = 0,
+								},
+								focus = false
+							}
+						)
+					end,
+					desc = "Buffer Diagnostics (Trouble)"
+				},
+				{"<leader>xQ",
+					function ()
+						tr.toggle(
+						---@diagnostic disable-next-line: missing-fields
+						{
+								mode = "qflist",
+								focus = false
+							}
+						)
+					end,
+					desc = "Quickfix List (Trouble)"
+				},
+				{"<leader>cs",
+					function ()
+						tr.toggle(
+						---@diagnostic disable-next-line: missing-fields
+						{
+								mode = "symbols",
+								focus = false
+							}
+						)
+					end,
+					desc = "Symbols (Trouble)"
+				}
+			}
+		end
+
+	}
 }

lua/plugins/spec/lualine.lua

@@ -1,46 +1,102 @@
+---@module "lazy.nvim"
+---@type LazySpec[]
 return {
-	"nvim-lualine/lualine.nvim",
+	{"nvim-lualine/lualine.nvim",
-	dependencies = {
+		dependencies = {
-		"nvim-tree/nvim-web-devicons",
+			"nvim-tree/nvim-web-devicons",
-		"sherlock5512/lualine-spell-status",
+			"sherlock5512/lualine-spell-status",
-	},
-	opts = {
-		options = {
-			theme = "auto",
-			component_separators = { left = "|", right = "|" },
-			section_separators = { left = "", right = "" },
-			disabled_filetypes = {},
-			always_divide_middle = true,
-			globalstatus = true,
 		},
-		sections = {
+		opts = {
-			lualine_a = {
+			options = {
-				"mode",
+				theme = "auto",
-				"spell_status",
+				component_separators = { left = "|", right = "|" },
+				section_separators = { left = "", right = "" },
+				disabled_filetypes = {
+					winbar = {
+						'neo-tree',
+						'help',
+						'snacks_dashboard',
+						'telescope',
+						'trouble'
+					},
+				},
+				always_divide_middle = true,
+				globalstatus = true,
 			},
-			lualine_b = {
+			sections = {
-				"branch",
+				lualine_a = {
-				"diff",
+					"mode",
-				"diagnostics",
+					"spell_status",
+					"lsp_status",
+				},
+				lualine_b = {
+					"branch",
+					"diff",
+					"diagnostics",
+				},
+				lualine_c = {
+					{ "filename", path = 1 },
+					{ "filetype", icon_only = true },
+				},
+				lualine_x = {
+					"encoding",
+					"fileformat",
+					"filetype",
+					{ require("lazy.status").updates, cond = require("lazy.status").has_updates },
+				},
+				lualine_y = {
+					"progress",
+					"searchcount",
+				},
+				lualine_z = {
+					"location",
+				},
 			},
-			lualine_c = {
+			tabline = {},
-				{ "filename", path = 1 },
+			winbar = {
-				{ "filetype", icon_only = true },
+				lualine_a = {
-			},
+					{
-			lualine_x = {
+						"buffers",
-				"encoding",
+						mode = 3,
-				"fileformat",
+						show_modified_status = false,
-				"filetype",
+						icons_enabled = false,
-				{ require("lazy.status").updates, cond = require("lazy.status").has_updates },
+					},
-			},
+					{
-			lualine_y = {
+						"filetype",
-				"progress",
+						icon_only = true,
-				"searchcount",
+					},
-			},
+					{
-			lualine_z = {
+						"filename",
-				"location",
+						file_status = false,
+						newfile_status = false,
+						path = 0,
+						symbols = {
+							modified = '',
+							readonly = '',
+							unnamed = '',
+							newfile = '',
+						},
+					},
+				},
 			},
+			winbar_inactive = {
+				lualine_a = {
+					{
+						"filename",
+						file_status = false,
+						newfile_status = false,
+						path = 0,
+						symbols = {
+							modified = '',
+							readonly = '',
+							unnamed = '',
+							newfile = '',
+						},
+						disabled_filetypes = { 'neo-tree' }
+					},
+				}
+			}
 		},
-		tabline = {},
+
-	},
+	}
 }

lua/plugins/spec/neo-tree.lua

@@ -1,5 +1,7 @@
+---@module "lazy.nvim"
+---@type LazySpec[]
 return {
-	"nvim-neo-tree/neo-tree.nvim",
+	{"nvim-neo-tree/neo-tree.nvim",
 	branch = "v3.x",
 	dependencies = {
 		"nvim-lua/plenary.nvim",
@@ -7,29 +9,68 @@ return {
 		"nvim-tree/nvim-web-devicons",
 	},
 	lazy = false,
+	opts = function ()
+
 	---@module 'neo-tree'
 	---@type neotree.Config
-	opts = {
+		local opts = {
-		enable_git_status = true,
+			enable_git_status = true,
-		enable_diagnostics = true,
+			enable_diagnostics = true,
-		sort_case_insensitive = true,
+			sort_case_insensitive = true,
 
-		filesystem = {
+			open_files_do_not_replace_types = {
-			filtered_items = {
+				"terminal",
-				visible = false,
+				"trouble",
-				hide_dotfiles = true,
+				"qf",
-				hide_gitignored = true,
+				"help",
-				hide_hidden = true,
 			},
-			follow_current_file = { enabled = true },
-			hijack_netrw_behaviour = "open_default",
-			use_libuv_file_watcher = true,
-		},
 
-		window = { position = "left" },
+			filesystem = {
+				filtered_items = {
+					visible = false,
+					hide_dotfiles = true,
+					hide_gitignored = true,
+					hide_hidden = true,
+				},
+				bind_to_cwd = true,
+				cwd_target = {
+					sidebar = "global",
+					window = "global",
+				},
+				follow_current_file = { enabled = true },
+				hijack_netrw_behaviour = "open_default",
+				use_libuv_file_watcher = true,
+			},
 
-		buffers = {
+			window = { position = "left" },
-			follow_current_file = { enabled = true },
+
-		},
+			buffers = {
-	},
+				follow_current_file = { enabled = true },
+			},
+		}
+
+		local function on_move(data)
+			Snacks.rename.on_rename_file(data.source, data.destination)
+		end
+		local events = require("neo-tree.events")
+		opts.event_handlers = opts.event_handlers or {}
+		vim.list_extend(opts.event_handlers, {
+			{ event = events.FILE_MOVED, handler = on_move },
+			{ event = events.FILE_RENAMED, handler = on_move},
+		})
+		return opts
+	end,
+	keys = {
+		{
+			"<leader>n",
+			function()
+				require("neo-tree.command").execute{toggle = true}
+			end,
+			mode = "n",
+			noremap = true,
+			silent = true,
+			desc = "Toggle Neotree"
+		}
+	}
+	}
 }

lua/plugins/spec/snacks.lua

@@ -0,0 +1,62 @@
+---@module "lazy.nvim"
+---@type LazySpec[]
+return {
+	{
+		"folke/snacks.nvim",
+		priority = 1000,
+		lazy = false,
+		---@module "snacks"
+		---@type snacks.Config
+		opts = {
+			bufdelete = {
+				enabled = true
+			},
+			---@type snacks.dashboard.Config
+			dashboard =
+				{
+					sections = {
+						{ section = "header"},
+						{
+							icon = " ",
+							title = "keymaps",
+							section = "keys",
+							indent = 2,
+							padding = 1,
+						},
+						{
+							icon = " ",
+							title = "Recent Files",
+							section = "recent_files",
+							indent = 2,
+							padding = 1,
+						},
+						{
+							icon = " ",
+							title = "Projects",
+							section = "projects",
+							indent = 2,
+							padding = 1,
+						},
+						{ section = "startup"},
+					},
+					formats =  {}
+				},
+			indent = {enabled = true},
+			rename = {enabled = true},
+			styles = {
+				notification ={
+					wo = { wrap = true }
+				}
+			}
+		},
+		keys = {
+			{"<leader>bd",
+				function ()
+					require("snacks").bufdelete()
+				end,
+				desc = "Delete current buffer",
+				mode = "n"
+			}
+		}
+	}
+}

lua/plugins/spec/telescope.lua

@@ -0,0 +1,18 @@
+---@module "lazy.nvim"
+---@type LazySpec[]
+return{
+	{
+		"nvim-telescope/telescope.nvim", version = '*',
+		dependencies = {
+			'nvim-lua/plenary.nvim',
+			{ 'nvim-telescope/telescope-fzf-native.nvim', build = 'make' }
+		},
+		cmd = "Telescope",
+		keys = {
+			{"<leader>h",
+				require("telescope.builtin").help_tags,
+				desc = "Telescope Help_tags"
+			}
+		}
+	}
+}

lua/plugins/spec/todo-comments.lua

@@ -0,0 +1,12 @@
+---@module 'lazy.nvim'
+---@type LazySpec[]
+return{
+	{
+		"folke/todo-comments.nvim",
+		dependencies = { "nvim-lua/plenary.nvim" },
+		opts = {
+
+		},
+		event = "BufRead"
+	}
+}

lua/plugins/spec/toggleterm.lua

@@ -0,0 +1,18 @@
+---@module "lazy.nvim"
+---@type LazySpec[]
+return {
+	{
+		"akinsho/toggleterm.nvim",
+		version = "*",
+		---@module "toggleterm.config"
+		---@type ToggleTermConfig
+		---@diagnostic disable-next-line: missing-fields
+		opts = {
+			open_mapping = "<leader>t",
+			direction = "float",
+		},
+		keys = {
+			{ "<leader>t",desc = "toggle terminal" }
+		}
+	}
+}

lua/plugins/spec/treesitter.lua

@@ -1,3 +1,5 @@
+---@module "lazy.nvim"
+---@type LazySpec
 return {
 	{
 		"nvim-treesitter/nvim-treesitter",
@@ -12,4 +14,24 @@ return {
 			"nvim-treesitter/nvim-treesitter",
 		},
 	},
+	{
+		"MeanderingProgrammer/treesitter-modules.nvim",
+		dependencies = { "nvim-treesitter/nvim-treesitter" },
+
+		opts = {
+				incremental_selection = {
+				enable = true,
+					keymaps = {
+					init_selection = "<CR>",
+					scope_incremental = "<CR>",
+					node_incremental = "<TAB>",
+					node_decremental = "<S-TAB>",
+				}
+			}
+		},
+		cond = function ()
+			return (vim.fn.has("nvim-0.12") == 0)
+		end
+	}
 }
+

lua/plugins/spec/vimtex.lua

@@ -0,0 +1,12 @@
+--- @module 'lazy.nvim'
+--- @type LazySpec[]
+return {
+  "lervag/vimtex",
+  lazy = false,     -- we don't want to lazy load VimTeX
+  init = function()
+    -- VimTeX configuration goes here, e.g.
+	vim.g.tex_flavour='latex'
+	vim.g.vimtex_quickfix_mode=0
+    vim.g.vimtex_view_method = "skim"
+  end
+}

lua/sherlock5512/scriptutils/init.lua

@@ -0,0 +1,33 @@
+-- scriptutils: some useful functions for scripts to use.
+
+require('sherlock5512.scriptutils.types')
+
+local M = {}
+
+
+--- Run a command in a shell
+-- This function only works on UNIX-like systems 
+-- that have a POSIX compliant shell installed.
+---@param cmdline string Your command-line to send to sh
+---@param timeout? integer Timeout for command
+---@return shReturn status [1]
+---@return string? stdout the contents of stdout from executing your cmdline
+function M.shellexec(cmdline,timeout)
+	timeout = timeout or nil
+	-- by default vim.system runs async, but as we need the output immediately we don't really need that.
+	-- Note the timeout is passed to wait and not as an option to system,
+	-- In this case I don't think it really matters as we wait immediately after calling vim.system
+	local result = vim.system({'sh', '-c', cmdline}):wait(timeout)
+	-- Breaking the result into variables makes my programming intent clearer
+	local stdout = result.stdout
+	local stderr = result.stderr
+	local code = result.code
+
+	return {
+		ok = (code == 0),
+		code = code,
+		stderr = stderr,
+	}, stdout
+end
+
+return M

lua/sherlock5512/scriptutils/types.lua

@@ -0,0 +1,4 @@
+---@class shReturn
+---@field ok boolean True if successful
+---@field code integer Return code (useful for debugging)
+---@field stderr string Stderr (if any)

luasnip/markdown.lua

@@ -0,0 +1,109 @@
+-- Markdown snippets
+
+-- We manually create these as the LSP doesn't understand 
+-- if they are loaded properly.
+local ls = require('luasnip')
+local lsf = require('luasnip.extras.fmt')
+local s = ls.snippet
+local t = ls.text_node
+local i = ls.insert_node
+local c = ls.choice_node
+local sn = ls.snippet_node
+local fmt = lsf.fmt
+local fmta = lsf.fmta
+local currentUser
+
+
+if vim.fn.has('linux') == 1 then
+	--- Get the current users full name
+	---@return string @The users full name OR NAME
+	currentUser = function ()
+		local status, res = require('sherlock5512.scriptutils').shellexec("getent passwd $USER | cut -d: -f5 | cut -d, -f1")
+		if status.ok then
+			-- We know there will only be stdout if the command runs successfully
+			---@diagnostic disable-next-line: return-type-mismatch, need-check-nil
+			return res:match("^[\r\n]*(.-)[\r\n]*$")
+		end
+			return "NAME"
+	end
+elseif vim.fn.has('mac') == 1 then
+	--- Get the current users full name
+	---@return string @The users full name OR NAME
+	currentUser = function ()
+		local status, res = require('sherlock5512.scriptutils').shellexec("id -F")
+		if status.ok then
+			-- We know there will only be stdout if the command runs successfully
+			---@diagnostic disable-next-line: return-type-mismatch, need-check-nil
+			return res:match("^[\r\n]*(.-)[\r\n]*$")
+		end
+		return "NAME"
+	end
+else
+	--- Get the current users full name
+	---@return string @The users full name OR NAME
+	currentUser = function ()
+		return "NAME"
+	end
+end
+
+--- @module 'luasnip'
+--- @type LuaSnip.Snippet[]
+return {
+	s(
+		{ trig = '\\yaml', dscr = 'YAML frontmatter block'}, {
+			t {'---',''}, -- end with empty block to force a newline
+			t {'author: "' },
+			i(1, currentUser()),
+			t {'"',''},
+			t {'title: "'},
+			i(2),
+			t {'"', ''},
+			t {'date: '},
+			i(3),
+			t {'',''},
+			t {'description: "'},
+			i(4),
+			t {'"', ''},
+			c(5,
+				{
+					t '', 
+					sn(nil,{
+						t {"keywords: [ "},
+						i(1),
+						t { ' ]', '' },
+					})
+				}
+			),
+			t {"lang: "},
+			i(6, 'en-gb'),
+			t {'', ''},
+			c(7, {
+				sn(nil, {
+					t {'math: true', ''},
+					i(1),
+					c(2, {
+						t {'mathjax: true', ''},
+						t {'mathjax: false', ''}
+					}),
+				}),
+				t {'math: false', ''},
+			}),
+			c(8, {
+				t {'needs-syntax-highlighting: true', ''},
+				t {'needs-syntax-highlighting: false', ''},
+			}),
+			c(9, {
+				t {'allow-comments: true', ''},
+				t {'allow-comments: false', ''},
+			}),
+			c(10, {
+				t '',
+				sn(nil, {
+					t {'style: "', ''},
+					i(1),
+					t {'','"', ''}
+				})
+			}),
+			t {'---',''}
+		})
+}

readme.md

@@ -7,6 +7,12 @@ This time instead of copying large swathes of config from my previous
 setup, the majority of this is a clean rewrite, and at current is not fully
 implemented. 
 
+# Note:
+this readme is not guaranteed to be up-to-date
+Changes happen fast. and I don't always have time to document things.
+Ideally if this becomes stabilised I will have the time/need to document
+better
+
 # Currently missing
 
 The current major feature that is missing is I do not have any keybinds set
@@ -26,3 +32,18 @@ different purposes. However actually this just increases the time it takes
 to make changes, as often changes to plugin spec also require some amount
 of change in the plugin config. Also this means that everything relating to
 a single plugin is contained in one place and not spread across two files
+
+# Oddities
+
+# `lua/plugins/spec/builtin.lua`
+This file contains virtual plugin entries that allows me to load 
+built-in plugins using lazy. 
+I load `nvim.undotree` and `nohlsearch` this way.
+
+# typing longer options
+So that I can understand this when I need to make changes I try not to make
+abbreviations or aliases for built-in functions,
+I also refrain from using the short names for options unless they are just
+as descriptive as the full name. 
+This way I can actually understand my config when I come back to edit it
+every month or so.