From be97b3d6475501b17b610cacfcba72572c1d50dd Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 23 Nov 2021 00:11:02 +0100
Subject: [PATCH 1/8] Add flakeModule

---
 flake-module.nix | 64 ++++++++++++++++++++++++++++++++++++++++++++++++
 flake.nix        |  5 +++-
 2 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 flake-module.nix

diff --git a/flake-module.nix b/flake-module.nix
new file mode 100644
index 00000000..98e6aa49
--- /dev/null
+++ b/flake-module.nix
@@ -0,0 +1,64 @@
+/*
+  A module to import into flakes based on flake-modules-core.
+  Makes integration into a flake easy and tidy.
+  See https://github.com/hercules-ci/flake-modules-core#readme
+*/
+
+{ lib, self, ... }:
+let
+  inherit (lib)
+    mkOption
+    types
+    ;
+in
+{
+  config = {
+    perSystem = system: { config, self', inputs', ... }:
+      let
+        cfg = config.pre-commit;
+      in
+      {
+        options = {
+          pre-commit = {
+            pkgs = mkOption {
+              type = types.uniq (types.lazyAttrsOf (types.raw or types.unspecified));
+              description = ''
+                Nixpkgs to use for pre-commit checking.
+              '';
+              # Not sure what's the best default:
+              #  - pre-commit-hooks-nix.inputs.nixpkgs.legacyPackages.${system}
+              #    (could be passed in, making this file a function to a module function)
+              #    ci-checked but incompatible with user pkgs unless they use inputs.nixpkgs.follows
+              #    awkward if user wants to use an overlay
+              #  - config._module.args.pkgs (a default pkgs set by user / some other module)
+              #    always compatible with user pkgs, because it is user pkgs
+              #    not sure if we want to standardize having a default pkgs
+              #  - nothing: keep this as a manual setting.
+              #    foolproof but inconvenient.
+            };
+            settings = mkOption {
+              type = types.submoduleWith {
+                modules = [ ./modules/all-modules.nix ];
+                specialArgs = { inherit (cfg) pkgs; };
+              };
+              default = { };
+            };
+            installationScript = mkOption {
+              type = types.str;
+              description = "A bash fragment that sets up pre-commit.";
+              default = cfg.settings.installationScript;
+              readOnly = true;
+            };
+          };
+        };
+        config = {
+          checks.pre-commit = cfg.settings.run;
+          pre-commit.settings = { pkgs, ... }: {
+            rootSrc = self.outPath;
+            package = lib.mkDefault pkgs.pre-commit;
+            tools = import ./nix/call-tools.nix pkgs;
+          };
+        };
+      };
+  };
+}
diff --git a/flake.nix b/flake.nix
index 6ba33170..8e3e63ef 100644
--- a/flake.nix
+++ b/flake.nix
@@ -12,7 +12,10 @@
         "x86_64-linux"
       ];
     in
