Merge pull request #252 from NotAShelf/docs-refactor

docs: restructure; describe DAGs for end-user usage

docs/default.nix

@@ -2,11 +2,17 @@
   inputs,
   pkgs,
   lib ? import ../lib/stdlib-extended.nix pkgs.lib inputs,
+  manpageUrls ? pkgs.path + "/doc/manpage-urls.json",
   ...
 }: let
   inherit (lib.modules) mkForce evalModules;
   inherit (lib.strings) hasPrefix removePrefix;
   inherit (lib.attrsets) isAttrs mapAttrs optionalAttrs recursiveUpdate isDerivation;
+  inherit (builtins) fromJSON readFile;
+
+  # release data
+  release-config = fromJSON (readFile ../release.json);
+  revision = release-config.release;
 
   # From home-manager:
   #
@@ -54,11 +60,14 @@
   buildOptionsDocs = args @ {
     modules,
     includeModuleSystemOptions ? true,
+    warningsAreErrors ? true,
     ...
   }: let
     inherit ((evalModules {inherit modules;})) options;
 
     # Declaration of the Github site URL.
+    # Takes a user, repo, and subpath, and returns a declaration site
+    # as a string.
     githubDeclaration = user: repo: subpath: let
       urlRef = "github.com";
       branch = "main";
