docs: New documentation using mdbook (#471)

* docs: mdbook init

* Separate sub-options into their section

* docs: enable fold

* docs: merge core options into a single section

* doc generation: fix submodules index pages

* docs: add contributing section

* docs: rename 'core' group to 'Neovim Options'

docs: removed the index pages of empty sections

docs: remove obsolete 'mergeFunctionResults' function

* docs: use nix syntax highlighting

* docs: point to the new repo url

* docs: use recursive generation
docs: split submodules into subsections

* docs: fix contributing separator
docs: fix missing submodules docs

docs.nix

@@ -1,39 +0,0 @@
-{
-  pkgs,
-  lib,
-  modules,
-  ...
-}: let
-  options = lib.evalModules {
-    inherit modules;
-    specialArgs = {inherit pkgs lib;};
-  };
-  docs = pkgs.nixosOptionsDoc {
-    # If we don't do this, we end up with _module.args on the generated options, which we do not want
-    options = lib.filterAttrs (k: _: k != "_module") options.options;
-    warningsAreErrors = false;
-  };
-  asciidoc = docs.optionsAsciiDoc;
-in
-  pkgs.stdenv.mkDerivation {
-    name = "nixvim-docs";
-
-    src = asciidoc;
-    buildInputs = [
-      pkgs.asciidoctor
-    ];
-
-    phases = ["buildPhase"];
-
-    buildPhase = ''
-      mkdir -p $out/share/doc
-      cat <<EOF > header.adoc
-      = NixVim options
-      This lists all the options available for NixVim.
-      :toc:
-
-      EOF
-      cat header.adoc $src > tmp.adoc
-      asciidoctor tmp.adoc -o $out/share/doc/index.html
-    '';
-  }

docs/SUMMARY.md

@@ -0,0 +1,11 @@
+# Structure for nixvim docs 
+
+# Options
+
+@NIXVIM_OPTIONS@
+
+#
+
+---
+
+[Contributing](./CONTRIBUTING.md)

docs/book.toml

@@ -0,0 +1,10 @@
+[book]
+authors = []
+language = "en"
+multilingual = false
+src = "."
+title = "nixvim docs"
+
+[output.html.fold]
+enable = true
+level = 0

docs/default.nix

@@ -0,0 +1,235 @@
+{
+  pkgs,
+  lib,
+  modules,
+  ...
+}:
+with lib; let
+  options = lib.evalModules {
+    inherit modules;
+    specialArgs = {inherit pkgs lib;};
+  };
+
+  mkMDDoc = options:
+    (pkgs.nixosOptionsDoc {
+      options = filterAttrs (k: _: k != "_module") options;
+      warningsAreErrors = false;
+      transformOptions = opts:
+        opts
+        // {
+          declarations = with builtins;
+            map
+            (
+              decl:
+                if hasPrefix "/nix/store/" decl
+                then let
+                  filepath = toString (match "^/nix/store/[^/]*/(.*)" decl);
+                in {
+                  url = "https://github.com/nix-community/nixvim/blob/main/${filepath}";
+                  name = filepath;
+                }
+                else decl
+            )
+            opts.declarations;
+        };
+    })
+    .optionsCommonMark;
+
+  removeUnwanted = attrs:
+    builtins.removeAttrs attrs [
+      "_module"
+      "_freeformOptions"
+      "warnings"
+      "assertions"
+      "content"
+    ];
+
+  removeWhitespace = builtins.replaceStrings [" "] [""];
+
+  getSubOptions = opts: path: removeUnwanted (opts.type.getSubOptions path);
+
+  wrapModule = path: opts: isOpt: rec {
+    index = {
+      options =
+        if isOpt
+        then opts
+        else filterAttrs (_: component: component.isOption) opts;
+      path = concatStringsSep "/" path;
+    };
+
+    components =
+      if isOpt
+      then {}
+      else filterAttrs (_: component: !component.isOption) opts;
+
+    hasComponents = components != {};
+
+    isOption = isOpt;
+  };
+
+  processModulesRec = modules: let
+    recurse = path: mods: let
+      g = name: opts:
+        if !isOption opts
+        then wrapModule (path ++ [name]) (recurse (path ++ [name]) opts) false
+        else let
+          subOpts = getSubOptions opts (path ++ [name]);
+        in
+          if subOpts != {}
+          then
+            wrapModule
+            (path ++ [name])
+            (
+              (recurse (path ++ [name]) subOpts)
+              // {
+                # This is necessary to include the submodule option's definition in the docs (description, type, etc.)
+                # For instance, this helps submodules like "autoCmd" to include their base definitions and examples in the docs
+                # Though there might be a better, less "hacky" solution than this.
+                ${name} = recursiveUpdate opts {
+                  isOption = true;
+                  type.getSubOptions = _: _: {}; # Used to exclude suboptions from the submodule definition itself
+                };
+              }
+            )
+            false
+          else wrapModule (path ++ [name]) opts true;
+    in
+      mapAttrs g mods;
+  in
+    foldlAttrs
+    (
+      acc: name: opts: let
+        group =
+          if !opts.hasComponents
+          then "Neovim Options"
+          else "none";
+
+        last =
+          acc.${group}
+          or {
+            index = {
+              options = {};
+              path = removeWhitespace "${group}";
+            };
+            components = {};
+            isGroup = true;
+            hasComponents = false;
+          };
+
+        isOpt = !opts.hasComponents && (isOption opts.index.options);
+      in
+        acc
+        // {
+          ${group} = recursiveUpdate last {
+            index.options = optionalAttrs isOpt {
+              ${name} = opts.index.options;
+            };
+
+            components = optionalAttrs (!isOpt) {
+              ${name} = recursiveUpdate opts {
+                index.path = removeWhitespace (concatStringsSep "/" ((optional (group != "none") group) ++ [opts.index.path]));
+                hasComponents = true;
+              };
+            };
+
+            hasComponents = last.components != {};
+          };
+        }
+    )
+    {}
+    (recurse [] modules);
+
+  mapModulesToString = f: modules: let
+    recurse = mods: let
+      g = name: opts:
+        if (opts ? "isGroup")
+        then
+          if name != "none"
+          then (f name opts) + ("\n" + recurse opts.components)
+          else recurse opts.components
+        else if opts.hasComponents
+        then (f name opts) + ("\n" + recurse opts.components)
+        else f name opts;
+    in
+      concatStringsSep "\n" (mapAttrsToList g mods);
+  in
+    recurse modules;
+
+  docs = rec {
+    modules = processModulesRec (removeUnwanted options.options);
+    commands =
+      mapModulesToString
+      (
+        name: opts: let
+          isBranch =
+            if (hasSuffix "index" opts.index.path)
+            then true
+            else opts.hasComponents;
+          path =
+            if isBranch
+            then "${opts.index.path}/index.md"
+            else "${opts.index.path}.md";
+        in
+          (optionalString isBranch
+            "mkdir -p ${opts.index.path}\n")
+          + "cp ${mkMDDoc opts.index.options} ${path}"
+      )
+      modules;
+  };
+
+  mdbook = {
+    nixvimOptions =
+      mapModulesToString
+      (
+        name: opts: let
+          isBranch =
+            if name == "index"
+            then true
+            else opts.hasComponents && opts.index.options != {};
+
+          path =
+            if isBranch
+            then "${opts.index.path}/index.md"
+            else if !opts.hasComponents
+            then "${opts.index.path}.md"
+            else "";
+
+          indentLevel = with builtins; length (filter isString (split "/" opts.index.path)) - 1;
+
+          padding = concatStrings (builtins.genList (_: "\t") indentLevel);
+        in "${padding}- [${name}](${path})"
+      )
+      docs.modules;
+  };
+
+  prepareMD = ''
+    # Copy inputs into the build directory
+    cp -r --no-preserve=all $inputs/* ./
+    cp ${../CONTRIBUTING.md} ./CONTRIBUTING.md
+
+    # Copy the generated MD docs into the build directory
+    # Using pkgs.writeShellScript helps to avoid the "bash: argument list too long" error
+    ${pkgs.writeShellScript "copy_docs" docs.commands}
+
+    # Prepare SUMMARY.md for mdBook
+    # Using pkgs.writeText helps to avoid the same error as above
+    substituteInPlace ./SUMMARY.md \
+      --replace "@NIXVIM_OPTIONS@" "$(cat ${pkgs.writeText "nixvim-options-summary.md" mdbook.nixvimOptions})"
+  '';
+in
+  pkgs.stdenv.mkDerivation {
+    name = "nixvim-docs";
+
+    phases = ["buildPhase"];
+
+    buildInputs = [pkgs.mdbook];
+    inputs = sourceFilesBySuffices ./. [".md" ".toml" ".js"];
+
+    buildPhase = ''
+      dest=$out/share/doc
+      mkdir -p $dest
+      ${prepareMD}
+      mdbook build
+      cp -r ./book/* $dest
+    '';
+  }

flake.nix

@@ -117,7 +117,7 @@
             };
           };
           packages = {
-            docs = pkgs-unfree.callPackage (import ./docs.nix) {
+            docs = pkgs-unfree.callPackage (import ./docs) {
               modules = nixvimModules;
             };
             runUpdates =

plugins/colorschemes/kanagawa.nix

@@ -76,7 +76,7 @@ in {
               Change specific usages for a certain theme, or for all of them
 
               Example:
-              ```
+              ```nix
                 {
                   wave = {
                     ui = {
@@ -103,7 +103,7 @@ in {
             Change all usages of these colors.
 
             Example:
-            ```
+            ```nix
               {
                 sumiInk0 = "#000000";
                 fujiWhite = "#FFFFFF";

plugins/completion/copilot-lua.nix

@@ -89,7 +89,7 @@ in {
             Each value can be either a boolean or a lua function that returns a boolean.
 
             Example:
-            ```
+            ```nix
               {
                 markdown = true; # overrides default
                 terraform = false; # disallow specific filetype
@@ -107,7 +107,7 @@ in {
 
             The key `"*"` can be used to disable the default configuration.
             Example:
-            ```
+            ```nix
               {
                 javascript = true; # allow specific filetype
                 typescript = true; # allow specific filetype
@@ -138,7 +138,7 @@ in {
           See `:h vim.lsp.start_client` for list of options.
 
           Example:
-          ```
+          ```nix
             {
               trace = "verbose";
               settings = {

plugins/completion/nvim-cmp/default.nix

@@ -126,7 +126,7 @@ in {
           - ultisnips
 
           You can also provide a custom function:
-          ```
+          ```nix
           {
             __raw = \'\'
               function(args)

plugins/dap/dap-ui.nix

@@ -122,7 +122,7 @@ in {
       layouts =
         helpers.defaultNullOpts.mkNullable (types.listOf layoutOption)
         ''
-          ```
+          ```nix
             [
               {
                 elements = [

plugins/filetrees/neo-tree.nix

@@ -317,7 +317,7 @@ in {
           - values are lua code defining the callback function.
 
           Example:
-          ```
+          ```nix
           {
             before_render = \'\'
               function (state)
@@ -626,7 +626,7 @@ in {
           mappings =
             mkMappingsOption
             ''
-              ```
+              ```nix
                 {
                   "<space>" = {
                     command = "toggle_node";
@@ -679,7 +679,7 @@ in {
         };
       filesystem = helpers.mkCompositeOption "Filesystem options" {
         window = mkWindowMappingsOption (lib.mdDoc ''
-          ```
+          ```nix
             {
               H = "toggle_hidden";
               "/" = "fuzzy_finder";
@@ -747,7 +747,7 @@ in {
             Hide by pattern.
 
             Example:
-            ```
+            ```nix
               [
                 "*.meta"
                 "*/src/*/tsconfig.json"
@@ -808,7 +808,7 @@ in {
 
             Either use a list of strings:
 
-            ```
+            ```nix
             findArgs = {
               fd = [
                 "--exclude"

plugins/languages/nvim-jdtls.nix

@@ -21,7 +21,7 @@ in {
         You should either set a value for this option, or, you can instead set the `data` (and
         `configuration`) options.
 
-        ```
+        ```nix
         plugins.nvim-jdtls = {
           enable = true;
           cmd = [
@@ -34,7 +34,7 @@ in {
         ```
 
         Or,
-        ```
+        ```nix
         plugins.nvim-jdtls = {
           enable = true;
           data =  "/path/to/your/workspace";

plugins/languages/sniprun.nix

@@ -36,7 +36,7 @@ in {
           only sucessful runs (or errored-out runs respectively)
 
           Example:
-          ```
+          ```nix
           [
             "Classic"                    # display results in the command-line  area
             "VirtualTextOk"              # display ok results as virtual text (multiline is shortened)

plugins/languages/vim-slime.nix

@@ -53,14 +53,14 @@ in
 
           Examples:
             - `tmux`:
-              ```
+              ```nix
                 {
                   socket_name = "default";
                   target_pane = "{last}";
                 }
               ```
             - `zellij`:
-              ```
+              ```nix
                 {
                   session_id = "current";
                   relative_pane = "right";

plugins/lsp/language-servers/ltex-settings.nix

@@ -100,7 +100,7 @@ in {
     ''
       Lists of additional words that should not be counted as spelling errors.
       This setting is language-specific, so use an attrs of the format
-      ```
+      ```nix
         {
           "<LANGUAGE1>" = [
             "<WORD1>"
@@ -121,7 +121,7 @@ in {
       By default, no additional spelling errors will be ignored.
 
       Example:
-      ```
+      ```nix
       {
         "en-US" = [
           "adaptivity"
@@ -143,7 +143,7 @@ in {
     ''
       Lists of rules that should be disabled (if enabled by default by LanguageTool).
       This setting is language-specific, so use an attrs of the format
-      ```
+      ```nix
         {
           "<LANGUAGE1>" = [
             "<WORD1>"
@@ -165,7 +165,7 @@ in {
       By default, no additional rules will be disabled.
 
       Example:
-      ```
+      ```nix
       {
         "en-US" = [
           "EN_QUOTES"
@@ -183,7 +183,7 @@ in {
     ''
       Lists of rules that should be enabled (if disabled by default by LanguageTool).
       This setting is language-specific, so use an attrs of the format
-      ```
+      ```nix
         {
           "<LANGUAGE1>" = [
             "<WORD1>"
@@ -205,7 +205,7 @@ in {
       By default, no additional rules will be enabled.
 
       Example:
-      ```
+      ```nix
         {
           "en-GB" = [
             "PASSIVE_VOICE"
@@ -224,7 +224,7 @@ in {
       Lists of false-positive diagnostics to hide (by hiding all diagnostics of a specific rule
       within a specific sentence).
       This setting is language-specific, so use an attrs of the format
-      ```
+      ```nix
         {
           "<LANGUAGE1>" = [
             "<JSON1>"
@@ -256,7 +256,7 @@ in {
       If this list is very large, performance may suffer.
 
       Example:
-      ```
+      ```nix
         {
           "en-US" = [ ":/path/to/externalFile.txt" ];
         }
@@ -273,7 +273,7 @@ in {
     Some common fields are already ignored, even if you set this setting to an empty attrs.
 
     Example:
-    ```
+    ```nix
       {
         maintitle = false;
         seealso = true;
@@ -295,7 +295,7 @@ in {
       attrs.
 
       Example:
-      ```
+      ```nix
         {
           "\\label{}" = "ignore";
           "\\documentclass[]{}" = "ignore";
@@ -315,7 +315,7 @@ in {
       attrs.
 
       Example:
-      ```
+      ```nix
         {
           lstlisting = "ignore";
           verbatim = "ignore";
@@ -338,7 +338,7 @@ in {
       empty attrs.
 
       Example:
-      ```
+      ```nix
         {
           CodeBlock = "ignore";
           FencedCodeBlock = "ignore";

plugins/utils/coverage.nix

@@ -244,7 +244,7 @@ in {
         See plugin documentation for language specific options.
 
         Example:
-        ```
+        ```nix
           {
             python = {
               coverage_file = ".coverage";

plugins/utils/leap.nix

@@ -60,7 +60,7 @@ in {
           either be defined as strings or tables.
 
           Example:
-          ```
+          ```nix
             [
               "\r\n"
               ")]}>"

plugins/utils/neogen.nix

@@ -93,7 +93,7 @@ in {
           https://github.com/danymat/neogen/blob/main/docs/adding-languages.md#default-generator
 
         Example:
-        ```
+        ```nix
           {
             csharp = {
               template = {

plugins/utils/presence-nvim.nix

@@ -84,7 +84,7 @@ in {
           `source`: The source of the asset, either an art asset key or the URL of an image asset.
 
           Example:
-          ```
+          ```nix
             {
               # Use art assets uploaded in Discord application for the configured client id
               js = [ "JavaScript" "javascript" ];

plugins/utils/todo-comments.nix

@@ -55,7 +55,7 @@ in {
             Configurations for keywords to be recognized as todo comments.
 
             Default:
-            ```
+            ```nix
             {
               FIX = {
                 icon = " "; # Icon used for the sign, and in search results.
@@ -144,7 +144,7 @@ in {
             of highlight groups or use the hex color if hl not found as a fallback.
 
             Default:
-            ```
+            ```nix
             {
               error = [ "DiagnosticError" "ErrorMsg" "#DC2626" ];
               warning = [ "DiagnosticWarn" "WarningMsg" "#FBBF24" ];
@@ -163,7 +163,7 @@ in {
             Arguments to use for the search command in list form.
 
             Default:
-            ```
+            ```nix
             [
               "--color=never"
               "--no-heading"

plugins/utils/toggleterm.nix

@@ -19,7 +19,7 @@ in {
         Size of the terminal.
         `size` can be a number or function
         Example:
-        ```
+        ```nix
         size = 20
         ```
         OR
@@ -78,7 +78,7 @@ in {
       Highlights which map to a highlight group name and a table of it's values.
 
       Example:
-      ```
+      ```nix
         highlights = {
           Normal = {
             guibg = "<VALUE-HERE>";