-    flake-utils.lib.eachSystem defaultSystems (system:
+    {
+      flakeModule = ./flake-module.nix;
+    }
+    // flake-utils.lib.eachSystem defaultSystems (system:
       let
         exposed = import ./nix { nixpkgs = nixpkgs; inherit system; gitignore-nix-src = null; isFlakes = true; };
       in

From f77cd6093b9135825309fa6bfd3903dc4a64d8bd Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 25 Nov 2021 13:49:45 +0100
Subject: [PATCH 2/8] Add template

---
 flake.nix          |  7 +++++++
 template/flake.nix | 43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 template/flake.nix

diff --git a/flake.nix b/flake.nix
index 8e3e63ef..aa05906f 100644
--- a/flake.nix
+++ b/flake.nix
@@ -14,6 +14,13 @@
     in
     {
       flakeModule = ./flake-module.nix;
+
+      defaultTemplate = {
+        path = ./template;
+        description = ''
+          A template with flake-parts and nixpkgs-fmt.
+        '';
+      };
     }
     // flake-utils.lib.eachSystem defaultSystems (system:
       let
diff --git a/template/flake.nix b/template/flake.nix
new file mode 100644
index 00000000..82a94968
--- /dev/null
+++ b/template/flake.nix
@@ -0,0 +1,43 @@
+{
+  description = "A flake with pre-commit hooks";
+
+  inputs = {
+    flake-modules-core.url = "github:hercules-ci/flake-modules-core";
+    flake-modules-core.inputs.nixpkgs.follows = "nixpkgs";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    pre-commit-hooks-nix.url = "github:hercules-ci/pre-commit-hooks.nix/flakeModule";
+    pre-commit-hooks-nix.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs = inputs@{ self, flake-modules-core, ... }:
+    (flake-modules-core.lib.evalFlakeModule
+      { inherit self; }
+      {
+        imports = [
+          inputs.pre-commit-hooks-nix.flakeModule
+        ];
+        systems = [ "x86_64-linux" "aarch64-darwin" ];
+        perSystem = system: { config, self', inputs', ... }: {
+          # Per-system attributes can be defined here. The self' and inputs'
+          # module parameters provide easy access to attributes of the same
+          # system.
+
+          packages.hello = inputs'.nixpkgs.legacyPackages.hello;
+          pre-commit.pkgs = inputs'.nixpkgs.legacyPackages;
+          pre-commit.settings.hooks.nixpkgs-fmt.enable = true;
+          devShell = inputs'.nixpkgs.legacyPackages.mkShell {
+            shellHook = ''
+              ${config.pre-commit.installationScript}
+              echo 1>&2 "Welcome to the development shell!"
+            '';
+          };
+        };
+        flake = {
+          # The usual flake attributes can be defined here, including system-
+          # agnostic ones like nixosModule and system-enumerating ones, although
+          # those are more easily expressed in perSystem.
+
+        };
+      }
+    ).config.flake;
+}

From 53df6d3270ab0f4bfc89b8b9a023ed37240d3902 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Wed, 25 May 2022 18:07:05 +0200
Subject: [PATCH 3/8] flake-modules-core -> flake-parts, decide pkgs source

---
 flake-module.nix   | 27 +++++++++------------------
 template/flake.nix |  8 ++++----
 2 files changed, 13 insertions(+), 22 deletions(-)

diff --git a/flake-module.nix b/flake-module.nix
index 98e6aa49..de6a7aac 100644
--- a/flake-module.nix
+++ b/flake-module.nix
@@ -1,10 +1,10 @@
 /*
-  A module to import into flakes based on flake-modules-core.
+  A module to import into flakes based on flake-parts.
   Makes integration into a flake easy and tidy.
-  See https://github.com/hercules-ci/flake-modules-core#readme
+  See https://flake.parts
 */
 
-{ lib, self, ... }:
+{ lib, self, flake-parts-lib, ... }:
 let
   inherit (lib)
     mkOption
@@ -12,10 +12,9 @@ let
     ;
 in
 {
-  config = {
-    perSystem = system: { config, self', inputs', ... }:
-      let
-        cfg = config.pre-commit;
+  options = {
+    perSystem = flake-parts-lib.mkPerSystemOption ({ config, pkgs, ... }:
+      let cfg = config.pre-commit;
       in
       {
         options = {
@@ -25,16 +24,8 @@ in
               description = ''
                 Nixpkgs to use for pre-commit checking.
               '';
-              # Not sure what's the best default:
-              #  - pre-commit-hooks-nix.inputs.nixpkgs.legacyPackages.${system}
-              #    (could be passed in, making this file a function to a module function)
-              #    ci-checked but incompatible with user pkgs unless they use inputs.nixpkgs.follows
-              #    awkward if user wants to use an overlay
-              #  - config._module.args.pkgs (a default pkgs set by user / some other module)
-              #    always compatible with user pkgs, because it is user pkgs
-              #    not sure if we want to standardize having a default pkgs
-              #  - nothing: keep this as a manual setting.
-              #    foolproof but inconvenient.
+              default = pkgs;
+              defaultText = "pkgs  # module argument";
             };
             settings = mkOption {
               type = types.submoduleWith {
@@ -59,6 +50,6 @@ in
             tools = import ./nix/call-tools.nix pkgs;
           };
         };
-      };
+      });
   };
 }
diff --git a/template/flake.nix b/template/flake.nix
index 82a94968..99c360f1 100644
--- a/template/flake.nix
+++ b/template/flake.nix
@@ -2,15 +2,15 @@
   description = "A flake with pre-commit hooks";
 
   inputs = {
-    flake-modules-core.url = "github:hercules-ci/flake-modules-core";
-    flake-modules-core.inputs.nixpkgs.follows = "nixpkgs";
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    flake-parts.inputs.nixpkgs.follows = "nixpkgs";
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
     pre-commit-hooks-nix.url = "github:hercules-ci/pre-commit-hooks.nix/flakeModule";
     pre-commit-hooks-nix.inputs.nixpkgs.follows = "nixpkgs";
   };
 
-  outputs = inputs@{ self, flake-modules-core, ... }:
-    (flake-modules-core.lib.evalFlakeModule
+  outputs = inputs@{ self, flake-parts, ... }:
+    (flake-parts.lib.evalFlakeModule
       { inherit self; }
       {
         imports = [

From 59b64996544ce0bf3afa2cea7eee2dfdfb2c7e73 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 28 May 2022 18:22:15 +0200
Subject: [PATCH 4/8] template/flake.nix: Update

---
 template/flake.nix | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/template/flake.nix b/template/flake.nix
index 99c360f1..f6770713 100644
--- a/template/flake.nix
+++ b/template/flake.nix
@@ -10,22 +10,22 @@
   };
 
   outputs = inputs@{ self, flake-parts, ... }:
-    (flake-parts.lib.evalFlakeModule
+    flake-parts.lib.mkFlake
       { inherit self; }
       {
         imports = [
           inputs.pre-commit-hooks-nix.flakeModule
         ];
         systems = [ "x86_64-linux" "aarch64-darwin" ];
-        perSystem = system: { config, self', inputs', ... }: {
+        perSystem = { config, self', inputs', pkgs, ... }: {
           # Per-system attributes can be defined here. The self' and inputs'
           # module parameters provide easy access to attributes of the same
           # system.
 
-          packages.hello = inputs'.nixpkgs.legacyPackages.hello;
-          pre-commit.pkgs = inputs'.nixpkgs.legacyPackages;
+          # Equivalent to  inputs'.nixpkgs.legacyPackages.hello;
+          packages.hello = pkgs.hello;
           pre-commit.settings.hooks.nixpkgs-fmt.enable = true;
-          devShell = inputs'.nixpkgs.legacyPackages.mkShell {
+          devShells.default = pkgs.mkShell {
             shellHook = ''
               ${config.pre-commit.installationScript}
               echo 1>&2 "Welcome to the development shell!"
@@ -38,6 +38,5 @@
           # those are more easily expressed in perSystem.
 
         };
-      }
-    ).config.flake;
+      };
 }

From 68079e4cb42754873fa2d167282ae682a6543e62 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 29 May 2022 18:04:05 +0200
Subject: [PATCH 5/8] Make the docs build

---
 flake-module.nix       | 3 ++-
 modules/hooks.nix      | 4 ++++
 modules/pre-commit.nix | 9 +++++----
 3 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/flake-module.nix b/flake-module.nix
index de6a7aac..bfe2973f 100644
--- a/flake-module.nix
+++ b/flake-module.nix
@@ -25,7 +25,7 @@ in
                 Nixpkgs to use for pre-commit checking.
               '';
               default = pkgs;
-              defaultText = "pkgs  # module argument";
+              defaultText = lib.literalDocBook "<literal>pkgs</literal> (module argument)";
             };
             settings = mkOption {
               type = types.submoduleWith {
@@ -38,6 +38,7 @@ in
               type = types.str;
               description = "A bash fragment that sets up pre-commit.";
               default = cfg.settings.installationScript;
+              defaultText = lib.literalDocBook "bash statements";
               readOnly = true;
             };
           };
diff --git a/modules/hooks.nix b/modules/hooks.nix
index bff8f461..1ae661bb 100644
--- a/modules/hooks.nix
+++ b/modules/hooks.nix
@@ -112,6 +112,9 @@ in
               description =
                 "Prettier binary path. E.g. if you want to use the prettier in node_modules, use ./node_modules/.bin/prettier";
               default = "${tools.prettier}/bin/prettier";
+              defaultText = lib.literalExpression ''
+                "''${tools.prettier}/bin/prettier"
+              '';
             };
         };
       eslint =
@@ -122,6 +125,7 @@ in
               description =
                 "Eslint binary path. E.g. if you want to use the eslint in node_modules, use ./node_modules/.bin/eslint";
               default = "${tools.eslint}/bin/eslint";
+              defaultText = lib.literalExpression "\${tools.eslint}/bin/eslint";
             };
 
           extensions =
