From dc0d42e54107b0076532f11d639019f54121e3dd Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 6 Feb 2025 08:06:08 +0000 Subject: [PATCH] Deploy PR #591 preview --- docs-preview-591/index.xhtml | 104 +++++++++++++++++++++++++--- docs-preview-591/options.html | 10 +-- docs-preview-591/quirks.html | 4 +- docs-preview-591/release-notes.html | 6 +- 4 files changed, 106 insertions(+), 18 deletions(-) diff --git a/docs-preview-591/index.xhtml b/docs-preview-591/index.xhtml index 451c1e67..85b61706 100644 --- a/docs-preview-591/index.xhtml +++ b/docs-preview-591/index.xhtml @@ -33,7 +33,7 @@
-

Table of Contents

Preface
What is nvf
Bugs & Suggestions
Try it out
Using Prebuilt Configs
Default Configs
Maximal
Nix
Installing nvf
Standalone Installation
Standalone Installation on NixOS
Standalone Installation on Home-Manager
Module Installation
NixOS Module
Home-Manager Module
Configuring nvf
Custom Neovim Package
Custom Plugins
Adding Plugins
Custom Inputs
Language Support
LSP Custom Packages/Command
Using DAGs
entryAnywhere
entryAfter
entryBefore
entryBetween
entriesAnywhere
entriesAfter
entriesBefore
entriesBetween
DAG entries in nvf
vim.luaConfigRC (top-level DAG)
Helpful Tips
Debugging nvf
Offline Documentation
Hacking nvf
Getting Started
Guidelines
Testing Changes
Keybinds
Adding Plugins
A. Known Issues and Quirks
NodeJS
B. Neovim Flake Configuration Options
C. Release Notes
Release 0.1
Release 0.2
Release 0.3
Release 0.4
Release 0.5
Release 0.6
Release 0.7
+

Table of Contents

Preface
Try it out
Default Configs
Maximal
Nix
Installing nvf
Standalone Installation
Module Installation
Configuring nvf
Custom Neovim Package
Custom Plugins
Custom Inputs
Language Support
Using DAGs
DAG entries in nvf
Helpful Tips
Pure Lua Configuration
Debugging nvf
Offline Documentation
Hacking nvf
A. Known Issues and Quirks
B. nvf Configuration Options
C. Release Notes

Preface

Table of Contents

What is nvf
Bugs & Suggestions

What is nvf

nvf is a highly modular, configurable, extensible and easy to use Neovim configuration in Nix. Designed for flexibility and ease of use, nvf allows you to easily configure your fully featured Neovim instance with a few lines of Nix.

@@ -43,7 +43,7 @@ reporting them over at the pull requests tab.

-

Try it out

Table of Contents

Using Prebuilt Configs
Available Configs

Thanks to the portability of Nix, you can try out nvf without actually +

Try it out

Table of Contents

Using Prebuilt Configs

Thanks to the portability of Nix, you can try out nvf without actually installing it to your machine. Below are the commands you may run to try out different configurations provided by this flake. As of v0.5, two specialized configurations are provided:

  • Nix - Nix language server + simple utility plugins

  • Maximal - Variable language servers + utility and decorative plugins

You may try out any of the provided configurations using the nix run command @@ -80,7 +80,7 @@ downloading a whole bunch of language servers and associated tools.

the standalone installation method, which does not depend on a module system and may be done on any system that has the Nix package manager or the appropriate modules for NixOS and home-manager as described in the -module installation section.

Table of Contents

Standalone Installation
Standalone Installation on NixOS
Standalone Installation on Home-Manager
Module Installation
NixOS Module
Home-Manager Module

Standalone Installation

Table of Contents

Standalone Installation on NixOS
Standalone Installation on Home-Manager

It is possible to install nvf without depending on NixOS or Home-Manager as the +module installation section.

Table of Contents

Standalone Installation
Module Installation

Standalone Installation

Table of Contents

Standalone Installation on NixOS
Standalone Installation on Home-Manager

