mirror of
https://github.com/NotAShelf/nvf.git
synced 2024-11-22 13:20:44 +00:00
docs/manual: add more details to existing documentation pages
This commit is contained in:
parent
96c568f99b
commit
0c848869cf
7 changed files with 131 additions and 39 deletions
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
pkgs,
|
||||
lib ? import ../lib/stdlib-extended.nix pkgs.lib,
|
||||
lib,
|
||||
nmdSrc,
|
||||
}: let
|
||||
nmd = import nmdSrc {
|
||||
|
|
|
|||
|
|
@ -18,8 +18,8 @@
|
|||
<xi:include href="manual/try-it-out.xml"/>
|
||||
<xi:include href="manual/default-configs.xml"/>
|
||||
<xi:include href="manual/custom-configs.xml"/>
|
||||
<xi:include href="manual/custom-plugins.xml"/>
|
||||
<xi:include href="manual/custom-package.xml"/>
|
||||
<xi:include href="manual/custom-plugins.xml"/>
|
||||
<xi:include href="manual/home-manager.xml"/>
|
||||
<xi:include href="manual/languages.xml"/>
|
||||
<xi:include href="manual/hacking.xml"/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
[[ch-custom-configuration]]
|
||||
== Custom Configuration
|
||||
|
||||
Custom configuration is done with the `neovimConfiguration` function. It takes in the configuration as a module. The output of the configuration function is an attrset.
|
||||
Custom configuration is done with the `neovimConfiguration` while using the flake as a standalone package.
|
||||
It takes in the configuration as a module. The output of the configuration function is an attrset.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
|
|
@ -40,8 +41,28 @@ The following is an example of a barebones vim configuration with the default th
|
|||
inherit pkgs;
|
||||
};
|
||||
in {
|
||||
# this will make the package available as a flake input
|
||||
packages.${system}.neovim = customNeovim.neovim;
|
||||
|
||||
# this is an example nixosConfiguration using the built neovim package
|
||||
nixosConfigurations = {
|
||||
yourHostName = nixpkgs.lib.nixosSystem {
|
||||
# ...
|
||||
modules = [
|
||||
./configuration.nix # or whatever your configuration is
|
||||
|
||||
# this will make wrapped neovim available in your system packages
|
||||
{environment.systemPackages = [customNeovim.neovim];}
|
||||
];
|
||||
# ...
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
Your built neovim configuration can be exposed as a flake output, or be added to your system packages to make
|
||||
it available across your system. You may also consider passing the flake output to home-manager to make it available
|
||||
to a specific user *without* using the home-manager module.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
You can use custom plugins, before they are implemented in the flake.
|
||||
To add a plugin, you need to add it to your config's `config.vim.startPlugins` array.
|
||||
|
||||
|
||||
[[sec-new-method]]
|
||||
=== New Method
|
||||
As of version 0.5, we have a more extensive API for configuring plugins, under `vim.extraPlugins`.
|
||||
|
||||
|
|
@ -22,7 +22,7 @@ Instead of using DAGs exposed by the library, you may use the extra plugin modul
|
|||
}
|
||||
'';
|
||||
};
|
||||
|
||||
|
||||
harpoon = {
|
||||
package = harpoon;
|
||||
setup = "require('harpoon').setup {}";
|
||||
|
|
@ -32,8 +32,10 @@ Instead of using DAGs exposed by the library, you may use the extra plugin modul
|
|||
}
|
||||
----
|
||||
|
||||
[[sec-old-method]]
|
||||
=== Old Method
|
||||
Users who have not yet updated to 0.5, or prefer a more hands-on approach may use the old method where the load orderof the plugins is determined by DAGs.
|
||||
Users who have not yet updated to 0.5, or prefer a more hands-on approach may use the old method where the load order
|
||||
of the plugins is determined by DAGs.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
|
|
@ -50,16 +52,23 @@ Users who have not yet updated to 0.5, or prefer a more hands-on approach may us
|
|||
}
|
||||
----
|
||||
|
||||
However, just making the plugin available might not be enough. In that case, you can write custom vimscript or lua config, using `config.vim.configRC` or `config.vim.luaConfigRC` respectively.
|
||||
However, just making the plugin available might not be enough. In that case, you can write custom vimscript
|
||||
or lua config, using `config.vim.configRC` or `config.vim.luaConfigRC` respectively.
|
||||
These options are attribute sets, and you need to give the configuration you're adding some name, like this:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
{
|
||||
# this will create an "aquarium" section in your init.vim with the contents of your custom config
|
||||
# which will be *appended* to the rest of your configuration, inside your init.vim
|
||||
config.vim.configRC.aquarium = "colorscheme aquiarum";
|
||||
}
|
||||
----
|
||||
|
||||
Note: If your configuration needs to be put in a specific place in the config, you can use functions from `inputs.neovim-flake.lib.nvim.dag` to order it. Refer to https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix.
|
||||
Note: If your configuration needs to be put in a specific place in the config, you can use functions from
|
||||
`inputs.neovim-flake.lib.nvim.dag` to order it.
|
||||
Refer to https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix to find out more about
|
||||
the DAG system.
|
||||
|
||||
Also, if you successfully made your plugin work, please make a PR to add it to the flake, or open an issue with your findings so that we can make it available for everyone easily.
|
||||
Also, if you successfully made your plugin work, please make a PR to add it to the flake, or open an issue
|
||||
with your findings so that we can make it available for everyone easily.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,10 @@
|
|||
[[ch-hm-module]]
|
||||
== Home Manager
|
||||
|
||||
The Home Manager module allows us to customize the different `vim` options. To use it, we first add the input flake.
|
||||
The Home Manager module allows us to customize the different `vim` options from inside the home-manager configuration
|
||||
and it is the preferred way of configuring neovim-flake, both on NixOS and non-NixOS systems.
|
||||
|
||||
To use it, we first add the input flake.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
|
|
@ -10,20 +13,49 @@ The Home Manager module allows us to customize the different `vim` options. To u
|
|||
url = github:notashelf/neovim-flake;
|
||||
# you can override input nixpkgs
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
# you can also override individual plugins
|
||||
# i.e inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- obsidian nvim needs to be in your inputs
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
Followed by importing the HM module.
|
||||
Followed by importing the home-manager module somewhere in your configuration.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
{
|
||||
imports = [ neovim-flake.homeManagerModules.default ];
|
||||
# assuming neovim-flake is in your inputs and inputs is in the argset
|
||||
imports = [ inputs.neovim-flake.homeManagerModules.default ];
|
||||
}
|
||||
----
|
||||
|
||||
Then we should be able to use the given module. E.g.
|
||||
An example installation for standalone home-manager would look like this:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
{
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
home-manager.url = "github:nix-community/home-manager";
|
||||
stylix.url = "github:notashelf/neovim-flake";
|
||||
};
|
||||
|
||||
outputs = { nixpkgs, home-manager, neovim-flake ... }: let
|
||||
system = "x86_64-linux"; in {
|
||||
# ↓ this is the home-manager output in the flake schema
|
||||
homeConfigurations."yourUsername»" = home-manager.lib.homeManagerConfiguration {
|
||||
pkgs = nixpkgs.legacyPackages.x86_64-linux;
|
||||
modules = [
|
||||
neovim-flake.homeManagerModules.default # <- this imports the home-manager module that provides the options
|
||||
./home.nix # your home-manager configuration, probably where you will want to add programs.neovim-flake options
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
Once the module is imported, we will be able to define the following options (and much more) from inside the
|
||||
home-manager configuration.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
|
|
@ -31,7 +63,8 @@ Then we should be able to use the given module. E.g.
|
|||
programs.neovim-flake = {
|
||||
|
||||
enable = true;
|
||||
# your settings need to go into the settings attrset
|
||||
# your settings need to go into the settings attribute set
|
||||
# most settings are documented in the appendix
|
||||
settings = {
|
||||
vim.viAlias = false;
|
||||
vim.vimAlias = true;
|
||||
|
|
@ -43,4 +76,10 @@ Then we should be able to use the given module. E.g.
|
|||
}
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
You may find all avaliable options in the https://notashelf.github.io/neovim-flake/options[appendix]
|
||||
====
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -15,21 +15,25 @@ Language specific support means there is a combination of language specific plug
|
|||
* SQL: <<opt-vim.languages.sql.enable>>
|
||||
* Dart: <<opt-vim.languages.dart.enable>>
|
||||
* Go: <<opt-vim.languages.go.enable>>
|
||||
* Lua: <<opt-vim.languages.lua.enable>>
|
||||
|
||||
Adding support for more languages, and improving support for existing ones are great places where you can contribute with a PR.
|
||||
Adding support for more languages, and improving support for existing ones are great places
|
||||
where you can contribute with a PR.
|
||||
|
||||
=== LSP Custom Packages/Command
|
||||
|
||||
In any of the `opt.languages.<language>.lsp.package` options you can provide your own LSP package, or provide the command to launch the language server, as a list of strings.
|
||||
In any of the `opt.languages.<language>.lsp.package` options you can provide your own LSP package, or provide
|
||||
the command to launch the language server, as a list of strings.
|
||||
|
||||
You can use this to skip automatic installation of a language server, and instead use the one found in your `$PATH` during runtime, for example:
|
||||
You can use this to skip automatic installation of a language server, and instead
|
||||
use the one found in your `$PATH` during runtime, for example:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
vim.languages.java = {
|
||||
lsp = {
|
||||
enable = true;
|
||||
package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
|
||||
};
|
||||
lsp = {
|
||||
enable = true;
|
||||
package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
|
||||
};
|
||||
}
|
||||
----
|
||||
|
|
|
|||
|
|
@ -1,34 +1,53 @@
|
|||
[[ch-try-it-out]]
|
||||
== Try it out
|
||||
|
||||
Thanks to the portability of Nix, you can try out neovim-flake 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, three
|
||||
configurations are provided:
|
||||
|
||||
* Nix
|
||||
* Tidal
|
||||
* Maximal
|
||||
|
||||
You may try out any of the provided configurations using the `nix run` command on a system where Nix is installed.
|
||||
|
||||
[source,console]
|
||||
----
|
||||
$ cachix use neovim-flake # Optional: it'll save you CPU resources and time
|
||||
$ nix run github:notashelf/neovim-flake # will run the default configuration
|
||||
$ nix run github:notashelf/neovim-flake#nix # will run the default minimal configuration
|
||||
----
|
||||
|
||||
Do keep in mind that this is **susceptible to garbage collection** meaning it will be removed from your Nix store
|
||||
once you garbage collect. If you wish to install neovim-flake, please take a look at
|
||||
<<ch-custom-configuration,custom-configuration>> or <<ch-hm-module,home-manager>> sections for installation
|
||||
instructions.
|
||||
|
||||
=== Nix
|
||||
|
||||
By default LSP support for Nix is enabled alongside all complementary Neovim plugins. By running `nix run .`, which is the default package,
|
||||
you will build Neovim with this config.
|
||||
|
||||
=== Tidal
|
||||
|
||||
Tidal is an alternative config that adds vim-tidal on top of the plugins from the Nix configuration.
|
||||
|
||||
=== Maximal
|
||||
|
||||
Maximal is the ultimate configuration that will enable basically everything. Keep in mind, however, that this will pull a lot of dependencies.
|
||||
|
||||
You are strongly recommended to use the binary cache if you would like to try the Maximal configuration.
|
||||
|
||||
|
||||
[[sec-using-prebuild-configs]]
|
||||
=== Using Prebuilt Configs
|
||||
|
||||
[source,console]
|
||||
----
|
||||
$ nix run github:notashelf/neovim-flake#nix
|
||||
$ nix run github:notashelf/neovim-flake#nix
|
||||
$ nix run github:notashelf/neovim-flake#tidal
|
||||
$ nix run github:notashelf/neovim-flake#maximal
|
||||
----
|
||||
|
||||
|
||||
[[sec-available-configs]]
|
||||
=== Available Configs
|
||||
|
||||
==== Nix
|
||||
|
||||
`Nix` configuration by default provides LSP/diagnostic support for Nix alongisde a set of visual and functional plugins.
|
||||
By running `nix run .`, which is the default package, you will build Neovim with this config.
|
||||
|
||||
==== Tidal
|
||||
|
||||
Tidal is an alternative config that adds vim-tidal on top of the plugins from the Nix configuration.
|
||||
|
||||
==== Maximal
|
||||
|
||||
`Maximal` is the ultimate configuration that will enable support for more commonly used language as well as additional
|
||||
complementary plugins. Keep in mind, however, that this will pull a lot of dependencies.
|
||||
|
||||
You are *strongly* recommended to use the binary cache if you would like to try the Maximal configuration.
|
||||
|
|
|
|||
Loading…
Reference in a new issue