diff --git a/dev/flake.lock b/dev/flake.lock
index 2681688..60bc8b0 100644
--- a/dev/flake.lock
+++ b/dev/flake.lock
@@ -97,11 +97,11 @@
         "nixpkgs": "nixpkgs_2"
       },
       "locked": {
-        "lastModified": 1668065367,
-        "narHash": "sha256-v8LdAfDSzxRS4BS+qZvorRGC8nXhN9xMJevu/hf+Gt0=",
+        "lastModified": 1668147980,
+        "narHash": "sha256-dHu5VIGQvZoHtqr5tmndpiVVk5JnJ/6wZUNRwEfvIxk=",
         "owner": "hercules-ci",
         "repo": "hercules-ci-effects",
-        "rev": "692309d1cbb24847cc2b0a345ec9f0fe9481a7db",
+        "rev": "244595b8dcfea8c6ac52a99157653162d26ea6d3",
         "type": "github"
       },
       "original": {
@@ -183,16 +183,16 @@
     },
     "nixpkgs_3": {
       "locked": {
-        "lastModified": 1667991831,
-        "narHash": "sha256-DHgEsLZI044B9T4AjA3K6+yB9/DqLr4dyA7OIx0FG7o=",
-        "owner": "NixOS",
+        "lastModified": 1668145650,
+        "narHash": "sha256-RJsYVz7j6HhXQtcFQJz9bZsgwFG8MblmOt8A4iD1AlY=",
+        "owner": "hercules-ci",
         "repo": "nixpkgs",
-        "rev": "872fceeed60ae6b7766cc0a4cd5bf5901b9098ec",
+        "rev": "b106ff14ede4034f8771025f8ac785144358f3cd",
         "type": "github"
       },
       "original": {
-        "owner": "NixOS",
-        "ref": "nixos-unstable",
+        "owner": "hercules-ci",
+        "ref": "options-markdown-and-errors",
         "repo": "nixpkgs",
         "type": "github"
       }
diff --git a/dev/flake.nix b/dev/flake.nix
index 6042561..3344f42 100644
--- a/dev/flake.nix
+++ b/dev/flake.nix
@@ -6,7 +6,7 @@
     # As a consequence, this flake is a little non-standard, and
     # we can't use the `nix` CLI as expected.
 
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    nixpkgs.url = "github:hercules-ci/nixpkgs/options-markdown-and-errors";
 
     pre-commit-hooks-nix.url = "github:cachix/pre-commit-hooks.nix";
     pre-commit-hooks-nix.inputs.nixpkgs.follows = "nixpkgs";
diff --git a/modules/apps.nix b/modules/apps.nix
index a3f8219..f763700 100644
--- a/modules/apps.nix
+++ b/modules/apps.nix
@@ -27,14 +27,14 @@ let
       type = mkOption {
         type = lib.types.enum [ "app" ];
         default = "app";
-        description = ''
-          A type tag for <literal>apps</literal> consumers.
+        description = lib.mdDoc ''
+          A type tag for `apps` consumers.
         '';
       };
       program = mkOption {
         type = programType;
-        description = ''
-          A path to an executable or a derivation with <literal>meta.mainProgram</literal>.
+        description = lib.mdDoc ''
+          A path to an executable or a derivation with `meta.mainProgram`.
         '';
       };
     };
@@ -46,7 +46,7 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf appType;
     default = { };
     description = ''
-      Programs runnable with nix run <literal>.#&lt;name></literal>.
+      Programs runnable with nix run `<name>`.
     '';
     example = lib.literalExpression or lib.literalExample ''
       {
diff --git a/modules/checks.nix b/modules/checks.nix
index 12dde09..d849c65 100644
--- a/modules/checks.nix
+++ b/modules/checks.nix
@@ -14,7 +14,7 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.package;
     default = { };
     description = ''
-      Derivations to be built by nix flake check.
+      Derivations to be built by [`nix flake check`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake-check.html).
     '';
   };
   file = ./checks.nix;
diff --git a/modules/darwinModules.nix b/modules/darwinModules.nix
index 0e3b017..3927c47 100644
--- a/modules/darwinModules.nix
+++ b/modules/darwinModules.nix
@@ -18,8 +18,8 @@ in
         type = types.lazyAttrsOf types.unspecified;
         default = { };
         apply = mapAttrs (k: v: { _file = "${toString self.outPath}/flake.nix#darwinModules.${k}"; imports = [ v ]; });
-        description = ''
-          Nix-darwin modules.
+        description = lib.mdDoc ''
+          [nix-darwin](https://daiderd.com/nix-darwin/) modules.
         '';
       };
     };
