treewide: attempt at markdown option docs

2 files changed, 17 insertions, 1 deletions

diff --git a/lib/default.nix b/lib/default.nix
index a0d3339ef08e..070c2a67cf07 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -131,7 +131,8 @@ let
       getValues getFiles
       optionAttrSetToDocList optionAttrSetToDocList'
       scrubOptionValue literalExpression literalExample literalDocBook
-      showOption showFiles unknownModule mkOption mkPackageOption;
+      showOption showFiles unknownModule mkOption mkPackageOption
+      mdDoc literalMD;
     inherit (self.types) isType setType defaultTypeMerge defaultFunctor
       isOptionType mkOptionType;
     inherit (self.asserts)
diff --git a/lib/options.nix b/lib/options.nix
index 8d82a809083b..50b19e483736 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -280,6 +280,21 @@ rec {
     if ! isString text then throw "literalDocBook expects a string."
     else { _type = "literalDocBook"; inherit text; };
 
+  /* Transition marker for documentation that's already migrated to markdown
+     syntax.
+  */
+  mdDoc = text:
+    if ! isString text then throw "mdDoc expects a string."
+    else { _type = "mdDoc"; inherit text; };
+
+  /* For use in the `defaultText` and `example` option attributes. Causes the
+     given MD text to be inserted verbatim in the documentation, for when
+     a `literalExpression` would be too hard to read.
+  */
+  literalMD = text:
+    if ! isString text then throw "literalMD expects a string."
+    else { _type = "literalMD"; inherit text; };
+
   # Helper functions.
 
   /* Convert an option, described as a list of the option parts in to a