diff --git a/modules/pre-commit.nix b/modules/pre-commit.nix
index 308bbb28..b2dddd70 100644
--- a/modules/pre-commit.nix
+++ b/modules/pre-commit.nix
@@ -44,7 +44,7 @@ let
               mkOption {
                 type = types.str;
                 default = name;
-                defaultText = literalExample "internal name, same as id";
+                defaultText = lib.literalDocBook or literalExample "internal name, same as id";
                 description =
                   ''
                     The name of the hook - shown during hook execution.
@@ -202,7 +202,7 @@ in
               The pre-commit package to use.
             '';
           defaultText =
-            literalExample ''
+            lib.literalExpression or literalExample ''
               pkgs.pre-commit
             '';
         };
@@ -217,7 +217,7 @@ in
               nix-pre-commit comes with its own set of packages for this purpose.
             '';
           defaultText =
-            literalExample ''pre-commit-hooks.nix-pkgs.callPackage tools-dot-nix { inherit (pkgs) system; }'';
+            lib.literalExpression or literalExample ''pre-commit-hooks.nix-pkgs.callPackage tools-dot-nix { inherit (pkgs) system; }'';
         };
 
       hooks =
@@ -240,6 +240,7 @@ in
             '';
           readOnly = true;
           default = run;
+          defaultText = "<derivation>";
         };
 
       installationScript =
@@ -270,7 +271,7 @@ in
 
               This is used in the derivation that performs the check.
             '';
-          defaultText = literalExample ''gitignoreSource config.src'';
+          defaultText = lib.literalExpression or literalExample ''gitignoreSource config.src'';
         };
 
       excludes =

From 06a04338a1bbaca242ab9a2cd42ecc9acde98fb2 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 19 Sep 2022 12:14:15 +0100
Subject: [PATCH 6/8] flakeModule: Add check.enable option

---
 flake-module.nix | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/flake-module.nix b/flake-module.nix