diff --git a/modules/devShells.nix b/modules/devShells.nix
index 7ebbeb6..6521fa8 100644
--- a/modules/devShells.nix
+++ b/modules/devShells.nix
@@ -14,8 +14,8 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.package;
     default = { };
     description = ''
-      An attribute set of packages to be built by <literal>nix develop .#&lt;name></literal>.
-      <literal>nix build .#&lt;name></literal> will run <literal>devShells.&lt;name></literal>.
+      An attribute set of packages to be used as shells.
+      [`nix develop .#<name>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.<name>`.
     '';
   };
   file = ./devShells.nix;
diff --git a/modules/flake.nix b/modules/flake.nix
index 3b8ed92..36382cc 100644
--- a/modules/flake.nix
+++ b/modules/flake.nix
@@ -16,8 +16,8 @@ in
           { freeformType = types.lazyAttrsOf types.raw; }
         ];
       };
-      description = ''
-        Raw flake attributes. Any attribute can be set here, but some
+      description = lib.mdDoc ''
+        Raw flake output attributes. Any attribute can be set here, but some
         attributes are represented by options, to provide appropriate
         configuration merging.
       '';
diff --git a/modules/formatter.nix b/modules/formatter.nix
index d5b0435..b6098db 100644
--- a/modules/formatter.nix
+++ b/modules/formatter.nix
@@ -14,7 +14,7 @@ mkTransposedPerSystemModule {
     type = types.nullOr types.package;
     default = null;
     description = ''
-      A package used by <literal>nix fmt</literal>.
+      A package used by [`nix fmt`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-fmt.html).
     '';
   };
   file = ./formatter.nix;
diff --git a/modules/legacyPackages.nix b/modules/legacyPackages.nix
index f07ab16..36df4dd 100644
--- a/modules/legacyPackages.nix
+++ b/modules/legacyPackages.nix
@@ -14,7 +14,7 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.raw;
     default = { };
     description = ''
-      An attribute set of unmergeable values. This is also used by <literal>nix build .#&lt;attrpath></literal>.
+      An attribute set of unmergeable values. This is also used by [`nix build .#<attrpath>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
     '';
   };
   file = ./legacyPackages.nix;
diff --git a/modules/nixosConfigurations.nix b/modules/nixosConfigurations.nix
index f62e4b4..01dea7f 100644
--- a/modules/nixosConfigurations.nix
+++ b/modules/nixosConfigurations.nix
@@ -15,8 +15,8 @@ in
       nixosConfigurations = mkOption {
         type = types.lazyAttrsOf types.raw;
         default = { };
-        description = ''
-          Instantiated NixOS configurations.
+        description = lib.mdDoc ''
+          Instantiated NixOS configurations. Used by `nixos-rebuild`.
         '';
         example = literalExpression ''
           {
@@ -24,6 +24,7 @@ in
               system = "x86_64-linux";
               modules = [
                 ./my-machine/nixos-configuration.nix
+                config.nixosModules.my-module
               ];
             };
           }
diff --git a/modules/nixosModules.nix b/modules/nixosModules.nix
index bbd1afd..f5ca608 100644
--- a/modules/nixosModules.nix
+++ b/modules/nixosModules.nix
@@ -18,8 +18,10 @@ in
         type = types.lazyAttrsOf types.unspecified;
         default = { };
         apply = mapAttrs (k: v: { _file = "${toString self.outPath}/flake.nix#nixosModules.${k}"; imports = [ v ]; });
-        description = ''
+        description = lib.mdDoc ''
           NixOS modules.
+
+          You may use this for reusable pieces of configuration, service modules, etc.
         '';
       };
     };
diff --git a/modules/overlays.nix b/modules/overlays.nix
index 9363c82..eef0616 100644
--- a/modules/overlays.nix
+++ b/modules/overlays.nix
@@ -23,13 +23,13 @@ in
             default = final: prev: {};
           }
         '';
-        description = ''
-          An attribute set of overlays.
+        description = lib.mdDoc ''
+          An attribute set of [overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays).
 
           Note that the overlays themselves are not mergeable. While overlays
           can be composed, the order of composition is significant, but the
           module system does not guarantee sufficiently deterministic
-          definition ordering, across versions and when changing <literal>imports</literal>.
+          definition ordering, across versions and when changing `imports`.
         '';
       };
     };
diff --git a/modules/packages.nix b/modules/packages.nix
index a6a22c5..dcb29eb 100644
--- a/modules/packages.nix
+++ b/modules/packages.nix
@@ -14,8 +14,9 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.package;
     default = { };
     description = ''
-      An attribute set of packages to be built by <literal>nix build .#&lt;name></literal>.
-      <literal>nix build .#&lt;name></literal> will build <literal>packages.&lt;name></literal>.
+      An attribute set of packages to be built by [`nix build`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
+
+      `nix build .#<name>` will build `packages.<name>`.
     '';
   };
   file = ./packages.nix;
