NotAShelf/nvf
1
0
Fork 0
mirror of https://github.com/NotAShelf/nvf.git synced 2024-11-22 13:20:44 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge 8f1b38ee81 into 516174e296

Browse source
This commit is contained in:
raf 2024-11-09 23:07:32 +00:00 committed by GitHub
commit 8889f71247
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
26 changed files with 401 additions and 1127 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
.github/README.md vendored
View file

@ -48,7 +48,7 @@
[Documentation]: #documentation
[Help]: #help
[Contribute]: #contributing
[FAQ]: #faq
[FAQ]: #frequently-asked-questions
[Credits]: #credits
**[<kbd><br> Features <br></kbd>][Features]**
@ -56,7 +56,7 @@
**[<kbd><br> Documentation <br></kbd>][Documentation]**
**[<kbd><br> Help <br></kbd>][Help]**
**[<kbd><br> Contribute <br></kbd>][Contribute]**
**[<kbd><br> FAQ <br></kbd>][Faq]** **[<kbd><br> Credits <br></kbd>][Credits]**
**[<kbd><br> FAQ <br></kbd>][FAQ]** **[<kbd><br> Credits <br></kbd>][Credits]**
</p></div>
@ -64,12 +64,21 @@
## Features
[standalone]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-installation
[NixOS module]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-nixos
[Home-Manager module]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-hm
- **Simple**: One language to rule them all! Use Nix to configure everything,
with additional Lua Support
- **Reproducible**: Your configuration will behave the same _anywhere_. No
surprises, promise!
- **Portable**: nvf depends _solely_ on your Nix store, and nothing else. No
more global binaries! Works on all platforms, without hassle.
- Options to install [standalone], [NixOS module] or [Home-Manager module].
- **Customizable**: There are _almost no defaults_ to annoy you. nvf is fully
customizable through the Nix module system.
- Not comfortable with a full-nix config or want to bring your Lua config? You
can do just that, no unnecessary restrictions.
- **Well-documented**: Documentation is priority. You will _never_ face
undocumented, obscure behaviour.
- **Idiomatic**: nvf does things ✨ _the right way_ ✨ - the codebase is, and
@ -120,7 +129,9 @@ instructions.
## Documentation
The _recommended_ way of installing **nvf** is using either the NixOS or the
### Installation
The _recommended_ way of installing nvf is using either the NixOS or the
Home-Manager module, though it is completely possible and no less supported to
install **nvf** as a standalone package, or a flake output.
@ -138,11 +149,13 @@ Please create an issue on the [issue tracker] if you find the documentation
lacking or confusing. Any improvements to the documentation through pull
requests are also welcome, and appreciated.
## Help
## Getting Help
You can create an issue on the [issue tracker] to ask questions or report bugs.
I am not yet on spaces like matrix or IRC, so please use the issue tracker for
now.
If you are confused, stuck or would like to ask a simple question; you may
create an issue on the [issue tracker] to ask questions or report bugs.
We are not not yet on spaces like matrix or IRC, so please use the issue tracker
for now.
## Contributing
@ -152,7 +165,7 @@ submitting a pull request. You can also create an issue on the [issue tracker]
before submitting a pull request if you would like to discuss a feature or bug
fix.
## FAQ
## Frequently Asked Questions
[appropriate issue template]: https://github.com/NotAShelf/nvf/issues/new/choose
[list of branches]: https://github.com/NotAShelf/nvf/branches
@ -160,13 +173,15 @@ fix.
**Q**: What platforms are supported?
<br/> **A**: nvf actively supports Linux and Darwin platforms using standalone
Nix, NixOS or Home-Manager. Please take a look at the
Nix, NixOS or Home-Manager. Please take a look at the [nvf manual] for available
installation instructions.
**Q**: Can you add _X_?
<br/> **A**: Maybe! It is not one of our goals to support each and every Neovim
plugin, however, I am always open to new modules and plugin setup additions to
**nvf**. Use the [appropriate issue template] and I will consider a module
addition. As mentioned before, PRs adding new features are also welcome.
addition. As mentioned before, pull requests to add new features are also
welcome.
**Q**: A plugin I need is not available in **nvf**. What to do?
<br/> **A**: **nvf** exposes several APIs for you to be able to add your own
@ -185,22 +200,26 @@ better prepare to breaking changes.
### Contributors
Special, heart-felt thanks to
[mnw]: https://github.com/gerg-l/mnw
- [@fufexan](https://github.com/fufexan) - For the transition to flake-parts
- [@FlafyDev](https://github.com/FlafyDev) - For getting the home-manager to
work
nvf would not be what it is today without the awesome people below. Special,
heart-felt thanks to
- [@fufexan](https://github.com/fufexan) - For the transition to flake-parts and
invaluable Nix assistance.
- [@FlafyDev](https://github.com/FlafyDev) - For getting home-manager module to
work and Nix assistance.
- [@n3oney](https://github.com/n3oney) - For making custom keybinds finally
possible
possible, and other module additions.
- [@horriblename](https://github.com/horriblename) - For actively implementing
planned features and quality of life updates
planned features and quality of life updates.
- [@Yavko](https://github.com/Yavko) - For the amazing **nvf** logo
- [@FrothyMarrow](https://github.com/FrothyMarrow) - For seeing mistakes that I
could not
- [@Diniamo](https://github.com/Diniamo) - For actively submitting PRs, pull
requests and overall assistence
- [@Gerg-l](https://github.com/gerg-l) - For the modern Neovim wrapper, mnw and
occasional code improvements
could not.
- [@Diniamo](https://github.com/Diniamo) - For actively submitting pull
requests, issues and assistance with maintenance of nvf.
- [@Gerg-l](https://github.com/gerg-l) - For the modern Neovim wrapper, [mnw],
and occasional code improvements.
and everyone who has submitted issues or pull requests!
@ -214,7 +233,7 @@ including:
is originally based on.
- [@sioodmy's](https://github.com/sioodmy)
[dotfiles](https://github.com/sioodmy/dotfiles) that inspired the design
choices.
choices for UI and plugin defaults.
- [@wiltaylor's](https://github.com/wiltaylor)
[neovim-flake](https://github.com/wiltaylor/neovim-flake) for plugin and
design ideas.
@ -229,10 +248,11 @@ recommend checking their work out.
## License
Following the license of the
[original neovim-flake](https://github.com/jordanisaacs/neovim-flake), **nvf**
has been made available under the [**MIT License**](LICENSE). However, all
assets and documentation are published under the
[**CC BY License**](https://github.com/NotAShelf/nvf/blob/main/.github/assets/LICENSE).
[original neovim-flake](https://github.com/jordanisaacs/neovim-flake), nvf has
been made available under the [**MIT License**](LICENSE). However, all assets
and documentation are published under the
[**CC BY License**](https://github.com/NotAShelf/nvf/blob/main/.github/assets/LICENSE)
under explicit permission by the artist.
<h6 align="center">Yes, this includes the logo work too. Stop taking artwork that is not yours!</h6>

85
docs/manual.nix
View file

@ -1,62 +1,111 @@
{
lib,
stdenvNoCC,
fetchzip,
runCommandLocal,
# build inputs
nixos-render-docs,
documentation-highlighter,
dart-sass,
path,
# nrd configuration
release,
optionsJSON,
}:
} @ args: let
manual-release = args.release or "unstable";
scss-reset = fetchzip {
url = "https://github.com/Frontend-Layers/scss-reset/archive/refs/tags/1.4.2.zip";
hash = "sha256-cif5Sx8Ca5vxdw/mNAgpulLH15TwmzyJFNM7JURpoaE=";
};
compileStylesheet = runCommandLocal "compile-nvf-stylesheet" {} ''
mkdir -p $out
tmpfile=$(mktemp -d)
trap "rm -r $tmpfile" EXIT
ln -s "${scss-reset}/build" "$tmpfile/scss-reset"
${dart-sass}/bin/sass --load-path "$tmpfile" \
${./static/style.scss} "$out/style.css"
echo "Generated styles"
'';
in
stdenvNoCC.mkDerivation {
name = "nvf-manual";
src = builtins.path {
path = lib.sourceFilesBySuffices ./manual [".md"];
name = "nvf-manual";
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,media}
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
substituteInPlace ./options.md \
--subst-var-by \
OPTIONS_JSON \
${optionsJSON}/share/doc/nixos/options.json
--subst-var-by OPTIONS_JSON ./config-options.json
substituteInPlace ./manual.md \
--subst-var-by \
NVF_VERSION \
${release}
--subst-var-by NVF_VERSION ${manual-release}
# copy stylesheet
cp ${./static/style.css} "$dest/style.css"
substituteInPlace ./hacking/additional-plugins.md \
--subst-var-by NVF_REPO "https://github.com/notashelf/nvf/blob/${manual-release}"
# copy release notes
# Move compiled stylesheet
cp -vt $dest \
${compileStylesheet}/style.css
# Move release notes
cp -vr ${./release-notes} release-notes
# generate manual from
# 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 release} \
--stylesheet style.css \
--script highlightjs/highlight.pack.js \
--script highlightjs/loader.js \
--revision ${lib.trivial.revisionWithDefault manual-release} \
--stylesheet "$dest"/style.css \
--script ./highlightjs/highlight.pack.js \
--script ./highlightjs/loader.js \
--script script/anchor-use.js \
--script script/anchor-min.js \
--toc-depth 2 \
--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
'';

38
docs/manual/configuring/custom-plugins/configuring.md
View file

@ -1,12 +1,13 @@
# Configuring {#sec-configuring-plugins}
Just making the plugin to your Neovim configuration available might not always be enough. In that
case, you can write custom lua config using either `config.vim.lazy.plugins.*.setupOpts`
`config.vim.extraPlugins.*.setup` or `config.vim.luaConfigRC`.
Just making the plugin to your Neovim configuration available might not always
be enough. In that case, you can write custom lua config using either
`config.vim.lazy.plugins.*.setupOpts` `config.vim.extraPlugins.*.setup` or
`config.vim.luaConfigRC`.
The first option uses an extended version of `lz.n`'s PluginSpec. `setupModule` and `setupOpt` can
be used if the plugin uses a `require('module').setup(...)` pattern. Otherwise, the `before` and
`after` hooks should do what you need.
The first option uses an extended version of `lz.n`'s PluginSpec. `setupModule`
and `setupOpt` can be used if the plugin uses a `require('module').setup(...)`
pattern. Otherwise, the `before` and `after` hooks should do what you need.
```nix
{
@ -24,10 +25,11 @@ be used if the plugin uses a `require('module').setup(...)` pattern. Otherwise,
}
```
The second option uses an attribute set, which maps DAG section names to a custom type, which has
the fields `package`, `after`, `setup`. They allow you to set the package of the plugin, the
sections its setup code should be after (note that the `extraPlugins` option has its own DAG
scope), and the its setup code respectively. For example:
The second option uses an attribute set, which maps DAG section names to a
custom type, which has the fields `package`, `after`, `setup`. They allow you to
set the package of the plugin, the sections its setup code should be after (note
that the `extraPlugins` option has its own DAG scope), and the its setup code
respectively. For example:
```nix
config.vim.extraPlugins = with pkgs.vimPlugins; {
@ -56,13 +58,17 @@ For example:
}
```
<!-- deno-fmt-ignore-start -->
::: {.note}
If your configuration needs to be put in a specific place in the config, you
can use functions from `inputs.nvf.lib.nvim.dag` to order it. Refer to
https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix
One of the greatest strengths of nvf is the ability to order
snippets of configuration via the DAG system. It will allow specifying positions
of individual sections of configuration as needed. nvf provides helper functions
in the extended library, usually under `inputs.nvf.lib.nvim.dag` that you may
use.
Please refer to the [DAG section](/index.xhtml#ch-dag-entries) in the nvf manual
to find out more about the DAG system.
:::
If you successfully made your plugin work, please feel free to create a PR to
add it to **nvf** or open an issue with your findings so that we can make it
available for everyone easily.
<!-- deno-fmt-ignore-end -->

15
docs/manual/configuring/custom-plugins/legacy-method.md
View file

@ -1,6 +1,6 @@
# Legacy Method {#sec-legacy-method}
Prior to version 0.5, the method of adding new plugins was adding the plugin
Prior to version v0.5, the method of adding new plugins was adding the plugin
package to `vim.startPlugins` and add its configuration as a DAG under one of
`vim.configRC` or `vim.luaConfigRC`. Users who have not yet updated to 0.5, or
prefer a more hands-on approach may use the old method where the load order of
@ -8,13 +8,14 @@ the plugins is determined by DAGs.
## Adding plugins {#sec-adding-plugins}
To add a plugin to **nvf**'s runtime, you may add it
To add a plugin not available in nvf as a module to your configuration, you may
add it to [](#opt-vim.startPlugins) in order to make it available to Neovim at
runtime.
```nix
{pkgs, ...}: {
# add a package from nixpkgs to startPlugins
vim.startPlugins = [
pkgs.vimPlugins.aerial-nvim ];
# Add a Neovim plugin from Nixpkgs to the runtime.
vim.startPlugins = [pkgs.vimPlugins.aerial-nvim];
}
```
@ -23,7 +24,9 @@ provide configuration as a DAG using the **nvf** extended library.
```nix
{inputs, ...}: let
# assuming you have an input called nvf pointing at the nvf repository
# This assumes you have an input called 'nvf' in your flake inputs
# and 'inputs' in your specialArgs. In the case you have passed 'nvf'
# to specialArgs, the 'inputs' prefix may be omitted.
inherit (inputs.nvf.lib.nvim.dag) entryAnywhere;
in {
vim.luaConfigRC.aerial-nvim= entryAnywhere ''

29
docs/manual/hacking.md
View file

@ -1,16 +1,25 @@
# Hacking nvf {#ch-hacking}
**nvf** is designed for developers as much as it is for the end user. I would like any potential contributor
to be able to propagate their desired changes into the repository without the extra effort. As such, below are guides
(and guidelines) to streamline the contribution process and ensure that your valuable input seamlessly integrates
into **nvf**'s development without leaving question marks in your head.
[open issues]: https://github.com/notashelf/nvf/issues
[new issue]: https://github.com/notashelf/nvf/issues/new
This section is mainly directed towards those who wish to contribute code into **nvf**. If you wish to instead
report a bug or discuss a potential feature implementation, first look among the
already [open issues](https://github.com/notashelf/nvf/issues) and if no matching issue exists you may open
a [new issue](https://github.com/notashelf/nvf/issues/new) and describe your problem/request. While creating an
issue, please try to include as much information as you can, ideally also include relevant context in which an issue
occurs or a feature should be implemented.
nvf is designed for the developer as much as it is designed for the end-user. We
would like for any contributor to be able to propagate their changes, or add new
features to the project with minimum possible friction. As such, below are the
guides and guidelines written to streamline the contribution process and to
ensure that your valuable input integrates into nvf's development as seamlessly
as possible without leaving any question marks in your head.
This section is directed mainly towards those who wish to contribute code into
the project. If you instead wish to report a bug, or discuss a potential new
feature implementation (which you do not wish to implement yourself) first look
among the already [open issues] and if no matching issue exists you may open a
[new issue] and describe your problem/request.
While creating an issue, please try to include as much information as you can,
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

34
docs/manual/hacking/additional-plugins.md
View file

@ -1,10 +1,9 @@
# Adding Plugins {#sec-additional-plugins}
To add a new Neovim plugin, first add the source url in the inputs section of `flake.nix`
with the prefix `plugin-`
To add a new Neovim plugin, first add the source url in the inputs section of
`flake.nix` with the prefix `plugin-`
```nix
{
inputs = {
# ...
@ -17,13 +16,18 @@ with the prefix `plugin-`
}
```
Prepending `plugin-` to the name of the input will allow nvf to automatically
discover inputs that are marked as plugins, and make them available in
`vim.startPlugins` or other areas that require a very specific plugin type as it
is defined in `@NVF_REPO@/lib/types/plugins.nix`
The addition of the `plugin-` prefix will allow **nvf** to autodiscover the
input from the flake inputs automatically, allowing you to refer to it in areas
that require a very specific plugin type as defined in `lib/types/plugins.nix`
You can now reference this plugin using its string name, the plugin will be
built with the name and source URL from the flake input, allowing you to
refer to it as a **string**.
built with the name and source URL from the flake input, allowing you to refer
to it as a **string**.
```nix
config.vim.startPlugins = ["neodev-nvim"];
@ -33,11 +37,11 @@ config.vim.startPlugins = ["neodev-nvim"];
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`.
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:
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
@ -86,7 +90,8 @@ require('plugin-name').setup({
})
```
Now users can set any of the pre-defined option field, and can also add their own fields!
Now users can set any of the pre-defined option field, and can also add their
own fields!
```nix
# in user's config
@ -110,8 +115,8 @@ As you've seen above, `toLuaObject` is used to convert our nix attrSet
1. nix `null` converts to lua `nil`
2. number and strings convert to their lua counterparts
3. nix attrSet/list convert into lua tables
4. you can write raw lua code using `lib.generators.mkLuaInline`. This
function is part of nixpkgs.
4. you can write raw lua code using `lib.generators.mkLuaInline`. This function
is part of nixpkgs.
Example:
@ -127,8 +132,8 @@ vim.your-plugin.setupOpts = {
## 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`.
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
@ -163,6 +168,7 @@ in {
```
This results in the following lua code:
```lua
require('lz.n').load({
{

9
docs/manual/installation.md
View file

@ -1,9 +1,12 @@
# 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](#ch-module-installation)
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

56
docs/manual/installation/custom-configuration.md
View file

@ -1,8 +1,9 @@
# Standalone Installation {#ch-standalone-installation}
It is possible to install **nvf** without depending on NixOS or home-manager as the parent
module system, using the `neovimConfiguration` function exposed by **nvf** extended library.
It takes in the configuration as a module, and returns an attribute set as a result.
It is possible to install nvf without depending on NixOS or Home-Manager as the
parent module system, using the `neovimConfiguration` function exposed in the
extended library. This function will take `modules` and `extraSpecialArgs` as
arguments, and return the following schema as a result.
```nix
{
@ -13,6 +14,55 @@ It takes in the configuration as a module, and returns an attribute set as a res
}
```
An example flake that exposes your custom Neovim configuration might look like
```nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
nvf.url = "github:notashelf/nvf";
};
outputs = {
self,
nixpkgs,
...
} @ inputs: {
packages."x86_64-linux" = let
neovimConfigured = (inputs.nvf.lib.neovimConfiguration {
inherit (nixpkgs.legacyPackages."x86_64-linux") pkgs;
modules = [{
config.vim = {
# Enable custom theming options
theme.enable = true;
# Enable Treesitter
tree-sitter.enable = true;
# Other options will go here. Refer to the config
# reference in Appendix B of the nvf manual.
# ...
};
}];
});
in {
# Set the default package to the wrapped instance of Neovim.
# This will allow running your Neovim configuration with
# `nix run` and in addition, sharing your configuration with
# other users in case your repository is public.
default = neovimConfigured.neovim;
};
};
}
```
<!-- TODO: mention the built-in flake template here when it is added -->
The above setup will allow to set up nvf as a standalone flake, which you can
build independently from your system configuration while also possibly sharing
it with others. The next two chapters will detail specific usage of such a setup
for a package output in the context of NixOS or Home-Manager installation.
```{=include=} chapters
standalone/nixos.md
standalone/home-manager.md

4
docs/manual/installation/modules.md
View file

@ -1,5 +1,9 @@
# Module Installation {#ch-module-installation}
The below chapters will describe installing nvf as NixOS and Home-Manager
modules. Note that those methods are mutually exclusive, and will likely cause
path collisions if used simultaneously.
```{=include=} chapters
modules/nixos.md
modules/home-manager.md

6
docs/manual/installation/modules/home-manager.md
View file

@ -77,7 +77,9 @@ configure **nvf**.
```
::: {.note}
**nvf** exposes a lot of options, most of which are not referenced in the
installation sections of the manual. You may find all avaliable options
in the [appendix](https://notashelf.github.io/nvf/options)
installation sections of the manual. You may find all available options in the
[appendix](https://notashelf.github.io/nvf/options)
:::

6
docs/manual/installation/modules/nixos.md
View file

@ -76,7 +76,9 @@ configure **nvf**.
```
::: {.note}
**nvf** exposes a lot of options, most of which are not referenced in the
installation sections of the manual. You may find all avaliable options
in the [appendix](https://notashelf.github.io/nvf/options)
installation sections of the manual. You may find all available options in the
[appendix](https://notashelf.github.io/nvf/options)
:::

19
docs/manual/installation/standalone/home-manager.md
View file

@ -1,12 +1,12 @@
# Standalone Installation on Home-Manager {#ch-standalone-hm}
Your built Neoevim configuration can be exposed as a flake output to make it
Your built Neovim configuration can be exposed as a flake output to make it
easier to share across machines, repositories and so on. Or it can be added to
your system packages to make it available across your system.
The following is an example installation of `nvf` as a standalone package with
the default theme enabled. You may use other options inside `config.vim` in
`configModule`, but this example will not cover that.
`configModule`, but this example will not cover that extensively.
```nix
{
@ -30,23 +30,22 @@ the default theme enabled. You may use other options inside `config.vim` in
};
customNeovim = nvf.lib.neovimConfiguration {
modules = [configModule];
inherit pkgs;
modules = [configModule];
};
in {
# this will make the package available as a flake input
# This will make the package available as a flake output under 'packages'
packages.${system}.my-neovim = customNeovim.neovim;
# this is an example home-manager configuration
# using the built neovim package
# Example Home-Manager configuration using the configured Neovim package
homeConfigurations = {
"your-username@your-hostname" = home-manager.lib.homeManagerConfiguration {
# ...
modules = [
./home.nix
# this will make wrapped neovim available in your system packages
{environment.systemPackages = [customNeovim.neovim];}
# This will make Neovim available to users using the Home-Manager
# configuration. To make the package available to all users, prefer
# environment.systemPackages in your NixOS configuration.
{home.packages = [customNeovim.neovim];}
];
# ...
};

14
docs/manual/installation/standalone/nixos.md
View file

@ -1,12 +1,12 @@
# Standalone Installation on NixOS {#ch-standalone-nixos}
Your built Neoevim configuration can be exposed as a flake output to make it
Your built Neovim configuration can be exposed as a flake output to make it
easier to share across machines, repositories and so on. Or it can be added to
your system packages to make it available across your system.
The following is an example installation of `nvf` as a standalone package with
the default theme enabled. You may use other options inside `config.vim` in
`configModule`, but this example will not cover that.
`configModule`, but this example will not cover that extensively.
```nix
{
@ -30,21 +30,19 @@ the default theme enabled. You may use other options inside `config.vim` in
};
customNeovim = nvf.lib.neovimConfiguration {
modules = [configModule];
inherit pkgs;
modules = [configModule];
};
in {
# this will make the package available as a flake input
# This will make the package available as a flake output under 'packages'
packages.${system}.my-neovim = customNeovim.neovim;
# this is an example nixosConfiguration using the built neovim package
# Example nixosConfiguration using the configured Neovim package
nixosConfigurations = {
yourHostName = nixpkgs.lib.nixosSystem {
# ...
modules = [
./configuration.nix # or whatever your configuration is
# this will make wrapped neovim available in your system packages
# This will make wrapped neovim available in your system packages
{environment.systemPackages = [customNeovim.neovim];}
];
# ...

4
docs/manual/manual.md
View file

@ -17,8 +17,8 @@ configuring.md
hacking.md
```
```{=include=} appendix html:into-file=//plugins.html
plugins.md
```{=include=} appendix html:into-file=//quirks.html
quirks.md
```
```{=include=} appendix html:into-file=//options.html

12
docs/manual/options.md
View file

@ -1,8 +1,14 @@
# Neovim Flake Configuration Options {#ch-options}
Below are the options provided by nvf provided in no particular order.
They may include useful comments and warnings, or examples on how a module option
is meant to be used.
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.
<!--
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-

16
docs/manual/plugins.md
View file

@ -1,16 +0,0 @@
# Plugin specific quirks {#ch-plugins}
At times, certain plugins refuse to play nicely. Be it as a result of generating
lua from Nix, or the state of packaging. This page shall list any plugins that
are known to misbehave, and potential workarounds.
```{=include=} chapters
plugins/nodejs.md
```
<!--
If adding a new section, uncomment this part and add your page to
plugins/<page>.md
```{=include=} chapters
plugins/page.md
```
-->

21
docs/manual/preface.md
View file

@ -1,7 +1,20 @@
# Preface {#ch-preface}
If you noticed a bug caused by **nvf** then please consider reporting it over
[the issue tracker](https://github.com/notashelf/nvf/issues).
## What is nvf {#sec-what-is-it}
Bugfixes, feature additions and upstreamed changes from your local configurations
are always welcome in the [the pull requests tab](https://github.com/notashelf/nvf/pulls).
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].

13
docs/manual/quirks.md Normal file
View file

@ -0,0 +1,13 @@
# Known Issues and Quirks {#ch-known-issues-quirks}
At times, certain plugins and modules may refuse to play nicely with your setup,
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.-->
```{=include=} chapters
quirks/nodejs.md
```

16
docs/manual/plugins/nodejs.md → docs/manual/quirks/nodejs.md
View file

@ -1,16 +1,22 @@
# NodeJS {#ch-plugins-nodejs}
# 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.
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`).
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-formating relying on your prettier config, while your eslint config diagnoses formatting [which it's not supposed to](https://prettier.io/docs/en/comparison.html))
This results in auto-formating 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.
In the end, you get discrepancies between what your editor does and what it
wants.
Solutions are:

39
docs/manual/try-it-out.md
View file

@ -1,25 +1,27 @@
# 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, three
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
- Maximal
- **Nix** - Nix language server + simple utility plugins
- **Maximal** - Variable language servers + utility and decorative plugins
You may try out any of the provided configurations using the `nix run` command on a system where Nix is installed.
You may try out any of the provided configurations using the `nix run` command
on a system where Nix is installed.
```console
```bash
$ 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 it will be removed from your Nix store
once you garbage collect.
Do keep in mind that this is **susceptible to garbage collection** meaning it
will be removed from your Nix store once you garbage collect.
## Using Prebuilt Configs {#sec-using-prebuild-configs}
## Using Prebuilt Configs {#sec-using-prebuilt-configs}
```console
```bash
$ nix run github:notashelf/nvf#nix
$ nix run github:notashelf/nvf#maximal
```
@ -28,12 +30,19 @@ $ nix run github:notashelf/nvf#maximal
#### Nix {#sec-configs-nix}
`Nix` configuration by default provides LSP/diagnostic support for Nix alongisde a set of visual and functional plugins.
By running `nix run .#`, which is the default package, you will build Neovim with this config.
`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.
#### 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.
`Maximal` is the ultimate configuration that will enable support for more
commonly used language as well as additional complementary plugins. Keep in
mind, however, that this will pull a lot of dependencies.
You are _strongly_ recommended to use the binary cache if you would like to try the Maximal configuration.
::: {.tip}
You are _strongly_ recommended to use the binary cache if you would like to try
the Maximal configuration.
:::

10
docs/static/script/anchor-min.js vendored Normal file
View file

File diff suppressed because one or more lines are too long

4
docs/static/script/anchor-use.js vendored Normal file
View file

@ -0,0 +1,4 @@
document.addEventListener('DOMContentLoaded', function(event) {
anchors.add('h1[id]:not(div.note h1, div.warning h1, div.tip h1, div.caution h1, div.important h1), h2[id]:not(div.note h2, div.warning h2, div.tip h2, div.caution h2, div.important h2), h3[id]:not(div.note h3, div.warning h3, div.tip h3, div.caution h3, div.important h3), h4[id]:not(div.note h4, div.warning h4, div.tip h4, div.caution h4, div.important h4), h5[id]:not(div.note h5, div.warning h5, div.tip h5, div.caution h5, div.important h5), h6[id]:not(div.note h6, div.warning h6, div.tip h6, div.caution h6, div.important h6)');
});

827
docs/static/style.css vendored
View file

File diff suppressed because one or more lines are too long

4
docs/static/style.scss vendored
View file

@ -1,3 +1,5 @@
@use "scss-reset/reset";
:root {
--nmd-color0: #0a3e68;
--nmd-color1: #268598;
@ -32,8 +34,6 @@ $color-blue-700: #1d4ed8;
$color-blue-800: #1e40af;
$color-blue-900: #1e3a8a;
@use "scss-reset/reset";
@mixin boxed {
background: $color-gray-50;
margin: 2rem 16px;

97
docs/static/tomorrow-night.min.css vendored
View file

@ -4,99 +4,4 @@
License: ~ MIT (or more permissive) [via base16-schemes-source]
Maintainer: @highlightjs/core-team
Version: 2021.09.0
*/
pre code.hljs {
display: block;
overflow-x: auto;
padding: 1em;
}
code.hljs {
padding: 3px 5px;
}
.hljs {
color: #ccc;
background: #2d2d2d;
}
.hljs ::selection,
.hljs::selection {
background-color: #515151;
color: #ccc;
}
.hljs-comment {
color: #999;
}
.hljs-tag {
color: #b4b7b4;
}
.hljs-operator,
.hljs-punctuation,
.hljs-subst {
color: #ccc;
}
.hljs-operator {
opacity: 0.7;
}
.hljs-bullet,
.hljs-deletion,
.hljs-name,
.hljs-selector-tag,
.hljs-template-variable,
.hljs-variable {
color: #f2777a;
}
.hljs-attr,
.hljs-link,
.hljs-literal,
.hljs-number,
.hljs-symbol,
.hljs-variable.constant_ {
color: #f99157;
}
.hljs-class .hljs-title,
.hljs-title,
.hljs-title.class_ {
color: #fc6;
}
.hljs-strong {
font-weight: 700;
color: #fc6;
}
.hljs-addition,
.hljs-code,
.hljs-string,
.hljs-title.class_.inherited__ {
color: #9c9;
}
.hljs-built_in,
.hljs-doctag,
.hljs-keyword.hljs-atrule,
.hljs-quote,
.hljs-regexp {
color: #6cc;
}
.hljs-attribute,
.hljs-function .hljs-title,
.hljs-section,
.hljs-title.function_,
.ruby .hljs-property {
color: #69c;
}
.diff .hljs-meta,
.hljs-keyword,
.hljs-template-tag,
.hljs-type {
color: #c9c;
}
.hljs-emphasis {
color: #c9c;
font-style: italic;
}
.hljs-meta,
.hljs-meta .hljs-keyword,
.hljs-meta .hljs-string {
color: #a3685a;
}
.hljs-meta .hljs-keyword,
.hljs-meta-keyword {
font-weight: 700;
}
*/pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}.hljs{color:#ccc;background:#2d2d2d}.hljs ::selection,.hljs::selection{background-color:#515151;color:#ccc}.hljs-comment{color:#999}.hljs-tag{color:#b4b7b4}.hljs-operator,.hljs-punctuation,.hljs-subst{color:#ccc}.hljs-operator{opacity:.7}.hljs-bullet,.hljs-deletion,.hljs-name,.hljs-selector-tag,.hljs-template-variable,.hljs-variable{color:#f2777a}.hljs-attr,.hljs-link,.hljs-literal,.hljs-number,.hljs-symbol,.hljs-variable.constant_{color:#f99157}.hljs-class .hljs-title,.hljs-title,.hljs-title.class_{color:#fc6}.hljs-strong{font-weight:700;color:#fc6}.hljs-addition,.hljs-code,.hljs-string,.hljs-title.class_.inherited__{color:#9c9}.hljs-built_in,.hljs-doctag,.hljs-keyword.hljs-atrule,.hljs-quote,.hljs-regexp{color:#6cc}.hljs-attribute,.hljs-function .hljs-title,.hljs-section,.hljs-title.function_,.ruby .hljs-property{color:#69c}.diff .hljs-meta,.hljs-keyword,.hljs-template-tag,.hljs-type{color:#c9c}.hljs-emphasis{color:#c9c;font-style:italic}.hljs-meta,.hljs-meta .hljs-keyword,.hljs-meta .hljs-string{color:#a3685a}.hljs-meta .hljs-keyword,.hljs-meta-keyword{font-weight:700}

20
flake.nix
View file

@ -30,29 +30,25 @@
};
homeManagerModules = {
nvf = import ./flake/modules/home-manager.nix self.packages lib;
default = self.homeManagerModules.nvf;
neovim-flake =
lib.warn ''
homeManagerModules.neovim-flake has been deprecated.
Plese use the homeManagerModules.nvf instead
'homeManagerModules.neovim-flake' has been deprecated, and will be removed
in a future release. Please use 'homeManagerModules.nvf' instead.
''
self.homeManagerModules.nvf;
nvf = import ./flake/modules/home-manager.nix self.packages lib;
default = self.homeManagerModules.nvf;
};
nixosModules = {
nvf = import ./flake/modules/nixos.nix self.packages lib;
default = self.nixosModules.nvf;
neovim-flake =
lib.warn ''
nixosModules.neovim-flake has been deprecated.
Please use the nixosModules.nvf instead
'nixosModules.neovim-flake' has been deprecated, and will be removed
in a future release. Please use 'nixosModules.nvf' instead.
''
self.nixosModules.nvf;
nvf = import ./flake/modules/nixos.nix self.packages lib;
default = self.nixosModules.nvf;
};
};