mirror of
https://github.com/NotAShelf/nvf.git
synced 2024-11-01 11:01:15 +00:00
docs: refactor
This commit is contained in:
parent
a35eab716a
commit
e360a1c16c
38 changed files with 829 additions and 789 deletions
141
docs/default.nix
141
docs/default.nix
|
|
@ -2,6 +2,7 @@
|
|||
pkgs,
|
||||
lib ? import ../lib/stdlib-extended.nix pkgs.lib,
|
||||
nmdSrc,
|
||||
...
|
||||
}: let
|
||||
nmd = import nmdSrc {
|
||||
inherit lib;
|
||||
|
|
@ -29,6 +30,8 @@
|
|||
];
|
||||
};
|
||||
|
||||
dontCheckDefinitions = {_module.check = false;};
|
||||
|
||||
githubDeclaration = user: repo: subpath: let
|
||||
urlRef = "main";
|
||||
in {
|
||||
|
|
@ -36,96 +39,102 @@
|
|||
name = "<${repo}/${subpath}>";
|
||||
};
|
||||
|
||||
dontCheckDefinitions = {_module.check = false;};
|
||||
|
||||
nvimPath = toString ./..;
|
||||
hmPath = toString ./..;
|
||||
|
||||
buildOptionsDocs = args @ {
|
||||
modules,
|
||||
includeModuleSystemsOptions ? true,
|
||||
includeModuleSystemOptions ? true,
|
||||
...
|
||||
}: let
|
||||
options = (lib.evalModules {inherit modules;}).options;
|
||||
inherit ((lib.evalModules {inherit modules;})) options;
|
||||
in
|
||||
pkgs.buildPackages.nixosOptionsDoc
|
||||
({
|
||||
pkgs.buildPackages.nixosOptionsDoc ({
|
||||
options =
|
||||
if includeModuleSystemsOptions
|
||||
if includeModuleSystemOptions
|
||||
then options
|
||||
else builtins.removeAttrs (options ["_module"]);
|
||||
else builtins.removeAttrs options ["_module"];
|
||||
transformOptions = opt:
|
||||
opt
|
||||
// {
|
||||
# Clean up declaration sites to not refer to local source tree
|
||||
declarations =
|
||||
map
|
||||
(decl:
|
||||
if lib.hasPrefix nvimPath (toString decl)
|
||||
then
|
||||
githubDeclaration "notashelf" "neovim-flake"
|
||||
(lib.removePrefix "/" (lib.removePrefix nvimPath (toString decl)))
|
||||
else decl)
|
||||
opt.declarations;
|
||||
# Clean up declaration sites to not refer to the Home Manager
|
||||
# source tree.
|
||||
declarations = map (decl:
|
||||
if lib.hasPrefix hmPath (toString decl)
|
||||
then
|
||||
githubDeclaration "notashelf" "neovim-flake"
|
||||
(lib.removePrefix "/" (lib.removePrefix hmPath (toString decl)))
|
||||
else if decl == "lib/modules.nix"
|
||||
then
|
||||
# TODO: handle this in a better way (may require upstream
|
||||
# changes to nixpkgs)
|
||||
githubDeclaration "NixOS" "nixpkgs" decl
|
||||
else decl)
|
||||
opt.declarations;
|
||||
};
|
||||
}
|
||||
// builtins.removeAttrs args ["modules" "includeModuleSystemsOptions"]);
|
||||
// builtins.removeAttrs args ["modules" "includeModuleSystemOptions"]);
|
||||
|
||||
nvimModuleDocs = buildOptionsDocs {
|
||||
modules =
|
||||
import ../modules/modules.nix
|
||||
{
|
||||
inherit pkgs lib;
|
||||
import ../modules/modules.nix {
|
||||
inherit lib pkgs;
|
||||
check = false;
|
||||
}
|
||||
++ [scrubbedPkgsModule];
|
||||
variablelistId = "neovim-flake-options";
|
||||
};
|
||||
|
||||
docs = nmd.buildDocBookDocs {
|
||||
pathName = "neovim-flake";
|
||||
projectName = "neovim-flake";
|
||||
modulesDocs = [
|
||||
{
|
||||
docBook = pkgs.linkFarm "nvim-module-docs-for-nmd" {
|
||||
"nmd-result/neovim-flake-options.xml" = nvimModuleDocs.optionsDocBook;
|
||||
};
|
||||
}
|
||||
];
|
||||
documentsDirectory = ./.;
|
||||
documentType = "book";
|
||||
chunkToc = ''
|
||||
<toc>
|
||||
<d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-neovim-flake-manual">
|
||||
<?dbhtml filename="index.html"?>
|
||||
<d:tocentry linkend="ch-options">
|
||||
<?dbhtml filename="options.html"?>
|
||||
</d:tocentry>
|
||||
<d:tocentry linkend="ch-release-notes">
|
||||
<?dbhtml filename="release-notes.html"?>
|
||||
</d:tocentry>
|
||||
</d:tocentry>
|
||||
</toc>
|
||||
'';
|
||||
};
|
||||
in {
|
||||
options.json =
|
||||
pkgs.runCommand "options.json"
|
||||
# TODO: Use `nvimOptionsDoc.optionsJSON` directly once upstream
|
||||
# `nixosOptionsDoc` is more customizable
|
||||
{
|
||||
meta.description = "List of neovim-flake options in JSON format";
|
||||
release-config = builtins.fromJSON (builtins.readFile ../release.json);
|
||||
revision = "release-${release-config.release}";
|
||||
# Generate the `man home-configuration.nix` package
|
||||
home-configuration-manual =
|
||||
pkgs.runCommand "neovim-flake-reference-manpage" {
|
||||
nativeBuildInputs = [pkgs.buildPackages.installShellFiles pkgs.nixos-render-docs];
|
||||
allowedReferences = ["out"];
|
||||
} ''
|
||||
mkdir -p $out/{share/doc,nix-support}
|
||||
cp -a ${nvimModuleDocs.optionsJSON}/share/doc/nixos $out/share/doc/neovim-flake
|
||||
substitute \
|
||||
${nvimModuleDocs.optionsJSON}/nix-support/hydra-build-products \
|
||||
$out/nix-support/hydra-build-products \
|
||||
--replace \
|
||||
'${nvimModuleDocs.optionsJSON}/share/doc/nixos' \
|
||||
"$out/share/doc/neovim-flake"
|
||||
# Generate manpages.
|
||||
mkdir -p $out/share/man/man5
|
||||
mkdir -p $out/share/man/man1
|
||||
nixos-render-docs -j $NIX_BUILD_CORES options manpage \
|
||||
--revision ${revision} \
|
||||
--header ${./home-configuration-nix-header.5} \
|
||||
--footer ${./home-configuration-nix-footer.5} \
|
||||
${nvimModuleDocs.optionsJSON}/share/doc/nixos/options.json \
|
||||
$out/share/man/man5/home-configuration.nix.5
|
||||
cp ${./home-manager.1} $out/share/man/man1/home-manager.1
|
||||
'';
|
||||
# Generate the HTML manual pages
|
||||
neovim-flake-manual = pkgs.callPackage ./manual.nix {
|
||||
inherit revision;
|
||||
outputPath = "share/doc/neovim-flake";
|
||||
nmd = nmdSrc;
|
||||
options = {
|
||||
neovim-flake = nvimModuleDocs.optionsJSON;
|
||||
};
|
||||
};
|
||||
html = neovim-flake-manual;
|
||||
htmlOpenTool = pkgs.callPackage ./html-open-tool.nix {} {inherit html;};
|
||||
in {
|
||||
inherit nmdSrc;
|
||||
|
||||
inherit (docs) manPages;
|
||||
options = {
|
||||
# TODO: Use `hmOptionsDocs.optionsJSON` directly once upstream
|
||||
# `nixosOptionsDoc` is more customizable.
|
||||
json =
|
||||
pkgs.runCommand "options.json" {
|
||||
meta.description = "List of Home Manager options in JSON format";
|
||||
} ''
|
||||
mkdir -p $out/{share/doc,nix-support}
|
||||
cp -a ${nvimModuleDocs.optionsJSON}/share/doc/nixos $out/share/doc/home-manager
|
||||
substitute \
|
||||
${nvimModuleDocs.optionsJSON}/nix-support/hydra-build-products \
|
||||
$out/nix-support/hydra-build-products \
|
||||
--replace \
|
||||
'${nvimModuleDocs.optionsJSON}/share/doc/nixos' \
|
||||
"$out/share/doc/home-manager"
|
||||
'';
|
||||
};
|
||||
|
||||
manual = {inherit (docs) html htmlOpenTool;};
|
||||
manPages = home-configuration-manual;
|
||||
manual = {inherit html htmlOpenTool;};
|
||||
}
|
||||
|
|
|
|||
8
docs/highlight-style.css
Normal file
8
docs/highlight-style.css
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
pre {
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
pre code.hljs {
|
||||
border: none;
|
||||
margin: 0;
|
||||
}
|
||||
43
docs/html-open-tool.nix
Normal file
43
docs/html-open-tool.nix
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
{
|
||||
writeShellScriptBin,
|
||||
makeDesktopItem,
|
||||
symlinkJoin,
|
||||
}: {
|
||||
html,
|
||||
pathName ? "neovim-flake",
|
||||
projectName ? pathName,
|
||||
name ? "${pathName}-help",
|
||||
}: let
|
||||
helpScript = writeShellScriptBin name ''
|
||||
set -euo pipefail
|
||||
|
||||
if [[ ! -v BROWSER || -z $BROWSER ]]; then
|
||||
for candidate in xdg-open open w3m; do
|
||||
BROWSER="$(type -P $candidate || true)"
|
||||
if [[ -x $BROWSER ]]; then
|
||||
break;
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
if [[ ! -v BROWSER || -z $BROWSER ]]; then
|
||||
echo "$0: unable to start a web browser; please set \$BROWSER"
|
||||
exit 1
|
||||
else
|
||||
exec "$BROWSER" "${html}/share/doc/${pathName}/index.xhtml"
|
||||
fi
|
||||
'';
|
||||
|
||||
desktopItem = makeDesktopItem {
|
||||
name = "${pathName}-manual";
|
||||
desktopName = "${projectName} Manual";
|
||||
genericName = "View ${projectName} documentation in a web browser";
|
||||
icon = "nix-snowflake";
|
||||
exec = "${helpScript}/bin/${name}";
|
||||
categories = ["System"];
|
||||
};
|
||||
in
|
||||
symlinkJoin {
|
||||
inherit name;
|
||||
paths = [helpScript desktopItem];
|
||||
}
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<refmeta>
|
||||
<refentrytitle>neovim-flake configuration</refentrytitle>
|
||||
<manvolnum>5</manvolnum>
|
||||
<refmiscinfo class="source">neovim-flake</refmiscinfo>
|
||||
<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>neovim configuration</refname>
|
||||
<refpurpose>neovim-flake configuration specification</refpurpose>
|
||||
</refnamediv>
|
||||
<refsection>
|
||||
<title>Description</title>
|
||||
<para>
|
||||
Custom configuration is done with the neovim-flake.lib.neovimConfiguration if home-manager module is not in use.
|
||||
It takes in the configuration as a module.
|
||||
|
||||
<programlisting>
|
||||
neovim-flake.lib.neovimConfiguration {
|
||||
inherit pkgs;
|
||||
modules = [{config = xxx;}];
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
The output of the configuration function is an attrset.
|
||||
</para>
|
||||
<para>
|
||||
In case of the home-manager module, all options will be available under programs.neovim-flake once the module has
|
||||
been imported from the flake inputs.
|
||||
|
||||
<programlisting>
|
||||
{
|
||||
options = "The options that were available to configure";
|
||||
config = "The outputted configuration";
|
||||
pkgs = "The package set used to evaluate the module";
|
||||
neovim = "The built neovim package";
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsection>
|
||||
<refsection>
|
||||
<title>Options</title>
|
||||
<para>
|
||||
You can use the following options in your neovim configuration.
|
||||
</para>
|
||||
<xi:include href="./nmd-result/neovim-flake-options.xml" xpointer="neovim-flake-options"/>
|
||||
</refsection>
|
||||
</refentry>
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
<reference xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<title>neovim-flake Reference Pages</title>
|
||||
<info>
|
||||
<author><personname>neovim-flake contributors</personname></author>
|
||||
<copyright>
|
||||
<year>2023</year>
|
||||
<holder>neovim-flake contributors</holder>
|
||||
</copyright>
|
||||
</info>
|
||||
<xi:include href="man-configuration.xml" />
|
||||
</reference>
|
||||
64
docs/manual.nix
Normal file
64
docs/manual.nix
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
{
|
||||
stdenv,
|
||||
lib,
|
||||
documentation-highlighter,
|
||||
nmd,
|
||||
revision,
|
||||
outputPath ? "share/doc/neovim-flake",
|
||||
options,
|
||||
nixos-render-docs,
|
||||
}:
|
||||
stdenv.mkDerivation {
|
||||
name = "neovim-flake-manual";
|
||||
|
||||
nativeBuildInputs = [nixos-render-docs];
|
||||
|
||||
src = ./manual;
|
||||
|
||||
buildPhase = ''
|
||||
mkdir -p out/media
|
||||
|
||||
mkdir -p out/highlightjs
|
||||
cp -t out/highlightjs \
|
||||
${documentation-highlighter}/highlight.pack.js \
|
||||
${documentation-highlighter}/LICENSE \
|
||||
${documentation-highlighter}/mono-blue.css \
|
||||
${documentation-highlighter}/loader.js
|
||||
|
||||
substituteInPlace ./options.md \
|
||||
--replace \
|
||||
'@OPTIONS_JSON@' \
|
||||
${options.neovim-flake}/share/doc/nixos/options.json
|
||||
|
||||
substituteInPlace ./manual.md \
|
||||
--replace \
|
||||
'@VERSION@' \
|
||||
${revision}
|
||||
|
||||
cp ${nmd}/static/style.css out/style.css
|
||||
cp -t out/highlightjs ${nmd}/static/highlightjs/tomorrow-night.min.css
|
||||
cp ${./highlight-style.css} out/highlightjs/highlight-style.css
|
||||
|
||||
nixos-render-docs manual html \
|
||||
--manpage-urls ./manpage-urls.json \
|
||||
--revision ${lib.trivial.revisionWithDefault revision} \
|
||||
--stylesheet style.css \
|
||||
--stylesheet highlightjs/tomorrow-night.min.css \
|
||||
--stylesheet highlightjs/highlight-style.css \
|
||||
--script highlightjs/highlight.pack.js \
|
||||
--script highlightjs/loader.js \
|
||||
--toc-depth 1 \
|
||||
--section-toc-depth 1 \
|
||||
manual.md \
|
||||
out/index.xhtml
|
||||
'';
|
||||
|
||||
installPhase = ''
|
||||
dest="$out/${outputPath}"
|
||||
mkdir -p "$(dirname "$dest")"
|
||||
mv out "$dest"
|
||||
|
||||
mkdir -p $out/nix-support/
|
||||
echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products
|
||||
'';
|
||||
}
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
<book xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="book-neovim-flake-manual">
|
||||
<info>
|
||||
<title>neovim-flake Manual</title>
|
||||
</info>
|
||||
<preface>
|
||||
<title>Preface</title>
|
||||
<para>
|
||||
If you believe your problem is caused by a bug in neovim-flake then please consider reporting it over
|
||||
<link xlink:href="tps://github.com/notashelf/neovim-flake/issues">the neovim-flake issue tracker</link>.
|
||||
Bugfixes, feature additions and upstream changes are welcome over
|
||||
<link xlink:href="https://github.com/notashelf/neovim-flake/pulls">the neovim-flake pull requests tab</link>.
|
||||
</para>
|
||||
</preface>
|
||||
<xi:include href="manual/try-it-out.xml"/>
|
||||
<xi:include href="manual/default-configs.xml"/>
|
||||
<xi:include href="manual/custom-configs.xml"/>
|
||||
<xi:include href="manual/custom-package.xml"/>
|
||||
<xi:include href="manual/custom-plugins.xml"/>
|
||||
<xi:include href="manual/home-manager.xml"/>
|
||||
<xi:include href="manual/languages.xml"/>
|
||||
<xi:include href="manual/hacking.xml"/>
|
||||
<appendix xml:id="ch-options">
|
||||
<title>Configuration Options</title>
|
||||
<xi:include href="nmd-result/neovim-flake-options.xml" xpointer="neovim-flake-options" />
|
||||
</appendix>
|
||||
<xi:include href="release-notes/release-notes.xml"/>
|
||||
</book>
|
||||
|
|
@ -1,23 +1,20 @@
|
|||
[[ch-custom-configuration]]
|
||||
== Custom Configuration
|
||||
# Custom Configuration {#ch-custom-configuration}
|
||||
|
||||
Custom configuration is done with the `neovimConfiguration` while using the flake as a standalone package.
|
||||
It takes in the configuration as a module. The output of the configuration function is an attrset.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
```nix
|
||||
{
|
||||
options = "The options that were available to configure";
|
||||
config = "The outputted configuration";
|
||||
pkgs = "The package set used to evaluate the module";
|
||||
neovim = "The built neovim package";
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
The following is an example of a barebones vim configuration with the default theme enabled.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
```nix
|
||||
{
|
||||
inputs.neovim-flake = {
|
||||
url = "github:notashelf/neovim-flake";
|
||||
|
|
@ -59,10 +56,8 @@ The following is an example of a barebones vim configuration with the default th
|
|||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
Your built neovim configuration can be exposed as a flake output, or be added to your system packages to make
|
||||
it available across your system. You may also consider passing the flake output to home-manager to make it available
|
||||
to a specific user *without* using the home-manager module.
|
||||
|
||||
|
||||
to a specific user _without_ using the home-manager module.
|
||||
|
|
@ -1,14 +1,12 @@
|
|||
[[ch-custom-package]]
|
||||
== Custom Neovim Package
|
||||
# Custom Neovim Package {#ch-custom-package}
|
||||
|
||||
As of v0.5, you may now specify the neovim package that will be wrapped with your configuration. This is done with the `vim.package` option.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
```nix
|
||||
{inputs, pkgs, ...}: {
|
||||
# using the neovim-nightly overlay
|
||||
config.vim.package = inputs.neovim-overlay.packages.${pkgs.system}.neovim;
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
The neovim-nightly-overlay always exposes an unwrapped package. If using a different source, you are highly recommended to get an "unwrapped" version of the neovim package,similar to `neovim-unwrapped` in nixpkgs.
|
||||
|
|
@ -1,74 +0,0 @@
|
|||
[[ch-custom-plugins]]
|
||||
== Custom Plugins
|
||||
|
||||
You can use custom plugins, before they are implemented in the flake.
|
||||
To add a plugin, you need to add it to your config's `config.vim.startPlugins` array.
|
||||
|
||||
[[sec-new-method]]
|
||||
=== New Method
|
||||
As of version 0.5, we have a more extensive API for configuring plugins, under `vim.extraPlugins`.
|
||||
|
||||
Instead of using DAGs exposed by the library, you may use the extra plugin module as follows:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
{
|
||||
config.vim.extraPlugins = with pkgs.vimPlugins; {
|
||||
aerial = {
|
||||
package = aerial-nvim;
|
||||
setup = ''
|
||||
require('aerial').setup {
|
||||
-- some lua configuration here
|
||||
}
|
||||
'';
|
||||
};
|
||||
|
||||
harpoon = {
|
||||
package = harpoon;
|
||||
setup = "require('harpoon').setup {}";
|
||||
after = ["aerial"];
|
||||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
[[sec-old-method]]
|
||||
=== Old Method
|
||||
Users who have not yet updated to 0.5, or prefer a more hands-on approach may use the old method where the load order
|
||||
of the plugins is determined by DAGs.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
{
|
||||
# fetch plugin source from GitHub and add it to startPlugins
|
||||
config.vim.startPlugins = [
|
||||
(pkgs.fetchFromGitHub {
|
||||
owner = "FrenzyExists";
|
||||
repo = "aquarium-vim";
|
||||
rev = "d09b1feda1148797aa5ff0dbca8d8e3256d028d5";
|
||||
sha256 = "CtyEhCcGxxok6xFQ09feWpdEBIYHH+GIFVOaNZx10Bs=";
|
||||
})
|
||||
];
|
||||
}
|
||||
----
|
||||
|
||||
However, just making the plugin available might not be enough. In that case, you can write custom vimscript
|
||||
or lua config, using `config.vim.configRC` or `config.vim.luaConfigRC` respectively.
|
||||
These options are attribute sets, and you need to give the configuration you're adding some name, like this:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
{
|
||||
# this will create an "aquarium" section in your init.vim with the contents of your custom config
|
||||
# which will be *appended* to the rest of your configuration, inside your init.vim
|
||||
config.vim.configRC.aquarium = "colorscheme aquiarum";
|
||||
}
|
||||
----
|
||||
|
||||
Note: If your configuration needs to be put in a specific place in the config, you can use functions from
|
||||
`inputs.neovim-flake.lib.nvim.dag` to order it.
|
||||
Refer to https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix to find out more about
|
||||
the DAG system.
|
||||
|
||||
Also, if you successfully made your plugin work, please make a PR to add it to the flake, or open an issue
|
||||
with your findings so that we can make it available for everyone easily.
|
||||
10
docs/manual/custom-plugins.md
Normal file
10
docs/manual/custom-plugins.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
# Custom Plugins {#ch-custom-plugins}
|
||||
|
||||
You can use custom plugins, before they are implemented in the flake.
|
||||
To add a plugin, you need to add it to your config's `config.vim.startPlugins` array.
|
||||
|
||||
```{=include=} sections
|
||||
custom-plugins/new-method.md
|
||||
custom-plugins/old-method.md
|
||||
custom-plugins/configuring.md
|
||||
```
|
||||
23
docs/manual/custom-plugins/configuring.md
Normal file
23
docs/manual/custom-plugins/configuring.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
# Configuring {#configuring-plugins}
|
||||
|
||||
Just making the plugin to your neovim configuration available might not always be enough.
|
||||
In that case, you can write custom vimscript or lua config, using `config.vim.configRC` or `config.vim.luaConfigRC`
|
||||
respectively. These options are attribute sets, and you need to give the configuration you're adding some name, like this:
|
||||
|
||||
```nix
|
||||
{
|
||||
# this will create an "aquarium" section in your init.vim with the contents of your custom config
|
||||
# which will be *appended* to the rest of your configuration, inside your init.vim
|
||||
config.vim.configRC.aquarium = "colorscheme aquiarum";
|
||||
}
|
||||
```
|
||||
|
||||
:::{.note}
|
||||
If your configuration needs to be put in a specific place in the config, you can use functions from
|
||||
`inputs.neovim-flake.lib.nvim.dag` to order it.
|
||||
Refer to https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix to find out more about
|
||||
the DAG system.
|
||||
:::
|
||||
|
||||
Also, if you successfully made your plugin work, please make a PR to add it to the flake, or open an issue
|
||||
with your findings so that we can make it available for everyone easily.
|
||||
26
docs/manual/custom-plugins/new-method.md
Normal file
26
docs/manual/custom-plugins/new-method.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
# New Method {#sec-new-method}
|
||||
|
||||
As of version 0.5, we have a more extensive API for configuring plugins, under `vim.extraPlugins`.
|
||||
|
||||
Instead of using DAGs exposed by the library, you may use the extra plugin module as follows:
|
||||
|
||||
```nix
|
||||
{
|
||||
config.vim.extraPlugins = with pkgs.vimPlugins; {
|
||||
aerial = {
|
||||
package = aerial-nvim;
|
||||
setup = ''
|
||||
require('aerial').setup {
|
||||
-- some lua configuration here
|
||||
}
|
||||
'';
|
||||
};
|
||||
|
||||
harpoon = {
|
||||
package = harpoon;
|
||||
setup = "require('harpoon').setup {}";
|
||||
after = ["aerial"];
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
18
docs/manual/custom-plugins/old-method.md
Normal file
18
docs/manual/custom-plugins/old-method.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
# Old Method {#sec-old-method}
|
||||
|
||||
Users who have not yet updated to 0.5, or prefer a more hands-on approach may use the old method where the load order
|
||||
of the plugins is determined by DAGs.
|
||||
|
||||
```nix
|
||||
{
|
||||
# fetch plugin source from GitHub and add it to startPlugins
|
||||
config.vim.startPlugins = [
|
||||
(pkgs.fetchFromGitHub {
|
||||
owner = "FrenzyExists";
|
||||
repo = "aquarium-vim";
|
||||
rev = "d09b1feda1148797aa5ff0dbca8d8e3256d028d5";
|
||||
sha256 = "CtyEhCcGxxok6xFQ09feWpdEBIYHH+GIFVOaNZx10Bs=";
|
||||
})
|
||||
];
|
||||
}
|
||||
```
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
[[ch-default-configs]]
|
||||
== Default Configs
|
||||
|
||||
While you can configure neovim-flake yourself using the builder, here are a few default configurations you can use.
|
||||
|
||||
[[sec-default-tidal]]
|
||||
=== Tidal Cycles
|
||||
|
||||
[source,console]
|
||||
$ nix run github:notashelf/neovim-flake#tidal file.tidal
|
||||
|
||||
Utilizing https://github.com/tidalcycles/vim-tidal[vim-tidal] and mitchmindtree's fantastic https://github.com/mitchmindtree/tidalcycles.nix[tidalcycles.nix] start playing with tidal cycles in a single command.
|
||||
|
||||
In your tidal file, type a cycle e.g. `d1 $ s "drum"` and then press _ctrl+enter_. Super collider with superdirt, and a modified GHCI with tidal will start up and begin playing. Note, you need jack enabled on your system. If you are using pipewire, its as easy as setting `services.pipewire.jack.enable = true`.
|
||||
|
||||
|
||||
[[sec-default-nix]]
|
||||
=== Nix
|
||||
|
||||
[source,console]
|
||||
$ nix run github:notashelf/neovim-flake#nix test.nix
|
||||
|
||||
Enables all the of neovim plugins, with language support for specifically Nix. This lets you see what a fully configured neovim setup looks like without downloading a whole bunch of language servers and associated tools.
|
||||
|
||||
[[sec-default-maximal]]
|
||||
=== Maximal
|
||||
|
||||
[source,console]
|
||||
$ nix shell github:notashelf/neovim-flake#maximal test.nix
|
||||
|
||||
It is the same fully configured neovim as with the <<sec-default-nix,Nix>> config, but with every supported language enabled.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Running the maximal config will download *a lot* of packages as it is downloading language servers, formatters, and more.
|
||||
====
|
||||
10
docs/manual/default-configs.md
Normal file
10
docs/manual/default-configs.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
# Default Configs {#ch-default-configs}
|
||||
|
||||
While you can configure neovim-flake yourself using the builder, you can also use the pre-built configs that are available.
|
||||
Here are a few default configurations you can use.
|
||||
|
||||
```{=include=} sections
|
||||
default-configs/maximal.md
|
||||
default-configs/nix.md
|
||||
default-configs/tidal.md
|
||||
```
|
||||
11
docs/manual/default-configs/maximal.md
Normal file
11
docs/manual/default-configs/maximal.md
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
# Maximal {#sec-default-maximal}
|
||||
|
||||
```bash
|
||||
$ nix shell github:notashelf/neovim-flake#maximal test.nix
|
||||
```
|
||||
|
||||
It is the same fully configured neovim as with the [Nix](#sec-default-nix) config, but with every supported language enabled.
|
||||
|
||||
::: note
|
||||
Running the maximal config will download _a lot_ of packages as it is downloading language servers, formatters, and more.
|
||||
:::
|
||||
7
docs/manual/default-configs/nix.md
Normal file
7
docs/manual/default-configs/nix.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
# Nix {#sec-default-nix}
|
||||
|
||||
```bash
|
||||
$ nix run github:notashelf/neovim-flake#nix test.nix
|
||||
```
|
||||
|
||||
Enables all the of neovim plugins, with language support for specifically Nix. This lets you see what a fully configured neovim setup looks like without downloading a whole bunch of language servers and associated tools.
|
||||
12
docs/manual/default-configs/tidal.md
Normal file
12
docs/manual/default-configs/tidal.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# Tidal Cycles {#sec-default-tidal}
|
||||
|
||||
```bash
|
||||
$ nix run github:notashelf/neovim-flake#tidal file.tidal
|
||||
```
|
||||
|
||||
Utilizing [vim-tidal](https://github.com/tidalcycles/vim-tidal) and mitchmindtree's fantastic
|
||||
[tidalcycles.nix](https://github.com/mitchmindtree/tidalcycles.nix) start playing with tidal cycles in a single command.
|
||||
|
||||
In your tidal file, type a cycle e.g. `d1 $ s "drum"` and then press _ctrl+enter_. Super collider with superdirt, and a
|
||||
modified GHCI with tidal will start up and begin playing. Note, you need jack enabled on your system. If you are using
|
||||
pipewire, its as easy as setting `services.pipewire.jack.enable = true` in your configuration.
|
||||
|
|
@ -1,412 +0,0 @@
|
|||
[[ch-hacking]]
|
||||
== Hacking neovim-flake
|
||||
|
||||
neovim-flake 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 neovim-flake's development without leaving question marks in your head.
|
||||
|
||||
:fork-a-repo: https://help.github.com/articles/fork-a-repo/
|
||||
:open-issues: https://github.com/notashelf/neovim-flake/issues
|
||||
:new-issue: https://github.com/notashelf/neovim-flake/issues/new
|
||||
:seven-rules: https://cbea.ms/git-commit/#seven-rules
|
||||
:example-commit-message: https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef
|
||||
|
||||
This section is mainly directed towards those who wish to contribute code into neovim-flake. If you wish to instead
|
||||
report a bug or discuss a potential feature implementation, first look among the already {open-issues}[open issues] and
|
||||
if no matching issue exists you may open a {new-issue}[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.
|
||||
|
||||
[[sec-contrib-getting-started]]
|
||||
=== Getting started
|
||||
|
||||
You naturally would like to start by forking the repository. If you are new to git, have a look at GitHub's
|
||||
{fork-a-repo}[Fork a repo guide] for instructions on how you can do this. Once you have a fork of neovim-flake
|
||||
you should create a branch starting at the most recent `main` branch.
|
||||
Give your branch a reasonably descriptive name, suffixed by its type - i.e `feature/debugger` or `fix/pesky-bug`.
|
||||
|
||||
Implement your changes and commit them to the newly created branch and when you are happy with the result and positive
|
||||
that it fulfills <<sec-guidelines>>. Once you are confident everything is in order, push the branch to GitHub and
|
||||
{create-a-pull-request}[create a pull request], following the template that you will be prompted to fill.
|
||||
|
||||
[[sec-guidelines]]
|
||||
=== Guidelines
|
||||
:assertions: https://nixos.org/manual/nixos/stable/index.html#sec-assertions
|
||||
:discussions-tab: https://github.com/NotAShelf/neovim-flake/discussions
|
||||
|
||||
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}[discussions tab] ideally (but not necessarily) before you start developing.
|
||||
|
||||
[[sec-documentation]]
|
||||
==== Add adequate documentation
|
||||
:nixpkgs-markdown: https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup
|
||||
:docbook: https://tdg.docbook.org/
|
||||
:asciidoc: https://asciidoc.org/
|
||||
|
||||
Most, if not all, changes warrant changes to the documentation. Module options should be documented with
|
||||
{nixpkgs-markdown}[Nixpkgs-flavoured Markdown], albeit with exceptions.
|
||||
neovim-flake is itself documented using a combination of {docbook}[DocBook] and {asciidoc}[AsciiDoc] conventions.
|
||||
|
||||
The HTML version of this manual containing both the module option descriptions and the documentation of neovim-flake
|
||||
(such as this page) can be generated and opened by typing the following in a shell within a clone of the
|
||||
neovim-flake Git repository:
|
||||
|
||||
[source,console]
|
||||
----
|
||||
$ nix build .#docs-html
|
||||
$ xdg-open ./result/share/doc/neovim-flake/index.html
|
||||
----
|
||||
|
||||
[[sec-guidelines-code-style]]
|
||||
==== Format your code
|
||||
|
||||
Make sure your code is formatted as described in <<sec-code-style>>. To maintain consistency throughout the project
|
||||
you are encouraged to browse through existing code and adopt its style also in new code.
|
||||
|
||||
[[sec-guidelines-commit-message-style]]
|
||||
==== Format your commit messages
|
||||
|
||||
Similar to <<sec-guidelines-code-style>> we encourage a consistent commit message format as described
|
||||
in <<sec-commit-style>>.
|
||||
|
||||
[[sec-commit-style]]
|
||||
==== Commits
|
||||
|
||||
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}[seven rules], 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 <<ex-commit-message>> for a commit message that fulfills these requirements.
|
||||
|
||||
[[ex-commit-message]]
|
||||
.Compliant commit message
|
||||
===============================================================================
|
||||
The commit {example-commit-message}[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef] contains the 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.
|
||||
----
|
||||
===============================================================================
|
||||
|
||||
Long description can be ommitted 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 for your changes.
|
||||
|
||||
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`.
|
||||
|
||||
|
||||
[[sec-code-style]]
|
||||
==== Code Style
|
||||
:alejandra: https://github.com/kamadorueda/alejandra
|
||||
|
||||
**Treewide**
|
||||
Keep lines at a reasonable width, ideally 80 characters or less. This also applies to string literals and module
|
||||
descriptions and documentation.
|
||||
|
||||
**Nix**
|
||||
neovim-flake is formatted by the {alejandra}[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:
|
||||
|
||||
[source,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
|
||||
someOtherValue = mkOption {
|
||||
type = lib.types.bool;
|
||||
description = "Some other description"
|
||||
default = true;
|
||||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
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.
|
||||
|
||||
[source,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.
|
||||
|
||||
[source,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
|
||||
singleItemList = [item1];
|
||||
----
|
||||
|
||||
[[sec-testing]]
|
||||
=== Testing Your Changes
|
||||
|
||||
Once you have made your changes, you will need to test them throughly. 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 posssible.
|
||||
|
||||
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.
|
||||
|
||||
[[sec-keybinds]]
|
||||
=== 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 https://github.com/NotAShelf/neovim-flake/tree/main/lib[extended standard library]. The following section contains
|
||||
a general overview to how you may utilize said functions.
|
||||
|
||||
[[sec-custom-key-mappings]]
|
||||
==== Custom Key Mappings Support for a Plugin
|
||||
|
||||
:maps: https://notashelf.github.io/neovim-flake/options.html#opt-vim.maps.command._name_.action
|
||||
|
||||
To set a mapping, you should define it in `vim.maps.<<mode>>`.
|
||||
The available modes are:
|
||||
|
||||
* normal
|
||||
* insert
|
||||
* select
|
||||
* visual
|
||||
* terminal
|
||||
* normalVisualOp
|
||||
* visualOnly
|
||||
* operator
|
||||
* insertCommand
|
||||
* lang
|
||||
* command
|
||||
|
||||
An example, simple keybinding, can look like this:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
{
|
||||
vim.maps.normal = {
|
||||
"<leader>wq" = {
|
||||
action = ":wq<CR>";
|
||||
silent = true;
|
||||
desc = "Save file and quit";
|
||||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
There are many settings available in the options. Please refer to the {maps}[documentation] to see a list of them.
|
||||
|
||||
`neovim-flake` provides a list of helper commands, so that you don't have to write the mapping attribute sets every
|
||||
time:
|
||||
|
||||
* `mkBinding = key: action: desc:` - makes a basic binding, with `silent` set to true.
|
||||
* `mkExprBinding = key: action: desc:` - makes an expression binding, with `lua`, `silent`, and `expr` set to true.
|
||||
* `mkLuaBinding = key: action: desc:` - makes an expression binding, with `lua`, and `silent` set to true.
|
||||
|
||||
Note that the Lua in these bindings is actual Lua, not pasted into a `:lua` command.
|
||||
Therefore, you either pass in a function like `require('someplugin').some_function`, without actually calling it,
|
||||
or you define your own function, like `function() require('someplugin').some_function() end`.
|
||||
|
||||
Additionally, to not have to repeat the descriptions, there's another utility function with its own set of functions:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
# Utility function that takes two attrsets:
|
||||
# { someKey = "some_value" } and
|
||||
# { someKey = { description = "Some Description"; }; }
|
||||
# and merges them into
|
||||
# { someKey = { value = "some_value"; description = "Some Description"; }; }
|
||||
|
||||
addDescriptionsToMappings = actualMappings: mappingDefinitions:
|
||||
----
|
||||
|
||||
This function can be used in combination with the same `mkBinding` functions as above, except they only take two
|
||||
arguments - `binding` and `action`, and have different names:
|
||||
|
||||
* `mkSetBinding = binding: action:` - makes a basic binding, with `silent` set to true.
|
||||
* `mkSetExprBinding = binding: action:` - makes an expression binding, with `lua`, `silent`, and `expr` set to true.
|
||||
* `mkSetLuaBinding = binding: action:` - makes an expression binding, with `lua`, and `silent` set to true.
|
||||
|
||||
You can read the source code of some modules to see them in action, but their usage should look something like this:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
# plugindefinition.nix
|
||||
{lib, ...}:
|
||||
with lib; {
|
||||
options.vim.plugin = {
|
||||
enable = mkEnableOption "Enable plugin";
|
||||
|
||||
# Mappings should always be inside an attrset called mappings
|
||||
mappings = {
|
||||
# mkMappingOption is a helper function from lib,
|
||||
# that takes a description (which will also appear in which-key),
|
||||
# and a default mapping (which can be null)
|
||||
toggleCurrentLine = mkMappingOption "Toggle current line comment" "gcc";
|
||||
toggleCurrentBlock = mkMappingOption "Toggle current block comment" "gbc";
|
||||
|
||||
toggleOpLeaderLine = mkMappingOption "Toggle line comment" "gc";
|
||||
toggleOpLeaderBlock = mkMappingOption "Toggle block comment" "gb";
|
||||
|
||||
toggleSelectedLine = mkMappingOption "Toggle selected comment" "gc";
|
||||
toggleSelectedBlock = mkMappingOption "Toggle selected block" "gb";
|
||||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
# config.nix
|
||||
{
|
||||
pkgs,
|
||||
config,
|
||||
lib,
|
||||
...
|
||||
}:
|
||||
with lib;
|
||||
with builtins; let
|
||||
cfg = config.vim.plugin;
|
||||
self = import ./plugindefinition.nix {inherit lib;};
|
||||
mappingDefinitions = self.options.vim.plugin;
|
||||
|
||||
# addDescriptionsToMappings is a helper function from lib,
|
||||
# that merges mapping values and their descriptions
|
||||
# into one nice attribute set
|
||||
mappings = addDescriptionsToMappings cfg.mappings mappingDefinitions;
|
||||
in {
|
||||
config = mkIf (cfg.enable) {
|
||||
# ...
|
||||
|
||||
vim.maps.normal = mkMerge [
|
||||
# mkSetBinding is another helper function from lib,
|
||||
# that actually adds the mapping with a description.
|
||||
(mkSetBinding mappings.findFiles "<cmd> Telescope find_files<CR>")
|
||||
(mkSetBinding mappings.liveGrep "<cmd> Telescope live_grep<CR>")
|
||||
(mkSetBinding mappings.buffers "<cmd> Telescope buffers<CR>")
|
||||
(mkSetBinding mappings.helpTags "<cmd> Telescope help_tags<CR>")
|
||||
(mkSetBinding mappings.open "<cmd> Telescope<CR>")
|
||||
|
||||
(mkSetBinding mappings.gitCommits "<cmd> Telescope git_commits<CR>")
|
||||
(mkSetBinding mappings.gitBufferCommits "<cmd> Telescope git_bcommits<CR>")
|
||||
(mkSetBinding mappings.gitBranches "<cmd> Telescope git_branches<CR>")
|
||||
(mkSetBinding mappings.gitStatus "<cmd> Telescope git_status<CR>")
|
||||
(mkSetBinding mappings.gitStash "<cmd> Telescope git_stash<CR>")
|
||||
|
||||
(mkIf config.vim.lsp.enable (mkMerge [
|
||||
(mkSetBinding mappings.lspDocumentSymbols "<cmd> Telescope lsp_document_symbols<CR>")
|
||||
(mkSetBinding mappings.lspWorkspaceSymbols "<cmd> Telescope lsp_workspace_symbols<CR>")
|
||||
|
||||
(mkSetBinding mappings.lspReferences "<cmd> Telescope lsp_references<CR>")
|
||||
(mkSetBinding mappings.lspImplementations "<cmd> Telescope lsp_implementations<CR>")
|
||||
(mkSetBinding mappings.lspDefinitions "<cmd> Telescope lsp_definitions<CR>")
|
||||
(mkSetBinding mappings.lspTypeDefinitions "<cmd> Telescope lsp_type_definitions<CR>")
|
||||
(mkSetBinding mappings.diagnostics "<cmd> Telescope diagnostics<CR>")
|
||||
]))
|
||||
|
||||
(
|
||||
mkIf config.vim.treesitter.enable
|
||||
(mkSetBinding mappings.treesitter "<cmd> Telescope treesitter<CR>")
|
||||
)
|
||||
];
|
||||
|
||||
# ...
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
[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.
|
||||
====
|
||||
|
||||
[[sec-additional-plugins]]
|
||||
=== Adding Plugins
|
||||
|
||||
To add a new neovim plugin, first add the source url in the inputs section of `flake.nix`
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
{
|
||||
inputs = {
|
||||
# ...
|
||||
neodev-nvim = {
|
||||
url = "github:folke/neodev.nvim";
|
||||
flake = false;
|
||||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
Then add the name of the plugin into the `availablePlugins` variable in `lib/types/plugins.nix`:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
# ...
|
||||
availablePlugins = [
|
||||
# ...
|
||||
"neodev-nvim"
|
||||
];
|
||||
----
|
||||
|
||||
You can now reference this plugin using its string name:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
config.vim.startPlugins = ["neodev-nvim"];
|
||||
----
|
||||
21
docs/manual/hacking.md
Normal file
21
docs/manual/hacking.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
# Hacking neovim-flake {#ch-hacking}
|
||||
|
||||
neovim-flake 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 neovim-flake's development without leaving question marks in your head.
|
||||
|
||||
This section is mainly directed towards those who wish to contribute code into neovim-flake. 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/neovim-flake/issues) and if no matching issue exists you may open
|
||||
a [new issue](https://github.com/notashelf/neovim-flake/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.
|
||||
|
||||
```{=include=} sections
|
||||
hacking/getting-started.md
|
||||
hacking/guidelines.md
|
||||
hacking/testing.md
|
||||
hacking/keybinds.md
|
||||
hacking/additional-plugins.md
|
||||
```
|
||||
33
docs/manual/hacking/additional-plugins.md
Normal file
33
docs/manual/hacking/additional-plugins.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
# Adding Plugins {#sec-additional-plugins}
|
||||
|
||||
To add a new neovim plugin, first add the source url in the inputs section of `flake.nix`
|
||||
|
||||
```nix
|
||||
|
||||
{
|
||||
inputs = {
|
||||
# ...
|
||||
neodev-nvim = {
|
||||
url = "github:folke/neodev.nvim";
|
||||
flake = false;
|
||||
};
|
||||
# ...
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Then add the name of the plugin into the `availablePlugins` variable in `lib/types/plugins.nix`:
|
||||
|
||||
```nix
|
||||
# ...
|
||||
availablePlugins = [
|
||||
# ...
|
||||
"neodev-nvim"
|
||||
];
|
||||
```
|
||||
|
||||
You can now reference this plugin using its string name:
|
||||
|
||||
```nix
|
||||
config.vim.startPlugins = ["neodev-nvim"];
|
||||
```
|
||||
10
docs/manual/hacking/getting-started.md
Normal file
10
docs/manual/hacking/getting-started.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
# Getting Started {#sec-contrib-getting-started}
|
||||
|
||||
You naturally would like to start by forking the repository. If you are new to git, 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 neovim-flake
|
||||
you should create a branch starting at the most recent `main` branch.
|
||||
Give your branch a reasonably descriptive name, suffixed by its type - i.e `feature/debugger` or `fix/pesky-bug`.
|
||||
|
||||
Implement your changes and commit them to the newly created branch and when you are happy with the result and positive
|
||||
that it fulfills [Guidelines](#sec-guidelines). Once you are confident everything is in order, push the branch to GitHub and
|
||||
[create a pull request](https://help.github.com/articles/creating-a-pull-request), following the template that you will be prompted to fill.
|
||||
155
docs/manual/hacking/guidelines.md
Normal file
155
docs/manual/hacking/guidelines.md
Normal file
|
|
@ -0,0 +1,155 @@
|
|||
# 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/neovim-flake/discussions) ideally (but not necessarily)
|
||||
before you start developing.
|
||||
|
||||
## Adding Documentation {#sec-guidelines-documentation}
|
||||
|
||||
Most, if not all, changes warrant changes to the documentation. Module options should be documented with
|
||||
[Nixpkgs-flavoured Markdown](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup), albeit with exceptions.
|
||||
|
||||
:::{.note}
|
||||
As of v0.6, neovim-flake is itself documented using full markdown in both module options and the manual.
|
||||
:::
|
||||
|
||||
The HTML version of this manual containing both the module option descriptions and the documentation of neovim-flake
|
||||
(such as this page) can be generated and opened by typing the following in a shell within a clone of the
|
||||
neovim-flake Git repository:
|
||||
|
||||
```console
|
||||
$ nix build .#docs-html
|
||||
$ xdg-open $PWD/result/share/doc/neovim-flake/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}[seven rules], 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 <<ex-commit-message>> for a commit message that fulfills these requirements.
|
||||
|
||||
## Example Commit {#sec-guidelines-ex-commit-message}
|
||||
|
||||
The commit {example-commit-message}[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef] contains the 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.
|
||||
|
||||
```
|
||||
|
||||
Long description can be ommitted 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 for your changes.
|
||||
|
||||
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**
|
||||
Keep lines at a reasonable width, ideally 80 characters or less. This also applies to string literals and module
|
||||
descriptions and documentation.
|
||||
|
||||
**Nix**
|
||||
neovim-flake is formatted by the [alejandra](https://github.com/kamadorueda/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
|
||||
someOtherValue = mkOption {
|
||||
type = lib.types.bool;
|
||||
description = "Some other description";
|
||||
default = true;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
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];
|
||||
|
||||
# this is not ok
|
||||
listToBeAvoided = [
|
||||
item1
|
||||
];
|
||||
```
|
||||
166
docs/manual/hacking/keybinds.md
Normal file
166
docs/manual/hacking/keybinds.md
Normal file
|
|
@ -0,0 +1,166 @@
|
|||
# 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 https://github.com/NotAShelf/neovim-flake/tree/main/lib[extended standard library]. 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}
|
||||
|
||||
:maps: https://notashelf.github.io/neovim-flake/options.html#opt-vim.maps.command._name_.action
|
||||
|
||||
To set a mapping, you should define it in `vim.maps.<<mode>>`.
|
||||
The available modes are:
|
||||
|
||||
- normal
|
||||
- insert
|
||||
- select
|
||||
- visual
|
||||
- terminal
|
||||
- normalVisualOp
|
||||
- visualOnly
|
||||
- operator
|
||||
- insertCommand
|
||||
- lang
|
||||
- command
|
||||
|
||||
An example, simple keybinding, can look like this:
|
||||
|
||||
```nix
|
||||
{
|
||||
vim.maps.normal = {
|
||||
"<leader>wq" = {
|
||||
action = ":wq<CR>";
|
||||
silent = true;
|
||||
desc = "Save file and quit";
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
There are many settings available in the options. Please refer to the {maps}[documentation] to see a list of them.
|
||||
|
||||
`neovim-flake` provides a list of helper commands, so that you don't have to write the mapping attribute sets every
|
||||
time:
|
||||
|
||||
- `mkBinding = key: action: desc:` - makes a basic binding, with `silent` set to true.
|
||||
- `mkExprBinding = key: action: desc:` - makes an expression binding, with `lua`, `silent`, and `expr` set to true.
|
||||
- `mkLuaBinding = key: action: desc:` - makes an expression binding, with `lua`, and `silent` set to true.
|
||||
|
||||
Note that the Lua in these bindings is actual Lua, not pasted into a `:lua` command.
|
||||
Therefore, you either pass in a function like `require('someplugin').some_function`, without actually calling it,
|
||||
or you define your own function, like `function() require('someplugin').some_function() end`.
|
||||
|
||||
Additionally, to not have to repeat the descriptions, there's another utility function with its own set of functions:
|
||||
|
||||
Utility function that takes two attrsets:
|
||||
|
||||
- `{ someKey = "some_value" }`
|
||||
- `{ someKey = { description = "Some Description"; }; }`
|
||||
|
||||
and merges them into `{ someKey = { value = "some_value"; description = "Some Description"; }; }`
|
||||
|
||||
```
|
||||
addDescriptionsToMappings = actualMappings: mappingDefinitions:
|
||||
```
|
||||
|
||||
This function can be used in combination with the same `mkBinding` functions as above, except they only take two
|
||||
arguments - `binding` and `action`, and have different names:
|
||||
|
||||
- `mkSetBinding = binding: action:` - makes a basic binding, with `silent` set to true.
|
||||
- `mkSetExprBinding = binding: action:` - makes an expression binding, with `lua`, `silent`, and `expr` set to true.
|
||||
- `mkSetLuaBinding = binding: action:` - makes an expression binding, with `lua`, and `silent` set to true.
|
||||
|
||||
You can read the source code of some modules to see them in action, but their usage should look something like this:
|
||||
|
||||
```nix
|
||||
|
||||
# plugindefinition.nix
|
||||
{lib, ...}: with lib; {
|
||||
options.vim.plugin = {
|
||||
enable = mkEnableOption "Enable plugin";
|
||||
|
||||
# Mappings should always be inside an attrset called mappings
|
||||
mappings = {
|
||||
# mkMappingOption is a helper function from lib,
|
||||
# that takes a description (which will also appear in which-key),
|
||||
# and a default mapping (which can be null)
|
||||
toggleCurrentLine = mkMappingOption "Toggle current line comment" "gcc";
|
||||
toggleCurrentBlock = mkMappingOption "Toggle current block comment" "gbc";
|
||||
|
||||
toggleOpLeaderLine = mkMappingOption "Toggle line comment" "gc";
|
||||
toggleOpLeaderBlock = mkMappingOption "Toggle block comment" "gb";
|
||||
|
||||
toggleSelectedLine = mkMappingOption "Toggle selected comment" "gc";
|
||||
toggleSelectedBlock = mkMappingOption "Toggle selected block" "gb";
|
||||
};
|
||||
|
||||
};
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
```nix
|
||||
|
||||
# config.nix
|
||||
{
|
||||
pkgs,
|
||||
config,
|
||||
lib,
|
||||
...
|
||||
}:
|
||||
with lib;
|
||||
with builtins; let
|
||||
cfg = config.vim.plugin;
|
||||
self = import ./plugindefinition.nix {inherit lib;};
|
||||
mappingDefinitions = self.options.vim.plugin;
|
||||
|
||||
# addDescriptionsToMappings is a helper function from lib,
|
||||
# that merges mapping values and their descriptions
|
||||
# into one nice attribute set
|
||||
mappings = addDescriptionsToMappings cfg.mappings mappingDefinitions;
|
||||
in {
|
||||
config = mkIf (cfg.enable) {
|
||||
# ...
|
||||
vim.maps.normal = mkMerge [
|
||||
# mkSetBinding is another helper function from lib,
|
||||
# that actually adds the mapping with a description.
|
||||
(mkSetBinding mappings.findFiles "<cmd> Telescope find_files<CR>")
|
||||
(mkSetBinding mappings.liveGrep "<cmd> Telescope live_grep<CR>")
|
||||
(mkSetBinding mappings.buffers "<cmd> Telescope buffers<CR>")
|
||||
(mkSetBinding mappings.helpTags "<cmd> Telescope help_tags<CR>")
|
||||
(mkSetBinding mappings.open "<cmd> Telescope<CR>")
|
||||
|
||||
(mkSetBinding mappings.gitCommits "<cmd> Telescope git_commits<CR>")
|
||||
(mkSetBinding mappings.gitBufferCommits "<cmd> Telescope git_bcommits<CR>")
|
||||
(mkSetBinding mappings.gitBranches "<cmd> Telescope git_branches<CR>")
|
||||
(mkSetBinding mappings.gitStatus "<cmd> Telescope git_status<CR>")
|
||||
(mkSetBinding mappings.gitStash "<cmd> Telescope git_stash<CR>")
|
||||
|
||||
(mkIf config.vim.lsp.enable (mkMerge [
|
||||
(mkSetBinding mappings.lspDocumentSymbols "<cmd> Telescope lsp_document_symbols<CR>")
|
||||
(mkSetBinding mappings.lspWorkspaceSymbols "<cmd> Telescope lsp_workspace_symbols<CR>")
|
||||
|
||||
(mkSetBinding mappings.lspReferences "<cmd> Telescope lsp_references<CR>")
|
||||
(mkSetBinding mappings.lspImplementations "<cmd> Telescope lsp_implementations<CR>")
|
||||
(mkSetBinding mappings.lspDefinitions "<cmd> Telescope lsp_definitions<CR>")
|
||||
(mkSetBinding mappings.lspTypeDefinitions "<cmd> Telescope lsp_type_definitions<CR>")
|
||||
(mkSetBinding mappings.diagnostics "<cmd> Telescope diagnostics<CR>")
|
||||
]))
|
||||
|
||||
(
|
||||
mkIf config.vim.treesitter.enable
|
||||
(mkSetBinding mappings.treesitter "<cmd> Telescope treesitter<CR>")
|
||||
)
|
||||
];
|
||||
# ...
|
||||
};
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
:::{.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.
|
||||
|
||||
:::
|
||||
11
docs/manual/hacking/testing.md
Normal file
11
docs/manual/hacking/testing.md
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
# Testing Changes {#sec-testing-changes}
|
||||
|
||||
Once you have made your changes, you will need to test them throughly. 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 posssible.
|
||||
|
||||
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,13 +1,11 @@
|
|||
[[ch-hm-module]]
|
||||
== Home Manager
|
||||
# Home Manager {#ch-hm-module}
|
||||
|
||||
The Home Manager module allows us to customize the different `vim` options from inside the home-manager configuration
|
||||
and it is the preferred way of configuring neovim-flake, both on NixOS and non-NixOS systems.
|
||||
|
||||
To use it, we first add the input flake.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
```nix
|
||||
{
|
||||
neovim-flake = {
|
||||
url = github:notashelf/neovim-flake;
|
||||
|
|
@ -17,22 +15,20 @@ To use it, we first add the input flake.
|
|||
# i.e inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- obsidian nvim needs to be in your inputs
|
||||
};
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
Followed by importing the home-manager module somewhere in your configuration.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
```nix
|
||||
{
|
||||
# assuming neovim-flake is in your inputs and inputs is in the argset
|
||||
imports = [ inputs.neovim-flake.homeManagerModules.default ];
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
An example installation for standalone home-manager would look like this:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
```nix
|
||||
{
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
|
|
@ -52,14 +48,12 @@ An example installation for standalone home-manager would look like this:
|
|||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
Once the module is imported, we will be able to define the following options (and much more) from inside the
|
||||
home-manager configuration.
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
{
|
||||
```nix{
|
||||
programs.neovim-flake = {
|
||||
|
||||
enable = true;
|
||||
|
|
@ -74,12 +68,8 @@ home-manager configuration.
|
|||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
You may find all avaliable options in the https://notashelf.github.io/neovim-flake/options[appendix]
|
||||
====
|
||||
|
||||
|
||||
```
|
||||
|
||||
:::{.note}
|
||||
You may find all avaliable options in the [appendix](https://notashelf.github.io/neovim-flake/options)
|
||||
:::
|
||||
|
|
@ -1,40 +0,0 @@
|
|||
[[ch-languages]]
|
||||
== Language Support
|
||||
|
||||
Language specific support means there is a combination of language specific plugins, `treesitter` support, `nvim-lspconfig` language servers, and `null-ls` integration. This gets you capabilities ranging from autocompletion to formatting to diagnostics. The following languages have sections under the `vim.languages` attribute. See the configuration docs for details.
|
||||
|
||||
* Rust: <<opt-vim.languages.rust.enable>>
|
||||
* Nix: <<opt-vim.languages.nix.enable>>
|
||||
* SQL: <<opt-vim.languages.sql.enable>>
|
||||
* C/C++: <<opt-vim.languages.clang.enable>>
|
||||
* Typescript/Javascript: <<opt-vim.languages.ts.enable>>
|
||||
* Python: <<opt-vim.languages.python.enable>>:
|
||||
* Zig: <<opt-vim.languages.zig.enable>>
|
||||
* Markdown: <<opt-vim.languages.markdown.enable>>
|
||||
* HTML: <<opt-vim.languages.html.enable>>
|
||||
* SQL: <<opt-vim.languages.sql.enable>>
|
||||
* Dart: <<opt-vim.languages.dart.enable>>
|
||||
* Go: <<opt-vim.languages.go.enable>>
|
||||
* Lua: <<opt-vim.languages.lua.enable>>
|
||||
* PHP: <<opt-vim.languages.php.enable>>
|
||||
|
||||
Adding support for more languages, and improving support for existing ones are great places
|
||||
where you can contribute with a PR.
|
||||
|
||||
=== LSP Custom Packages/Command
|
||||
|
||||
In any of the `opt.languages.<language>.lsp.package` options you can provide your own LSP package, or provide
|
||||
the command to launch the language server, as a list of strings.
|
||||
|
||||
You can use this to skip automatic installation of a language server, and instead
|
||||
use the one found in your `$PATH` during runtime, for example:
|
||||
|
||||
[source,nix]
|
||||
----
|
||||
vim.languages.java = {
|
||||
lsp = {
|
||||
enable = true;
|
||||
package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
|
||||
};
|
||||
}
|
||||
----
|
||||
24
docs/manual/languages.md
Normal file
24
docs/manual/languages.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
# Language Support {#ch-languages}
|
||||
|
||||
Language specific support means there is a combination of language specific plugins, `treesitter` support, `nvim-lspconfig` language servers, and `null-ls` integration. This gets you capabilities ranging from autocompletion to formatting to diagnostics. The following languages have sections under the `vim.languages` attribute. See the configuration docs for details.
|
||||
|
||||
- Rust: [vim.languages.rust.enable](#opt-vim.languages.rust.enable)
|
||||
- Nix: [vim.languages.nix.enable](#opt-vim.languages.nix.enable)
|
||||
- SQL: [vim.languages.sql.enable](#opt-vim.languages.sql.enable)
|
||||
- C/C++: [vim.languages.clang.enable](#opt-vim.languages.clang.enable)
|
||||
- Typescript/Javascript: [vim.languages.ts.enable](#opt-vim.languages.ts.enable)
|
||||
- Python: [vim.languages.python.enable](#opt-vim.languages.python.enable):
|
||||
- Zig: [vim.languages.zig.enable](#opt-vim.languages.zig.enable)
|
||||
- Markdown: [vim.languages.markdown.enable](#opt-vim.languages.markdown.enable)
|
||||
- HTML: [vim.languages.html.enable](#opt-vim.languages.html.enable)
|
||||
- Dart: [vim.languages.dart.enable](#opt-vim.languages.dart.enable)
|
||||
- Go: [vim.languages.go.enable](#opt-vim.languages.go.enable)
|
||||
- Lua: [vim.languages.lua.enable](#opt-vim.languages.lua.enable)
|
||||
- PHP: [vim.languages.php.enable](#opt-vim.languages.php.enable)
|
||||
|
||||
Adding support for more languages, and improving support for existing ones are great places
|
||||
where you can contribute with a PR.
|
||||
|
||||
```{=include=} sections
|
||||
languages/lsp.md
|
||||
```
|
||||
16
docs/manual/languages/lsp.md
Normal file
16
docs/manual/languages/lsp.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
# LSP Custom Packages/Command {#sec-languages-custom-lsp-packages}
|
||||
|
||||
In any of the `opt.languages.<language>.lsp.package` options you can provide your own LSP package, or provide
|
||||
the command to launch the language server, as a list of strings.
|
||||
|
||||
You can use this to skip automatic installation of a language server, and instead
|
||||
use the one found in your `$PATH` during runtime, for example:
|
||||
|
||||
```nix
|
||||
vim.languages.java = {
|
||||
lsp = {
|
||||
enable = true;
|
||||
package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
|
||||
};
|
||||
}
|
||||
```
|
||||
3
docs/manual/manpage-urls.json
Normal file
3
docs/manual/manpage-urls.json
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
{
|
||||
"nix.conf(5)": "https://nixos.org/manual/nix/stable/command-ref/conf-file.html"
|
||||
}
|
||||
22
docs/manual/manual.md
Normal file
22
docs/manual/manual.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
# neovim-flake-manual {#neovim-flake-manual}
|
||||
|
||||
## Version @VERSION@
|
||||
|
||||
```{=include=} preface
|
||||
preface.md
|
||||
try-it-out.md
|
||||
```
|
||||
|
||||
```{=include=} parts
|
||||
custom-configs.md
|
||||
custom-package.md
|
||||
custom-plugins.md
|
||||
default-configs.md
|
||||
home-manager.md
|
||||
languages.md
|
||||
hacking.md
|
||||
```
|
||||
|
||||
```{=include=} appendix html:into-file=//options.html
|
||||
options.md
|
||||
```
|
||||
7
docs/manual/options.md
Normal file
7
docs/manual/options.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
# Neovim Flake Configuration Options {#ch-options}
|
||||
|
||||
```{=include=} options
|
||||
id-prefix: opt-
|
||||
list-id: neovim-flake-options
|
||||
source: @OPTIONS_JSON@
|
||||
```
|
||||
6
docs/manual/preface.md
Normal file
6
docs/manual/preface.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# Preface {#sec-preface}
|
||||
|
||||
If you noticed a bug caused by neovim-flake then please consider reporting it over
|
||||
[the neovim-flake issue tracker](https://github.com/notashelf/neovim-flake/issues).
|
||||
Bugfixes, feature additions and upstreamed changes are welcome over
|
||||
[the neovim-flake pull requests tab](https://github.com/notashelf/neovim-flake/pulls).
|
||||
|
|
@ -1,53 +1,47 @@
|
|||
[[ch-try-it-out]]
|
||||
== Try it out
|
||||
# Try it out {#ch-try-it-out}
|
||||
|
||||
Thanks to the portability of Nix, you can try out neovim-flake without actually installing it to your machine.
|
||||
Below are the commands you may run to try out different configurations provided by this flake. As of v0.5, three
|
||||
configurations are provided:
|
||||
|
||||
* Nix
|
||||
* Tidal
|
||||
* Maximal
|
||||
- Nix
|
||||
- Tidal
|
||||
- Maximal
|
||||
|
||||
You may try out any of the provided configurations using the `nix run` command on a system where Nix is installed.
|
||||
|
||||
[source,console]
|
||||
----
|
||||
```console
|
||||
$ cachix use neovim-flake # Optional: it'll save you CPU resources and time
|
||||
$ nix run github:notashelf/neovim-flake#nix # will run the default minimal configuration
|
||||
----
|
||||
```
|
||||
|
||||
Do keep in mind that this is **susceptible to garbage collection** meaning it will be removed from your Nix store
|
||||
once you garbage collect. If you wish to install neovim-flake, please take a look at
|
||||
<<ch-custom-configuration,custom-configuration>> or <<ch-hm-module,home-manager>> sections for installation
|
||||
[custom-configuration](#ch-custom-configuration) or [home-manager](#ch-hm-module) sections for installation
|
||||
instructions.
|
||||
|
||||
[[sec-using-prebuild-configs]]
|
||||
=== Using Prebuilt Configs
|
||||
## Using Prebuilt Configs {#sec-using-prebuild-configs}
|
||||
|
||||
[source,console]
|
||||
----
|
||||
```console
|
||||
$ nix run github:notashelf/neovim-flake#nix
|
||||
$ nix run github:notashelf/neovim-flake#tidal
|
||||
$ nix run github:notashelf/neovim-flake#maximal
|
||||
----
|
||||
```
|
||||
|
||||
### Available Configs {#sec-available-configs}
|
||||
|
||||
[[sec-available-configs]]
|
||||
=== Available Configs
|
||||
|
||||
==== Nix
|
||||
#### 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.
|
||||
|
||||
==== Tidal
|
||||
#### Tidal {#sec-configs-tidal}
|
||||
|
||||
Tidal is an alternative config that adds vim-tidal on top of the plugins from the Nix configuration.
|
||||
|
||||
==== Maximal
|
||||
#### 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.
|
||||
|
||||
You are *strongly* recommended to use the binary cache if you would like to try the Maximal configuration.
|
||||
You are _strongly_ recommended to use the binary cache if you would like to try the Maximal configuration.
|
||||
14
flake.lock
14
flake.lock
|
|
@ -903,17 +903,17 @@
|
|||
"nmd": {
|
||||
"flake": false,
|
||||
"locked": {
|
||||
"lastModified": 1696846470,
|
||||
"narHash": "sha256-S/6s3nRcg+xZfsO7aLe01W+EMAKFVyieHa4eFvOKOLk=",
|
||||
"owner": "horriblename",
|
||||
"lastModified": 1701431551,
|
||||
"narHash": "sha256-5HPHG1u3koaWHG/TXHl5/YxYPYOuKc58104btrD8ypE=",
|
||||
"owner": "~rycee",
|
||||
"repo": "nmd",
|
||||
"rev": "bcf805ce85b9e938f7e027b3311137ffbd995794",
|
||||
"type": "github"
|
||||
"rev": "f18defadcc25e69e95b04493ee02682005472255",
|
||||
"type": "sourcehut"
|
||||
},
|
||||
"original": {
|
||||
"owner": "horriblename",
|
||||
"owner": "~rycee",
|
||||
"repo": "nmd",
|
||||
"type": "github"
|
||||
"type": "sourcehut"
|
||||
}
|
||||
},
|
||||
"noice-nvim": {
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@
|
|||
|
||||
# For generating documentation website
|
||||
nmd = {
|
||||
url = "github:horriblename/nmd";
|
||||
url = "sourcehut:~rycee/nmd";
|
||||
flake = false;
|
||||
};
|
||||
|
||||
|
|
|
|||
4
release.json
Normal file
4
release.json
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"release": "v0.6",
|
||||
"isReleaseBranch": false
|
||||
}
|
||||
Loading…
Reference in a new issue