🔥 lit.nvim

(experimental) Neovim package manager, minimal, literal

Alpha software, be careful but have fun.

See it in action here, kickstart.nvim rewritten with lit.nvim in markdown.

What it does

• 🖋️ Manage all your Neovim plugins with one markdown file, with out of box configured lsp, completion and formatting
• 💾 Partial clones instead of shallow clones
• 🔌 Automatic lazy-loading of Lua modules and lazy-loading on events, commands, filetypes, and key mappings, powered by lz.n
• 💪 Async execution for improved performance
• 🛠️ No need to manually compile plugins
• 🔒 Lockfile lit-lock.json to keep track of installed plugins
• 📋 Commit, branch, tag, version, and full Semver support
• 📦 Package formats support: lazy.lua, packspec, rockspec

What it won't do

• Have an UI
• Take over Neovim initialization

Bootstrap

In your init.lua:

local litpath = vim.fn.stdpath("data") .. "/site/pack/lit/start/lit.nvim"
if not (vim.uv or vim.loop).fs_stat(litpath) then
  local litrepo = "https://github.com/neo451/lit.nvim.git"
  local out = vim.fn.system({ "git", "clone", "--filter=blob:none", litrepo, litpath })
  if vim.v.shell_error ~= 0 then
    vim.api.nvim_echo({
      { "Failed to clone lit.nvim:\n", "ErrorMsg" },
      { out,                           "WarningMsg" },
      { "\nPress any key to exit..." },
    }, true, {})
    vim.fn.getchar()
    os.exit(1)
  end
end

Note

You can place init.lua and init.md in a separate directory like .config/litvim and just try out with:

  NVIM_APPNAME=litvim nvim

Config

No need for a setup function

vim.g.lit = {
    -- not much here yet
}

Usage

Write your config in markdown in .config/nvim/init.md:

1. author/repo or url -> heading

# Fuzzy Finder

## nvim-lua/plenary.nvim

## nvim-telescope/telescope.nvim

2. plugin config -> lua code blocks

# stevearc/oil.nvim

```lua
require"oil".setup{}
```

3. plugin spec -> list items

• Use build field for build setups
  • if starts with : -> vim cmd
  • else -> shell command
• If something is a dependency/library, use opt flag
• For other supported fields, see documentation for lz.n

# nvim-treesitter/nvim-treesitter

- build: `:TSUpdate`

# saghen/blink.cmp

- build: `cargo build --release`

# nvim-lua/plenary.nvim

- opt: `true`

# saghen/blink.cmp

- event: `InsertEnter`

# nvim-neorg/neorg

- ft: `norg`

# NeogitOrg/neogit

- cmd: `Neogit`
- keys: `{ { "<leader>gg", "<cmd>Neogit<cr>" } }`

4. options and vars -> yaml header

• .x for vim.o.x
• .g.x for vim.g.x

---
.g.mapleader: " "
.g.localmapleader: " "
.laststatus: 3
.wrap: true
.signcolumn: "yes"
---

Todos

• parser and code runner
  • config blocks
  • multiple blocks
  • extensible for languages
• config syntax
  • YAML header as vim.o / vim.g
  • lazy loading with lz.n
  • support markdown/html comments
• versioning
  • branch
  • pin
  • commit
  • tag
  • semver
• actions
  • clone
  • update
  • sync
  • list
  • edit
  • build
  • resolve
• editing
  • lsp -> otter.nvim
  • formatter -> conform.nvim
  • completion
• cool to have
  • nice ts folds
    • fold yaml header
  • plugin url in any heading level for organization
  • native snippets for code blocks -> NativeVim
  • native heading completion with activate.nvim
  • update info as diagnostic hover markdown

Thanks to

• paq-nvim for all the plugin management logic
• LitLua for the idea for a literate config
• lz.n for handling lazy loading