It is possible to install nvf without depending on NixOS or Home-Manager as the parent module system, using the neovimConfiguration function exposed in the extended library. This function will take modules and extraSpecialArgs as arguments, and return the following schema as a result.

{
@@ -224,7 +224,7 @@ the default theme enabled. You may use other options inside  
  
   
    
Module Installation   
  
 
 
Table of Contents
 
  
   NixOS Module 
   Example Installation 
   Home-Manager Module 
   Example Installation 
 
The below chapters will describe installing nvf as NixOS and Home-Manager
+

Module Installation

Table of Contents

NixOS Module
Home-Manager Module

The below chapters will describe installing nvf as NixOS and Home-Manager modules. Note that those methods are mutually exclusive, and will likely cause path collisions if used simultaneously.

NixOS Module

Table of Contents

Example Installation

The NixOS module allows us to customize the different vim options from inside the NixOS configuration without having to call for the wrapper yourself. It is @@ -359,7 +359,7 @@ installation sections of the manual. You may find all available options in the

-

Configuring nvf

Table of Contents

Custom Neovim Package
Custom Plugins
Adding Plugins
Custom Inputs
Language Support
LSP Custom Packages/Command
Using DAGs
entryAnywhere
entryAfter
entryBefore
entryBetween
entriesAnywhere
entriesAfter
entriesBefore
entriesBetween
DAG entries in nvf
vim.luaConfigRC (top-level DAG)

Custom Neovim Package

As of v0.5, you may now specify the Neovim package that will be wrapped with +

Configuring nvf

Table of Contents

Custom Neovim Package
Custom Plugins
Custom Inputs
Language Support
Using DAGs
DAG entries in nvf

Custom Neovim Package

As of v0.5, you may now specify the Neovim package that will be wrapped with your configuration. This is done with the vim.package option.

{inputs, pkgs, ...}: {
   # using the neovim-nightly overlay
   vim.package = inputs.neovim-overlay.packages.${pkgs.system}.neovim;
@@ -371,7 +371,7 @@ the neovim package, similar to neovim-unwrapped in
   vim.package = pkgs.neovim-unwrapped;
 }
-

Custom Plugins

Table of Contents

Adding Plugins
Configuring
Lazy Method
Non-lazy Method
Legacy Method

nvf, by default, exposes a wide variety of plugins as module options for +

Custom Plugins

Table of Contents

Adding Plugins

nvf, by default, exposes a wide variety of plugins as module options for your convenience and bundles necessary dependencies into nvf’s runtime. In case a plugin is not available in nvf, you may consider making a pull request to nvf to include it as a module or you may add it to your @@ -661,21 +661,107 @@ direct DAG, but is converted to, and resolved as one internally

    • -

    Helpful Tips

    Table of Contents

    Debugging nvf
    Offline Documentation

    Debugging nvf

    There may be instances where the your Nix configuration evaluates to invalid +

    Helpful Tips

    Table of Contents

    Pure Lua Configuration
    Debugging nvf
    Offline Documentation

    Pure Lua Configuration

    Table of Contents

    Pure Runtime Directory
    Impure Absolute Directory

    We recognize that you might not always want to configure your setup purely in +Nix, sometimes doing things in Lua is simply the “superior” option. In such a +case you might want to configure your Neovim instance using Lua, and nothing but +Lua. It is also possible to mix Lua and Nix configurations.

    Pure Lua or hybrid Lua/Nix configurations can be achieved in two different ways. +Purely, by modifying Neovim’s runtime directory or impurely by placing Lua +configuration in a directory found in $HOME. For your convenience, this +section will document both methods as they can be used.

    Pure Runtime Directory

    As of 0.6, nvf allows you to modify Neovim’s runtime path to suit your needs. +One of the ways the new runtime option is to add a configuration located +relative to your flake.nix, which must be version controlled in pure flakes +manner.

    {
+  # Let us assume we are in the repository root, i.e., the same directory as the
+  # flake.nix. For the sake of the argument, we will assume that the Neovim lua
+  # configuration is in a nvim/ directory relative to flake.nix.
+  vim = {
+    additionalRuntimeDirectories = [
+      # This will be added to Neovim's runtime paths. Conceptually, this behaves
+      # very similarly to ~/.config/nvim but you may not place a top-level
+      # init.lua to be able to require it directly.
+      ./nvim
+    ];
+  };
+}
+

    This will add the nvim directory, or rather, the store path that will be +realised after your flake gets copied to the Nix store, to Neovim’s runtime +directory. You may now create a lua/myconfig directory within this nvim +directory, and call it with vim.luaConfigRC.

    {pkgs, ...}: {
+  vim = {
+    additionalRuntimeDirectories = [
+      # You can list more than one file here.
+      ./nvim-custom-1
+
+      # To make sure list items are ordered, use lib.mkBefore or lib.mkAfter
+      # Simply placing list items in a given order will **not** ensure that
+      # this list  will be deterministic.
+      ./nvim-custom-2
+    ];
+
+    startPlugins = [pkgs.vimPlugins.gitsigns];
+
+    # Neovim supports in-line syntax highlighting for multi-line strings.
+    # Simply place the filetype in a /* comment */ before the line.
+    luaConfigRC.myconfig = /* lua */ ''
+      -- Call the Lua module from ./nvim/lua/myconfig
+      require("myconfig")
+
+      -- Any additional Lua configuration that you might want *after* your own
+      -- configuration. For example, a plugin setup call.
+      require('gitsigns').setup({})
+    '';
+  };
+}
+
    +

    Impure Absolute Directory

    As of Neovim 0.9, $NVIM_APPNAME is a variable expected by Neovim to +decide on the configuration directory. nvf sets this variable as "nvf", +meaning ~/.config/nvf will be regarded as the configuration directory by +Neovim, similar to how ~/.config/nvim behaves in regular installations. This +allows some degree of Lua configuration, backed by our low-level wrapper +mnw. Creating a lua/ directory located in +$NVIM_APPNAME (“nvf” by default) and placing your configuration in, e.g., +~/.config/nvf/lua/myconfig will allow you to require it as a part of the Lua +module system through nvf’s module system.

    Let’s assume your ~/.config/nvf/lua/myconfig/init.lua consists of the +following:

    -- init.lua
+vim.keymap.set("n", " ", "<Nop>", { silent = true, remap = false })
+vim.g.mapleader = " "
+

    The following Nix configuration via vim.luaConfigRC will allow loading +this

    {
+  # The attribute name "myconfig-dir" here is arbitrary. It is required to be
+  # a *named* attribute by the DAG system, but the name is entirely up to you.
+  vim.luaConfigRC.myconfig-dir = ''
+    require("myconfig")
+
+    -- Any additional Lua
+  '';
+}
+

    After you load your custom configuration, you may use an init.lua located in +your custom configuration directory to configure Neovim exactly as you would +without a wrapper like nvf. If you want to place your require call in a +specific position (i.e., before or after options you set in nvf) the +DAG system will let you place your configuration in a location of your +choosing.

    +
    + +

    Debugging nvf

    Table of Contents

    Accessing neovimConfig

    There may be instances where the your Nix configuration evaluates to invalid Lua, or times when you will be asked to provide your built Lua configuration for easier debugging by nvf maintainers. nvf provides two helpful utilities out of the box.

    nvf-print-config and nvf-print-config-path will be bundled with nvf as lightweight utilities to help you view or share your built configuration when necessary.

    To view your configuration with syntax highlighting, you may use the bat pager.

    nvf-print-config | bat --language=lua
-

    Alternatively, cat or less may also be used.

    +

    Alternatively, cat or less may also be used.

    Accessing neovimConfig

    It is also possible to access the configuration for the wrapped package. The +built Neovim package will contain a neovimConfig attribute in its +passthru.

    +
    +

    Offline Documentation

    The manpages provided by nvf contains an offline version of the option search normally available at https://notashelf.github.io/nvf/options.html. You may use the man 5 nvf command to view option documentation from the comfort of your terminal.

    Note that this is only available for NixOS and Home-Manager module installations.

    -

    Hacking nvf

    Table of Contents

    Getting Started
    Guidelines
    Adding Documentation
    Formatting Code
    Formatting Commits
    Commit Style
    Example Commit
    Code Style
    Testing Changes
    Keybinds
    Custom Key Mappings Support for a Plugin
    Adding Plugins
    Modular setup options
    Details of toLuaObject
    Lazy plugins

    nvf is designed for the developer as much as it is designed for the end-user. We +

    Hacking nvf

    Table of Contents

    Getting Started
    Guidelines
    Testing Changes
    Keybinds
    Adding Plugins

    nvf is designed for the developer as much as it is designed for the end-user. We would like for any contributor to be able to propagate their changes, or add new features to the project with minimum possible friction. As such, below are the guides and guidelines written to streamline the contribution process and to diff --git a/docs-preview-591/options.html b/docs-preview-591/options.html index 7635681a..f61d2364 100644 --- a/docs-preview-591/options.html +++ b/docs-preview-591/options.html @@ -4,7 +4,7 @@ - Appendix B. Neovim Flake Configuration Options + Appendix B. nvf Configuration Options @@ -15,7 +15,7 @@

    - + @@ -24,9 +24,11 @@
    Appendix B. Neovim Flake Configuration OptionsAppendix B. nvf Configuration Options
    Prev 
    -

    Appendix B. Neovim Flake Configuration Options

    Below are the module options provided by nvf, in no particular order. Most +

    Appendix B. nvf Configuration Options

    Below are the module options provided by nvf, in no particular order. Most options will include useful comments, warnings or setup tips on how a module -option is meant to be used as well as examples in complex cases.

    +option is meant to be used as well as examples in complex cases.

    An offline version of this page is bundled with nvf as a part of the manpages +which you can access with man 5 nvf. Please us know if you believe any of the +options below are missing useful examples.

    diff --git a/docs-preview-591/quirks.html b/docs-preview-591/quirks.html index 4ff1fa95..94944908 100644 --- a/docs-preview-591/quirks.html +++ b/docs-preview-591/quirks.html @@ -9,7 +9,7 @@ - +
    @@ -48,7 +48,7 @@ wants.

    Solutions are:

      nvf manual  Home -  Appendix B. Neovim Flake Configuration Options +  Appendix B. nvf Configuration Options
    diff --git a/docs-preview-591/release-notes.html b/docs-preview-591/release-notes.html index 4cf04722..b38f9392 100644 --- a/docs-preview-591/release-notes.html +++ b/docs-preview-591/release-notes.html @@ -9,7 +9,7 @@ - +
    @@ -226,7 +226,7 @@ string of enum, or a Lua function. The default is “compact”, but you may change it according to nvim-notify documentation.

    -

    Release 0.7

    Table of Contents

    Breaking Changes and Migration Guide
    vim.configRC removed
    vim.maps rewrite
    vim.lsp.nvimCodeActionMenu removed in favor of vim.ui.fastaction
    type based modules removed
    nixpkgs-fmt removed in favor of nixfmt
    leader changes
    vim.* changes
    Changelog

    Release notes for release 0.7

    Breaking Changes and Migration Guide

    vim.configRC removed
    vim.maps rewrite
    vim.lsp.nvimCodeActionMenu removed in favor of vim.ui.fastaction
    type based modules removed
    nixpkgs-fmt removed in favor of nixfmt
    leader changes
    vim.* changes

    vim.configRC removed

    In v0.7 we are removing vim.configRC in favor of making vim.luaConfigRC the +

    Release 0.7

    Table of Contents

    Breaking Changes and Migration Guide
    Changelog

    Release notes for release 0.7

    Breaking Changes and Migration Guide

    vim.configRC removed
    vim.maps rewrite
    vim.lsp.nvimCodeActionMenu removed in favor of vim.ui.fastaction
    type based modules removed
    nixpkgs-fmt removed in favor of nixfmt
    leader changes
    vim.* changes

    vim.configRC removed

    In v0.7 we are removing vim.configRC in favor of making vim.luaConfigRC the top-level DAG, and thereby making the entire configuration Lua based. This change introduces a few breaking changes: