mirror of
				https://github.com/NotAShelf/nvf.git
				synced 2025-10-31 02:52:37 +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