From 7c7abab0c482a25e5edb4618602f6519b98f638e Mon Sep 17 00:00:00 2001
From: Luke Bailey <baileylu@tcd.ie>
Date: Sun, 7 Dec 2025 15:31:49 +0000
Subject: [PATCH 1/3] nixos-render-docs: tag `literalExpression` code blocks
 with `nix` correctly

---
 .../ni/nixos-render-docs/src/nixos_render_docs/options.py       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/options.py b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/options.py
index 75fbeadce1d0..9e337e6b1082 100644
--- a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/options.py
+++ b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/options.py
@@ -97,7 +97,7 @@ class BaseConverter(Converter[md.TR], Generic[md.TR]):
         if lit := option_is(option, key, 'literalMD'):
             return [ self._render(f"*{key.capitalize()}:*\n{lit['text']}") ]
         elif lit := option_is(option, key, 'literalExpression'):
-            code = md_make_code(lit['text'])
+            code = md_make_code(lit['text'], info="nix")
             return [ self._render(f"*{key.capitalize()}:*\n{code}") ]
         elif key in option:
             raise Exception(f"{key} has unrecognized type", option[key])

From 4d2e351d55c47863fd4fadafb46f63a56472faaf Mon Sep 17 00:00:00 2001
From: Luke Bailey <baileylu@tcd.ie>
Date: Sun, 7 Dec 2025 15:43:03 +0000
Subject: [PATCH 2/3] lib.literalExpression: add example and properly describe
 function arg

---
 lib/options.nix | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/lib/options.nix b/lib/options.nix
index a36fc2220d21..42f451bd8674 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -672,11 +672,30 @@ rec {
     is necessary for complex values, e.g. functions, or values that depend on
     other values or packages.
 
+    # Examples
+    :::{.example}
+    ## `literalExpression` usage example
+
+    ```nix
+    llvmPackages = mkOption {
+      type = types.str;
+      description = ''
+        Version of llvm packages to use for
+        this module
+      '';
+      example = literalExpression ''
+        llvmPackages = pkgs.llvmPackages_20;
+      '';
+    };
+    ```
+
+    :::
+
     # Inputs
 
     `text`
 
-    : 1\. Function argument
+    : The text to render as a Nix expression
   */
   literalExpression =
     text:

From 56cee4ffd37062d7598c36d064287ba86b2facd1 Mon Sep 17 00:00:00 2001
From: Luke Bailey <baileylu@tcd.ie>
Date: Sun, 7 Dec 2025 15:43:18 +0000
Subject: [PATCH 3/3] lib.literalCode: init

---
 lib/options.nix | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/lib/options.nix b/lib/options.nix
index 42f451bd8674..e6b51fb0603e 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -707,6 +707,49 @@ rec {
         inherit text;
       };
 
+  /**
+    For use in the `defaultText` and `example` option attributes. Causes the
+    given string to be rendered verbatim in the documentation as a code
+    block with the language bassed on the provided input tag.
+
+    If you wish to render Nix code, please see `literalExpression`.
+
+    # Examples
+    :::{.example}
+    ## `literalCode` usage example
+
+    ```nix
+    myPythonScript = mkOption {
+      type = types.str;
+      description = ''
+        Example python script used by a module
+      '';
+      example = literalCode "python" ''
+        print("Hello world!")
+      '';
+    };
+    ```
+
+    :::
+
+    # Inputs
+
+    `languageTag`
+
+    : The language tag to use when producing the code block (i.e. `js`, `rs`, etc).
+
+    `text`
+
+    : The text to render as a Nix expression
+  */
+  literalCode =
+    languageTag: text:
+    lib.literalMD ''
+      ```${languageTag}
+      ${text}
+      ```
+    '';
+
   /**
     For use in the `defaultText` and `example` option attributes. Causes the
     given MD text to be inserted verbatim in the documentation, for when