diff --git a/modules/perSystem.nix b/modules/perSystem.nix
index 1e9be2c..2b19b28 100644
--- a/modules/perSystem.nix
+++ b/modules/perSystem.nix
@@ -16,17 +16,21 @@ in
 {
   options = {
     systems = mkOption {
-      description = "All the system types to enumerate in the flake.";
+      description = lib.mdDoc ''
+        All the system types to enumerate in the flake output subattributes.
+
+        In other words, all valid values for `system` in e.g. `packages.<system>.foo`.
+      '';
       type = types.listOf types.str;
     };
 
     perInput = mkOption {
-      description = "Function from system to function from flake to <literal>system</literal>-specific attributes.";
+      description = lib.mdDoc "Function from system to function from flake to `system`-specific attributes.";
       type = types.functionTo (types.functionTo (types.lazyAttrsOf types.unspecified));
     };
 
     perSystem = mkOption {
-      description = "A function from system to flake-like attributes omitting the <literal>&lt;system></literal> attribute.";
+      description = lib.mdDoc "A function from system to flake-like attributes omitting the `<system>` attribute.";
       type = mkPerSystemType ({ config, system, ... }: {
         _file = ./perSystem.nix;
         config = {
@@ -46,7 +50,7 @@ in
 
     allSystems = mkOption {
       type = types.lazyAttrsOf types.unspecified;
-      description = "The system-specific config for each of systems.";
+      description = lib.mdDoc "The system-specific config for each of systems.";
       internal = true;
     };
   };
diff --git a/modules/transposition.nix b/modules/transposition.nix
index aec1563..8e56d59 100644
--- a/modules/transposition.nix
+++ b/modules/transposition.nix
@@ -17,12 +17,12 @@ let
       adHoc = mkOption {
         type = types.bool;
         default = false;
-        description = ''
-          Whether to provide a stub option declaration for <option>perSystem.&lt;name></option>
+        description = lib.mdDoc ''
+          Whether to provide a stub option declaration for {option}`perSystem.<name>`.
 
           The stub option declaration does not support merging and lacks
-          documentation, so you are recommended to declare the <option>perSystem.&lt;name></option>
-          option yourself and avoid <option>adHoc</option>.
+          documentation, so you are recommended to declare the {option}`perSystem.<name>`
+          option yourself and avoid {option}`adHoc`.
         '';
       };
     };
@@ -32,18 +32,18 @@ in
 {
   options = {
     transposition = lib.mkOption {
-      description = ''
+      description = lib.mdDoc ''
         A helper that defines transposed attributes in the flake outputs.
 
         Transposition is the operation that swaps the indices of a data structure.
         Here it refers specifically to the transposition between
 
-        <literal>
-          perSystem: .''${system}.''${attribute}
-          outputs:   .''${attribute}.''${system}
-        </literal>
+        ```plain
+        perSystem: .''${system}.''${attribute}
+        outputs:   .''${attribute}.''${system}
+        ```
 
-        It also defines the reverse operation in <option>perInput</option>.
+        It also defines the reverse operation in [{option}`perInput`](#opt-perInput).
       '';
       type =
         types.lazyAttrsOf
diff --git a/site/flake-module.nix b/site/flake-module.nix
index 38312f0..617ccd8 100644
--- a/site/flake-module.nix
+++ b/site/flake-module.nix
@@ -16,15 +16,16 @@
         let sourcePathStr = toString sourcePath;
         in
         opt:
-        let declarations = concatMap
-          (decl:
-            if hasPrefix sourcePathStr (toString decl)
-            then
-              let subpath = removePrefix sourcePathStr (toString decl);
-              in [{ url = baseUrl + subpath; name = sourceName + subpath; }]
-            else [ ]
-          )
-          opt.declarations;
+        let
+          declarations = concatMap
+            (decl:
+              if hasPrefix sourcePathStr (toString decl)
+              then
+                let subpath = removePrefix sourcePathStr (toString decl);
+                in [{ url = baseUrl + subpath; name = sourceName + subpath; }]
+              else [ ]
+            )
+            opt.declarations;
         in
         if declarations == [ ]
         then opt // { visible = false; }
@@ -39,6 +40,8 @@
             transformOptions = filterTransformOptions {
               inherit sourceName baseUrl sourcePath;
             };
+            warningsAreErrors = true; # not sure if feasible long term
+            markdownByDefault = true;
           }).optionsDocBook;
           inherit title;
         } ''