index bfe2973f..8933bb4d 100644
--- a/flake-module.nix
+++ b/flake-module.nix
@@ -19,6 +19,16 @@ in
       {
         options = {
           pre-commit = {
+            check.enable = mkOption {
+              description = ''
+                Whether to add a derivation to the flake <literal>checks</literal>.
+
+                You can disable this if one of your hooks does not run properly in
+                the Nix sandbox; for example because it needs network access.
+              '';
+              type = types.bool;
+              default = true;
+            };
             pkgs = mkOption {
               type = types.uniq (types.lazyAttrsOf (types.raw or types.unspecified));
               description = ''
@@ -44,7 +54,7 @@ in
           };
         };
         config = {
-          checks.pre-commit = cfg.settings.run;
+          checks = lib.optionalAttrs cfg.check.enable { pre-commit = cfg.settings.run; };
           pre-commit.settings = { pkgs, ... }: {
             rootSrc = self.outPath;
             package = lib.mkDefault pkgs.pre-commit;

From aa013d6afcf7d742db12dd889d68637ef3f5bacc Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Fri, 4 Nov 2022 15:19:43 +0100
Subject: [PATCH 7/8] .envrc: Fix completions for system commands such as nix

---
 .envrc | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.envrc b/.envrc
index 17d3448b..44015bff 100644
--- a/.envrc
+++ b/.envrc
@@ -1,4 +1,6 @@
+HOST_XDG_DATA_DIRS="${XDG_DATA_DIRS:-}"
 eval "$(lorri direnv)"
+export XDG_DATA_DIRS="${XDG_DATA_DIRS}:${HOST_XDG_DATA_DIRS}"
 
 # Use system PKI
 unset SSL_CERT_FILE

From 1ee64b852871d790a49f0b8e17b788f5eeb2d52a Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 5 Nov 2022 02:33:21 +0100
Subject: [PATCH 8/8] Improve docs

---
 flake-module.nix       | 16 ++++---
 modules/hooks.nix      | 96 +++++++++++++++++++++---------------------
 modules/pre-commit.nix | 94 +++++++++++++++++++++++++++--------------
 3 files changed, 121 insertions(+), 85 deletions(-)

diff --git a/flake-module.nix b/flake-module.nix
index 8933bb4d..b4331ade 100644
--- a/flake-module.nix
+++ b/flake-module.nix
@@ -20,10 +20,11 @@ in
         options = {
           pre-commit = {
             check.enable = mkOption {
-              description = ''
-                Whether to add a derivation to the flake <literal>checks</literal>.
+              description = lib.mdDoc ''
+                Whether to add a derivation to the flake `checks`.
+                It will perform the pre-commit checks in `nix flake check`.
 
-                You can disable this if one of your hooks does not run properly in
+                You can disable this if one of your hooks do not run properly in
                 the Nix sandbox; for example because it needs network access.
               '';
               type = types.bool;
@@ -31,8 +32,8 @@ in
             };
             pkgs = mkOption {
               type = types.uniq (types.lazyAttrsOf (types.raw or types.unspecified));
-              description = ''
-                Nixpkgs to use for pre-commit checking.
+              description = lib.mdDoc ''
+                Nixpkgs to use in the pre-commit [`settings`](#opt-perSystem.pre-commit.settings).
               '';
               default = pkgs;
               defaultText = lib.literalDocBook "<literal>pkgs</literal> (module argument)";
@@ -43,10 +44,13 @@ in
                 specialArgs = { inherit (cfg) pkgs; };
               };
               default = { };
+              description = lib.mdDoc ''
+                The pre-commit-hooks.nix configuration.
+              '';
             };
             installationScript = mkOption {
               type = types.str;
-              description = "A bash fragment that sets up pre-commit.";
+              description = lib.mdDoc "A bash fragment that sets up [pre-commit](https://pre-commit.com/).";
               default = cfg.settings.installationScript;
               defaultText = lib.literalDocBook "bash statements";
               readOnly = true;
diff --git a/modules/hooks.nix b/modules/hooks.nix
index 1ae661bb..5fd33111 100644
--- a/modules/hooks.nix
+++ b/modules/hooks.nix
@@ -11,7 +11,7 @@ in
           silent =
             mkOption {
               type = types.bool;
-              description = "Should generation should be silent";
+              description = lib.mdDoc "Whether generation should be silent.";
               default = false;
             };
         };
@@ -20,13 +20,13 @@ in
           defaultExtensions =
             mkOption {
               type = types.listOf types.str;
-              description = "Haskell language extensions to enable";
+              description = lib.mdDoc "Haskell language extensions to enable.";
               default = [ ];
             };
           cabalDefaultExtensions =
             mkOption {
               type = types.bool;
-              description = "Use default-extensions from .cabal files";
+              description = lib.mdDoc "Use `default-extensions` from `.cabal` files.";
               default = false;
             };
         };
@@ -35,7 +35,7 @@ in
           exclude =
             mkOption {
               type = types.listOf types.str;
-              description = "Files or directories to exclude from formatting";
+              description = lib.mdDoc "Files or directories to exclude from formatting.";
               default = [ ];
               example = [ "flake.nix" "./templates" ];
             };
@@ -45,35 +45,35 @@ in
           fix =
             mkOption {
               type = types.bool;
-              description = "Remove unused code and write to source file";
+              description = lib.mdDoc "Remove unused code and write to source file.";
               default = false;
             };
 
           noLambdaArg =
             mkOption {
               type = types.bool;
-              description = "Don't check lambda parameter arguments";
+              description = lib.mdDoc "Don't check lambda parameter arguments.";
               default = false;
             };
 
           noLambdaPatternNames =
             mkOption {
               type = types.bool;
-              description = "Don't check lambda pattern names (don't break nixpkgs callPackage)";
+              description = lib.mdDoc "Don't check lambda pattern names (don't break nixpkgs `callPackage`).";
               default = false;
             };
 
           noUnderscore =
             mkOption {
               type = types.bool;
-              description = "Don't check any bindings that start with a _";
+              description = lib.mdDoc "Don't check any bindings that start with a `_`.";
               default = false;
             };
 
           quiet =
             mkOption {
               type = types.bool;
-              description = "Don't print dead code report";
+              description = lib.mdDoc "Don't print a dead code report.";
               default = false;
             };
         };
@@ -82,14 +82,14 @@ in
           format =
             mkOption {
               type = types.enum [ "stderr" "errfmt" "json" ];
-              description = "Error Output format";
+              description = lib.mdDoc "Error Output format.";
               default = "errfmt";
             };
 
           ignore =
             mkOption {
               type = types.listOf types.str;
-              description = "Globs of file patterns to skip";
+              description = lib.mdDoc "Globs of file patterns to skip.";
               default = [ ];
               example = [ "flake.nix" "_*" ];
             };
@@ -99,8 +99,8 @@ in
           checks =
             mkOption {
               type = types.listOf types.str;
-              description =
-                "Available checks (See `nix-linter --help-for [CHECK]` for more details)";
+              description = lib.mdDoc
+                "Available checks. See `nix-linter --help-for [CHECK]` for more details.";
               default = [ ];
             };
         };
@@ -109,8 +109,8 @@ in
           binPath =
             mkOption {
               type = types.path;
-              description =
-                "Prettier binary path. E.g. if you want to use the prettier in node_modules, use ./node_modules/.bin/prettier";
+              description = lib.mdDoc
+                "`prettier` binary path. E.g. if you want to use the `prettier` in `node_modules`, use `./node_modules/.bin/prettier`.";
               default = "${tools.prettier}/bin/prettier";
               defaultText = lib.literalExpression ''
                 "''${tools.prettier}/bin/prettier"
@@ -122,8 +122,8 @@ in
           binPath =
             mkOption {
               type = types.path;
-              description =
-                "Eslint binary path. E.g. if you want to use the eslint in node_modules, use ./node_modules/.bin/eslint";
+              description = lib.mdDoc
+                "`eslint` binary path. E.g. if you want to use the `eslint` in `node_modules`, use `./node_modules/.bin/eslint`.";
               default = "${tools.eslint}/bin/eslint";
               defaultText = lib.literalExpression "\${tools.eslint}/bin/eslint";
             };
@@ -131,8 +131,8 @@ in
           extensions =
             mkOption {
               type = types.str;
-              description =
-                "The pattern of files to run on, see https://pre-commit.com/#hooks-files";
+              description = lib.mdDoc
+                "The pattern of files to run on, see [https://pre-commit.com/#hooks-files](https://pre-commit.com/#hooks-files).";
               default = "\\.js$";
             };
         };
@@ -142,7 +142,7 @@ in
           configPath =
             mkOption {
               type = types.str;
-              description = "path to the configuration TOML file";
+              description = lib.mdDoc "Path to the configuration TOML file.";
               # an empty string translates to use default configuration of the
               # underlying revive binary
               default = "";
@@ -156,7 +156,7 @@ in
       actionlint =
         {
           name = "actionlint";
-          description = "Static checker for GitHub Actions workflow files";
+          description = "Static checker for GitHub Actions workflow files.";
           files = "^.github/workflows/";
           types = [ "yaml" ];
           entry = "${tools.actionlint}/bin/actionlint";
@@ -165,27 +165,27 @@ in
         {
           name = "ansible-lint";
           description =
-            "Ansible linter";
+            "Ansible linter.";
           entry = "${tools.ansible-lint}/bin/ansible-lint";
         };
       black =
         {
           name = "black";
-          description = "The uncompromising Python code formatter";
+          description = "The uncompromising Python code formatter.";
           entry = "${pkgs.python3Packages.black}/bin/black";
           types = [ "file" "python" ];
         };
       cabal2nix =
         {
           name = "cabal2nix";
-          description = "Run cabal2nix on all *.cabal files to generate corresponding default.nix files.";
+          description = "Run `cabal2nix` on all `*.cabal` files to generate corresponding `default.nix` files.";
           files = "\\.cabal$";
           entry = "${tools.cabal2nix-dir}/bin/cabal2nix-dir";
         };
       clang-format =
         {
           name = "clang-format";
-          description = "Format your code using clang-format";
+          description = "Format your code using `clang-format`.";
           entry = "${tools.clang-tools}/bin/clang-format -style=file -i";
           types = [ "file" ];
         };
@@ -198,7 +198,7 @@ in
         };
       dhall-format = {
         name = "dhall-format";
-        description = "Dhall code formatter";
+        description = "Dhall code formatter.";
         entry = "${tools.dhall}/bin/dhall format";
         files = "\\.dhall$";
       };
@@ -214,7 +214,7 @@ in
         {
           name = "hpack";
           description =
-            "hpack converts package definitions in the hpack format (package.yaml) to Cabal files.";
+            "`hpack` converts package definitions in the hpack format (`package.yaml`) to Cabal files.";
           entry = "${tools.hpack-dir}/bin/hpack-dir --${if settings.hpack.silent then "silent" else "verbose"}";
           files = "(\\.l?hs$)|(^[^/]+\\.cabal$)|(^package\\.yaml$)";
         };
@@ -228,14 +228,14 @@ in
       latexindent =
         {
           name = "latexindent";
-          description = "Perl script to add indentation to LaTeX files";
+          description = "Perl script to add indentation to LaTeX files.";
           types = [ "file" "tex" ];
           entry = "${tools.latexindent}/bin/latexindent --local --silent --modifyIfDifferent";
         };
       luacheck =
         {
           name = "luacheck";
-          description = "A tool for linting and static analysis of Lua code";
+          description = "A tool for linting and static analysis of Lua code.";
           types = [ "file" "lua" ];
           entry = "${tools.luacheck}/bin/luacheck";
         };
@@ -294,7 +294,7 @@ in
       alejandra =
         {
           name = "alejandra";
-          description = "The Uncompromising Nix Code Formatter";
+          description = "The Uncompromising Nix Code Formatter.";
           entry = with settings.alejandra;
             "${tools.alejandra}/bin/alejandra ${if (exclude != [ ]) then "-e ${lib.escapeShellArgs (lib.unique exclude)}" else ""}";
           files = "\\.nix$";
@@ -362,7 +362,7 @@ in
       elm-format =
         {
           name = "elm-format";
-          description = "Format Elm files";
+          description = "Format Elm files.";
           entry =
             "${tools.elm-format}/bin/elm-format --yes --elm-version=0.19";
           files = "\\.elm$";
@@ -378,7 +378,7 @@ in
       elm-test =
         {
           name = "elm-test";
-          description = "Run unit and fuzz tests for Elm code.";
+          description = "Run unit tests and fuzz tests for Elm code.";
           entry = "${tools.elm-test}/bin/elm-test";
           files = "\\.elm$";
           pass_filenames = false;
@@ -386,7 +386,7 @@ in
       shellcheck =
         {
           name = "shellcheck";
-          description = "Format shell files";
+          description = "Format shell files.";
           types = [ "shell" ];
           types_or =
             # based on `goodShells` in https://github.com/koalaman/shellcheck/blob/master/src/ShellCheck/Parser.hs
@@ -403,28 +403,28 @@ in
       stylua =
         {
           name = "stylua";
-          description = "An Opinionated Lua Code Formatter";
+          description = "An Opinionated Lua Code Formatter.";
           types = [ "file" "lua" ];
           entry = "${tools.stylua}/bin/stylua";
         };
       shfmt =
         {
           name = "shfmt";
-          description = "Format shell files";
+          description = "Format shell files.";
           types = [ "shell" ];
           entry = "${tools.shfmt}/bin/shfmt -w -s -l";
         };
       terraform-format =
         {
           name = "terraform-format";
-          description = "Format terraform (.tf) files";
+          description = "Format terraform (`.tf`) files.";
           entry = "${tools.terraform-fmt}/bin/terraform-fmt";
           files = "\\.tf$";
         };
       yamllint =
         {
           name = "yamllint";
-          description = "Yaml linter";
+          description = "Yaml linter.";
           types = [ "file" "yaml" ];
           entry = "${tools.yamllint}/bin/yamllint";
         };
@@ -469,7 +469,7 @@ in
       cargo-check =
         {
           name = "cargo-check";
-          description = "Check the cargo package for errors";
+          description = "Check the cargo package for errors.";
           entry = "${tools.cargo}/bin/cargo check";
           files = "\\.rs$";
           pass_filenames = false;
@@ -477,35 +477,35 @@ in
       purty =
         {
           name = "purty";
-          description = "Format purescript files";
+          description = "Format purescript files.";
           entry = "${tools.purty}/bin/purty";
           files = "\\.purs$";
         };
       purs-tidy =
         {
           name = "purs-tidy";
-          description = "Format purescript files";
+          description = "Format purescript files.";
           entry = "${tools.purs-tidy}/bin/purs-tidy format-in-place";
           files = "\\.purs$";
         };
       prettier =
         {
           name = "prettier";
-          description = "Opinionated multi-language code formatter";
+          description = "Opinionated multi-language code formatter.";
           entry = "${settings.prettier.binPath} --write --list-different --ignore-unknown";
           types = [ "text" ];
         };
       hunspell =
         {
           name = "hunspell";
-          description = "Spell checker and morphological analyzer";
+          description = "Spell checker and morphological analyzer.";
           entry = "${tools.hunspell}/bin/hunspell -l";
           files = "\\.((txt)|(html)|(xml)|(md)|(rst)|(tex)|(odf)|\\d)$";
         };
       html-tidy =
         {
           name = "html-tidy";
-          description = "HTML linter";
+          description = "HTML linter.";
           entry = "${tools.html-tidy}/bin/tidy -quiet -errors";
           files = "\\.html$";
         };
@@ -513,7 +513,7 @@ in
       eslint =
         {
           name = "eslint";
-          description = "Find and fix problems in your JavaScript code";
+          description = "Find and fix problems in your JavaScript code.";
           entry = "${settings.eslint.binPath} --fix";
           files = "${settings.eslint.extensions}";
         };
@@ -521,7 +521,7 @@ in
       hadolint =
         {
           name = "hadolint";
-          description = "Dockerfile linter, validate inline bash";
+          description = "Dockerfile linter, validate inline bash.";
           entry = "${tools.hadolint}/bin/hadolint";
           files = "Dockerfile$";
         };
@@ -529,7 +529,7 @@ in
       markdownlint =
         {
           name = "markdownlint";
-          description = "Style checker and linter for markdown files";
+          description = "Style checker and linter for markdown files.";
           entry = "${tools.markdownlint-cli}/bin/markdownlint";
           files = "\\.md$";
         };
@@ -537,7 +537,7 @@ in
       govet =
         {
           name = "govet";
-          description = "Checks correctness of Go programs";
+          description = "Checks correctness of Go programs.";
           entry =
             let
               # go vet requires package (directory) names as inputs.
@@ -560,7 +560,7 @@ in
       revive =
         {
           name = "revive";
-          description = "A linter for Go source code";
+          description = "A linter for Go source code.";
           entry =
             let
               cmdArgs =
diff --git a/modules/pre-commit.nix b/modules/pre-commit.nix
index b2dddd70..d4e6a20c 100644
--- a/modules/pre-commit.nix
+++ b/modules/pre-commit.nix
@@ -26,13 +26,13 @@ let
             enable =
               mkOption {
                 type = types.bool;
-                description = "Whether to enable this pre-commit hook.";
+                description = lib.mdDoc "Whether to enable this pre-commit hook.";
                 default = false;
               };
             raw =
               mkOption {
                 type = types.attrsOf types.unspecified;
-                description =
+                description = lib.mdDoc
                   ''
                     Raw fields of a pre-commit hook. This is mostly for internal use but
                     exposed in case you need to work around something.
@@ -45,7 +45,7 @@ let
                 type = types.str;
                 default = name;
                 defaultText = lib.literalDocBook or literalExample "internal name, same as id";
-                description =
+                description = lib.mdDoc
                   ''
                     The name of the hook - shown during hook execution.
                   '';
@@ -53,15 +53,15 @@ let
             entry =
               mkOption {
                 type = types.str;
-                description =
+                description = lib.mdDoc
                   ''
-                    The entry point - the executable to run. entry can also contain arguments that will not be overridden such as entry: autopep8 -i.
+                    The entry point - the executable to run. {option}`entry` can also contain arguments that will not be overridden, such as `entry = "autopep8 -i";`.
                   '';
               };
             language =
               mkOption {
                 type = types.str;
-                description =
+                description = lib.mdDoc
                   ''
                     The language of the hook - tells pre-commit how to install the hook.
                   '';
@@ -70,7 +70,7 @@ let
             files =
               mkOption {
                 type = types.str;
-                description =
+                description = lib.mdDoc
                   ''
                     The pattern of files to run on.
                   '';
@@ -79,16 +79,16 @@ let
             types =
               mkOption {
                 type = types.listOf types.str;
-                description =
+                description = lib.mdDoc
                   ''
-                    List of file types to run on. See Filtering files with types (https://pre-commit.com/#plugins).
+                    List of file types to run on. See [Filtering files with types](https://pre-commit.com/#plugins).
                   '';
                 default = [ "file" ];
               };
             types_or =
               mkOption {
                 type = types.listOf types.str;
-                description =
+                description = lib.mdDoc
                   ''
                     List of file types to run on, where only a single type needs to match.
                   '';
@@ -97,7 +97,7 @@ let
             description =
               mkOption {
                 type = types.str;
-                description =
+                description = lib.mdDoc
                   ''
                     Description of the hook. used for metadata purposes only.
                   '';
@@ -106,7 +106,7 @@ let
             excludes =
               mkOption {
                 type = types.listOf types.str;
-                description =
+                description = lib.mdDoc
                   ''
                     Exclude files that were matched by these patterns.
                   '';
@@ -115,13 +115,17 @@ let
             pass_filenames =
               mkOption {
                 type = types.bool;
-                description = "Whether to pass filenames as arguments to the entry point.";
+                description = lib.mdDoc ''
+                  Whether to pass filenames as arguments to the entry point.
+                '';
                 default = true;
               };
             stages =
               mkOption {
                 type = types.listOf types.str;
-                description = "Confines the hook to run at a particular stage.";
+                description = lib.mdDoc ''
+                  Confines the hook to run at a particular stage.
+                '';
                 default = cfg.default_stages;
                 defaultText = (lib.literalExpression or lib.literalExample) "default_stages";
               };
@@ -197,9 +201,9 @@ in
       package =
         mkOption {
           type = types.package;
-          description =
+          description = lib.mdDoc
             ''
-              The pre-commit package to use.
+              The `pre-commit` package to use.
             '';
           defaultText =
             lib.literalExpression or literalExample ''
@@ -210,11 +214,11 @@ in
       tools =
         mkOption {
           type = types.lazyAttrsOf types.package;
-          description =
+          description = lib.mdDoc
             ''
-              Tool set from which nix-pre-commit will pick binaries.
+              Tool set from which `nix-pre-commit-hooks` will pick binaries.
 
-              nix-pre-commit comes with its own set of packages for this purpose.
+              `nix-pre-commit-hooks` comes with its own set of packages for this purpose.
             '';
           defaultText =
             lib.literalExpression or literalExample ''pre-commit-hooks.nix-pkgs.callPackage tools-dot-nix { inherit (pkgs) system; }'';
@@ -223,9 +227,31 @@ in
       hooks =
         mkOption {
           type = types.attrsOf hookType;
-          description =
+          description = lib.mdDoc
             ''
               The hook definitions.
+
+              Pre-defined hooks can be enabled by, for example:
+
+              ```nix
+              hooks.nixpkgs-fmt.enable = true;
+              ```
+
+              The pre-defined hooks are:
+
+              ${
+                lib.concatStringsSep
+                  "\n" 
+                  (lib.mapAttrsToList
+                    (hookName: hookConf:
+                      ''
+                        **`${hookName}`**
+
+                        ${hookConf.description}
+
+                      '')
+                    config.hooks)
+              }
             '';
           default = { };
         };
@@ -233,7 +259,7 @@ in
       run =
         mkOption {
           type = types.package;
-          description =
+          description = lib.mdDoc
             ''
               A derivation that tests whether the pre-commit hooks run cleanly on
               the entire project.
@@ -246,18 +272,21 @@ in
       installationScript =
         mkOption {
           type = types.str;
-          description =
+          description = lib.mdDoc
             ''
-              A bash snippet that installs nix-pre-commit in the current directory
+              A bash snippet that installs nix-pre-commit-hooks in the current directory
             '';
           readOnly = true;
         };
 
       src =
         lib.mkOption {
-          description = ''
-            Root of the project. By default this will be filtered with the gitignoreSource
-            function later, unless rootSrc is specified.
+          description = lib.mdDoc ''
+            Root of the project. By default this will be filtered with the `gitignoreSource`
+            function later, unless `rootSrc` is specified.
+
+            If you use the `flakeModule`, the default is `self.outPath`; the whole flake
+            sources.
           '';
           type = lib.types.path;
         };
@@ -265,11 +294,14 @@ in
       rootSrc =
         mkOption {
           type = types.path;
-          description =
+          description = lib.mdDoc
             ''
               The source of the project to be checked.
 
               This is used in the derivation that performs the check.
+
+              If you use the `flakeModule`, the default is `self.outPath`; the whole flake
+              sources.
             '';
           defaultText = lib.literalExpression or literalExample ''gitignoreSource config.src'';
         };
@@ -277,7 +309,7 @@ in
       excludes =
         mkOption {
           type = types.listOf types.str;
-          description =
+          description = lib.mdDoc
             ''
               Exclude files that were matched by these patterns.
             '';
@@ -287,11 +319,11 @@ in
       default_stages =
         mkOption {
           type = types.listOf types.str;
-          description =
+          description = lib.mdDoc
             ''
               A configuration wide option for the stages property.
               Installs hooks to the defined stages.
-              See https://pre-commit.com/#confining-hooks-to-run-at-certain-stages
+              See [https://pre-commit.com/#confining-hooks-to-run-at-certain-stages](https://pre-commit.com/#confining-hooks-to-run-at-certain-stages).
             '';
           default = [ "commit" ];
         };
@@ -299,7 +331,7 @@ in
       rawConfig =
         mkOption {
           type = types.attrs;
-          description =
+          description = lib.mdDoc
             ''
               The raw configuration before writing to file.