@@ -68,10 +77,13 @@
     };
   in
     pkgs.buildPackages.nixosOptionsDoc ({
+        inherit warningsAreErrors;
+
         options =
           if includeModuleSystemOptions
           then options
           else builtins.removeAttrs options ["_module"];
+
         transformOptions = opt:
           recursiveUpdate opt {
             # Clean up declaration sites to not refer to the neovim-flakee
@@ -93,18 +105,16 @@
       // builtins.removeAttrs args ["modules" "includeModuleSystemOptions"]);
 
   nvimModuleDocs = buildOptionsDocs {
+    variablelistId = "neovim-flake-options";
+
     modules =
       import ../modules/modules.nix {
         inherit lib pkgs;
         check = false;
       }
       ++ [scrubbedPkgsModule];
-    variablelistId = "neovim-flake-options";
   };
 
-  release-config = builtins.fromJSON (builtins.readFile ../release.json);
-  revision = "release-${release-config.release}";
-
   # Generate the `man home-configuration.nix` package
   nvf-configuration-manual =
     pkgs.runCommand "neovim-flake-reference-manpage" {
@@ -125,8 +135,7 @@
 
   # Generate the HTML manual pages
   neovim-flake-manual = pkgs.callPackage ./manual.nix {
-    inherit (inputs) nmd;
+    inherit revision manpageUrls;
-    inherit revision;
     outputPath = "share/doc/neovim-flake";
     options = {
       neovim-flake = nvimModuleDocs.optionsJSON;

docs/highlight-style.css

@@ -1,8 +0,0 @@
-pre {
-	padding: 0;
-}
-
-pre code.hljs {
-	border: none;
-	margin: 0;
-}

docs/manual.nix

@@ -1,54 +1,57 @@
 {
-  stdenv,
   lib,
-  documentation-highlighter,
+  stdenvNoCC,
-  nmd,
+  # build inputs
-  revision,
-  outputPath ? "share/doc/neovim-flake",
-  options,
   nixos-render-docs,
+  documentation-highlighter,
+  # nrd configuration
+  manpageUrls,
+  revision,
+  options,
+  outputPath ? "share/doc/neovim-flake",
 }:
-stdenv.mkDerivation {
+stdenvNoCC.mkDerivation {
   name = "neovim-flake-manual";
-  src = ./manual;
+  src = builtins.path {
+    path = lib.sourceFilesBySuffices ./manual [".md"];
+    name = "neovim-flake-manual";
+  };
 
   nativeBuildInputs = [nixos-render-docs];
 
   buildPhase = ''
-    mkdir -p out/media
+    mkdir -p out/{highlightjs,media}
 
-    mkdir -p out/highlightjs
+    cp -vt 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 \
+      --subst-var-by \
-        '@OPTIONS_JSON@' \
+        OPTIONS_JSON \
         ${options.neovim-flake}/share/doc/nixos/options.json
 
     substituteInPlace ./manual.md \
-      --replace \
+      --subst-var-by \
-        '@VERSION@' \
+        NVF_VERSION \
         ${revision}
 
-    cp -v ${nmd}/static/style.css out/style.css
+    # copy stylesheet
-    cp -vt out/highlightjs ${nmd}/static/highlightjs/tomorrow-night.min.css
+    cp ${./static/style.css} out/style.css
-    cp -v ${./highlight-style.css} out/highlightjs/highlight-style.css
 
+    # copy release notes
     cp -vr ${./release-notes} release-notes
 
+    # generate manual from
     nixos-render-docs manual html \
-      --manpage-urls ./manpage-urls.json \
+      --manpage-urls ${manpageUrls} \
       --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 \
+      --toc-depth 2 \
       --section-toc-depth 1 \
       manual.md \
       out/index.xhtml

docs/manual/configuring.md

@@ -0,0 +1,8 @@
+# Configuring neovim-flake {#ch-configuring}
+
+```{=include=} chapters
+configuring/custom-package.md
+configuring/custom-plugins.md
+configuring/languages.md
+configuring/dags.md
+```

docs/manual/configuring/custom-package.md

@@ -0,0 +1,20 @@
+# 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.
+
+```nix
+{inputs, pkgs, ...}: {
+  # using the neovim-nightly overlay
+  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.
+
+```nix
+{ pkgs, ...}: {
+  # using the neovim-nightly overlay
+  vim.package = pkgs.neovim-unwrapped;
+}
+```

docs/manual/configuring/custom-plugins.md

@@ -0,0 +1,25 @@
+# Custom Plugins {#ch-custom-plugins}
+
+Neovim-flake, by default, exposes a wide variety of plugins as module options
+for your convience and bundles necessary dependencies into neovim-flake's
+runtime. In case a plugin is not available in neovim-flake, you may consider
+making a pull request to neovim-flake to include it as a module or you may add
+it to your configuration locally.
+
+## Adding Plugins {#ch-adding-plugins}
+
+There are multiple ways of adding custom plugins to your neovim-flake
+configuration.
+
+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 `vim.startPlugins` array.
+
+Adding a plugin to `startPlugins` will not allow you to configure the plugin
+that you have addeed, but neovim-flake provides multiple way of configuring any
+custom plugins that you might have added to your configuration.
+
+```{=include=} sections
+custom-plugins/configuring.md
+custom-plugins/new-method.md
+custom-plugins/old-method.md
+```

docs/manual/configuring/custom-plugins/configuring.md

@@ -1,4 +1,4 @@
-# Configuring {#configuring-plugins}
+# 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 vimscript or lua config, using `config.vim.configRC` or `config.vim.luaConfigRC`

docs/manual/configuring/custom-plugins/new-method.md

@@ -1,6 +1,6 @@
 # New Method {#sec-new-method}
 
-As of version 0.5, we have a more extensive API for configuring plugins, under `vim.extraPlugins`.
+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:
 

docs/manual/configuring/custom-plugins/old-method.md

@@ -0,0 +1,33 @@
+# Old Method {#sec-old-method}
+
+Prior to version 0.5, the method of adding new plugins was adding the plugin package to `vim.startPlugins` and add
+its configuration as a DAG under `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 the plugins is determined by DAGs.
+
+## Adding plugins {#sec-adding-plugins}
+
+To add a plugin to neovim-flake's runtime, you may add it
+
+```nix
+{pkgs, ...}: {
+  # add a package from nixpkgs to startPlugins
+  vim.startPlugins = [
+    pkgs.vimPlugins.aerial-nvim  ];
+}
+```
+
+And to configure the added plugin, you can use the `luaConfigRC` option to provide configuration
+as a DAG using the neovim-flake extended library.
+
+```nix
+{inputs, ...}: let
+  # assuming you have an input called neovim-flake pointing at the neovim-flake repo
+  inherit (inputs.neovim-flake.lib.nvim.dag) entryAnywhere;
+in {
+  vim.luaConfigRC.aerial-nvim= entryAnywhere ''
+    require('aerial').setup {
+      -- your configuration here
+    }
+  '';
+}
+```

docs/manual/configuring/dags.md

@@ -0,0 +1,181 @@
+# Using DAGs {#ch-using-dags}
+
+We conform to the NixOS options types for the most part, however, a noteworthy addition
+for certain options is the [**DAG (Directed acyclic graph)**](https://en.wikipedia.org/wiki/Directed_acyclic_graph)
+type which is borrowed from home-manager's extended library. This type is most used for
+topologically sorting strings. The DAG type allows the attribute set entries to express dependency
+relations among themselves. This can, for example, be used to control the order of configuration
+sections in your `configRC` or `luaConfigRC`.
+
+The below section, mostly taken from the [home-manager manual](https://raw.githubusercontent.com/nix-community/home-manager/master/docs/manual/writing-modules/types.md) explains the overal usage logic of the DAG typee
+
+## entryAnywhere {#sec-types-dag-entryAnywhere}
+
+> `lib.dag.entryAnywhere (value: T) : DagEntry<T>`
+
+Indicates that `value` can be placed anywhere within the DAG.
+This is also the default for plain attribute set entries, that
+is
+
+```nix
+foo.bar = {
+  a = lib.dag.entryAnywhere 0;
+}
+```
+
+and
+
+```nix
+foo.bar = {
+  a = 0;
+}
+```
+
+are equivalent.
+
+## entryAfter {#ch-types-dag-entryAfter}
+
+> `lib.dag.entryAfter (afters: list string) (value: T) : DagEntry<T>`
+
+Indicates that `value` must be placed _after_ each of the
+attribute names in the given list. For example
+
+```nix
+foo.bar = {
+  a = 0;
+  b = lib.dag.entryAfter [ "a" ] 1;
+}
+```
+
+would place `b` after `a` in the graph.
+
+## entryBefore {#ch-types-dag-entryBefore}
+
+> `lib.dag.entryBefore (befores: list string) (value: T) : DagEntry<T>`
+
+Indicates that `value` must be placed _before_ each of the
+attribute names in the given list. For example
+
+```nix
+foo.bar = {
+  b = lib.dag.entryBefore [ "a" ] 1;
+  a = 0;
+}
+```
+
+would place `b` before `a` in the graph.
+
+## entryBetween {#sec-types-dag-entryBetween}
+
+> `lib.dag.entryBetween (befores: list string) (afters: list string) (value: T) : DagEntry<T>`
+
+Indicates that `value` must be placed _before_ the attribute
+names in the first list and _after_ the attribute names in the
+second list. For example
+
+```nix
+foo.bar = {
+  a = 0;
+  c = lib.dag.entryBetween [ "b" ] [ "a" ] 2;
+  b = 1;
+}
+```
+
+would place `c` before `b` and after `a` in the graph.
+
+There are also a set of functions that generate a DAG from a list.
+These are convenient when you just want to have a linear list of DAG
+entries, without having to manually enter the relationship between
+each entry. Each of these functions take a `tag` as argument and the
+DAG entries will be named `${tag}-${index}`.
+
+## entriesAnywhere {#sec-types-dag-entriesAnywhere}
+
+> `lib.dag.entriesAnywhere (tag: string) (values: [T]) : Dag<T>`
+
+Creates a DAG with the given values with each entry labeled
+using the given tag. For example
+
+```nix
+foo.bar = lib.dag.entriesAnywhere "a" [ 0 1 ];
+```
+
+is equivalent to
+
+```nix
+foo.bar = {
+  a-0 = 0;
+  a-1 = lib.dag.entryAfter [ "a-0" ] 1;
+}
+```
+
+## entriesAfter {#sec-types-dag-entriesAfter}
+
+> `lib.dag.entriesAfter (tag: string) (afters: list string) (values: [T]) : Dag<T>`
+
+Creates a DAG with the given values with each entry labeled
+using the given tag. The list of values are placed are placed
+_after_ each of the attribute names in `afters`. For example
+
+```nix
+foo.bar =
+  { b = 0; } // lib.dag.entriesAfter "a" [ "b" ] [ 1 2 ];
+```
+
+is equivalent to
+
+```nix
+foo.bar = {
+  b = 0;
+  a-0 = lib.dag.entryAfter [ "b" ] 1;
+  a-1 = lib.dag.entryAfter [ "a-0" ] 2;
+}
+```
+
+## entriesBefore {#sec-types-dag-entriesBefore}
+
+> `lib.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag<T>`
+
+Creates a DAG with the given values with each entry labeled
+using the given tag. The list of values are placed _before_ each
+of the attribute names in `befores`. For example
+
+```nix
+  foo.bar =
+    { b = 0; } // lib.dag.entriesBefore "a" [ "b" ] [ 1 2 ];
+```
+
+is equivalent to
+
+```nix
+foo.bar = {
+  b = 0;
+  a-0 = 1;
+  a-1 = lib.dag.entryBetween [ "b" ] [ "a-0" ] 2;
+}
+```
+
+## entriesBetween {#sec-types-dag-entriesBetween}
+
+> `lib.dag.entriesBetween (tag: string) (befores: list string) (afters: list string) (values: [T]) : Dag<T>`
+
+Creates a DAG with the given values with each entry labeled
+using the given tag. The list of values are placed _before_ each
+of the attribute names in `befores` and _after_ each of the
+attribute names in `afters`. For example
+
+```nix
+foo.bar =
+  { b = 0; c = 3; } // lib.dag.entriesBetween "a" [ "b" ] [ "c" ] [ 1 2 ];
+```
+
+is equivalent to
+
+```nix
+foo.bar = {
+  b = 0;
+  c = 3;
+  a-0 = lib.dag.entryAfter [ "c" ] 1;
+  a-1 = lib.dag.entryBetween [ "b" ] [ "a-0" ] 2;
+}
+```

docs/manual/configuring/languages.md

@@ -1,6 +1,8 @@
 # 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.
+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.
 
 - Rust: [vim.languages.rust.enable](#opt-vim.languages.rust.enable)
 - Nix: [vim.languages.nix.enable](#opt-vim.languages.nix.enable)

docs/manual/custom-package.md

@@ -1,12 +0,0 @@
-# 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.
-
-```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.

docs/manual/custom-plugins.md

@@ -1,10 +0,0 @@
-# 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
-```

docs/manual/custom-plugins/old-method.md

@@ -1,18 +0,0 @@
-# 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=";
-    })
-  ];
-}
-```

docs/manual/default-configs.md

@@ -3,7 +3,7 @@
 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
+```{=include=} chapters
 default-configs/maximal.md
 default-configs/nix.md
 default-configs/tidal.md

docs/manual/hacking/guidelines.md

@@ -64,20 +64,28 @@ See [example commit message](#sec-guidelines-ex-commit-message) for a commit mes
 
 ## Example Commit {#sec-guidelines-ex-commit-message}
 
-The commit [69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef) contains the commit message
+The commit [69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef)
+in home-manager 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.
+```
 
+Similarly, if you are contributing to neovim-flake, you would include the scope of the commit followed by
+the description
+
+```
+languages/ruby: init module
+
+Adds a language module for Ruby, and adds appropriate formatters and TS grammers
 ```
 
 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.
+relevant context, e.g. the reasoning behind it, for your commit.
 
 Finally, when adding a new module, say `modules/foo.nix`, we use the fixed commit format `foo: add module`.
 You can, of course, still include a long description if you wish.

docs/manual/installation.md

@@ -0,0 +1,11 @@
+# Installing neovim-flake {#ch-installation}
+
+There are multiple ways of installing neovim-flake 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)
+
+```{=include=} chapters
+installation/custom-configuration.md
+installation/modules.md
+```

docs/manual/installation/custom-configuration.md

@@ -0,0 +1,19 @@
+# Standalone Installation {#ch-standalone-installation}
+
+It is possible to install neovim-flake without depending on NixOS or home-manager as the parent
+module system, using the `neovimConfiguration` function exposed by neovim-flake extended library.
+It takes in the configuration as a module, and returns an attribute set as a result.
+
+```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";
+}
+```
+
+```{=include=} chapters
+standalone/nixos.md
+standalone/home-manager.md
+```

docs/manual/installation/modules.md

@@ -0,0 +1,6 @@
+# Module Installation {#ch-module-installation}
+
+```{=include=} chapters
+modules/nixos.md
+modules/home-manager.md
+```

docs/manual/installation/modules/home-manager.md

@@ -1,4 +1,4 @@
-# Home Manager {#ch-hm-module}
+# Home Manager Module {#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.

docs/manual/installation/modules/nixos.md

@@ -0,0 +1,3 @@
+# NixOS Module {#ch-nixos-module}
+
+This artice is a stub. It will be written as the NixOS module is finalized.

docs/manual/installation/standalone/home-manager.md

@@ -0,0 +1,37 @@
+# Standalone Installation (home-manager) {#ch-standalone-home-manager}
+
+The following is an example of a barebones vim configuration with the default theme enabled.
+
+```nix
+{
+  inputs.neovim-flake = {
+    url = "github:notashelf/neovim-flake";
+    inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs = {nixpkgs, neovim-flake, ...}: let
+    system = "x86_64-linux";
+    pkgs = nixpkgs.legacyPackages.${system};
+    configModule = {
+      # Add any custom options (and feel free to upstream them!)
+      # options = ...
+
+      config.vim = {
+        theme.enable = true;
+      };
+    };
+
+    customNeovim = neovim-flake.lib.neovimConfiguration {
+      modules = [configModule];
+      inherit pkgs;
+    };
+  in {
+    # this is an example nixosConfiguration using the built neovim package
+    homeConfigurations = {
+      yourHostName = home-manager.lib.nixosSystem {
+        # TODO
+      };
+    };
+  };
+}
+```

docs/manual/installation/standalone/nixos.md

@@ -1,16 +1,4 @@
-# Custom Configuration {#ch-custom-configuration}
+# Standalone Installation (NixOS) {#ch-standalone-nixos}
-
-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.
-
-```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.
 
@@ -60,4 +48,4 @@ 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.

docs/manual/manpage-urls.json

@@ -1,3 +0,0 @@
-{
-	"nix.conf(5)": "https://nixos.org/manual/nix/stable/command-ref/conf-file.html"
-}

docs/manual/manual.md

@@ -1,6 +1,6 @@
 # neovim-flake-manual {#neovim-flake-manual}
 
-## Version @VERSION@
+## Version @NVF_VERSION@
 
 ```{=include=} preface
 preface.md
@@ -8,12 +8,12 @@ try-it-out.md
 ```
 
 ```{=include=} parts
-custom-configs.md
-custom-package.md
-custom-plugins.md
 default-configs.md
-home-manager.md
+installation.md
-languages.md
+configuring.md
+```
+
+```{=include=} chapters
 hacking.md
 ```
 

docs/manual/options.md

@@ -1,5 +1,9 @@
 # Neovim Flake Configuration Options {#ch-options}
 
+Below are the options provided by neovim-flake provided in no particular order.
+They may include useful comments and warnings, or examples on how a module option
+is meant to be used.
+
 ```{=include=} options
 id-prefix: opt-
 list-id: neovim-flake-options

docs/manual/preface.md

@@ -1,6 +1,7 @@
-# Preface {#sec-preface}
+# Preface {#ch-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).
+Bugfixes, feature additions and upstreamed changes from your local configurations
+are always welcome in the [the neovim-flake pull requests tab](https://github.com/notashelf/neovim-flake/pulls).

docs/manual/try-it-out.md

@@ -16,9 +16,7 @@ $ nix run github:notashelf/neovim-flake#nix # will run the default minimal confi
 ```
 
 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
+once you garbage collect.
-[custom-configuration](#ch-custom-configuration) or [home-manager](#ch-hm-module) sections for installation
-instructions.
 
 ## Using Prebuilt Configs {#sec-using-prebuild-configs}
 
@@ -33,7 +31,7 @@ $ nix run github:notashelf/neovim-flake#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.
+By running `nix run .#`, which is the default package, you will build Neovim with this config.
 
 #### Tidal {#sec-configs-tidal}
 

docs/static/style.css

@@ -0,0 +1,830 @@
+:root {
+	--nmd-color0: #0a3e68;
+	--nmd-color1: #268598;
+	--nmd-color2: #b8d09e;
+	--nmd-color3: #f6cf5e;
+	--nmd-color4: #ec733b;
+	--nmd-color-info: #167cb9;
+	--nmd-color-warn: #ff6700;
+}
+html {
+	-webkit-text-size-adjust: 100%;
+}
+html:focus-within {
+	scroll-behavior: smooth;
+}
+body {
+	-webkit-text-size-adjust: 100%;
+	-moz-text-size-adjust: 100%;
+	text-size-adjust: 100%;
+	-moz-osx-font-smoothing: grayscale;
+	-webkit-font-smoothing: antialiased;
+	min-height: 100vh;
+	position: relative;
+	text-rendering: optimizeSpeed;
+	width: 100%;
+}
+*,
+:after,
+:before {
+	box-sizing: border-box;
+}
+a:not([class]) {
+	-webkit-text-decoration-skip: ink;
+	text-decoration-skip-ink: auto;
+}
+a,
+abbr,
+acronym,
+address,
+applet,
+article,
+aside,
+audio,
+b,
+big,
+blockquote,
+body,
+canvas,
+caption,
+center,
+cite,
+code,
+dd,
+del,
+details,
+dfn,
+div,
+dl,
+dt,
+em,
+embed,
+fieldset,
+figcaption,
+figure,
+footer,
+form,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+header,
+hgroup,
+html,
+i,
+iframe,
+img,
+ins,
+kbd,
+label,
+legend,
+li,
+mark,
+menu,
+nav,
+object,
+ol,
+output,
+p,
+pre,
+q,
+ruby,
+s,
+samp,
+section,
+small,
+span,
+strike,
+strong,
+sub,
+summary,
+sup,
+table,
+tbody,
+td,
+tfoot,
+th,
+thead,
+time,
+tr,
+tt,
+u,
+ul,
+var,
+video {
+	border: 0;
+	font-size: 100%;
+	font: inherit;
+	margin: 0;
+	padding: 0;
+	vertical-align: baseline;
+}
+:focus {
+	outline: 0;
+}
+article,
+aside,
+details,
+figcaption,
+figure,
+footer,
+header,
+hgroup,
+main,
+menu,
+nav,
+section {
+	display: block;
+}
+ol,
+ul {
+	list-style: none;
+}
+blockquote,
+q {
+	quotes: none;
+}
+blockquote:after,
+blockquote:before,
+q:after,
+q:before {
+	content: "";
+	content: none;
+}
+input,
+input:required {
+	box-shadow: none;
+}
+input:-webkit-autofill,
+input:-webkit-autofill:active,
+input:-webkit-autofill:focus,
+input:-webkit-autofill:hover {
+	-webkit-box-shadow: inset 0 0 0 30px #fff;
+}
+input[type="search"]::-webkit-search-cancel-button,
+input[type="search"]::-webkit-search-decoration,
+input[type="search"]::-webkit-search-results-button,
+input[type="search"]::-webkit-search-results-decoration {
+	-webkit-appearance: none;
+	-moz-appearance: none;
+}
+input[type="search"] {
+	-webkit-appearance: none;
+	-moz-appearance: none;
+}
+input:focus {
+	outline: 0;
+}
+audio,
+canvas,
+video {
+	display: inline-block;
+	max-width: 100%;
+}
+audio:not([controls]) {
+	display: none;
+	height: 0;
+}
+[hidden] {
+	display: none;
+}
+a:active,
+a:hover {
+	outline: 0;
+}
+img {
+	height: auto;
+	max-width: 100%;
+	vertical-align: middle;
+}
+img,
+picture {
+	display: inline-block;
+}
+button,
+input {
+	line-height: normal;
+}
+button,
+html input[type="button"],
+input[type="reset"],
+input[type="submit"] {
+	-webkit-appearance: button;
+	background: 0 0;
+	border: 0;
+	cursor: pointer;
+}
+button[disabled],
+html input[disabled] {
+	cursor: default;
+}
+[disabled] {
+	pointer-events: none;
+}
+input[type="checkbox"],
+input[type="radio"] {
+	padding: 0;
+}
+input[type="search"] {
+	-webkit-appearance: textfield;
+	box-sizing: content-box;
+}
+input[type="search"]::-webkit-search-cancel-button,
+input[type="search"]::-webkit-search-decoration {
+	-webkit-appearance: none;
+}
+button::-moz-focus-inner,
+input::-moz-focus-inner {
+	border: 0;
+	padding: 0;
+}
+button {
+	background: 0 0;
+	border: 0;
+}
+textarea {
+	overflow: auto;
+	resize: vertical;
+	vertical-align: top;
+}
+table {
+	border-collapse: collapse;
+	border-spacing: 0;
+	text-indent: 0;
+}
+hr {
+	background: #000;
+	border: 0;
+	box-sizing: content-box;
+	height: 1px;
+	line-height: 0;
+	margin: 0;
+	overflow: visible;
+	padding: 0;
+	page-break-after: always;
+	width: 100%;
+}
+pre {
+	font-family: monospace, monospace;
+	font-size: 100%;
+}
+a {
+	background-color: transparent;
+}
+abbr[title] {
+	border-bottom: none;
+	text-decoration: none;
+}
+code,
+kbd,
+pre,
+samp {
+	font-family: monospace, monospace;
+}
+small,
+sub,
+sup {
+	font-size: 75%;
+}
+sub,
+sup {
+	line-height: 0;
+	position: relative;
+	vertical-align: baseline;
+}
+sub {
+	bottom: -5px;
+}
+sup {
+	top: -5px;
+}
+button,
+input,
+optgroup,
+select,
+textarea {
+	font-family: inherit;
+	font-size: 100%;
+	line-height: 1;
+	margin: 0;
+	padding: 0;
+}
+button,
+input {
+	overflow: visible;
+}
+button,
+select {
+	text-transform: none;
+}
+[type="button"],
+[type="reset"],
+[type="submit"],
+button {
+	-webkit-appearance: button;
+}
+[type="button"]::-moz-focus-inner,
+[type="reset"]::-moz-focus-inner,
+[type="submit"]::-moz-focus-inner,
+button::-moz-focus-inner {
+	border-style: none;
+	outline: 0;
+	padding: 0;
+}
+legend {
+	border: 0;
+	color: inherit;
+	display: block;
+	max-width: 100%;
+	white-space: normal;
+	width: 100%;
+}
+fieldset {
+	min-width: 0;
+}
+body:not(:-moz-handler-blocked) fieldset {
+	display: block;
+}
+progress {
+	vertical-align: baseline;
+}
+[type="number"]::-webkit-inner-spin-button,
+[type="number"]::-webkit-outer-spin-button {
+	height: auto;
+}
+[type="search"] {
+	-webkit-appearance: textfield;
+	outline-offset: -2px;
+}
+[type="search"]::-webkit-search-decoration {
+	-webkit-appearance: none;
+}
+::-webkit-file-upload-button {
+	-webkit-appearance: button;
+	font: inherit;
+}
+summary {
+	display: list-item;
+}
+template {
+	display: none;
+}
+body {
+	background: white;
+	color: #111827;
+	max-width: min(100ch, 1024px);
+	margin: 0 auto;
+	padding: 10px;
+	font-family: "Lucida Sans", Arial, sans-serif;
+	font-size: 16px;
+	line-height: 1.4em;
+}
+@media (prefers-color-scheme: dark) {
+	body {
+		background: #111827;
+		color: #f9fafb;
+	}
+}
+h1,
+h2,
+h3 {
+	color: var(--nmd-color0);
+	font-family: "Lato", sans-serif;
+	font-weight: 300;
+	line-height: 1.125;
+}
+@media (prefers-color-scheme: dark) {
+	h1,
+	h2,
+	h3 {
+		color: var(--nmd-color4);
+	}
+}
+h1 {
+	font-size: 48px;
+	font-weight: 300;
+	margin: 4rem 0 1.5rem;
+}
+h2 {
+	font-size: 32px;
+	font-weight: 300;
+	margin: 2rem 0 1rem;
+}
+h3 {
+	font-size: 20px;
+	font-weight: 400;
+	margin: 0.5rem 0.25rem;
+}
+p {
+	margin: 0.9rem 0;
+}
+p:first-child {
+	margin-top: 0;
+}
+p:last-child {
+	margin-bottom: 0;
+}
+a {
+	color: var(--nmd-color0);
+	text-decoration: underline;
+	text-underline-offset: 3px;
+}
+a:visited {
+	color: var(--nmd-color1);
+}
+a:hover {
+	color: var(--nmd-color1);
+}
+@media (prefers-color-scheme: dark) {
+	a {
+		color: var(--nmd-color3);
+	}
+	a:visited {
+		color: var(--nmd-color2);
+	}
+	a:hover {
+		color: var(--nmd-color4);
+	}
+}
+code {
+	font-size: 90%;
+}
+span.command {
+	font-size: 90%;
+	font-family: monospace;
+}
+em {
+	font-style: italic;
+}
+strong {
+	font-weight: bold;
+}
+pre {
+	background: #f9fafb;
+	margin: 2rem 16px;
+	padding: 10px;
+	border: 1px solid #e5e7eb;
+	border-radius: 4px;
+	box-shadow: 4px 4px 8px #e5e7eb;
+	font-size: 90%;
+	margin-bottom: 1.5rem;
+	padding: 6px;
+	overflow: auto;
+}
+@media (prefers-color-scheme: dark) {
+	pre {
+		background: #1f2937;
+		border-color: black;
+		box-shadow: 4px 4px 8px black;
+	}
+}
+pre span img {
+	user-select: none;
+}
+pre:has(code) {
+	padding: 0;
+}
+td,
+th {
+	padding: 2px 5px;
+}
+td:first-child,
+th:first-child {
+	padding-left: 0;
+}
+td:last-child,
+th:last-child {
+	padding-right: 0;
+}
+dt {
+	margin: 1.2rem 0 0.8rem;
+}
+dd {
+	margin-left: 2rem;
+}
+ul {
+	margin: 0.9rem 0;
+	padding-left: 30px;
+	list-style: disc;
+}
+ul:first-child {
+	margin-top: 0;
+}
+ul:last-child {
+	margin-bottom: 0;
+}
+ol {
+	margin: 0.9rem 0;
+	padding-left: 30px;
+	list-style: decimal;
+}
+ol:first-child {
+	margin-top: 0;
+}
+ol:last-child {
+	margin-bottom: 0;
+}
+li {
+	margin: 0.9rem 0;
+	padding-left: 5px;
+}
+li:first-child {
+	margin-top: 0;
+}
+li:last-child {
+	margin-bottom: 0;
+}
+.navheader hr,
+.navfooter hr {
+	margin: 1rem 0;
+	background: #e5e7eb;
+}
+@media (prefers-color-scheme: dark) {
+	.navheader hr,
+	.navfooter hr {
+		background: #4b5563;
+	}
+}
+.navheader a,
+.navfooter a {
+	text-decoration: none;
+}
+div.titlepage {
+	margin: 40px 0;
+}
+div.titlepage hr {
+	display: none;
+}
+div.toc {
+	background: #f9fafb;
+	margin: 2rem 16px;
+	padding: 10px;
+	border: 1px solid #e5e7eb;
+	border-radius: 4px;
+	box-shadow: 4px 4px 8px #e5e7eb;
+}
+@media (prefers-color-scheme: dark) {
+	div.toc {
+		background: #1f2937;
+		border-color: black;
+		box-shadow: 4px 4px 8px black;
+	}
+}
+div.toc a {
+	text-decoration: none;
+}
+div.note,
+div.warning {
+	background: #f9fafb;
+	margin: 2rem 16px;
+	padding: 10px;
+	border: 1px solid #e5e7eb;
+	border-radius: 4px;
+	box-shadow: 4px 4px 8px #e5e7eb;
+	font-style: italic;
+}
+@media (prefers-color-scheme: dark) {
+	div.note,
+	div.warning {
+		background: #1f2937;
+		border-color: black;
+		box-shadow: 4px 4px 8px black;
+	}
+}
+div.note h3,
+div.warning h3 {
+	float: right;
+	margin: 0 0 1rem 1rem;
+	width: 42px;
+	height: 42px;
+	content: url();
+}
+div.note h3 + p,
+div.warning h3 + p {
+	margin-top: 0;
+}
+div.note h3 {
+	background-color: var(--nmd-color-info);
+	mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='42' height='42' viewBox='0 0 24 24' stroke-width='2' stroke='black' fill='none' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath stroke='none' d='M0 0h24v24H0z' fill='none'%3E%3C/path%3E%3Cpath d='M12 8h.01'%3E%3C/path%3E%3Cpath d='M11 12h1v4h1'%3E%3C/path%3E%3Cpath d='M12 3c7.2 0 9 1.8 9 9s-1.8 9 -9 9s-9 -1.8 -9 -9s1.8 -9 9 -9z'%3E%3C/path%3E%3C/svg%3E");
+	-webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='42' height='42' viewBox='0 0 24 24' stroke-width='2' stroke='black' fill='none' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath stroke='none' d='M0 0h24v24H0z' fill='none'%3E%3C/path%3E%3Cpath d='M12 8h.01'%3E%3C/path%3E%3Cpath d='M11 12h1v4h1'%3E%3C/path%3E%3Cpath d='M12 3c7.2 0 9 1.8 9 9s-1.8 9 -9 9s-9 -1.8 -9 -9s1.8 -9 9 -9z'%3E%3C/path%3E%3C/svg%3E");
+}
+div.warning h3 {
+	background-color: var(--nmd-color-warn);
+	mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='42' height='42' viewBox='0 0 24 24' stroke-width='2' stroke='black' fill='none' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath stroke='none' d='M0 0h24v24H0z' fill='none'%3E%3C/path%3E%3Cpath d='M12 9v2m0 4v.01'%3E%3C/path%3E%3Cpath d='M5 19h14a2 2 0 0 0 1.84 -2.75l-7.1 -12.25a2 2 0 0 0 -3.5 0l-7.1 12.25a2 2 0 0 0 1.75 2.75'%3E%3C/path%3E%3C/svg%3E");
+	-webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='42' height='42' viewBox='0 0 24 24' stroke-width='2' stroke='black' fill='none' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath stroke='none' d='M0 0h24v24H0z' fill='none'%3E%3C/path%3E%3Cpath d='M12 9v2m0 4v.01'%3E%3C/path%3E%3Cpath d='M5 19h14a2 2 0 0 0 1.84 -2.75l-7.1 -12.25a2 2 0 0 0 -3.5 0l-7.1 12.25a2 2 0 0 0 1.75 2.75'%3E%3C/path%3E%3C/svg%3E");
+}
+.term {
+	font-weight: 300;
+}
+.docbook .xref img[src^="images\/callouts\/"],
+.screen img,
+.programlisting img {
+	width: 1em;
+}
+.calloutlist img {
+	width: 1.3em;
+}
+.programlisting.language-shell .hljs-meta.prompt_ {
+	user-select: none;
+} /*!
+  Theme: Tomorrow
+  Author: Chris Kempson (http://chriskempson.com)
+  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: #4d4d4c;
+	background: #fff;
+}
+.hljs ::selection,
+.hljs::selection {
+	background-color: #d6d6d6;
+	color: #4d4d4c;
+}
+.hljs-comment {
+	color: #8e908c;
+}
+.hljs-tag {
+	color: #969896;
+}
+.hljs-operator,
+.hljs-punctuation,
+.hljs-subst {
+	color: #4d4d4c;
+}
+.hljs-operator {
+	opacity: 0.7;
+}
+.hljs-bullet,
+.hljs-deletion,
+.hljs-name,
+.hljs-selector-tag,
+.hljs-template-variable,
+.hljs-variable {
+	color: #c82829;
+}
+.hljs-attr,
+.hljs-link,
+.hljs-literal,
+.hljs-number,
+.hljs-symbol,
+.hljs-variable.constant_ {
+	color: #f5871f;
+}
+.hljs-class .hljs-title,
+.hljs-title,
+.hljs-title.class_ {
+	color: #eab700;
+}
+.hljs-strong {
+	font-weight: 700;
+	color: #eab700;
+}
+.hljs-addition,
+.hljs-code,
+.hljs-string,
+.hljs-title.class_.inherited__ {
+	color: #718c00;
+}
+.hljs-built_in,
+.hljs-doctag,
+.hljs-keyword.hljs-atrule,
+.hljs-quote,
+.hljs-regexp {
+	color: #3e999f;
+}
+.hljs-attribute,
+.hljs-function .hljs-title,
+.hljs-section,
+.hljs-title.function_,
+.ruby .hljs-property {
+	color: #4271ae;
+}
+.diff .hljs-meta,
+.hljs-keyword,
+.hljs-template-tag,
+.hljs-type {
+	color: #8959a8;
+}
+.hljs-emphasis {
+	color: #8959a8;
+	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;
+}
+@media (prefers-color-scheme: dark) {
+	/*!  Theme: Tomorrow Night  Author: Chris Kempson (http://chriskempson.com)  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;
+	}
+}

docs/static/style.scss

@@ -0,0 +1,312 @@
+:root {
+	--nmd-color0: #0a3e68;
+	--nmd-color1: #268598;
+	--nmd-color2: #b8d09e;
+	--nmd-color3: #f6cf5e;
+	--nmd-color4: #ec733b;
+
+	--nmd-color-info: #167cb9;
+	--nmd-color-warn: #ff6700;
+}
+
+// Copied from Tailwind CSS.
+$color-gray-50: #f9fafb;
+$color-gray-100: #f3f4f6;
+$color-gray-200: #e5e7eb;
+$color-gray-300: #d1d5db;
+$color-gray-400: #9ca3af;
+$color-gray-500: #6b7280;
+$color-gray-600: #4b5563;
+$color-gray-700: #374151;
+$color-gray-800: #1f2937;
+$color-gray-900: #111827;
+
+$color-blue-50: #eff6ff;
+$color-blue-100: #dbeafe;
+$color-blue-200: #bfdbfe;
+$color-blue-300: #93c5fd;
+$color-blue-400: #60a5fa;
+$color-blue-500: #3b82f6;
+$color-blue-600: #2563eb;
+$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;
+	padding: 10px;
+	border: 1px solid $color-gray-200;
+	border-radius: 4px;
+	box-shadow: 4px 4px 8px $color-gray-200;
+
+	@media (prefers-color-scheme: dark) {
+		background: $color-gray-800;
+		border-color: black;
+		box-shadow: 4px 4px 8px black;
+	}
+}
+
+@mixin margined {
+	margin: 0.9rem 0;
+
+	&:first-child {
+		margin-top: 0;
+	}
+
+	&:last-child {
+		margin-bottom: 0;
+	}
+}
+
+body {
+	background: white;
+	color: $color-gray-900;
+	max-width: min(100ch, 1024px);
+	margin: 0 auto;
+	padding: 10px;
+
+	font-family: "Lucida Sans", Arial, sans-serif;
+	font-size: 16px;
+	line-height: 1.4em;
+
+	@media (prefers-color-scheme: dark) {
+		background: $color-gray-900;
+		color: $color-gray-50;
+	}
+}
+
+h1,
+h2,
+h3 {
+	color: var(--nmd-color0);
+	font-family: "Lato", sans-serif;
+	font-weight: 300;
+	line-height: 1.125;
+
+	@media (prefers-color-scheme: dark) {
+		color: var(--nmd-color4);
+	}
+}
+
+h1 {
+	font-size: 48px;
+	font-weight: 300;
+	margin: 4rem 0 1.5rem;
+}
+
+h2 {
+	font-size: 32px;
+	font-weight: 300;
+	margin: 2rem 0 1rem;
+}
+
+h3 {
+	font-size: 20px;
+	font-weight: 400;
+	margin: 0.5rem 0.25rem;
+}
+
+p {
+	@include margined;
+}
+
+a {
+	color: var(--nmd-color0); //$color-secondary-1-3;
+	text-decoration: underline;
+	text-underline-offset: 3px;
+
+	&:visited {
+		color: var(--nmd-color1);
+	}
+
+	&:hover {
+		color: var(--nmd-color1);
+	}
+
+	@media (prefers-color-scheme: dark) {
+		color: var(--nmd-color3);
+
+		&:visited {
+			color: var(--nmd-color2);
+		}
+
+		&:hover {
+			color: var(--nmd-color4);
+		}
+	}
+}
+
+code {
+	font-size: 90%;
+}
+
+span.command {
+	font-size: 90%;
+	font-family: monospace;
+}
+
+em {
+	font-style: italic;
+}
+
+strong {
+	font-weight: bold;
+}
+
+pre {
+	@include boxed;
+
+	font-size: 90%;
+	margin-bottom: 1.5rem;
+	padding: 6px;
+	overflow: auto;
+
+	// The callout markers should not be selectable.
+	span img {
+		user-select: none;
+	}
+}
+
+pre:has(code) {
+	padding: 0;
+}
+
+td,
+th {
+	padding: 2px 5px;
+
+	&:first-child {
+		padding-left: 0;
+	}
+
+	&:last-child {
+		padding-right: 0;
+	}
+}
+
+dt {
+	margin: 1.2rem 0 0.8rem;
+}
+
+dd {
+	margin-left: 2rem;
+}
+
+div.book {
+}
+
+ul {
+	@include margined;
+
+	padding-left: 30px;
+	list-style: disc;
+}
+
+ol {
+	@include margined;
+
+	padding-left: 30px;
+	list-style: decimal;
+}
+
+li {
+	@include margined;
+
+	padding-left: 5px;
+}
+
+.navheader,
+.navfooter {
+	hr {
+		margin: 1rem 0;
+		background: $color-gray-200;
+		@media (prefers-color-scheme: dark) {
+			background: $color-gray-600;
+		}
+	}
+
+	a {
+		text-decoration: none;
+	}
+}
+
+div.titlepage {
+	margin: 40px 0;
+
+	hr {
+		display: none;
+	}
+}
+
+div.toc {
+	@include boxed;
+
+	a {
+		text-decoration: none;
+	}
+}
+
+div.note,
+div.warning {
+	@include boxed;
+
+	font-style: italic;
+
+	h3 {
+		float: right;
+		margin: 0 0 1rem 1rem;
+		width: 42px;
+		height: 42px;
+		content: url();
+	}
+
+	h3 + p {
+		margin-top: 0;
+	}
+}
+
+div.note {
+	h3 {
+		background-color: var(--nmd-color-info);
+		// From https://tabler-icons.io/i/info-square-rounded
+		mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='42' height='42' viewBox='0 0 24 24' stroke-width='2' stroke='black' fill='none' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath stroke='none' d='M0 0h24v24H0z' fill='none'%3E%3C/path%3E%3Cpath d='M12 8h.01'%3E%3C/path%3E%3Cpath d='M11 12h1v4h1'%3E%3C/path%3E%3Cpath d='M12 3c7.2 0 9 1.8 9 9s-1.8 9 -9 9s-9 -1.8 -9 -9s1.8 -9 9 -9z'%3E%3C/path%3E%3C/svg%3E");
+		-webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='42' height='42' viewBox='0 0 24 24' stroke-width='2' stroke='black' fill='none' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath stroke='none' d='M0 0h24v24H0z' fill='none'%3E%3C/path%3E%3Cpath d='M12 8h.01'%3E%3C/path%3E%3Cpath d='M11 12h1v4h1'%3E%3C/path%3E%3Cpath d='M12 3c7.2 0 9 1.8 9 9s-1.8 9 -9 9s-9 -1.8 -9 -9s1.8 -9 9 -9z'%3E%3C/path%3E%3C/svg%3E");
+	}
+}
+
+div.warning {
+	h3 {
+		background-color: var(--nmd-color-warn);
+		// From https://tabler-icons.io/i/alert-triangle
+		mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='42' height='42' viewBox='0 0 24 24' stroke-width='2' stroke='black' fill='none' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath stroke='none' d='M0 0h24v24H0z' fill='none'%3E%3C/path%3E%3Cpath d='M12 9v2m0 4v.01'%3E%3C/path%3E%3Cpath d='M5 19h14a2 2 0 0 0 1.84 -2.75l-7.1 -12.25a2 2 0 0 0 -3.5 0l-7.1 12.25a2 2 0 0 0 1.75 2.75'%3E%3C/path%3E%3C/svg%3E");
+		-webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='42' height='42' viewBox='0 0 24 24' stroke-width='2' stroke='black' fill='none' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath stroke='none' d='M0 0h24v24H0z' fill='none'%3E%3C/path%3E%3Cpath d='M12 9v2m0 4v.01'%3E%3C/path%3E%3Cpath d='M5 19h14a2 2 0 0 0 1.84 -2.75l-7.1 -12.25a2 2 0 0 0 -3.5 0l-7.1 12.25a2 2 0 0 0 1.75 2.75'%3E%3C/path%3E%3C/svg%3E");
+	}
+}
+
+.term {
+	font-weight: 300;
+}
+
+.docbook .xref img[src^="images\/callouts\/"],
+.screen img,
+.programlisting img {
+	width: 1em;
+}
+
+.calloutlist img {
+	width: 1.3em;
+}
+
+/** The console prompt, e.g., `$` and `#` should not be selectable. */
+.programlisting.language-shell .hljs-meta.prompt_ {
+	user-select: none;
+}
+
+@import "tomorrow.min.css";
+
+@media (prefers-color-scheme: dark) {
+	@import "tomorrow-night.min.css";
+}

docs/static/tomorrow-night.min.css

@@ -0,0 +1,102 @@
+/*!
+  Theme: Tomorrow Night
+  Author: Chris Kempson (http://chriskempson.com)
+  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;
+}

docs/static/tomorrow.min.css

@@ -0,0 +1,102 @@
+/*!
+  Theme: Tomorrow
+  Author: Chris Kempson (http://chriskempson.com)
+  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: #4d4d4c;
+	background: #fff;
+}
+.hljs ::selection,
+.hljs::selection {
+	background-color: #d6d6d6;
+	color: #4d4d4c;
+}
+.hljs-comment {
+	color: #8e908c;
+}
+.hljs-tag {
+	color: #969896;
+}
+.hljs-operator,
+.hljs-punctuation,
+.hljs-subst {
+	color: #4d4d4c;
+}
+.hljs-operator {
+	opacity: 0.7;
+}
+.hljs-bullet,
+.hljs-deletion,
+.hljs-name,
+.hljs-selector-tag,
+.hljs-template-variable,
+.hljs-variable {
+	color: #c82829;
+}
+.hljs-attr,
+.hljs-link,
+.hljs-literal,
+.hljs-number,
+.hljs-symbol,
+.hljs-variable.constant_ {
+	color: #f5871f;
+}
+.hljs-class .hljs-title,
+.hljs-title,
+.hljs-title.class_ {
+	color: #eab700;
+}
+.hljs-strong {
+	font-weight: 700;
+	color: #eab700;
+}
+.hljs-addition,
+.hljs-code,
+.hljs-string,
+.hljs-title.class_.inherited__ {
+	color: #718c00;
+}
+.hljs-built_in,
+.hljs-doctag,
+.hljs-keyword.hljs-atrule,
+.hljs-quote,
+.hljs-regexp {
+	color: #3e999f;
+}
+.hljs-attribute,
+.hljs-function .hljs-title,
+.hljs-section,
+.hljs-title.function_,
+.ruby .hljs-property {
+	color: #4271ae;
+}
+.diff .hljs-meta,
+.hljs-keyword,
+.hljs-template-tag,
+.hljs-type {
+	color: #8959a8;
+}
+.hljs-emphasis {
+	color: #8959a8;
+	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;
+}

lib/dag.nix

@@ -8,10 +8,10 @@
 #  - the addition of the function `entryBefore` indicating a "wanted
 #    by" relationship.
 {lib}: let
-  inherit (builtins) isAttrs attrValues attrNames elem all;
+  inherit (builtins) isAttrs attrValues attrNames elem all head tail length;
   inherit (lib.attrsets) filterAttrs mapAttrs;
   inherit (lib.lists) toposort;
-  inherit (lib.nvim.dag) isEntry entryBetween;
+  inherit (lib.nvim.dag) empty isEntry entryBetween entryAfter entriesBetween;
 in {
   empty = {};
 
@@ -108,6 +108,41 @@ in {
   entryAfter = entryBetween [];
   entryBefore = before: entryBetween before [];
 
+  # Given a list of entries, this function places them in order within the DAG.
+  # Each entry is labeled "${tag}-${entry index}" and other DAG entries can be
+  # added with 'before' or 'after' referring these indexed entries.
+  #
+  # The entries as a whole can be given a relation to other DAG nodes. All
+  # generated nodes are then placed before or after those dependencies.
+  entriesBetween = tag: let
+    go = i: before: after: entries: let
+      name = "${tag}-${toString i}";
+      i' = i + 1;
+    in
+      if entries == []
+      then empty
+      else if length entries == 1
+      then {
+        "${name}" = entryBetween before after (head entries);
+      }
+      else
+        {
+          "${name}" = entryAfter after (head entries);
+        }
+        // go (i + 1) before [name] (tail entries);
+  in
+    go 0;
+
+  entriesAnywhere = tag: entriesBetween tag [] [];
+  entriesAfter = tag: entriesBetween tag [];
+  entriesBefore = tag: before: entriesBetween tag before [];
+
+  # mkLuarcSection and mkVimrcSection take a section DAG
+  # and return a string containing a comment to identify
+  # the section, and the data contained within the section
+  #
+  # all operations are done without any modifications
+  # to the inputted section data
   mkLuarcSection = section: ''
     -- SECTION: ${section.name}
     ${section.data}