mirror of
https://github.com/NotAShelf/nvf.git
synced 2025-10-01 14:33:28 +00:00
docs: restructure to allow a clean migration to new documentation util
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I6a6a6964afba43bdda6a2cbf037404ca3fa4f8c9
This commit is contained in:
parent
6e1d539712
commit
b9dd1b816a
27 changed files with 760 additions and 898 deletions
103
docs/manual.nix
103
docs/manual.nix
|
@ -1,32 +1,38 @@
|
|||
{
|
||||
inputs,
|
||||
stdenvNoCC,
|
||||
runCommandLocal,
|
||||
# build inputs
|
||||
path,
|
||||
# nrd configuration
|
||||
release,
|
||||
stdenvNoCC,
|
||||
runCommandNoCCLocal,
|
||||
optionsJSON,
|
||||
} @ args: let
|
||||
manual-release = args.release or "unstable";
|
||||
in
|
||||
runCommandLocal "hjem-docs" {
|
||||
nativeBuildInputs = [inputs.ndg.packages.${stdenvNoCC.system}.ndg];
|
||||
runCommandNoCCLocal "nvf-docs-html" {
|
||||
nativeBuildInputs = [
|
||||
(inputs.ndg.packages.${stdenvNoCC.system}.ndg.overrideAttrs
|
||||
{
|
||||
# FIXME: the tests take too long to build
|
||||
doCheck = false;
|
||||
})
|
||||
];
|
||||
} ''
|
||||
mkdir -p $out/share/doc
|
||||
|
||||
# Copy the markdown sources to be processed by ndg
|
||||
# Copy the markdown sources to be processed by ndg. This is not
|
||||
# strictly necessary, but allows us to modify the Markdown sources
|
||||
# as we see fit.
|
||||
cp -rvf ${./manual} ./manual
|
||||
|
||||
substituteInPlace ./manual/options.md \
|
||||
--subst-var-by OPTIONS_JSON ./config-options.json
|
||||
|
||||
# Replace variables following the @VARIABLE@ style in the manual
|
||||
# pages. This can be built into ndg at a later date.
|
||||
substituteInPlace ./manual/index.md \
|
||||
--subst-var-by NVF_VERSION ${manual-release}
|
||||
|
||||
substituteInPlace ./manual/hacking/additional-plugins.md \
|
||||
--subst-var-by NVF_REPO "https://github.com/notashelf/nvf/blob/${manual-release}"
|
||||
|
||||
# Generate the final manual from a set of parameters. This uses
|
||||
# feel-co/ndg to render the web manual.
|
||||
ndg html \
|
||||
--jobs $NIX_BUILD_CORES --title "NVF" \
|
||||
--module-options ${optionsJSON}/share/doc/nixos/options.json \
|
||||
|
@ -41,78 +47,3 @@ in
|
|||
mkdir -p $out/nix-support/
|
||||
echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products
|
||||
''
|
||||
/*
|
||||
stdenvNoCC.mkDerivation {
|
||||
name = "nvf-manual";
|
||||
src = builtins.path {
|
||||
name = "nvf-manual-${manual-release}";
|
||||
path = lib.sourceFilesBySuffices ./manual [".md" ".md.in"];
|
||||
};
|
||||
|
||||
strictDependencies = true;
|
||||
nativeBuildInputs = [nixos-render-docs];
|
||||
|
||||
postPatch = ''
|
||||
ln -s ${optionsJSON}/share/doc/nixos/options.json ./config-options.json
|
||||
'';
|
||||
|
||||
buildPhase = ''
|
||||
dest="$out/share/doc/nvf"
|
||||
mkdir -p "$(dirname "$dest")"
|
||||
mkdir -p $dest/{highlightjs,script}
|
||||
|
||||
# Copy highlight scripts to /highlights in document root.
|
||||
cp -vt $dest/highlightjs \
|
||||
${documentation-highlighter}/highlight.pack.js \
|
||||
${documentation-highlighter}/LICENSE \
|
||||
${documentation-highlighter}/mono-blue.css \
|
||||
${documentation-highlighter}/loader.js
|
||||
|
||||
# Copy anchor scripts to the script directory in document root.
|
||||
cp -vt "$dest"/script \
|
||||
${./static/script}/anchor-min.js \
|
||||
${./static/script}/anchor-use.js \
|
||||
${./static/script}/search.js
|
||||
|
||||
|
||||
|
||||
# Move compiled stylesheet
|
||||
cp -vt $dest \
|
||||
${compileStylesheet}/style.css
|
||||
|
||||
# Move release notes
|
||||
cp -vr ${./release-notes} release-notes
|
||||
|
||||
# Generate final manual from a set of parameters. Explanation of the CLI flags are
|
||||
# as follows:
|
||||
#
|
||||
# 1. --manpage-urls will allow you to use manual pages as they are defined in
|
||||
# the nixpkgs documentation.
|
||||
# 2. --revision is the project revision as it is defined in 'release.json' in the
|
||||
# repository root
|
||||
# 3. --script will inject a given Javascript file into the resulting pages inside
|
||||
# the <script> tag.
|
||||
# 4. --toc-depth will determine the depth of the initial Table of Contents while
|
||||
# --section-toc-depth will determine the depth of per-section Table of Contents
|
||||
# sections.
|
||||
nixos-render-docs manual html \
|
||||
--manpage-urls ${path + "/doc/manpage-urls.json"} \
|
||||
--revision ${lib.trivial.revisionWithDefault manual-release} \
|
||||
--stylesheet style.css \
|
||||
--script highlightjs/highlight.pack.js \
|
||||
--script highlightjs/loader.js \
|
||||
--script script/anchor-use.js \
|
||||
--script script/anchor-min.js \
|
||||
--script script/search.js \
|
||||
--toc-depth 1 \
|
||||
--section-toc-depth 1 \
|
||||
manual.md \
|
||||
"$dest/index.xhtml"
|
||||
|
||||
# Hydra support. Probably not necessary.
|
||||
mkdir -p $out/nix-support/
|
||||
echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products
|
||||
'';
|
||||
}
|
||||
*/
|
||||
|
||||
|
|
|
@ -1,6 +1,7 @@
|
|||
# Configuring nvf {#ch-configuring}
|
||||
|
||||
[helpful tips section]: #ch-helpful-tips
|
||||
[options reference]: /nvf/options.html
|
||||
|
||||
nvf allows for _very_ extensive configuration in Neovim through the Nix module
|
||||
interface. The below chapters describe several of the options exposed in nvf for
|
||||
|
@ -8,7 +9,7 @@ your convenience. You might also be interested in the [helpful tips section] for
|
|||
more advanced or unusual configuration options supported by nvf.
|
||||
|
||||
Note that this section does not cover module _options_. For an overview of all
|
||||
module options provided by nvf, please visit the [appendix](/nvf/options.html)
|
||||
module options provided by nvf, please visit the [options reference]
|
||||
|
||||
```{=include=} chapters
|
||||
configuring/custom-package.md
|
||||
|
|
|
@ -21,10 +21,587 @@ ideally also include relevant context in which an issue occurs or a feature
|
|||
should be implemented. If you wish to make a contribution, but feel stuck -
|
||||
please do not be afraid to submit a pull request, we will help you get it in.
|
||||
|
||||
```{=include=} sections
|
||||
hacking/getting-started.md
|
||||
hacking/guidelines.md
|
||||
hacking/testing.md
|
||||
hacking/keybinds.md
|
||||
hacking/additional-plugins.md
|
||||
## Getting Started {#sec-contrib-getting-started}
|
||||
|
||||
You, naturally, would like to start by forking the repository to get started. If
|
||||
you are new to Git and GitHub, do have a look at GitHub's
|
||||
[Fork a repo guide](https://help.github.com/articles/fork-a-repo/) for
|
||||
instructions on how you can do this. Once you have a fork of **nvf**, you should
|
||||
create a separate branch based on the most recent `main` branch. Give your
|
||||
branch a reasonably descriptive name (e.g. `feature/debugger` or
|
||||
`fix/pesky-bug`) and you are ready to work on your changes
|
||||
|
||||
Implement your changes and commit them to the newly created branch and when you
|
||||
are happy with the result, and positive that it fulfills our
|
||||
[Contributing Guidelines](#sec-guidelines), push the branch to GitHub and
|
||||
[create a pull request](https://help.github.com/articles/creating-a-pull-request).
|
||||
The default pull request template available on the **nvf** repository will guide
|
||||
you through the rest of the process, and we'll gently nudge you in the correct
|
||||
direction if there are any mistakes.
|
||||
|
||||
## Guidelines {#sec-guidelines}
|
||||
|
||||
If your contribution tightly follows the guidelines, then there is a good chance
|
||||
it will be merged without too much trouble. Some of the guidelines will be
|
||||
strictly enforced, others will remain as gentle nudges towards the correct
|
||||
direction. As we have no automated system enforcing those guidelines, please try
|
||||
to double check your changes before making your pull request in order to avoid
|
||||
"faulty" code slipping by.
|
||||
|
||||
If you are uncertain how these rules affect the change you would like to make
|
||||
then feel free to start a discussion in the
|
||||
[discussions tab](https://github.com/NotAShelf/nvf/discussions) ideally (but not
|
||||
necessarily) before you start developing.
|
||||
|
||||
### Adding Documentation {#sec-guidelines-documentation}
|
||||
|
||||
[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax
|
||||
|
||||
Almost all changes warrant updates to the documentation: at the very least, you
|
||||
must update the changelog. Both the manual and module options use
|
||||
[Nixpkgs Flavoured Markdown].
|
||||
|
||||
The HTML version of this manual containing both the module option descriptions
|
||||
and the documentation of **nvf** (such as this page) can be generated and opened
|
||||
by typing the following in a shell within a clone of the **nvf** Git repository:
|
||||
|
||||
```console
|
||||
$ nix build .#docs-html
|
||||
$ xdg-open $PWD/result/share/doc/nvf/index.html
|
||||
```
|
||||
|
||||
### Formatting Code {#sec-guidelines-formatting}
|
||||
|
||||
Make sure your code is formatted as described in
|
||||
[code-style section](#sec-guidelines-code-style). To maintain consistency
|
||||
throughout the project you are encouraged to browse through existing code and
|
||||
adopt its style also in new code.
|
||||
|
||||
### Formatting Commits {#sec-guidelines-commit-message-style}
|
||||
|
||||
Similar to [code style guidelines](#sec-guidelines-code-style) we encourage a
|
||||
consistent commit message format as described in
|
||||
[commit style guidelines](#sec-guidelines-commit-style).
|
||||
|
||||
### Commit Style {#sec-guidelines-commit-style}
|
||||
|
||||
The commits in your pull request should be reasonably self-contained. Which
|
||||
means each and every commit in a pull request should make sense both on its own
|
||||
and in general context. That is, a second commit should not resolve an issue
|
||||
that is introduced in an earlier commit. In particular, you will be asked to
|
||||
amend any commit that introduces syntax errors or similar problems even if they
|
||||
are fixed in a later commit.
|
||||
|
||||
The commit messages should follow the
|
||||
[seven rules](https://chris.beams.io/posts/git-commit/#seven-rule), except for
|
||||
"Capitalize the subject line". We also ask you to include the affected code
|
||||
component or module in the first line. A commit message ideally, but not
|
||||
necessarily, follow the given template from home-manager's own documentation
|
||||
|
||||
```
|
||||
{component}: {description}
|
||||
|
||||
{long description}
|
||||
```
|
||||
|
||||
where `{component}` refers to the code component (or module) your change
|
||||
affects, `{description}` is a very brief description of your change, and
|
||||
`{long description}` is an optional clarifying description. As a rare exception,
|
||||
if there is no clear component, or your change affects many components, then the
|
||||
`{component}` part is optional. See
|
||||
[example commit message](#sec-guidelines-ex-commit-message) for a commit message
|
||||
that fulfills these requirements.
|
||||
|
||||
#### Example Commit {#sec-guidelines-ex-commit-message}
|
||||
|
||||
The commit
|
||||
[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef)
|
||||
in home-manager contains the following commit message.
|
||||
|
||||
```
|
||||
starship: allow running in Emacs if vterm is used
|
||||
|
||||
The vterm buffer is backed by libvterm and can handle Starship prompts
|
||||
without issues.
|
||||
```
|
||||
|
||||
Similarly, if you are contributing to **nvf**, you would include the scope of
|
||||
the commit followed by the description:
|
||||
|
||||
```
|
||||
languages/ruby: init module
|
||||
|
||||
Adds a language module for Ruby, adds appropriate formatters and Treesitter grammars
|
||||
```
|
||||
|
||||
Long description can be omitted if the change is too simple to warrant it. A
|
||||
minor fix in spelling or a formatting change does not warrant long description,
|
||||
however, a module addition or removal does as you would like to provide the
|
||||
relevant context, i.e. the reasoning behind it, for your commit.
|
||||
|
||||
Finally, when adding a new module, say `modules/foo.nix`, we use the fixed
|
||||
commit format `foo: add module`. You can, of course, still include a long
|
||||
description if you wish.
|
||||
|
||||
In case of nested modules, i.e `modules/languages/java.nix` you are recommended
|
||||
to contain the parent as well - for example `languages/java: some major change`.
|
||||
|
||||
### Code Style {#sec-guidelines-code-style}
|
||||
|
||||
#### Treewide {#sec-code-style-treewide}
|
||||
|
||||
Keep lines at a reasonable width, ideally 80 characters or less. This also
|
||||
applies to string literals and module descriptions and documentation.
|
||||
|
||||
#### Nix {#sec-code-style-nix}
|
||||
|
||||
[alejandra]: https://github.com/kamadorueda/alejandra
|
||||
|
||||
**nvf** is formatted by the [alejandra] tool and the formatting is checked in
|
||||
the pull request and push workflows. Run the `nix fmt` command inside the
|
||||
project repository before submitting your pull request.
|
||||
|
||||
While Alejandra is mostly opinionated on how code looks after formatting,
|
||||
certain changes are done at the user's discretion based on how the original code
|
||||
was structured.
|
||||
|
||||
Please use one line code for attribute sets that contain only one subset. For
|
||||
example:
|
||||
|
||||
```nix
|
||||
# parent modules should always be unfolded
|
||||
# which means module = { value = ... } instead of module.value = { ... }
|
||||
module = {
|
||||
value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible
|
||||
|
||||
# same as parent modules, unfold submodules
|
||||
subModule = {
|
||||
# this is an option that contains more than one nested value
|
||||
# Note: try to be careful about the ordering of `mkOption` arguments.
|
||||
# General rule of thumb is to order from least to most likely to change.
|
||||
# This is, for most cases, type < default < description.
|
||||
# Example, if present, would be between default and description
|
||||
someOtherValue = mkOption {
|
||||
type = lib.types.bool;
|
||||
default = true;
|
||||
description = "Some other description";
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
If you move a line down after the merge operator, Alejandra will automatically
|
||||
unfold the whole merged attrset for you, which we **do not** want.
|
||||
|
||||
```nix
|
||||
module = {
|
||||
key = mkEnableOption "some description" // {
|
||||
default = true; # we want this to be inline
|
||||
}; # ...
|
||||
}
|
||||
```
|
||||
|
||||
For lists, it is mostly up to your own discretion how you want to format them,
|
||||
but please try to unfold lists if they contain multiple items and especially if
|
||||
they are to include comments.
|
||||
|
||||
```nix
|
||||
# this is ok
|
||||
acceptableList = [
|
||||
item1 # comment
|
||||
item2
|
||||
item3 # some other comment
|
||||
item4
|
||||
];
|
||||
|
||||
# this is not ok
|
||||
listToBeAvoided = [item1 item2 /* comment */ item3 item4];
|
||||
|
||||
# this is ok
|
||||
acceptableList = [item1 item2];
|
||||
|
||||
# this is also ok if the list is expected to contain more elements
|
||||
acceptableList= [
|
||||
item1
|
||||
item2
|
||||
# more items if needed...
|
||||
];
|
||||
```
|
||||
|
||||
## Testing Changes {#sec-testing-changes}
|
||||
|
||||
Once you have made your changes, you will need to test them thoroughly. If it is
|
||||
a module, add your module option to `configuration.nix` (located in the root of
|
||||
this project) inside `neovimConfiguration`. Enable it, and then run the maximal
|
||||
configuration with `nix run .#maximal -Lv` to check for build errors. If neovim
|
||||
opens in the current directory without any error messages (you can check the
|
||||
output of `:messages` inside neovim to see if there are any errors), then your
|
||||
changes are good to go. Open your pull request, and it will be reviewed as soon
|
||||
as possible.
|
||||
|
||||
If it is not a new module, but a change to an existing one, then make sure the
|
||||
module you have changed is enabled in the maximal configuration by editing
|
||||
`configuration.nix`, and then run it with `nix run .#maximal -Lv`. Same
|
||||
procedure as adding a new module will apply here.
|
||||
|
||||
## Keybinds {#sec-keybinds}
|
||||
|
||||
As of 0.4, there exists an API for writing your own keybinds and a couple of
|
||||
useful utility functions are available in the
|
||||
[extended standard library](https://github.com/NotAShelf/nvf/tree/main/lib). The
|
||||
following section contains a general overview to how you may utilize said
|
||||
functions.
|
||||
|
||||
## Custom Key Mappings Support for a Plugin {#sec-custom-key-mappings}
|
||||
|
||||
To set a mapping, you should define it in `vim.keymaps`.
|
||||
|
||||
An example, simple keybinding, can look like this:
|
||||
|
||||
```nix
|
||||
{
|
||||
vim.keymaps = [
|
||||
{
|
||||
key = "<leader>wq";
|
||||
mode = ["n"];
|
||||
action = ":wq<CR>";
|
||||
silent = true;
|
||||
desc = "Save file and quit";
|
||||
}
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
There are many settings available in the options. Please refer to the
|
||||
[documentation](https://notashelf.github.io/nvf/options.html#opt-vim.keymaps) to
|
||||
see a list of them.
|
||||
|
||||
**nvf** provides a helper function, so that you don't have to write the mapping
|
||||
attribute sets every time:
|
||||
|
||||
- `mkKeymap`, which mimics neovim's `vim.keymap.set` function
|
||||
|
||||
You can read the source code of some modules to see them in action, but the
|
||||
usage should look something like this:
|
||||
|
||||
```nix
|
||||
# plugindefinition.nix
|
||||
{lib, ...}: let
|
||||
inherit (lib.options) mkEnableOption;
|
||||
inherit (lib.nvim.binds) mkMappingOption;
|
||||
in {
|
||||
options.vim.plugin = {
|
||||
enable = mkEnableOption "Enable plugin";
|
||||
|
||||
# Mappings should always be inside an attrset called mappings
|
||||
mappings = {
|
||||
workspaceDiagnostics = mkMappingOption "Workspace diagnostics [trouble]" "<leader>lwd";
|
||||
documentDiagnostics = mkMappingOption "Document diagnostics [trouble]" "<leader>ld";
|
||||
lspReferences = mkMappingOption "LSP References [trouble]" "<leader>lr";
|
||||
quickfix = mkMappingOption "QuickFix [trouble]" "<leader>xq";
|
||||
locList = mkMappingOption "LOCList [trouble]" "<leader>xl";
|
||||
symbols = mkMappingOption "Symbols [trouble]" "<leader>xs";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
```nix
|
||||
# config.nix
|
||||
{
|
||||
config,
|
||||
lib,
|
||||
options,
|
||||
...
|
||||
}: let
|
||||
inherit (lib.modules) mkIf;
|
||||
inherit (lib.nvim.binds) mkKeymap;
|
||||
|
||||
cfg = config.vim.plugin;
|
||||
|
||||
keys = cfg.mappings;
|
||||
inherit (options.vim.lsp.trouble) mappings;
|
||||
in {
|
||||
config = mkIf cfg.enable {
|
||||
vim.keymaps = [
|
||||
(mkKeymap "n" keys.workspaceDiagnostics "<cmd>Trouble toggle diagnostics<CR>" {desc = mappings.workspaceDiagnostics.description;})
|
||||
(mkKeymap "n" keys.documentDiagnostics "<cmd>Trouble toggle diagnostics filter.buf=0<CR>" {desc = mappings.documentDiagnostics.description;})
|
||||
(mkKeymap "n" keys.lspReferences "<cmd>Trouble toggle lsp_references<CR>" {desc = mappings.lspReferences.description;})
|
||||
(mkKeymap "n" keys.quickfix "<cmd>Trouble toggle quickfix<CR>" {desc = mappings.quickfix.description;})
|
||||
(mkKeymap "n" keys.locList "<cmd>Trouble toggle loclist<CR>" {desc = mappings.locList.description;})
|
||||
(mkKeymap "n" keys.symbols "<cmd>Trouble toggle symbols<CR>" {desc = mappings.symbols.description;})
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> If you have come across a plugin that has an API that doesn't seem to easily
|
||||
> allow custom keybindings, don't be scared to implement a draft PR. We'll help
|
||||
> you get it done.
|
||||
|
||||
## Adding Plugins {#sec-additional-plugins}
|
||||
|
||||
There are two methods for adding new Neovim plugins to **nvf**. npins is the
|
||||
faster option that should be preferred if the plugin consists of pure Lua or
|
||||
Vimscript code. In which case there is no building required, and we can easily
|
||||
handle the copying of plugin files. Alternative method, which is required when
|
||||
plugins try to build their own libraries (e.g., in Rust or C) that need to be
|
||||
built with Nix to function correctly.
|
||||
|
||||
### With npins {#sec-npins-for-plugins}
|
||||
|
||||
npins is the standard method of adding new plugins to **nvf**. You simply need
|
||||
the repository URL for the plugin, and can add it as a source to be built
|
||||
automatically with one command. To add a new Neovim plugin, use `npins`. For
|
||||
example:
|
||||
|
||||
```bash
|
||||
nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
|
||||
```
|
||||
|
||||
Then run:
|
||||
|
||||
```bash
|
||||
npins add --name <plugin name> github <owner> <repo> -b <branch>
|
||||
```
|
||||
|
||||
::: {.note}
|
||||
|
||||
Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
|
||||
example
|
||||
|
||||
```bash
|
||||
npins add --name lazydev-nvim github folke lazydev.nvim -b main
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
Once the `npins` command is done, you can start referencing the plugin as a
|
||||
**string**.
|
||||
|
||||
```nix
|
||||
{
|
||||
config.vim.startPlugins = ["lazydev-nvim"];
|
||||
}
|
||||
```
|
||||
|
||||
### Packaging Complex Plugins {#sec-pkgs-for-plugins}
|
||||
|
||||
[blink.cmp]: https://github.com/Saghen/blink.cmp
|
||||
|
||||
Some plugins require additional packages to be built and substituted to function
|
||||
correctly. For example [blink.cmp] requires its own fuzzy matcher library, built
|
||||
with Rust, to be installed or else defaults to a much slower Lua implementation.
|
||||
In the Blink documentation, you are advised to build with `cargo` but that is
|
||||
not ideal since we are leveraging the power of Nix. In this case the ideal
|
||||
solution is to write a derivation for the plugin.
|
||||
|
||||
We use `buildRustPackage` to build the library from the repository root, and
|
||||
copy everything in the `postInstall` phase.
|
||||
|
||||
```nix
|
||||
postInstall = ''
|
||||
cp -r {lua,plugin} "$out"
|
||||
|
||||
mkdir -p "$out/doc"
|
||||
cp 'doc/'*'.txt' "$out/doc/"
|
||||
|
||||
mkdir -p "$out/target"
|
||||
mv "$out/lib" "$out/target/release"
|
||||
'';
|
||||
```
|
||||
|
||||
In a similar fashion, you may utilize `stdenv.mkDerivation` and other Nixpkgs
|
||||
builders to build your library from source, and copy the relevant files and Lua
|
||||
plugin files in the `postInstall` phase. Do note, however, that you still need
|
||||
to fetch the plugin sources somehow. npins is, once again, the recommended
|
||||
option to fetch the plugin sources. Refer to the previous section on how to use
|
||||
npins to add a new plugin.
|
||||
|
||||
Plugins built from source must go into the `flake/pkgs/by-name` overlay. It will
|
||||
automatically create flake outputs for individual packages. Lastly, you must add
|
||||
your package to the plugin builder (`pluginBuilders`) function manually in
|
||||
`modules/wrapper/build/config.nix`. Once done, you may refer to your plugin as a
|
||||
**string**.
|
||||
|
||||
```nix
|
||||
{
|
||||
config.vim.startPlugins = ["blink-cmp"];
|
||||
}
|
||||
```
|
||||
|
||||
### Modular setup options {#sec-modular-setup-options}
|
||||
|
||||
Most plugins is initialized with a call to `require('plugin').setup({...})`.
|
||||
|
||||
We use a special function that lets you easily add support for such setup
|
||||
options in a modular way: `mkPluginSetupOption`.
|
||||
|
||||
Once you have added the source of the plugin as shown above, you can define the
|
||||
setup options like this:
|
||||
|
||||
```nix
|
||||
# in modules/.../your-plugin/your-plugin.nix
|
||||
|
||||
{lib, ...}:
|
||||
let
|
||||
inherit (lib.types) bool int;
|
||||
inherit (lib.nvim.types) mkPluginSetupOption;
|
||||
in {
|
||||
options.vim.your-plugin = {
|
||||
setupOpts = mkPluginSetupOption "plugin name" {
|
||||
enable_feature_a = mkOption {
|
||||
type = bool;
|
||||
default = false;
|
||||
# ...
|
||||
};
|
||||
|
||||
number_option = mkOption {
|
||||
type = int;
|
||||
default = 3;
|
||||
# ...
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
```nix
|
||||
# in modules/.../your-plugin/config.nix
|
||||
{lib, config, ...}:
|
||||
let
|
||||
cfg = config.vim.your-plugin;
|
||||
in {
|
||||
vim.luaConfigRC = lib.nvim.dag.entryAnywhere ''
|
||||
require('plugin-name').setup(${lib.nvim.lua.toLuaObject cfg.setupOpts})
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
This above config will result in this Lua script:
|
||||
|
||||
```lua
|
||||
require('plugin-name').setup({
|
||||
enable_feature_a = false,
|
||||
number_option = 3,
|
||||
})
|
||||
```
|
||||
|
||||
Now users can set any of the pre-defined option field, and can also add their
|
||||
own fields!
|
||||
|
||||
```nix
|
||||
# in user's config
|
||||
{
|
||||
vim.your-plugin.setupOpts = {
|
||||
enable_feature_a = true;
|
||||
number_option = 4;
|
||||
another_field = "hello";
|
||||
size = { # nested fields work as well
|
||||
top = 10;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Details of toLuaObject {#sec-details-of-toluaobject}
|
||||
|
||||
As you've seen above, `toLuaObject` is used to convert our nix attrSet
|
||||
`cfg.setupOpts`, into a lua table. Here are some rules of the conversion:
|
||||
|
||||
1. Nix `null` converts to lua `nil`
|
||||
2. Number and strings convert to their lua counterparts
|
||||
3. Nix attribute sets (`{}`) and lists (`[]`) convert into Lua dictionaries and
|
||||
tables respectively. Here is an example of Nix -> Lua conversion.
|
||||
- `{foo = "bar"}` -> `{["foo"] = "bar"}`
|
||||
- `["foo" "bar"]` -> `{"foo", "bar"}`
|
||||
4. You can write raw Lua code using `lib.generators.mkLuaInline`. This function
|
||||
is part of nixpkgs, and is accessible without relying on **nvf**'s extended
|
||||
library.
|
||||
- `mkLuaInline "function add(a, b) return a + b end"` will yield the
|
||||
following result:
|
||||
|
||||
```nix
|
||||
{
|
||||
_type = "lua-inline";
|
||||
expr = "function add(a, b) return a + b end";
|
||||
}
|
||||
```
|
||||
|
||||
The above expression will be interpreted as a Lua expression in the final
|
||||
config. Without the `mkLuaInline` function, you will only receive a string
|
||||
literal. You can use it to feed plugin configuration tables Lua functions
|
||||
that return specific values as expected by the plugins.
|
||||
|
||||
```nix
|
||||
{
|
||||
vim.your-plugin.setupOpts = {
|
||||
on_init = lib.generators.mkLuaInline ''
|
||||
function()
|
||||
print('we can write lua!')
|
||||
end
|
||||
'';
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Lazy plugins {#sec-lazy-plugins}
|
||||
|
||||
If the plugin can be lazy-loaded, `vim.lazy.plugins` should be used to add it.
|
||||
Lazy plugins are managed by `lz.n`.
|
||||
|
||||
```nix
|
||||
# in modules/.../your-plugin/config.nix
|
||||
{config, ...}: let
|
||||
cfg = config.vim.your-plugin;
|
||||
in {
|
||||
vim.lazy.plugins.your-plugin = {
|
||||
# Instead of vim.startPlugins, use this:
|
||||
package = "your-plugin";
|
||||
|
||||
# ıf your plugin uses the `require('your-plugin').setup{...}` pattern
|
||||
setupModule = "your-plugin";
|
||||
inherit (cfg) setupOpts;
|
||||
|
||||
# Events that trigger this plugin to be loaded
|
||||
event = ["DirChanged"];
|
||||
cmd = ["YourPluginCommand"];
|
||||
|
||||
# Plugin Keymaps
|
||||
keys = [
|
||||
# We'll cover this in detail in the 'keybinds' section
|
||||
{
|
||||
key = "<leader>d";
|
||||
mode = "n";
|
||||
action = ":YourPluginCommand";
|
||||
}
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
This results in the following lua code:
|
||||
|
||||
```lua
|
||||
require('lz.n').load({
|
||||
{
|
||||
"name-of-your-plugin",
|
||||
after = function()
|
||||
require('your-plugin').setup({
|
||||
--[[ your setupOpts ]]--
|
||||
})
|
||||
end,
|
||||
|
||||
event = {"DirChanged"},
|
||||
cmd = {"YourPluginCommand"},
|
||||
keys = {
|
||||
{"<leader>d", ":YourPluginCommand", mode = {"n"}},
|
||||
},
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
[`vim.lazy.plugins` spec]: https://notashelf.github.io/nvf/options.html#opt-vim.lazy.plugins
|
||||
|
||||
A full list of options can be found in the [`vim.lazy.plugins` spec] on the
|
||||
rendered manual.
|
||||
|
|
|
@ -1,266 +0,0 @@
|
|||
# Adding Plugins {#sec-additional-plugins}
|
||||
|
||||
There are two methods for adding new Neovim plugins to **nvf**. npins is the
|
||||
faster option that should be preferred if the plugin consists of pure Lua or
|
||||
Vimscript code. In which case there is no building required, and we can easily
|
||||
handle the copying of plugin files. Alternative method, which is required when
|
||||
plugins try to build their own libraries (e.g., in Rust or C) that need to be
|
||||
built with Nix to function correctly.
|
||||
|
||||
## With npins {#sec-npins-for-plugins}
|
||||
|
||||
npins is the standard method of adding new plugins to **nvf**. You simply need
|
||||
the repository URL for the plugin, and can add it as a source to be built
|
||||
automatically with one command. To add a new Neovim plugin, use `npins`. For
|
||||
example:
|
||||
|
||||
```bash
|
||||
nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
|
||||
```
|
||||
|
||||
Then run:
|
||||
|
||||
```bash
|
||||
npins add --name <plugin name> github <owner> <repo> -b <branch>
|
||||
```
|
||||
|
||||
::: {.note}
|
||||
|
||||
Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
|
||||
example
|
||||
|
||||
```bash
|
||||
npins add --name lazydev-nvim github folke lazydev.nvim -b main
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
Once the `npins` command is done, you can start referencing the plugin as a
|
||||
**string**.
|
||||
|
||||
```nix
|
||||
{
|
||||
config.vim.startPlugins = ["lazydev-nvim"];
|
||||
}
|
||||
```
|
||||
|
||||
## Packaging Complex Plugins {#sec-pkgs-for-plugins}
|
||||
|
||||
[blink.cmp]: https://github.com/Saghen/blink.cmp
|
||||
|
||||
Some plugins require additional packages to be built and substituted to function
|
||||
correctly. For example [blink.cmp] requires its own fuzzy matcher library, built
|
||||
with Rust, to be installed or else defaults to a much slower Lua implementation.
|
||||
In the Blink documentation, you are advised to build with `cargo` but that is
|
||||
not ideal since we are leveraging the power of Nix. In this case the ideal
|
||||
solution is to write a derivation for the plugin.
|
||||
|
||||
We use `buildRustPackage` to build the library from the repository root, and
|
||||
copy everything in the `postInstall` phase.
|
||||
|
||||
```nix
|
||||
postInstall = ''
|
||||
cp -r {lua,plugin} "$out"
|
||||
|
||||
mkdir -p "$out/doc"
|
||||
cp 'doc/'*'.txt' "$out/doc/"
|
||||
|
||||
mkdir -p "$out/target"
|
||||
mv "$out/lib" "$out/target/release"
|
||||
'';
|
||||
```
|
||||
|
||||
In a similar fashion, you may utilize `stdenv.mkDerivation` and other Nixpkgs
|
||||
builders to build your library from source, and copy the relevant files and Lua
|
||||
plugin files in the `postInstall` phase. Do note, however, that you still need
|
||||
to fetch the plugin sources somehow. npins is, once again, the recommended
|
||||
option to fetch the plugin sources. Refer to the previous section on how to use
|
||||
npins to add a new plugin.
|
||||
|
||||
Plugins built from source must go into the `flake/pkgs/by-name` overlay. It will
|
||||
automatically create flake outputs for individual packages. Lastly, you must add
|
||||
your package to the plugin builder (`pluginBuilders`) function manually in
|
||||
`modules/wrapper/build/config.nix`. Once done, you may refer to your plugin as a
|
||||
**string**.
|
||||
|
||||
```nix
|
||||
{
|
||||
config.vim.startPlugins = ["blink-cmp"];
|
||||
}
|
||||
```
|
||||
|
||||
## Modular setup options {#sec-modular-setup-options}
|
||||
|
||||
Most plugins is initialized with a call to `require('plugin').setup({...})`.
|
||||
|
||||
We use a special function that lets you easily add support for such setup
|
||||
options in a modular way: `mkPluginSetupOption`.
|
||||
|
||||
Once you have added the source of the plugin as shown above, you can define the
|
||||
setup options like this:
|
||||
|
||||
```nix
|
||||
# in modules/.../your-plugin/your-plugin.nix
|
||||
|
||||
{lib, ...}:
|
||||
let
|
||||
inherit (lib.types) bool int;
|
||||
inherit (lib.nvim.types) mkPluginSetupOption;
|
||||
in {
|
||||
options.vim.your-plugin = {
|
||||
setupOpts = mkPluginSetupOption "plugin name" {
|
||||
enable_feature_a = mkOption {
|
||||
type = bool;
|
||||
default = false;
|
||||
# ...
|
||||
};
|
||||
|
||||
number_option = mkOption {
|
||||
type = int;
|
||||
default = 3;
|
||||
# ...
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
```nix
|
||||
# in modules/.../your-plugin/config.nix
|
||||
{lib, config, ...}:
|
||||
let
|
||||
cfg = config.vim.your-plugin;
|
||||
in {
|
||||
vim.luaConfigRC = lib.nvim.dag.entryAnywhere ''
|
||||
require('plugin-name').setup(${lib.nvim.lua.toLuaObject cfg.setupOpts})
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
This above config will result in this Lua script:
|
||||
|
||||
```lua
|
||||
require('plugin-name').setup({
|
||||
enable_feature_a = false,
|
||||
number_option = 3,
|
||||
})
|
||||
```
|
||||
|
||||
Now users can set any of the pre-defined option field, and can also add their
|
||||
own fields!
|
||||
|
||||
```nix
|
||||
# in user's config
|
||||
{
|
||||
vim.your-plugin.setupOpts = {
|
||||
enable_feature_a = true;
|
||||
number_option = 4;
|
||||
another_field = "hello";
|
||||
size = { # nested fields work as well
|
||||
top = 10;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Details of toLuaObject {#sec-details-of-toluaobject}
|
||||
|
||||
As you've seen above, `toLuaObject` is used to convert our nix attrSet
|
||||
`cfg.setupOpts`, into a lua table. Here are some rules of the conversion:
|
||||
|
||||
1. Nix `null` converts to lua `nil`
|
||||
2. Number and strings convert to their lua counterparts
|
||||
3. Nix attribute sets (`{}`) and lists (`[]`) convert into Lua dictionaries and
|
||||
tables respectively. Here is an example of Nix -> Lua conversion.
|
||||
- `{foo = "bar"}` -> `{["foo"] = "bar"}`
|
||||
- `["foo" "bar"]` -> `{"foo", "bar"}`
|
||||
4. You can write raw Lua code using `lib.generators.mkLuaInline`. This function
|
||||
is part of nixpkgs, and is accessible without relying on **nvf**'s extended
|
||||
library.
|
||||
- `mkLuaInline "function add(a, b) return a + b end"` will yield the
|
||||
following result:
|
||||
|
||||
```nix
|
||||
{
|
||||
_type = "lua-inline";
|
||||
expr = "function add(a, b) return a + b end";
|
||||
}
|
||||
```
|
||||
|
||||
The above expression will be interpreted as a Lua expression in the final
|
||||
config. Without the `mkLuaInline` function, you will only receive a string
|
||||
literal. You can use it to feed plugin configuration tables Lua functions
|
||||
that return specific values as expected by the plugins.
|
||||
|
||||
```nix
|
||||
{
|
||||
vim.your-plugin.setupOpts = {
|
||||
on_init = lib.generators.mkLuaInline ''
|
||||
function()
|
||||
print('we can write lua!')
|
||||
end
|
||||
'';
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Lazy plugins {#sec-lazy-plugins}
|
||||
|
||||
If the plugin can be lazy-loaded, `vim.lazy.plugins` should be used to add it.
|
||||
Lazy plugins are managed by `lz.n`.
|
||||
|
||||
```nix
|
||||
# in modules/.../your-plugin/config.nix
|
||||
{config, ...}: let
|
||||
cfg = config.vim.your-plugin;
|
||||
in {
|
||||
vim.lazy.plugins.your-plugin = {
|
||||
# Instead of vim.startPlugins, use this:
|
||||
package = "your-plugin";
|
||||
|
||||
# ıf your plugin uses the `require('your-plugin').setup{...}` pattern
|
||||
setupModule = "your-plugin";
|
||||
inherit (cfg) setupOpts;
|
||||
|
||||
# Events that trigger this plugin to be loaded
|
||||
event = ["DirChanged"];
|
||||
cmd = ["YourPluginCommand"];
|
||||
|
||||
# Plugin Keymaps
|
||||
keys = [
|
||||
# We'll cover this in detail in the 'keybinds' section
|
||||
{
|
||||
key = "<leader>d";
|
||||
mode = "n";
|
||||
action = ":YourPluginCommand";
|
||||
}
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
This results in the following lua code:
|
||||
|
||||
```lua
|
||||
require('lz.n').load({
|
||||
{
|
||||
"name-of-your-plugin",
|
||||
after = function()
|
||||
require('your-plugin').setup({
|
||||
--[[ your setupOpts ]]--
|
||||
})
|
||||
end,
|
||||
|
||||
event = {"DirChanged"},
|
||||
cmd = {"YourPluginCommand"},
|
||||
keys = {
|
||||
{"<leader>d", ":YourPluginCommand", mode = {"n"}},
|
||||
},
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
[`vim.lazy.plugins` spec]: https://notashelf.github.io/nvf/options.html#opt-vim.lazy.plugins
|
||||
|
||||
A full list of options can be found in the [`vim.lazy.plugins` spec] on the
|
||||
rendered manual.
|
|
@ -1,17 +0,0 @@
|
|||
# Getting Started {#sec-contrib-getting-started}
|
||||
|
||||
You, naturally, would like to start by forking the repository to get started. If
|
||||
you are new to Git and GitHub, do have a look at GitHub's
|
||||
[Fork a repo guide](https://help.github.com/articles/fork-a-repo/) for
|
||||
instructions on how you can do this. Once you have a fork of **nvf**, you should
|
||||
create a separate branch based on the most recent `main` branch. Give your
|
||||
branch a reasonably descriptive name (e.g. `feature/debugger` or
|
||||
`fix/pesky-bug`) and you are ready to work on your changes
|
||||
|
||||
Implement your changes and commit them to the newly created branch and when you
|
||||
are happy with the result, and positive that it fulfills our
|
||||
[Contributing Guidelines](#sec-guidelines), push the branch to GitHub and
|
||||
[create a pull request](https://help.github.com/articles/creating-a-pull-request).
|
||||
The default pull request template available on the **nvf** repository will guide
|
||||
you through the rest of the process, and we'll gently nudge you in the correct
|
||||
direction if there are any mistakes.
|
|
@ -1,188 +0,0 @@
|
|||
# Guidelines {#sec-guidelines}
|
||||
|
||||
If your contribution tightly follows the guidelines, then there is a good chance
|
||||
it will be merged without too much trouble. Some of the guidelines will be
|
||||
strictly enforced, others will remain as gentle nudges towards the correct
|
||||
direction. As we have no automated system enforcing those guidelines, please try
|
||||
to double check your changes before making your pull request in order to avoid
|
||||
"faulty" code slipping by.
|
||||
|
||||
If you are uncertain how these rules affect the change you would like to make
|
||||
then feel free to start a discussion in the
|
||||
[discussions tab](https://github.com/NotAShelf/nvf/discussions) ideally (but not
|
||||
necessarily) before you start developing.
|
||||
|
||||
## Adding Documentation {#sec-guidelines-documentation}
|
||||
|
||||
[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax
|
||||
|
||||
Almost all changes warrant updates to the documentation: at the very least, you
|
||||
must update the changelog. Both the manual and module options use
|
||||
[Nixpkgs Flavoured Markdown].
|
||||
|
||||
The HTML version of this manual containing both the module option descriptions
|
||||
and the documentation of **nvf** (such as this page) can be generated and opened
|
||||
by typing the following in a shell within a clone of the **nvf** Git repository:
|
||||
|
||||
```console
|
||||
$ nix build .#docs-html
|
||||
$ xdg-open $PWD/result/share/doc/nvf/index.html
|
||||
```
|
||||
|
||||
## Formatting Code {#sec-guidelines-formatting}
|
||||
|
||||
Make sure your code is formatted as described in
|
||||
[code-style section](#sec-guidelines-code-style). To maintain consistency
|
||||
throughout the project you are encouraged to browse through existing code and
|
||||
adopt its style also in new code.
|
||||
|
||||
## Formatting Commits {#sec-guidelines-commit-message-style}
|
||||
|
||||
Similar to [code style guidelines](#sec-guidelines-code-style) we encourage a
|
||||
consistent commit message format as described in
|
||||
[commit style guidelines](#sec-guidelines-commit-style).
|
||||
|
||||
## Commit Style {#sec-guidelines-commit-style}
|
||||
|
||||
The commits in your pull request should be reasonably self-contained. Which
|
||||
means each and every commit in a pull request should make sense both on its own
|
||||
and in general context. That is, a second commit should not resolve an issue
|
||||
that is introduced in an earlier commit. In particular, you will be asked to
|
||||
amend any commit that introduces syntax errors or similar problems even if they
|
||||
are fixed in a later commit.
|
||||
|
||||
The commit messages should follow the
|
||||
[seven rules](https://chris.beams.io/posts/git-commit/#seven-rule), except for
|
||||
"Capitalize the subject line". We also ask you to include the affected code
|
||||
component or module in the first line. A commit message ideally, but not
|
||||
necessarily, follow the given template from home-manager's own documentation
|
||||
|
||||
```
|
||||
{component}: {description}
|
||||
|
||||
{long description}
|
||||
```
|
||||
|
||||
where `{component}` refers to the code component (or module) your change
|
||||
affects, `{description}` is a very brief description of your change, and
|
||||
`{long description}` is an optional clarifying description. As a rare exception,
|
||||
if there is no clear component, or your change affects many components, then the
|
||||
`{component}` part is optional. See
|
||||
[example commit message](#sec-guidelines-ex-commit-message) for a commit message
|
||||
that fulfills these requirements.
|
||||
|
||||
## Example Commit {#sec-guidelines-ex-commit-message}
|
||||
|
||||
The commit
|
||||
[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef)
|
||||
in home-manager contains the following commit message.
|
||||
|
||||
```
|
||||
starship: allow running in Emacs if vterm is used
|
||||
|
||||
The vterm buffer is backed by libvterm and can handle Starship prompts
|
||||
without issues.
|
||||
```
|
||||
|
||||
Similarly, if you are contributing to **nvf**, you would include the scope of
|
||||
the commit followed by the description:
|
||||
|
||||
```
|
||||
languages/ruby: init module
|
||||
|
||||
Adds a language module for Ruby, adds appropriate formatters and Treesitter grammars
|
||||
```
|
||||
|
||||
Long description can be omitted if the change is too simple to warrant it. A
|
||||
minor fix in spelling or a formatting change does not warrant long description,
|
||||
however, a module addition or removal does as you would like to provide the
|
||||
relevant context, i.e. the reasoning behind it, for your commit.
|
||||
|
||||
Finally, when adding a new module, say `modules/foo.nix`, we use the fixed
|
||||
commit format `foo: add module`. You can, of course, still include a long
|
||||
description if you wish.
|
||||
|
||||
In case of nested modules, i.e `modules/languages/java.nix` you are recommended
|
||||
to contain the parent as well - for example `languages/java: some major change`.
|
||||
|
||||
## Code Style {#sec-guidelines-code-style}
|
||||
|
||||
### Treewide {#sec-code-style-treewide}
|
||||
|
||||
Keep lines at a reasonable width, ideally 80 characters or less. This also
|
||||
applies to string literals and module descriptions and documentation.
|
||||
|
||||
### Nix {#sec-code-style-nix}
|
||||
|
||||
[alejandra]: https://github.com/kamadorueda/alejandra
|
||||
|
||||
**nvf** is formatted by the [alejandra] tool and the formatting is checked in
|
||||
the pull request and push workflows. Run the `nix fmt` command inside the
|
||||
project repository before submitting your pull request.
|
||||
|
||||
While Alejandra is mostly opinionated on how code looks after formatting,
|
||||
certain changes are done at the user's discretion based on how the original code
|
||||
was structured.
|
||||
|
||||
Please use one line code for attribute sets that contain only one subset. For
|
||||
example:
|
||||
|
||||
```nix
|
||||
# parent modules should always be unfolded
|
||||
# which means module = { value = ... } instead of module.value = { ... }
|
||||
module = {
|
||||
value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible
|
||||
|
||||
# same as parent modules, unfold submodules
|
||||
subModule = {
|
||||
# this is an option that contains more than one nested value
|
||||
# Note: try to be careful about the ordering of `mkOption` arguments.
|
||||
# General rule of thumb is to order from least to most likely to change.
|
||||
# This is, for most cases, type < default < description.
|
||||
# Example, if present, would be between default and description
|
||||
someOtherValue = mkOption {
|
||||
type = lib.types.bool;
|
||||
default = true;
|
||||
description = "Some other description";
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
If you move a line down after the merge operator, Alejandra will automatically
|
||||
unfold the whole merged attrset for you, which we **do not** want.
|
||||
|
||||
```nix
|
||||
module = {
|
||||
key = mkEnableOption "some description" // {
|
||||
default = true; # we want this to be inline
|
||||
}; # ...
|
||||
}
|
||||
```
|
||||
|
||||
For lists, it is mostly up to your own discretion how you want to format them,
|
||||
but please try to unfold lists if they contain multiple items and especially if
|
||||
they are to include comments.
|
||||
|
||||
```nix
|
||||
# this is ok
|
||||
acceptableList = [
|
||||
item1 # comment
|
||||
item2
|
||||
item3 # some other comment
|
||||
item4
|
||||
];
|
||||
|
||||
# this is not ok
|
||||
listToBeAvoided = [item1 item2 /* comment */ item3 item4];
|
||||
|
||||
# this is ok
|
||||
acceptableList = [item1 item2];
|
||||
|
||||
# this is also ok if the list is expected to contain more elements
|
||||
acceptableList= [
|
||||
item1
|
||||
item2
|
||||
# more items if needed...
|
||||
];
|
||||
```
|
|
@ -1,97 +0,0 @@
|
|||
# Keybinds {#sec-keybinds}
|
||||
|
||||
As of 0.4, there exists an API for writing your own keybinds and a couple of
|
||||
useful utility functions are available in the
|
||||
[extended standard library](https://github.com/NotAShelf/nvf/tree/main/lib). The
|
||||
following section contains a general overview to how you may utilize said
|
||||
functions.
|
||||
|
||||
## Custom Key Mappings Support for a Plugin {#sec-custom-key-mappings}
|
||||
|
||||
To set a mapping, you should define it in `vim.keymaps`.
|
||||
|
||||
An example, simple keybinding, can look like this:
|
||||
|
||||
```nix
|
||||
{
|
||||
vim.keymaps = [
|
||||
{
|
||||
key = "<leader>wq";
|
||||
mode = ["n"];
|
||||
action = ":wq<CR>";
|
||||
silent = true;
|
||||
desc = "Save file and quit";
|
||||
}
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
There are many settings available in the options. Please refer to the
|
||||
[documentation](https://notashelf.github.io/nvf/options.html#opt-vim.keymaps) to
|
||||
see a list of them.
|
||||
|
||||
**nvf** provides a helper function, so that you don't have to write the mapping
|
||||
attribute sets every time:
|
||||
|
||||
- `mkKeymap`, which mimics neovim's `vim.keymap.set` function
|
||||
|
||||
You can read the source code of some modules to see them in action, but the
|
||||
usage should look something like this:
|
||||
|
||||
```nix
|
||||
# plugindefinition.nix
|
||||
{lib, ...}: let
|
||||
inherit (lib.options) mkEnableOption;
|
||||
inherit (lib.nvim.binds) mkMappingOption;
|
||||
in {
|
||||
options.vim.plugin = {
|
||||
enable = mkEnableOption "Enable plugin";
|
||||
|
||||
# Mappings should always be inside an attrset called mappings
|
||||
mappings = {
|
||||
workspaceDiagnostics = mkMappingOption "Workspace diagnostics [trouble]" "<leader>lwd";
|
||||
documentDiagnostics = mkMappingOption "Document diagnostics [trouble]" "<leader>ld";
|
||||
lspReferences = mkMappingOption "LSP References [trouble]" "<leader>lr";
|
||||
quickfix = mkMappingOption "QuickFix [trouble]" "<leader>xq";
|
||||
locList = mkMappingOption "LOCList [trouble]" "<leader>xl";
|
||||
symbols = mkMappingOption "Symbols [trouble]" "<leader>xs";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
```nix
|
||||
# config.nix
|
||||
{
|
||||
config,
|
||||
lib,
|
||||
options,
|
||||
...
|
||||
}: let
|
||||
inherit (lib.modules) mkIf;
|
||||
inherit (lib.nvim.binds) mkKeymap;
|
||||
|
||||
cfg = config.vim.plugin;
|
||||
|
||||
keys = cfg.mappings;
|
||||
inherit (options.vim.lsp.trouble) mappings;
|
||||
in {
|
||||
config = mkIf cfg.enable {
|
||||
vim.keymaps = [
|
||||
(mkKeymap "n" keys.workspaceDiagnostics "<cmd>Trouble toggle diagnostics<CR>" {desc = mappings.workspaceDiagnostics.description;})
|
||||
(mkKeymap "n" keys.documentDiagnostics "<cmd>Trouble toggle diagnostics filter.buf=0<CR>" {desc = mappings.documentDiagnostics.description;})
|
||||
(mkKeymap "n" keys.lspReferences "<cmd>Trouble toggle lsp_references<CR>" {desc = mappings.lspReferences.description;})
|
||||
(mkKeymap "n" keys.quickfix "<cmd>Trouble toggle quickfix<CR>" {desc = mappings.quickfix.description;})
|
||||
(mkKeymap "n" keys.locList "<cmd>Trouble toggle loclist<CR>" {desc = mappings.locList.description;})
|
||||
(mkKeymap "n" keys.symbols "<cmd>Trouble toggle symbols<CR>" {desc = mappings.symbols.description;})
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
::: {.note}
|
||||
|
||||
If you have come across a plugin that has an API that doesn't seem to easily
|
||||
allow custom keybindings, don't be scared to implement a draft PR. We'll help
|
||||
you get it done.
|
||||
|
||||
:::
|
|
@ -1,15 +0,0 @@
|
|||
# Testing Changes {#sec-testing-changes}
|
||||
|
||||
Once you have made your changes, you will need to test them thoroughly. If it is
|
||||
a module, add your module option to `configuration.nix` (located in the root of
|
||||
this project) inside `neovimConfiguration`. Enable it, and then run the maximal
|
||||
configuration with `nix run .#maximal -Lv` to check for build errors. If neovim
|
||||
opens in the current directory without any error messages (you can check the
|
||||
output of `:messages` inside neovim to see if there are any errors), then your
|
||||
changes are good to go. Open your pull request, and it will be reviewed as soon
|
||||
as possible.
|
||||
|
||||
If it is not a new module, but a change to an existing one, then make sure the
|
||||
module you have changed is enabled in the maximal configuration by editing
|
||||
`configuration.nix`, and then run it with `nix run .#maximal -Lv`. Same
|
||||
procedure as adding a new module will apply here.
|
|
@ -1,30 +1,101 @@
|
|||
# nvf manual {#nvf-manual}
|
||||
# Introduction {#nvf-manual}
|
||||
|
||||
## Version @NVF_VERSION@
|
||||
Version @NVF_VERSION@
|
||||
|
||||
```{=include=} preface
|
||||
preface.md
|
||||
try-it-out.md
|
||||
## Preface {#ch-preface}
|
||||
|
||||
### What is nvf {#sec-what-is-it}
|
||||
|
||||
**nvf** is a highly modular, configurable, extensible and easy to use Neovim
|
||||
configuration framework built and designed to be used with Nix. Boasting
|
||||
flexibility, robustness and ease of use, this projecct allows you to configure a
|
||||
fully featured Neovim instance with a few lines of Nix with lots of options for
|
||||
advanced users as well.
|
||||
|
||||
## Try it out {#ch-try-it-out}
|
||||
|
||||
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** (`packages.nix`) - Nix language server + simple utility plugins
|
||||
- **Maximal** (`packages.maximal`) - Variable language servers + utility and
|
||||
decorative plugins
|
||||
|
||||
You may try out any of the provided configurations using the `nix run` command
|
||||
on a system where Nix is installed.
|
||||
|
||||
```sh
|
||||
$ cachix use nvf # Optional: it'll save you CPU resources and time
|
||||
$ nix run github:notashelf/nvf#nix # Will run the default minimal configuration
|
||||
```
|
||||
|
||||
```{=include=} parts
|
||||
installation.md
|
||||
configuring.md
|
||||
tips.md
|
||||
Do keep in mind that this is **susceptible to garbage collection** meaning that
|
||||
the built outputs will be removed from your Nix store once you garbage collect.
|
||||
|
||||
## Using Prebuilt Configs {#sec-using-prebuilt-configs}
|
||||
|
||||
```bash
|
||||
$ nix run github:notashelf/nvf#nix
|
||||
$ nix run github:notashelf/nvf#maximal
|
||||
```
|
||||
|
||||
```{=include=} chapters
|
||||
hacking.md
|
||||
### Available Configurations {#sec-available-configs}
|
||||
|
||||
> [!NOTE]
|
||||
> The below configurations are provided for demonstration purposes, and are
|
||||
> **not** designed to be installed as is. You may refer to the installation
|
||||
> steps below and the helpful tips section for details on creating your own
|
||||
> configurations.
|
||||
|
||||
#### Nix {#sec-configs-nix}
|
||||
|
||||
`Nix` configuration by default provides LSP/diagnostic support for Nix alongside
|
||||
a set of visual and functional plugins. By running `nix run .#`, which is the
|
||||
default package, you will build Neovim with this config.
|
||||
|
||||
```bash
|
||||
$ nix run github:notashelf/nvf#nix test.nix
|
||||
# => This will open a file called `test.nix` with Nix LSP and syntax highlighting
|
||||
```
|
||||
|
||||
```{=include=} appendix html:into-file=//quirks.html
|
||||
quirks.md
|
||||
This command will start Neovim with some opinionated plugin configurations, and
|
||||
is designed specifically for Nix. the `nix` configuration lets you see how a
|
||||
fully configured Neovim setup _might_ look like without downloading too many
|
||||
packages or shell utilities.
|
||||
|
||||
#### Maximal {#sec-configs-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.
|
||||
|
||||
```bash
|
||||
$ nix run github:notashelf/nvf#maximal -- test.nix
|
||||
# => This will open a file called `test.nix` with a variety of plugins available
|
||||
```
|
||||
|
||||
```{=include=} appendix html:into-file=//options.html
|
||||
options.md
|
||||
```
|
||||
It uses the same configuration template with the [Nix](#sec-configs-nix)
|
||||
configuration, but supports many more languages, and enables more utility,
|
||||
companion or fun plugins.
|
||||
|
||||
```{=include=} appendix html:into-file=//release-notes.html
|
||||
release-notes/release-notes.md
|
||||
> [!WARNING]
|
||||
> Running the maximal config will download _a lot_ of packages as it is
|
||||
> downloading language servers, formatters, and more. If CPU time and bandwidth
|
||||
> are concerns, please use the default package instead.
|
||||
|
||||
## Installing nvf {#ch-installation}
|
||||
|
||||
[module installation section]: #ch-module-installation
|
||||
|
||||
There are multiple ways of installing nvf on your system. You may either choose
|
||||
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].
|
||||
|
||||
```{=include=}
|
||||
installation/custom-configuration.md
|
||||
installation/modules.md
|
||||
```
|
||||
|
|
|
@ -1,14 +0,0 @@
|
|||
# Installing nvf {#ch-installation}
|
||||
|
||||
[module installation section]: #ch-module-installation
|
||||
|
||||
There are multiple ways of installing nvf on your system. You may either choose
|
||||
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].
|
||||
|
||||
```{=include=} chapters
|
||||
installation/custom-configuration.md
|
||||
installation/modules.md
|
||||
```
|
|
@ -1,21 +0,0 @@
|
|||
# nvf Configuration Options {#ch-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.
|
||||
|
||||
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 let us know if you believe any of
|
||||
the options below are missing useful examples.
|
||||
|
||||
<!--
|
||||
In the manual, individual options may be referenced in Hyperlinks as follows:
|
||||
[](#opt-vim.*) If changing the prefix here, do keep in mind the #opt- suffix will have
|
||||
to be changed everywhere.
|
||||
-->
|
||||
|
||||
```{=include=} options
|
||||
id-prefix: opt-
|
||||
list-id: nvf-options
|
||||
source: @OPTIONS_JSON@
|
||||
```
|
|
@ -1,20 +0,0 @@
|
|||
# Preface {#ch-preface}
|
||||
|
||||
## What is nvf {#sec-what-is-it}
|
||||
|
||||
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.
|
||||
|
||||
## Bugs & Suggestions {#sec-bugs-suggestions}
|
||||
|
||||
[issue tracker]: https://github.com/notashelf/nvf/issues
|
||||
[discussions tab]: https://github.com/notashelf/nvf/discussions
|
||||
[pull requests tab]: https://github.com/notashelf/nvf/pulls
|
||||
|
||||
If you notice any issues with nvf, or this documentation, then please consider
|
||||
reporting them over at the [issue tracker]. Issues tab, in addition to the
|
||||
[discussions tab] is a good place as any to request new features.
|
||||
|
||||
You may also consider submitting bugfixes, feature additions and upstreamed
|
||||
changes that you think are critical over at the [pull requests tab].
|
|
@ -5,9 +5,41 @@ be it a result of generating Lua from Nix, or the state of packaging. This page,
|
|||
in turn, will list any known modules or plugins that are known to misbehave, and
|
||||
possible workarounds that you may apply.
|
||||
|
||||
<!-- If adding a new known quirk, please create a new page in quirks/ and include
|
||||
the name of the file here.-->
|
||||
## NodeJS {#ch-quirks-nodejs}
|
||||
|
||||
```{=include=} chapters
|
||||
quirks/nodejs.md
|
||||
```
|
||||
### eslint-plugin-prettier {#sec-eslint-plugin-prettier}
|
||||
|
||||
When working with NodeJS, everything works as expected, but some projects have
|
||||
settings that can fool nvf.
|
||||
|
||||
If [this plugin](https://github.com/prettier/eslint-plugin-prettier) or similar
|
||||
is included, you might get a situation where your eslint configuration diagnoses
|
||||
your formatting according to its own config (usually `.eslintrc.js`).
|
||||
|
||||
The issue there is your formatting is made via prettierd.
|
||||
|
||||
This results in auto-formatting relying on your prettier config, while your
|
||||
eslint config diagnoses formatting
|
||||
[which it's not supposed to](https://prettier.io/docs/en/comparison.html))
|
||||
|
||||
In the end, you get discrepancies between what your editor does and what it
|
||||
wants.
|
||||
|
||||
Solutions are:
|
||||
|
||||
1. Don't add a formatting config to eslint, and separate prettier and eslint.
|
||||
2. PR this repo to add an ESLint formatter and configure nvf to use it.
|
||||
|
||||
## Bugs & Suggestions {#ch-bugs-suggestions}
|
||||
|
||||
[issue tracker]: https://github.com/notashelf/nvf/issues
|
||||
[discussions tab]: https://github.com/notashelf/nvf/discussions
|
||||
[pull requests tab]: https://github.com/notashelf/nvf/pulls
|
||||
|
||||
Some quirks are not exactly quirks, but bugs in the module systeme. If you
|
||||
notice any issues with nvf, or this documentation, then please consider
|
||||
reporting them over at the [issue tracker]. Issues tab, in addition to the
|
||||
[discussions tab] is a good place as any to request new features.
|
||||
|
||||
You may also consider submitting bugfixes, feature additions and upstreamed
|
||||
changes that you think are critical over at the [pull requests tab].
|
||||
|
|
|
@ -1,24 +0,0 @@
|
|||
# NodeJS {#ch-quirks-nodejs}
|
||||
|
||||
## eslint-plugin-prettier {#sec-eslint-plugin-prettier}
|
||||
|
||||
When working with NodeJS, everything works as expected, but some projects have
|
||||
settings that can fool nvf.
|
||||
|
||||
If [this plugin](https://github.com/prettier/eslint-plugin-prettier) or similar
|
||||
is included, you might get a situation where your eslint configuration diagnoses
|
||||
your formatting according to its own config (usually `.eslintrc.js`).
|
||||
|
||||
The issue there is your formatting is made via prettierd.
|
||||
|
||||
This results in auto-formatting relying on your prettier config, while your
|
||||
eslint config diagnoses formatting
|
||||
[which it's not supposed to](https://prettier.io/docs/en/comparison.html))
|
||||
|
||||
In the end, you get discrepancies between what your editor does and what it
|
||||
wants.
|
||||
|
||||
Solutions are:
|
||||
|
||||
1. Don't add a formatting config to eslint, and separate prettier and eslint.
|
||||
2. PR this repo to add an ESLint formatter and configure nvf to use it.
|
15
docs/manual/release-notes.md
Normal file
15
docs/manual/release-notes.md
Normal file
|
@ -0,0 +1,15 @@
|
|||
# Release Notes {#ch-release-notes}
|
||||
|
||||
This section lists the release notes for tagged version of **nvf** and the
|
||||
current main current main branch
|
||||
|
||||
```{=include=} chapters
|
||||
release-notes/rl-0.1.md
|
||||
release-notes/rl-0.2.md
|
||||
release-notes/rl-0.3.md
|
||||
release-notes/rl-0.4.md
|
||||
release-notes/rl-0.5.md
|
||||
release-notes/rl-0.6.md
|
||||
release-notes/rl-0.7.md
|
||||
release-notes/rl-0.8.md
|
||||
```
|
|
@ -1,4 +1,4 @@
|
|||
# Release 0.1 {#sec-release-0.1}
|
||||
# Release 0.1 {#sec-release-0-1}
|
||||
|
||||
This is the current master branch and information here is not final. These are
|
||||
changes from the v0.1 tag.
|
||||
|
@ -7,7 +7,7 @@ Special thanks to [home-manager](https://github.com/nix-community/home-manager/)
|
|||
for this release. Docs/manual generation, the new module evaluation system, and
|
||||
DAG implementation are from them.
|
||||
|
||||
## Changelog {#sec-release-0.1-changelog}
|
||||
## Changelog {#sec-release-0-1-changelog}
|
||||
|
||||
[jordanisaacs](https://github.com/jordanisaacs):
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
# Release 0.2 {#sec-release-0.2}
|
||||
# Release 0.2 {#sec-release-0-2}
|
||||
|
||||
Release notes for release 0.2
|
||||
|
||||
## Changelog {#sec-release-0.2-changelog}
|
||||
## Changelog {#sec-release-0-2-changelog}
|
||||
|
||||
[notashelf](https://github.com/notashelf):
|
||||
|
||||
|
@ -10,55 +10,39 @@ Release notes for release 0.2
|
|||
default, while `minimap.vim` is available with its code-minimap dependency.
|
||||
- A complementary plugin, `obsidian.nvim` and the Neovim alternative for Emacs'
|
||||
orgmode with `orgmode.nvim` have been added. Both will be disabled by default.
|
||||
|
||||
- Smooth scrolling for ANY movement command is now available with
|
||||
`cinnamon.nvim`
|
||||
|
||||
- You will now notice a dashboard on startup. This is provided by the
|
||||
`alpha.nvim` plugin. You can use any of the three available dashboard plugins,
|
||||
or disable them entirely.
|
||||
|
||||
- There is now a scrollbar on active buffers, which can highlight errors by
|
||||
hooking to your LSPs. This is on by default, but can be toggled off under
|
||||
`vim.visuals` if seen necessary.
|
||||
|
||||
- Discord Rich Presence has been added through `presence.nvim` for those who
|
||||
want to flex that they are using the _superior_ text editor.
|
||||
|
||||
- An icon picker is now available with telescope integration. You can use
|
||||
`:IconPickerInsert` or `:IconPickerYank` to add icons to your code.
|
||||
|
||||
- A general-purpose cheatsheet has been added through `cheatsheet.nvim`. Forget
|
||||
no longer!
|
||||
|
||||
- `ccc.nvim` has been added to the default plugins to allow picking colors with
|
||||
ease.
|
||||
|
||||
- Most UI components of Neovim have been replaced through the help of
|
||||
`noice.nvim`. There are also notifications and custom UI elements available
|
||||
for Neovim messages and prompts.
|
||||
|
||||
- A (floating by default) terminal has been added through `toggleterm.nvim`.
|
||||
|
||||
- Harness the power of ethical (`tabnine.nvim`) and not-so-ethical
|
||||
(`copilot.lua`) AI by those new assistant plugins. Both are off by default,
|
||||
TabNine needs to be wrapped before it's working.
|
||||
|
||||
- Experimental mouse gestures have been added through `gesture.nvim`. See plugin
|
||||
page and the relevant module for more details on how to use.
|
||||
|
||||
- Re-open last visited buffers via `nvim-session-manager`. Disabled by default
|
||||
as deleting buffers seems to be problematic at the moment.
|
||||
|
||||
- Most of NvimTree's configuration options have been changed with some options
|
||||
being toggled to off by default.
|
||||
|
||||
- Lualine had its configuration simplified and style toned down. Less color,
|
||||
more info.
|
||||
|
||||
- Modules where multiple plugin configurations were in the same directory have
|
||||
been simplified. Each plugin inside a single module gets its directory to be
|
||||
imported.
|
||||
|
||||
- Separate config options with the same parent attribute have been merged into
|
||||
one for simplicity.
|
|
@ -1,4 +1,4 @@
|
|||
# Release 0.3 {#sec-release-0.3}
|
||||
# Release 0.3 {#sec-release-0-3}
|
||||
|
||||
Release 0.3 had to come out before I wanted it to due to Neovim 0.9 dropping
|
||||
into nixpkgs-unstable. The Treesitter changes have prompted a Treesitter rework,
|
||||
|
@ -7,7 +7,7 @@ those are downstreamed from the original repository. The feature requests that
|
|||
was originally planned for 0.3 have been moved to 0.4, which should come out
|
||||
soon.
|
||||
|
||||
## Changelog {#sec-release-0.3-changelog}
|
||||
## Changelog {#sec-release-0-3-changelog}
|
||||
|
||||
- We have transitioned to flake-parts, from flake-utils to extend the
|
||||
flexibility of this flake. This means the flake structure is different than
|
|
@ -1,4 +1,4 @@
|
|||
# Release 0.4 {#sec-release-0.4}
|
||||
# Release 0.4 {#sec-release-0-4}
|
||||
|
||||
Following the release of v0.3, I have decided to release v0.4 with a massive new
|
||||
change: customizable keybinds. As of the 0.4 release, keybinds will no longer be
|
||||
|
@ -12,7 +12,7 @@ as `lazygit` integration and the new experimental Lua loader of Neovim 0.9
|
|||
thanks to our awesome contributors who made this update possible during my
|
||||
absence.
|
||||
|
||||
## Changelog {#sec-release-0.4-changelog}
|
||||
## Changelog {#sec-release-0-4-changelog}
|
||||
|
||||
[n3oney](https://github.com/n3oney):
|
||||
|
|
@ -1,8 +1,6 @@
|
|||
# Release 0.5 {#sec-release-0.5}
|
||||
# Release 0.5 {#sec-release-0-5}
|
||||
|
||||
Release notes for release 0.5
|
||||
|
||||
## Changelog {#sec-release-0.5-changelog}
|
||||
## Changelog {#sec-release-0-5-changelog}
|
||||
|
||||
[vagahbond](https://github.com/vagahbond):
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Release 0.6 {#sec-release-0.6}
|
||||
# Release 0.6 {#sec-release-0-6}
|
||||
|
||||
Release notes for release 0.6
|
||||
Release notes for release 0-6
|
||||
|
||||
## Breaking Changes and Migration Guide {#sec-breaking-changes-and-migration-guide}
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Release 0.7 {#sec-release-0.7}
|
||||
# Release 0.7 {#sec-release-0-7}
|
||||
|
||||
Release notes for release 0.7
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Release 0.8 {#sec-release-0.8}
|
||||
# Release 0.8 {#sec-release-0-8}
|
||||
|
||||
## Breaking changes
|
||||
|
||||
|
@ -28,6 +28,8 @@
|
|||
align with the "hunks" themed mapping and avoid conflict with the new [neogit]
|
||||
group.
|
||||
|
||||
## Changelog {#sec-release-0-8-changelog}
|
||||
|
||||
[NotAShelf](https://github.com/notashelf):
|
||||
|
||||
[typst-preview.nvim]: https://github.com/chomosuke/typst-preview.nvim
|
||||
|
@ -38,7 +40,6 @@
|
|||
[colorful-menu.nvim]: https://github.com/xzbdmw/colorful-menu.nvim
|
||||
[oil.nvim]: https://github.com/stevearc/oil.nvim
|
||||
[hunk.nvim]: https://github.com/julienvincent/hunk.nvim
|
||||
[undotree]: https://github.com/mbbill/undotree
|
||||
|
||||
- Add [typst-preview.nvim] under
|
||||
`languages.typst.extensions.typst-preview-nvim`.
|
|
@ -6,7 +6,7 @@ documentation, configuring **nvf** with pure Lua and using custom plugin sources
|
|||
in **nvf** in this section. For general configuration tips, please see previous
|
||||
chapters.
|
||||
|
||||
```{=include=} chapters
|
||||
```{=include=}
|
||||
tips/debugging-nvf.md
|
||||
tips/offline-docs.md
|
||||
tips/pure-lua-config.md
|
||||
|
|
|
@ -1,72 +0,0 @@
|
|||
# Try it out {#ch-try-it-out}
|
||||
|
||||
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** (`packages.nix`) - Nix language server + simple utility plugins
|
||||
- **Maximal** (`packages.maximal`) - Variable language servers + utility and
|
||||
decorative plugins
|
||||
|
||||
You may try out any of the provided configurations using the `nix run` command
|
||||
on a system where Nix is installed.
|
||||
|
||||
```sh
|
||||
$ cachix use nvf # Optional: it'll save you CPU resources and time
|
||||
$ nix run github:notashelf/nvf#nix # Will run the default minimal configuration
|
||||
```
|
||||
|
||||
Do keep in mind that this is **susceptible to garbage collection** meaning that
|
||||
the built outputs will be removed from your Nix store once you garbage collect.
|
||||
|
||||
## Using Prebuilt Configs {#sec-using-prebuilt-configs}
|
||||
|
||||
```bash
|
||||
$ nix run github:notashelf/nvf#nix
|
||||
$ nix run github:notashelf/nvf#maximal
|
||||
```
|
||||
|
||||
### Available Configurations {#sec-available-configs}
|
||||
|
||||
::: {.info}
|
||||
|
||||
The below configurations are provided for demonstration purposes, and are
|
||||
**not** designed to be installed as is. You may
|
||||
|
||||
#### Nix {#sec-configs-nix}
|
||||
|
||||
`Nix` configuration by default provides LSP/diagnostic support for Nix alongside
|
||||
a set of visual and functional plugins. By running `nix run .#`, which is the
|
||||
default package, you will build Neovim with this config.
|
||||
|
||||
```bash
|
||||
$ nix run github:notashelf/nvf#nix test.nix
|
||||
```
|
||||
|
||||
This command will start Neovim with some opinionated plugin configurations, and
|
||||
is designed specifically for Nix. the `nix` configuration lets you see how a
|
||||
fully configured Neovim setup _might_ look like without downloading too many
|
||||
packages or shell utilities.
|
||||
|
||||
#### Maximal {#sec-configs-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.
|
||||
|
||||
```bash
|
||||
$ nix run github:notashelf/nvf#maximal -- test.nix
|
||||
```
|
||||
|
||||
It uses the same configuration template with the [Nix](#sec-configs-nix)
|
||||
configuration, but supports many more languages, and enables more utility,
|
||||
companion or fun plugins.
|
||||
|
||||
::: {.warning}
|
||||
|
||||
Running the maximal config will download _a lot_ of packages as it is
|
||||
downloading language servers, formatters, and more. If CPU time and bandwidth
|
||||
are concerns, please use the default package instead.
|
||||
|
||||
:::
|
|
@ -1,14 +0,0 @@
|
|||
# Release Notes {#ch-release-notes}
|
||||
|
||||
This section lists the release notes for tagged version of **nvf** and the
|
||||
current main current main branch
|
||||
|
||||
```{=include=} chapters
|
||||
rl-0.1.md
|
||||
rl-0.2.md
|
||||
rl-0.3.md
|
||||
rl-0.4.md
|
||||
rl-0.5.md
|
||||
rl-0.6.md
|
||||
rl-0.7.md
|
||||
```
|
Loading…
Add table
Add a link
Reference in a new issue