sloth-flake.nvim

A neovim plugin and configuration management plugin, highly inspired by lazy, using nix.

• Description
• Features
• SemVer
• Installation
  • Flake installation
• Usage
• Documentation
  • nix
    • mkNeovimPkg
  • neovim (lua)
    • Using default init.lua
    • Using your own init.lua
    • API

Description

sloth-flake.nvim is an alpha software. Please use caution when using it.

sloth-flake.nvim is both

• a neovim plugin to manage your plugins
• a nix flake to build your neovim package with your own configuration and plugins.

ℹ️ If you never heard of nix or you never used it, then this plugin is not for you.

Features

• Declare your plugin via nix files
  • Declare nix package as dependencies
  • Generate nix package from local files
• Generate default init.lua
• Accepts your own init.lua
• Lazy load your plugins
  • on command
  • on filetype
  • on event
  • on keybinding
• load plugins in order (via plugin dependencies property)
• Generate spell files on build (maybe)

SemVer

This project will respect SemVer in the end, but will adopt a slightly different semantics in the beginning.

This project is considered alpha as long as the version is 0.0.x, therefore you can expect breaking change on each version. You can see the version as 0.0.MAJOR.

When this project will hit 0.1.0, the project will be in beta phase. If a new version have breaking change, then it will be 0.2.0 and 0.1.1 otherwise. You can see the version as 0.MAJOR.MINOR.

When this project will hit 1.0.0, it will then follow full SemVer (MAJOR.MINOR.PATCH).

Installation

Only flake installation is supported.

Flake installation

Import sloth-flake.nvim flake latest version:

inputs.sloth-flake.url = "github:lemarsu/sloth-flake.nvim";

You can give a specific version:

inputs.sloth-flake.url = "github:lemarsu/sloth-flake.nvim?ref=0.0.5";

Usage

Once installed, you can call the sloth-flake.lib.mkNeovimPkg to build your neovim package.

mkNeovimPkg requires a set as argument with at least pkgs that represents your nixpkgs.

sloth-flake.lib.mkNeovimPkg {
  inherit pkgs;
  runtime = {
    version = "0.1";
    src = sloth-flake.lib.sourcesWith ./. [
      ./after
      ./colors
      ./ftplugin
      ./lua
      ./plugin
      ./queries
    ];
  };

  dependencies = [
    rust-vim
    vim-openscad
    ./lsp
    {
      plugin = telescope-nvim;
      config = ./telescope.lua;
    }
  ];
}

Documentation

nix

mkNeovimPkg

mkNeovimPkg requires only the pkgs argument.

Here's a list of all accepted arguments

name	default	description
pkgs	N/A	The nixpkgs set. REQUIRED
package	pkgs.neovim-unwrapped	The unwrapped neovim package to use
runtime	{}	Your Runtime configuration (see below)
dependencies	[]	A list of your dependencies (see below)
dependenciesExtraArgs	{}	Extra arguments to load your dependencies in other files

The Runtime configuration object accepts the following properties:

name	default	description
version	null	The version of your runtime
init	null	The init.lua of your config¹
src	null	The content of your runtime

¹ If you give your own init.lua, you'll have to call sloth-flake lua plugin yourself. See more below.

The dependencies is a list of element of either:

• path: the path of the file to load other dependencies
• package: a nix package of a neovim/vim plugin
• Plugin configuration object: an object describing a plugin and its configuration.

The Plugin configuration object accepts the following properties:

name	default	description
plugin	N/A	The plugin to load² REQUIRED
init	null	lua code (as string of path) to call before loading the plugin³
config	null	lua code (as string of path) to call after loading the plugin
dependencies	[]	The plugin dependencies⁴

² The plugin can be either a nix package or an object with only name and src as properties. The latter will be used to create a nix package of your plugin on the fly.

³ Not yet implemented. The function is called, but the plugin is already loaded.

⁴ Not yet implemented. nix handles the installation of your plugin, therefore, this list is NOT to declare dependencies that the nix package of the plugin doesn't know. This will tell sloth-flake in what order your plugins should be loaded... when sloth-flake will handle asynchronous loading... (Soon™).

neovim (lua)

Using default init.lua

If your neovim configuration is only plugin configuration, sloth-flake will give you a default init.lua that will load sloth-flake plugin that will, in turn, load all your plugins. If you need more control over configuration startup, please look at next section.

Using your own init.lua

You can provide your init.lua, but you must call sloth-flake your self.

-- Requiring sloth-flake plugin
local sloth_flake = require 'sloth-flake'

-- Before this point, no plugin nor configuration is loaded
-- You can configure what you need before loading any plugin.
sloth_flake.setup {
  -- This function is called after calling all optional `init` functions of your plugins
  -- but before loading those plugins
  post_init = function()
    -- [...]
  end
}

-- From here, your plugins are loaded and their optional `config` function called

API

The lua API is not really defined yet. This documentation will be completed then.