From 0ba1ca2c4567f44ec6ac8ee24f886b34f6c4e1bf Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Thu, 22 Jun 2023 18:41:26 +0200
Subject: [PATCH 1/6] fix pattern argument output

the prior version with more ad-hoc indenting produced extraneous
newlines, breaking deflists in the process. textwrap is a much better
solution to indentation, and it composes more easily too.
---
 Cargo.lock                                | 117 +++++++++++++++++++++-
 Cargo.toml                                |   1 +
 src/commonmark.rs                         |  35 +++----
 src/main.rs                               |  18 ++++
 src/snapshots/nixdoc__arg_formatting.snap |  25 +++++
 test/arg-formatting.nix                   |  14 +++
 6 files changed, 184 insertions(+), 26 deletions(-)
 create mode 100644 src/snapshots/nixdoc__arg_formatting.snap
 create mode 100644 test/arg-formatting.nix

diff --git a/Cargo.lock b/Cargo.lock
index 1f47537..1f17177 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2,6 +2,26 @@
 # It is not intended for manual editing.
 version = 3
 
+[[package]]
+name = "ahash"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fcb51a0695d8f838b1ee009b3fbf66bda078cd64590202a864a8f3e8c4315c47"
+dependencies = [
+ "getrandom",
+ "once_cell",
+ "version_check",
+]
+
+[[package]]
+name = "aho-corasick"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43f6cb1bf222025340178f382c426f13757b2960e89779dfcb319c32542a5a41"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "ansi_term"
 version = "0.11.0"
@@ -35,7 +55,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "89a47830402e9981c5c41223151efcced65a0510c13097c769cede7efb34782a"
 dependencies = [
  "backtrace-sys",
- "cfg-if",
+ "cfg-if 0.1.6",
  "libc",
  "rustc-demangle",
  "winapi",
@@ -69,6 +89,12 @@ version = "0.1.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "082bb9b28e00d3c9d39cc03e64ce4cea0f1bb9b3fde493f0cbc008472d22bdf4"
 
+[[package]]
+name = "cfg-if"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
+
 [[package]]
 name = "clap"
 version = "2.32.0"
@@ -79,7 +105,7 @@ dependencies = [
  "atty",
  "bitflags",
  "strsim",
- "textwrap",
+ "textwrap 0.10.0",
  "unicode-width",
  "vec_map",
 ]
@@ -130,11 +156,25 @@ dependencies = [
  "synstructure",
 ]
 
+[[package]]
+name = "getrandom"
+version = "0.2.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be4136b2a15dd319360be1c07d9933517ccf0be8f16bf62a3bee4f0d618df427"
+dependencies = [
+ "cfg-if 1.0.0",
+ "libc",
+ "wasi",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.12.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
+dependencies = [
+ "ahash",
+]
 
 [[package]]
 name = "insta"
@@ -167,6 +207,12 @@ version = "0.5.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0717cef1bc8b636c6e1c1bbdefc09e6322da8a9321966e8928ef80d20f7f770f"
 
+[[package]]
+name = "memchr"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2dffe52ecf27772e601905b7522cb4ef790d2cc203488bbd0e2fe85fcb74566d"
+
 [[package]]
 name = "memoffset"
 version = "0.8.0"
@@ -185,9 +231,16 @@ dependencies = [
  "rnix",
  "rowan",
  "structopt",
+ "textwrap 0.16.0",
  "xml-rs",
 ]
 
+[[package]]
+name = "once_cell"
+version = "1.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd8b5dd2ae5ed71462c540258bedcb51965123ad7e7ccf4b9a8cafaa4a63576d"
+
 [[package]]
 name = "proc-macro2"
 version = "0.4.20"
@@ -221,6 +274,23 @@ dependencies = [
  "redox_syscall",
 ]
 
+[[package]]
+name = "regex"
+version = "1.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0ab3ca65655bb1e41f2a8c8cd662eb4fb035e67c3f78da1d61dffe89d07300f"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "436b050e76ed2903236f032a59761c1eb99e1b0aead2c257922771dab1fc8c78"
+
 [[package]]
 name = "rnix"
 version = "0.11.0"
@@ -261,6 +331,12 @@ version = "2.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "420acb44afdae038210c99e69aae24109f32f15500aa708e81d46c9f29d55fcf"
 
+[[package]]
+name = "smawk"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f67ad224767faa3c7d8b6d91985b78e70a1324408abcb1cfcc2be4c06bc06043"
+
 [[package]]
 name = "strsim"
 version = "0.7.0"
@@ -337,11 +413,32 @@ dependencies = [
  "unicode-width",
 ]
 
+[[package]]
+name = "textwrap"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "222a222a5bfe1bba4a77b45ec488a741b3cb8872e5e499451fd7d0129c9c7c3d"
+dependencies = [
+ "smawk",
+ "unicode-linebreak",
+ "unicode-width",
+]
+
+[[package]]
+name = "unicode-linebreak"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c5faade31a542b8b35855fff6e8def199853b2da8da256da52f52f1316ee3137"
+dependencies = [
+ "hashbrown",
+ "regex",
+]
+
 [[package]]
 name = "unicode-width"
-version = "0.1.5"
+version = "0.1.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "882386231c45df4700b275c7ff55b6f3698780a650026380e72dabe76fa46526"
+checksum = "c0edd1e5b14653f783770bce4a4dabb4a5108a5370a5f5d8cfe8710c361f6c8b"
 
 [[package]]
 name = "unicode-xid"
@@ -355,6 +452,18 @@ version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "05c78687fb1a80548ae3250346c3db86a80a7cdd77bda190189f2d0a0987c81a"
 
+[[package]]
+name = "version_check"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "49874b5167b65d7193b8aba1567f5c7d93d001cafc34600cee003eda787e483f"
+
+[[package]]
+name = "wasi"
+version = "0.11.0+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423"
+
 [[package]]
 name = "winapi"
 version = "0.3.6"
diff --git a/Cargo.toml b/Cargo.toml
index e8f04ed..6fa83c4 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -9,6 +9,7 @@ structopt = "0.2"
 failure = "0.1"
 rnix = "0.11"
 rowan = "0.15.11"
+textwrap = "0.16"
 
 [dev-dependencies]
 insta = "1.29.0"
diff --git a/src/commonmark.rs b/src/commonmark.rs
index a9a4dc8..18fce70 100644
--- a/src/commonmark.rs
+++ b/src/commonmark.rs
@@ -17,7 +17,6 @@
 //! representing a single entry in the manual.
 
 use failure::Error;
-use std::iter::repeat;
 
 use std::io::Write;
 
@@ -40,43 +39,35 @@ pub enum Argument {
     Pattern(Vec<SingleArg>),
 }
 
-fn print_indented<W: Write>(writer: &mut W, indent: usize, text: &str) -> Result<(), Error> {
-    let prefix = repeat(' ').take(indent).collect::<String>();
-    writeln!(
-        writer,
-        "{}",
-        text.replace("\r\n", "\n")
-            .replace("\n", &format!("\n{prefix}"))
-    )?;
-
-    Ok(())
-}
-
 impl Argument {
     /// Write CommonMark structure for a single function argument.
-    fn write_argument<W: Write>(self, writer: &mut W, indent: usize) -> Result<(), Error> {
+    fn format_argument(self) -> String {
         match self {
             // Write a flat argument entry.
             Argument::Flat(arg) => {
-                let arg_text = format!(
+                format!(
                     "`{}`\n\n: {}\n\n",
                     arg.name,
                     arg.doc.unwrap_or("Function argument".into()).trim()
-                );
-                print_indented(writer, indent, &arg_text)?;
+                )
             }
 
             // Write a pattern argument entry and its individual
             // parameters as a nested structure.
             Argument::Pattern(pattern_args) => {
-                print_indented(writer, indent, "structured function argument\n\n: ")?;
+                let mut inner = String::new();
                 for pattern_arg in pattern_args {
-                    Argument::Flat(pattern_arg).write_argument(writer, indent + 2)?;
+                    inner += &Argument::Flat(pattern_arg).format_argument();
                 }
+
+                let indented = textwrap::indent(&inner, "  ");
+                // drop leading indentation, the `: ` serves this function already
+                format!(
+                    "structured function argument\n\n: {}",
+                    indented.trim_start()
+                )
             }
         }
-
-        Ok(())
     }
 }
 
@@ -130,7 +121,7 @@ impl ManualEntry {
         // Function argument names
         if !self.args.is_empty() {
             for arg in self.args {
-                arg.write_argument(writer, 0)?;
+                writeln!(writer, "{}", arg.format_argument())?;
             }
         }
 
diff --git a/src/main.rs b/src/main.rs
index df81bfd..176c201 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -311,3 +311,21 @@ fn test_main() {
 
     insta::assert_snapshot!(output);
 }
+
+#[test]
+fn test_arg_formatting() {
+    let mut output = Vec::new();
+    let src = fs::read_to_string("test/arg-formatting.nix").unwrap();
+    let nix = rnix::Root::parse(&src).ok().expect("failed to parse input");
+    let category = "options";
+
+    for entry in collect_entries(nix, category) {
+        entry
+            .write_section(&mut output)
+            .expect("Failed to write section")
+    }
+
+    let output = String::from_utf8(output).expect("not utf8");
+
+    insta::assert_snapshot!(output);
+}
diff --git a/src/snapshots/nixdoc__arg_formatting.snap b/src/snapshots/nixdoc__arg_formatting.snap
new file mode 100644
index 0000000..fc2e8ee
--- /dev/null
+++ b/src/snapshots/nixdoc__arg_formatting.snap
@@ -0,0 +1,25 @@
+---
+source: src/main.rs
+expression: output
+---
+## `lib.options.fn` {#function-library-lib.options.fn}
+
+documented function
+
+`a`
+
+: single arugment
+
+
+structured function argument
+
+: `default`
+
+  : documented argument
+
+  `example`
+
+  : i like this argument. another!
+
+
+
diff --git a/test/arg-formatting.nix b/test/arg-formatting.nix
new file mode 100644
index 0000000..1c3c337
--- /dev/null
+++ b/test/arg-formatting.nix
@@ -0,0 +1,14 @@
+{
+  /* documented function */
+  fn =
+    # single arugment
+    a:
+    # set argument
+    {
+      # documented argument
+      default ? null,
+      # i like this argument. another!
+      example ? null
+    } @ args:
+    0;
+}

From ec10a53f134bb350e12155b8d8bce207de25face Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Thu, 22 Jun 2023 02:09:54 +0200
Subject: [PATCH 2/6] mark function types as such more obviously

just dumping the type into the section is only helpful to those who know
the haskell type syntax that's often used here, but not always. mark the
types with a prominent header to communicate them better.
---
 src/commonmark.rs               |  2 +-
 src/snapshots/nixdoc__main.snap | 88 ++++++++++++++++-----------------
 2 files changed, 45 insertions(+), 45 deletions(-)

diff --git a/src/commonmark.rs b/src/commonmark.rs
index 18fce70..6968b6f 100644
--- a/src/commonmark.rs
+++ b/src/commonmark.rs
@@ -109,7 +109,7 @@ impl ManualEntry {
 
         // <subtitle> (type signature)
         if let Some(t) = &self.fn_type {
-            writeln!(writer, "`{}`\n", t)?;
+            writeln!(writer, "**Type**: `{}`\n", t)?;
         }
 
         // Primary doc string
diff --git a/src/snapshots/nixdoc__main.snap b/src/snapshots/nixdoc__main.snap
index 9a77b59..9d1db1e 100644
--- a/src/snapshots/nixdoc__main.snap
+++ b/src/snapshots/nixdoc__main.snap
@@ -6,7 +6,7 @@ expression: output
 
 ## `lib.strings.concatStrings` {#function-library-lib.strings.concatStrings}
 
-`concatStrings :: [string] -> string`
+**Type**: `concatStrings :: [string] -> string`
 
 Concatenate a list of strings.
 
@@ -19,7 +19,7 @@ concatStrings ["foo" "bar"]
 
 ## `lib.strings.concatMapStrings` {#function-library-lib.strings.concatMapStrings}
 
-`concatMapStrings :: (a -> string) -> [a] -> string`
+**Type**: `concatMapStrings :: (a -> string) -> [a] -> string`
 
 Map a function over a list and concatenate the resulting strings.
 
@@ -42,7 +42,7 @@ concatMapStrings (x: "a" + x) ["foo" "bar"]
 
 ## `lib.strings.concatImapStrings` {#function-library-lib.strings.concatImapStrings}
 
-`concatImapStrings :: (int -> a -> string) -> [a] -> string`
+**Type**: `concatImapStrings :: (int -> a -> string) -> [a] -> string`
 
 Like `concatMapStrings` except that the f functions also gets the
 position as a parameter.
@@ -66,7 +66,7 @@ concatImapStrings (pos: x: "${toString pos}-${x}") ["foo" "bar"]
 
 ## `lib.strings.intersperse` {#function-library-lib.strings.intersperse}
 
-`intersperse :: a -> [a] -> [a]`
+**Type**: `intersperse :: a -> [a] -> [a]`
 
 Place an element between each element of a list
 
@@ -89,7 +89,7 @@ intersperse "/" ["usr" "local" "bin"]
 
 ## `lib.strings.concatStringsSep` {#function-library-lib.strings.concatStringsSep}
 
-`concatStringsSep :: string -> [string] -> string`
+**Type**: `concatStringsSep :: string -> [string] -> string`
 
 Concatenate a list of strings with a separator between each element
 
@@ -102,7 +102,7 @@ concatStringsSep "/" ["usr" "local" "bin"]
 
 ## `lib.strings.concatMapStringsSep` {#function-library-lib.strings.concatMapStringsSep}
 
-`concatMapStringsSep :: string -> (a -> string) -> [a] -> string`
+**Type**: `concatMapStringsSep :: string -> (a -> string) -> [a] -> string`
 
 Maps a function over a list of strings and then concatenates the
 result with the specified separator interspersed between
@@ -132,7 +132,7 @@ concatMapStringsSep "-" (x: toUpper x)  ["foo" "bar" "baz"]
 
 ## `lib.strings.concatImapStringsSep` {#function-library-lib.strings.concatImapStringsSep}
 
-`concatIMapStringsSep :: string -> (int -> a -> string) -> [a] -> string`
+**Type**: `concatIMapStringsSep :: string -> (int -> a -> string) -> [a] -> string`
 
 Same as `concatMapStringsSep`, but the mapping function
 additionally receives the position of its argument.
@@ -161,7 +161,7 @@ concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ]
 
 ## `lib.strings.concatLines` {#function-library-lib.strings.concatLines}
 
-`concatLines :: [string] -> string`
+**Type**: `concatLines :: [string] -> string`
 
 Concatenate a list of strings, adding a newline at the end of each one.
 Defined as `concatMapStrings (s: s + "\n")`.
@@ -175,7 +175,7 @@ concatLines [ "foo" "bar" ]
 
 ## `lib.strings.makeSearchPath` {#function-library-lib.strings.makeSearchPath}
 
-`makeSearchPath :: string -> [string] -> string`
+**Type**: `makeSearchPath :: string -> [string] -> string`
 
 Construct a Unix-style, colon-separated search path consisting of
 the given `subDir` appended to each of the given paths.
@@ -201,7 +201,7 @@ makeSearchPath "bin" [""]
 
 ## `lib.strings.makeSearchPathOutput` {#function-library-lib.strings.makeSearchPathOutput}
 
-`string -> string -> [package] -> string`
+**Type**: `string -> string -> [package] -> string`
 
 Construct a Unix-style search path by appending the given
 `subDir` to the specified `output` of each of the packages. If no
@@ -259,7 +259,7 @@ makeBinPath ["/root" "/usr" "/usr/local"]
 
 ## `lib.strings.normalizePath` {#function-library-lib.strings.normalizePath}
 
-`normalizePath :: string -> string`
+**Type**: `normalizePath :: string -> string`
 
 Normalize path, removing extraneous /s
 
@@ -277,7 +277,7 @@ normalizePath "/a//b///c/"
 
 ## `lib.strings.optionalString` {#function-library-lib.strings.optionalString}
 
-`optionalString :: bool -> string -> string`
+**Type**: `optionalString :: bool -> string -> string`
 
 Depending on the boolean `cond', return either the given string
 or the empty string. Useful to concatenate against a bigger string.
@@ -303,7 +303,7 @@ optionalString false "some-string"
 
 ## `lib.strings.hasPrefix` {#function-library-lib.strings.hasPrefix}
 
-`hasPrefix :: string -> string -> bool`
+**Type**: `hasPrefix :: string -> string -> bool`
 
 Determine whether a string has given prefix.
 
@@ -328,7 +328,7 @@ hasPrefix "foo" "barfoo"
 
 ## `lib.strings.hasSuffix` {#function-library-lib.strings.hasSuffix}
 
-`hasSuffix :: string -> string -> bool`
+**Type**: `hasSuffix :: string -> string -> bool`
 
 Determine whether a string has given suffix.
 
@@ -353,7 +353,7 @@ hasSuffix "foo" "barfoo"
 
 ## `lib.strings.hasInfix` {#function-library-lib.strings.hasInfix}
 
-`hasInfix :: string -> string -> bool`
+**Type**: `hasInfix :: string -> string -> bool`
 
 Determine whether a string contains the given infix
 
@@ -382,7 +382,7 @@ hasInfix "foo" "abcd"
 
 ## `lib.strings.stringToCharacters` {#function-library-lib.strings.stringToCharacters}
 
-`stringToCharacters :: string -> [string]`
+**Type**: `stringToCharacters :: string -> [string]`
 
 Convert a string to a list of characters (i.e. singleton strings).
 This allows you to, e.g., map a function over each character.  However,
@@ -410,7 +410,7 @@ stringToCharacters "🦄"
 
 ## `lib.strings.stringAsChars` {#function-library-lib.strings.stringAsChars}
 
-`stringAsChars :: (string -> string) -> string -> string`
+**Type**: `stringAsChars :: (string -> string) -> string -> string`
 
 Manipulate a string character by character and replace them by
 strings before concatenating the results.
@@ -434,7 +434,7 @@ stringAsChars (x: if x == "a" then "i" else x) "nax"
 
 ## `lib.strings.charToInt` {#function-library-lib.strings.charToInt}
 
-`charToInt :: string -> int`
+**Type**: `charToInt :: string -> int`
 
 Convert char to ascii value, must be in printable range
 
@@ -454,7 +454,7 @@ charToInt "("
 
 ## `lib.strings.escape` {#function-library-lib.strings.escape}
 
-`escape :: [string] -> string -> string`
+**Type**: `escape :: [string] -> string -> string`
 
 Escape occurrence of the elements of `list` in `string` by
 prefixing it with a backslash.
@@ -473,7 +473,7 @@ escape ["(" ")"] "(foo)"
 
 ## `lib.strings.escapeC` {#function-library-lib.strings.escapeC}
 
-`escapeC = [string] -> string -> string`
+**Type**: `escapeC = [string] -> string -> string`
 
 Escape occurrence of the element of `list` in `string` by
 converting to its ASCII value and prefixing it with \\x.
@@ -493,7 +493,7 @@ escapeC [" "] "foo bar"
 
 ## `lib.strings.escapeURL` {#function-library-lib.strings.escapeURL}
 
-`escapeURL :: string -> string`
+**Type**: `escapeURL :: string -> string`
 
 Escape the string so it can be safely placed inside a URL
 query.
@@ -507,7 +507,7 @@ escapeURL "foo/bar baz"
 
 ## `lib.strings.escapeShellArg` {#function-library-lib.strings.escapeShellArg}
 
-`escapeShellArg :: string -> string`
+**Type**: `escapeShellArg :: string -> string`
 
 Quote string to be used safely within the Bourne shell.
 
@@ -525,7 +525,7 @@ escapeShellArg "esc'ape\nme"
 
 ## `lib.strings.escapeShellArgs` {#function-library-lib.strings.escapeShellArgs}
 
-`escapeShellArgs :: [string] -> string`
+**Type**: `escapeShellArgs :: [string] -> string`
 
 Quote all arguments to be safely passed to the Bourne shell.
 
@@ -538,7 +538,7 @@ escapeShellArgs ["one" "two three" "four'five"]
 
 ## `lib.strings.isValidPosixName` {#function-library-lib.strings.isValidPosixName}
 
-`string -> bool`
+**Type**: `string -> bool`
 
 Test whether the given name is a valid POSIX shell variable name.
 
@@ -558,7 +558,7 @@ isValidPosixName "0-bad.jpg"
 
 ## `lib.strings.toShellVar` {#function-library-lib.strings.toShellVar}
 
-`string -> (string | listOf string | attrsOf string) -> string`
+**Type**: `string -> (string | listOf string | attrsOf string) -> string`
 
 Translate a Nix value into a shell variable declaration, with proper escaping.
 
@@ -591,7 +591,7 @@ ${toShellVar "foo" "some string"}
 
 ## `lib.strings.toShellVars` {#function-library-lib.strings.toShellVars}
 
-`attrsOf (string | listOf string | attrsOf string) -> string`
+**Type**: `attrsOf (string | listOf string | attrsOf string) -> string`
 
 Translate an attribute set into corresponding shell variable declarations
 using `toShellVar`.
@@ -615,7 +615,7 @@ ${toShellVars { inherit foo bar; }}
 
 ## `lib.strings.escapeNixString` {#function-library-lib.strings.escapeNixString}
 
-`string -> string`
+**Type**: `string -> string`
 
 Turn a string into a Nix expression representing that string
 
@@ -633,7 +633,7 @@ escapeNixString "hello\${}\n"
 
 ## `lib.strings.escapeRegex` {#function-library-lib.strings.escapeRegex}
 
-`string -> string`
+**Type**: `string -> string`
 
 Turn a string into an exact regular expression
 
@@ -646,7 +646,7 @@ escapeRegex "[^a-z]*"
 
 ## `lib.strings.escapeNixIdentifier` {#function-library-lib.strings.escapeNixIdentifier}
 
-`string -> string`
+**Type**: `string -> string`
 
 Quotes a string if it can't be used as an identifier directly.
 
@@ -666,7 +666,7 @@ escapeNixIdentifier "0abc"
 
 ## `lib.strings.escapeXML` {#function-library-lib.strings.escapeXML}
 
-`string -> string`
+**Type**: `string -> string`
 
 Escapes a string such that it is safe to include verbatim in an XML
 document.
@@ -688,7 +688,7 @@ Case conversion utilities.
 
 ## `lib.strings.toLower` {#function-library-lib.strings.toLower}
 
-`toLower :: string -> string`
+**Type**: `toLower :: string -> string`
 
 Converts an ASCII string to lower-case.
 
@@ -701,7 +701,7 @@ toLower "HOME"
 
 ## `lib.strings.toUpper` {#function-library-lib.strings.toUpper}
 
-`toUpper :: string -> string`
+**Type**: `toUpper :: string -> string`
 
 Converts an ASCII string to upper-case.
 
@@ -766,7 +766,7 @@ splitString "/" "/usr/local/bin"
 
 ## `lib.strings.removePrefix` {#function-library-lib.strings.removePrefix}
 
-`string -> string -> string`
+**Type**: `string -> string -> string`
 
 Return a string without the specified prefix, if the prefix matches.
 
@@ -791,7 +791,7 @@ removePrefix "xxx" "foo.bar.baz"
 
 ## `lib.strings.removeSuffix` {#function-library-lib.strings.removeSuffix}
 
-`string -> string -> string`
+**Type**: `string -> string -> string`
 
 Return a string without the specified suffix, if the suffix matches.
 
@@ -928,7 +928,7 @@ nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2
 
 ## `lib.strings.mesonOption` {#function-library-lib.strings.mesonOption}
 
-`mesonOption :: string -> string -> string@param feature The feature to be set@param value The desired value`
+**Type**: `mesonOption :: string -> string -> string@param feature The feature to be set@param value The desired value`
 
 Create a -D<feature>=<value> string that can be passed to typical Meson
 invocations.
@@ -952,7 +952,7 @@ mesonOption "engine" "opengl"
 
 ## `lib.strings.mesonBool` {#function-library-lib.strings.mesonBool}
 
-`mesonBool :: string -> bool -> string@param condition The condition to be made true or false@param flag The controlling flag of the condition`
+**Type**: `mesonBool :: string -> bool -> string@param condition The condition to be made true or false@param flag The controlling flag of the condition`
 
 Create a -D<condition>={true,false} string that can be passed to typical
 Meson invocations.
@@ -978,7 +978,7 @@ mesonBool "static" false
 
 ## `lib.strings.mesonEnable` {#function-library-lib.strings.mesonEnable}
 
-`mesonEnable :: string -> bool -> string@param feature The feature to be enabled or disabled@param flag The controlling flag`
+**Type**: `mesonEnable :: string -> bool -> string@param feature The feature to be enabled or disabled@param flag The controlling flag`
 
 Create a -D<feature>={enabled,disabled} string that can be passed to
 typical Meson invocations.
@@ -1110,7 +1110,7 @@ withFeatureAs false "shared" (throw "ignored")
 
 ## `lib.strings.fixedWidthString` {#function-library-lib.strings.fixedWidthString}
 
-`fixedWidthString :: int -> string -> string -> string`
+**Type**: `fixedWidthString :: int -> string -> string -> string`
 
 Create a fixed width string with additional prefix to match
 required width.
@@ -1235,7 +1235,7 @@ isStorePath [] || isStorePath 42 || isStorePath {} || …
 
 ## `lib.strings.toInt` {#function-library-lib.strings.toInt}
 
-`string -> int`
+**Type**: `string -> int`
 
 Parse a string as an int. Does not support parsing of integers with preceding zero due to
 ambiguity between zero-padded and octal numbers. See toIntBase10.
@@ -1267,7 +1267,7 @@ toInt "3.14"
 
 ## `lib.strings.toIntBase10` {#function-library-lib.strings.toIntBase10}
 
-`string -> int`
+**Type**: `string -> int`
 
 Parse a string as a base 10 int. This supports parsing of zero-padded integers.
 
@@ -1317,7 +1317,7 @@ readPathsFromFile /prefix
 
 ## `lib.strings.fileContents` {#function-library-lib.strings.fileContents}
 
-`fileContents :: path -> string`
+**Type**: `fileContents :: path -> string`
 
 Read the contents of a file removing the trailing \n
 
@@ -1337,7 +1337,7 @@ fileContents ./version
 
 ## `lib.strings.sanitizeDerivationName` {#function-library-lib.strings.sanitizeDerivationName}
 
-`sanitizeDerivationName :: String -> String`
+**Type**: `sanitizeDerivationName :: String -> String`
 
 Creates a valid derivation name from a potentially invalid one.
 
@@ -1354,7 +1354,7 @@ sanitizeDerivationName pkgs.hello
 
 ## `lib.strings.levenshtein` {#function-library-lib.strings.levenshtein}
 
-`levenshtein :: string -> string -> int`
+**Type**: `levenshtein :: string -> string -> int`
 
 Computes the Levenshtein distance between two strings.
 Complexity O(n*m) where n and m are the lengths of the strings.
@@ -1411,7 +1411,7 @@ Returns the length of the suffix common to both strings.
 
 ## `lib.strings.levenshteinAtMost` {#function-library-lib.strings.levenshteinAtMost}
 
-`levenshteinAtMost :: int -> string -> string -> bool`
+**Type**: `levenshteinAtMost :: int -> string -> string -> bool`
 
 Returns whether the levenshtein distance between two strings is at most some value
 Complexity is O(min(n,m)) for k <= 2 and O(n*m) otherwise

From 1350b5fbc1bafd9994c73c5b4f231a3a62a2d771 Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Thu, 22 Jun 2023 00:27:46 +0200
Subject: [PATCH 3/6] use nixos-render-docs example blocks

examples as sections clutters the TOC and removes them from the list of
examples. example blocks are supported in nixpkgs markdown, with
semantics very similar to old docbook example tags.
---
 src/commonmark.rs               |   7 +-
 src/snapshots/nixdoc__main.snap | 245 ++++++++++++++++++++++++--------
 2 files changed, 187 insertions(+), 65 deletions(-)

diff --git a/src/commonmark.rs b/src/commonmark.rs
index 6968b6f..909c571 100644
--- a/src/commonmark.rs
+++ b/src/commonmark.rs
@@ -132,10 +132,11 @@ impl ManualEntry {
         if let Some(example) = &self.example {
             writeln!(
                 writer,
-                "### {} usage example {{#function-library-example-{}}}\n",
-                title, ident
+                "::: {{.example #function-library-example-{}}}",
+                ident
             )?;
-            writeln!(writer, "```nix{}```\n", example)?;
+            writeln!(writer, "# `{}` usage example\n", title)?;
+            writeln!(writer, "```nix\n{}\n```\n:::\n", example.trim())?;
         }
 
         // TODO: add source links
diff --git a/src/snapshots/nixdoc__main.snap b/src/snapshots/nixdoc__main.snap
index 9d1db1e..38e64d0 100644
--- a/src/snapshots/nixdoc__main.snap
+++ b/src/snapshots/nixdoc__main.snap
@@ -10,12 +10,14 @@ expression: output
 
 Concatenate a list of strings.
 
-### lib.strings.concatStrings usage example {#function-library-example-lib.strings.concatStrings}
+::: {.example #function-library-example-lib.strings.concatStrings}
+# `lib.strings.concatStrings` usage example
 
 ```nix
 concatStrings ["foo" "bar"]
 => "foobar"
 ```
+:::
 
 ## `lib.strings.concatMapStrings` {#function-library-lib.strings.concatMapStrings}
 
@@ -33,12 +35,14 @@ Map a function over a list and concatenate the resulting strings.
 : Function argument
 
 
-### lib.strings.concatMapStrings usage example {#function-library-example-lib.strings.concatMapStrings}
+::: {.example #function-library-example-lib.strings.concatMapStrings}
+# `lib.strings.concatMapStrings` usage example
 
 ```nix
 concatMapStrings (x: "a" + x) ["foo" "bar"]
 => "afooabar"
 ```
+:::
 
 ## `lib.strings.concatImapStrings` {#function-library-lib.strings.concatImapStrings}
 
@@ -57,12 +61,14 @@ position as a parameter.
 : Function argument
 
 
-### lib.strings.concatImapStrings usage example {#function-library-example-lib.strings.concatImapStrings}
+::: {.example #function-library-example-lib.strings.concatImapStrings}
+# `lib.strings.concatImapStrings` usage example
 
 ```nix
 concatImapStrings (pos: x: "${toString pos}-${x}") ["foo" "bar"]
 => "1-foo2-bar"
 ```
+:::
 
 ## `lib.strings.intersperse` {#function-library-lib.strings.intersperse}
 
@@ -80,12 +86,14 @@ Place an element between each element of a list
 : Input list
 
 
-### lib.strings.intersperse usage example {#function-library-example-lib.strings.intersperse}
+::: {.example #function-library-example-lib.strings.intersperse}
+# `lib.strings.intersperse` usage example
 
 ```nix
 intersperse "/" ["usr" "local" "bin"]
 => ["usr" "/" "local" "/" "bin"].
 ```
+:::
 
 ## `lib.strings.concatStringsSep` {#function-library-lib.strings.concatStringsSep}
 
@@ -93,12 +101,14 @@ intersperse "/" ["usr" "local" "bin"]
 
 Concatenate a list of strings with a separator between each element
 
-### lib.strings.concatStringsSep usage example {#function-library-example-lib.strings.concatStringsSep}
+::: {.example #function-library-example-lib.strings.concatStringsSep}
+# `lib.strings.concatStringsSep` usage example
 
 ```nix
 concatStringsSep "/" ["usr" "local" "bin"]
 => "usr/local/bin"
 ```
+:::
 
 ## `lib.strings.concatMapStringsSep` {#function-library-lib.strings.concatMapStringsSep}
 
@@ -123,12 +133,14 @@ elements.
 : List of input strings
 
 
-### lib.strings.concatMapStringsSep usage example {#function-library-example-lib.strings.concatMapStringsSep}
+::: {.example #function-library-example-lib.strings.concatMapStringsSep}
+# `lib.strings.concatMapStringsSep` usage example
 
 ```nix
 concatMapStringsSep "-" (x: toUpper x)  ["foo" "bar" "baz"]
 => "FOO-BAR-BAZ"
 ```
+:::
 
 ## `lib.strings.concatImapStringsSep` {#function-library-lib.strings.concatImapStringsSep}
 
@@ -152,12 +164,14 @@ additionally receives the position of its argument.
 : List of input strings
 
 
-### lib.strings.concatImapStringsSep usage example {#function-library-example-lib.strings.concatImapStringsSep}
+::: {.example #function-library-example-lib.strings.concatImapStringsSep}
+# `lib.strings.concatImapStringsSep` usage example
 
 ```nix
 concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ]
 => "6-3-2"
 ```
+:::
 
 ## `lib.strings.concatLines` {#function-library-lib.strings.concatLines}
 
@@ -166,12 +180,14 @@ concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ]
 Concatenate a list of strings, adding a newline at the end of each one.
 Defined as `concatMapStrings (s: s + "\n")`.
 
-### lib.strings.concatLines usage example {#function-library-example-lib.strings.concatLines}
+::: {.example #function-library-example-lib.strings.concatLines}
+# `lib.strings.concatLines` usage example
 
 ```nix
 concatLines [ "foo" "bar" ]
 => "foo\nbar\n"
 ```
+:::
 
 ## `lib.strings.makeSearchPath` {#function-library-lib.strings.makeSearchPath}
 
@@ -190,7 +206,8 @@ the given `subDir` appended to each of the given paths.
 : List of base paths
 
 
-### lib.strings.makeSearchPath usage example {#function-library-example-lib.strings.makeSearchPath}
+::: {.example #function-library-example-lib.strings.makeSearchPath}
+# `lib.strings.makeSearchPath` usage example
 
 ```nix
 makeSearchPath "bin" ["/root" "/usr" "/usr/local"]
@@ -198,6 +215,7 @@ makeSearchPath "bin" ["/root" "/usr" "/usr/local"]
 makeSearchPath "bin" [""]
 => "/bin"
 ```
+:::
 
 ## `lib.strings.makeSearchPathOutput` {#function-library-lib.strings.makeSearchPathOutput}
 
@@ -223,19 +241,22 @@ the default.
 : List of packages
 
 
-### lib.strings.makeSearchPathOutput usage example {#function-library-example-lib.strings.makeSearchPathOutput}
+::: {.example #function-library-example-lib.strings.makeSearchPathOutput}
+# `lib.strings.makeSearchPathOutput` usage example
 
 ```nix
 makeSearchPathOutput "dev" "bin" [ pkgs.openssl pkgs.zlib ]
 => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev/bin:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/bin"
 ```
+:::
 
 ## `lib.strings.makeLibraryPath` {#function-library-lib.strings.makeLibraryPath}
 
 Construct a library search path (such as RPATH) containing the
 libraries for a set of packages
 
-### lib.strings.makeLibraryPath usage example {#function-library-example-lib.strings.makeLibraryPath}
+::: {.example #function-library-example-lib.strings.makeLibraryPath}
+# `lib.strings.makeLibraryPath` usage example
 
 ```nix
 makeLibraryPath [ "/usr" "/usr/local" ]
@@ -244,18 +265,21 @@ pkgs = import <nixpkgs> { }
 makeLibraryPath [ pkgs.openssl pkgs.zlib ]
 => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r/lib:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/lib"
 ```
+:::
 
 ## `lib.strings.makeBinPath` {#function-library-lib.strings.makeBinPath}
 
 Construct a binary search path (such as $PATH) containing the
 binaries for a set of packages.
 
-### lib.strings.makeBinPath usage example {#function-library-example-lib.strings.makeBinPath}
+::: {.example #function-library-example-lib.strings.makeBinPath}
+# `lib.strings.makeBinPath` usage example
 
 ```nix
 makeBinPath ["/root" "/usr" "/usr/local"]
 => "/root/bin:/usr/bin:/usr/local/bin"
 ```
+:::
 
 ## `lib.strings.normalizePath` {#function-library-lib.strings.normalizePath}
 
@@ -268,12 +292,14 @@ Normalize path, removing extraneous /s
 : Function argument
 
 
-### lib.strings.normalizePath usage example {#function-library-example-lib.strings.normalizePath}
+::: {.example #function-library-example-lib.strings.normalizePath}
+# `lib.strings.normalizePath` usage example
 
 ```nix
 normalizePath "/a//b///c/"
 => "/a/b/c/"
 ```
+:::
 
 ## `lib.strings.optionalString` {#function-library-lib.strings.optionalString}
 
@@ -292,7 +318,8 @@ or the empty string. Useful to concatenate against a bigger string.
 : String to return if condition is true
 
 
-### lib.strings.optionalString usage example {#function-library-example-lib.strings.optionalString}
+::: {.example #function-library-example-lib.strings.optionalString}
+# `lib.strings.optionalString` usage example
 
 ```nix
 optionalString true "some-string"
@@ -300,6 +327,7 @@ optionalString true "some-string"
 optionalString false "some-string"
 => ""
 ```
+:::
 
 ## `lib.strings.hasPrefix` {#function-library-lib.strings.hasPrefix}
 
@@ -317,7 +345,8 @@ Determine whether a string has given prefix.
 : Input string
 
 
-### lib.strings.hasPrefix usage example {#function-library-example-lib.strings.hasPrefix}
+::: {.example #function-library-example-lib.strings.hasPrefix}
+# `lib.strings.hasPrefix` usage example
 
 ```nix
 hasPrefix "foo" "foobar"
@@ -325,6 +354,7 @@ hasPrefix "foo" "foobar"
 hasPrefix "foo" "barfoo"
 => false
 ```
+:::
 
 ## `lib.strings.hasSuffix` {#function-library-lib.strings.hasSuffix}
 
@@ -342,7 +372,8 @@ Determine whether a string has given suffix.
 : Input string
 
 
-### lib.strings.hasSuffix usage example {#function-library-example-lib.strings.hasSuffix}
+::: {.example #function-library-example-lib.strings.hasSuffix}
+# `lib.strings.hasSuffix` usage example
 
 ```nix
 hasSuffix "foo" "foobar"
@@ -350,6 +381,7 @@ hasSuffix "foo" "foobar"
 hasSuffix "foo" "barfoo"
 => true
 ```
+:::
 
 ## `lib.strings.hasInfix` {#function-library-lib.strings.hasInfix}
 
@@ -367,7 +399,8 @@ Determine whether a string contains the given infix
 : Function argument
 
 
-### lib.strings.hasInfix usage example {#function-library-example-lib.strings.hasInfix}
+::: {.example #function-library-example-lib.strings.hasInfix}
+# `lib.strings.hasInfix` usage example
 
 ```nix
 hasInfix "bc" "abcd"
@@ -379,6 +412,7 @@ hasInfix "cd" "abcd"
 hasInfix "foo" "abcd"
 => false
 ```
+:::
 
 ## `lib.strings.stringToCharacters` {#function-library-lib.strings.stringToCharacters}
 
@@ -397,7 +431,8 @@ handle unicode.
 : Function argument
 
 
-### lib.strings.stringToCharacters usage example {#function-library-example-lib.strings.stringToCharacters}
+::: {.example #function-library-example-lib.strings.stringToCharacters}
+# `lib.strings.stringToCharacters` usage example
 
 ```nix
 stringToCharacters ""
@@ -407,6 +442,7 @@ stringToCharacters "abc"
 stringToCharacters "🦄"
 => [ "�" "�" "�" "�" ]
 ```
+:::
 
 ## `lib.strings.stringAsChars` {#function-library-lib.strings.stringAsChars}
 
@@ -425,12 +461,14 @@ strings before concatenating the results.
 : Input string
 
 
-### lib.strings.stringAsChars usage example {#function-library-example-lib.strings.stringAsChars}
+::: {.example #function-library-example-lib.strings.stringAsChars}
+# `lib.strings.stringAsChars` usage example
 
 ```nix
 stringAsChars (x: if x == "a" then "i" else x) "nax"
 => "nix"
 ```
+:::
 
 ## `lib.strings.charToInt` {#function-library-lib.strings.charToInt}
 
@@ -443,7 +481,8 @@ Convert char to ascii value, must be in printable range
 : Function argument
 
 
-### lib.strings.charToInt usage example {#function-library-example-lib.strings.charToInt}
+::: {.example #function-library-example-lib.strings.charToInt}
+# `lib.strings.charToInt` usage example
 
 ```nix
 charToInt "A"
@@ -451,6 +490,7 @@ charToInt "A"
 charToInt "("
 => 40
 ```
+:::
 
 ## `lib.strings.escape` {#function-library-lib.strings.escape}
 
@@ -464,12 +504,14 @@ prefixing it with a backslash.
 : Function argument
 
 
-### lib.strings.escape usage example {#function-library-example-lib.strings.escape}
+::: {.example #function-library-example-lib.strings.escape}
+# `lib.strings.escape` usage example
 
 ```nix
 escape ["(" ")"] "(foo)"
 => "\\(foo\\)"
 ```
+:::
 
 ## `lib.strings.escapeC` {#function-library-lib.strings.escapeC}
 
@@ -484,12 +526,14 @@ Only works for printable ascii characters.
 : Function argument
 
 
-### lib.strings.escapeC usage example {#function-library-example-lib.strings.escapeC}
+::: {.example #function-library-example-lib.strings.escapeC}
+# `lib.strings.escapeC` usage example
 
 ```nix
 escapeC [" "] "foo bar"
 => "foo\\x20bar"
 ```
+:::
 
 ## `lib.strings.escapeURL` {#function-library-lib.strings.escapeURL}
 
@@ -498,12 +542,14 @@ escapeC [" "] "foo bar"
 Escape the string so it can be safely placed inside a URL
 query.
 
-### lib.strings.escapeURL usage example {#function-library-example-lib.strings.escapeURL}
+::: {.example #function-library-example-lib.strings.escapeURL}
+# `lib.strings.escapeURL` usage example
 
 ```nix
 escapeURL "foo/bar baz"
 => "foo%2Fbar%20baz"
 ```
+:::
 
 ## `lib.strings.escapeShellArg` {#function-library-lib.strings.escapeShellArg}
 
@@ -516,12 +562,14 @@ Quote string to be used safely within the Bourne shell.
 : Function argument
 
 
-### lib.strings.escapeShellArg usage example {#function-library-example-lib.strings.escapeShellArg}
+::: {.example #function-library-example-lib.strings.escapeShellArg}
+# `lib.strings.escapeShellArg` usage example
 
 ```nix
 escapeShellArg "esc'ape\nme"
 => "'esc'\\''ape\nme'"
 ```
+:::
 
 ## `lib.strings.escapeShellArgs` {#function-library-lib.strings.escapeShellArgs}
 
@@ -529,12 +577,14 @@ escapeShellArg "esc'ape\nme"
 
 Quote all arguments to be safely passed to the Bourne shell.
 
-### lib.strings.escapeShellArgs usage example {#function-library-example-lib.strings.escapeShellArgs}
+::: {.example #function-library-example-lib.strings.escapeShellArgs}
+# `lib.strings.escapeShellArgs` usage example
 
 ```nix
 escapeShellArgs ["one" "two three" "four'five"]
 => "'one' 'two three' 'four'\\''five'"
 ```
+:::
 
 ## `lib.strings.isValidPosixName` {#function-library-lib.strings.isValidPosixName}
 
@@ -547,7 +597,8 @@ Test whether the given name is a valid POSIX shell variable name.
 : Function argument
 
 
-### lib.strings.isValidPosixName usage example {#function-library-example-lib.strings.isValidPosixName}
+::: {.example #function-library-example-lib.strings.isValidPosixName}
+# `lib.strings.isValidPosixName` usage example
 
 ```nix
 isValidPosixName "foo_bar000"
@@ -555,6 +606,7 @@ isValidPosixName "foo_bar000"
 isValidPosixName "0-bad.jpg"
 => false
 ```
+:::
 
 ## `lib.strings.toShellVar` {#function-library-lib.strings.toShellVar}
 
@@ -580,7 +632,8 @@ assume a shell that understands Bash syntax (e.g. Bash or ZSH).
 : Function argument
 
 
-### lib.strings.toShellVar usage example {#function-library-example-lib.strings.toShellVar}
+::: {.example #function-library-example-lib.strings.toShellVar}
+# `lib.strings.toShellVar` usage example
 
 ```nix
 ''
@@ -588,6 +641,7 @@ ${toShellVar "foo" "some string"}
 [[ "$foo" == "some string" ]]
 ''
 ```
+:::
 
 ## `lib.strings.toShellVars` {#function-library-lib.strings.toShellVars}
 
@@ -601,7 +655,8 @@ using `toShellVar`.
 : Function argument
 
 
-### lib.strings.toShellVars usage example {#function-library-example-lib.strings.toShellVars}
+::: {.example #function-library-example-lib.strings.toShellVars}
+# `lib.strings.toShellVars` usage example
 
 ```nix
 let
@@ -612,6 +667,7 @@ ${toShellVars { inherit foo bar; }}
 [[ "$foo" == "$bar" ]]
 ''
 ```
+:::
 
 ## `lib.strings.escapeNixString` {#function-library-lib.strings.escapeNixString}
 
@@ -624,12 +680,14 @@ Turn a string into a Nix expression representing that string
 : Function argument
 
 
-### lib.strings.escapeNixString usage example {#function-library-example-lib.strings.escapeNixString}
+::: {.example #function-library-example-lib.strings.escapeNixString}
+# `lib.strings.escapeNixString` usage example
 
 ```nix
 escapeNixString "hello\${}\n"
 => "\"hello\\\${}\\n\""
 ```
+:::
 
 ## `lib.strings.escapeRegex` {#function-library-lib.strings.escapeRegex}
 
@@ -637,12 +695,14 @@ escapeNixString "hello\${}\n"
 
 Turn a string into an exact regular expression
 
-### lib.strings.escapeRegex usage example {#function-library-example-lib.strings.escapeRegex}
+::: {.example #function-library-example-lib.strings.escapeRegex}
+# `lib.strings.escapeRegex` usage example
 
 ```nix
 escapeRegex "[^a-z]*"
 => "\\[\\^a-z]\\*"
 ```
+:::
 
 ## `lib.strings.escapeNixIdentifier` {#function-library-lib.strings.escapeNixIdentifier}
 
@@ -655,7 +715,8 @@ Quotes a string if it can't be used as an identifier directly.
 : Function argument
 
 
-### lib.strings.escapeNixIdentifier usage example {#function-library-example-lib.strings.escapeNixIdentifier}
+::: {.example #function-library-example-lib.strings.escapeNixIdentifier}
+# `lib.strings.escapeNixIdentifier` usage example
 
 ```nix
 escapeNixIdentifier "hello"
@@ -663,6 +724,7 @@ escapeNixIdentifier "hello"
 escapeNixIdentifier "0abc"
 => "\"0abc\""
 ```
+:::
 
 ## `lib.strings.escapeXML` {#function-library-lib.strings.escapeXML}
 
@@ -671,12 +733,14 @@ escapeNixIdentifier "0abc"
 Escapes a string such that it is safe to include verbatim in an XML
 document.
 
-### lib.strings.escapeXML usage example {#function-library-example-lib.strings.escapeXML}
+::: {.example #function-library-example-lib.strings.escapeXML}
+# `lib.strings.escapeXML` usage example
 
 ```nix
 escapeXML ''"test" 'test' < & >''
 => "&quot;test&quot; &apos;test&apos; &lt; &amp; &gt;"
 ```
+:::
 
 ## `lib.strings.replaceChars` {#function-library-lib.strings.replaceChars}
 
@@ -692,12 +756,14 @@ Case conversion utilities.
 
 Converts an ASCII string to lower-case.
 
-### lib.strings.toLower usage example {#function-library-example-lib.strings.toLower}
+::: {.example #function-library-example-lib.strings.toLower}
+# `lib.strings.toLower` usage example
 
 ```nix
 toLower "HOME"
 => "home"
 ```
+:::
 
 ## `lib.strings.toUpper` {#function-library-lib.strings.toUpper}
 
@@ -705,12 +771,14 @@ toLower "HOME"
 
 Converts an ASCII string to upper-case.
 
-### lib.strings.toUpper usage example {#function-library-example-lib.strings.toUpper}
+::: {.example #function-library-example-lib.strings.toUpper}
+# `lib.strings.toUpper` usage example
 
 ```nix
 toUpper "home"
 => "HOME"
 ```
+:::
 
 ## `lib.strings.addContextFrom` {#function-library-lib.strings.addContextFrom}
 
@@ -732,13 +800,15 @@ inputSrcs.
 : Function argument
 
 
-### lib.strings.addContextFrom usage example {#function-library-example-lib.strings.addContextFrom}
+::: {.example #function-library-example-lib.strings.addContextFrom}
+# `lib.strings.addContextFrom` usage example
 
 ```nix
 pkgs = import <nixpkgs> { };
 addContextFrom pkgs.coreutils "bar"
 => "bar"
 ```
+:::
 
 ## `lib.strings.splitString` {#function-library-lib.strings.splitString}
 
@@ -755,7 +825,8 @@ were separated by this separator.
 : Function argument
 
 
-### lib.strings.splitString usage example {#function-library-example-lib.strings.splitString}
+::: {.example #function-library-example-lib.strings.splitString}
+# `lib.strings.splitString` usage example
 
 ```nix
 splitString "." "foo.bar.baz"
@@ -763,6 +834,7 @@ splitString "." "foo.bar.baz"
 splitString "/" "/usr/local/bin"
 => [ "" "usr" "local" "bin" ]
 ```
+:::
 
 ## `lib.strings.removePrefix` {#function-library-lib.strings.removePrefix}
 
@@ -780,7 +852,8 @@ Return a string without the specified prefix, if the prefix matches.
 : Input string
 
 
-### lib.strings.removePrefix usage example {#function-library-example-lib.strings.removePrefix}
+::: {.example #function-library-example-lib.strings.removePrefix}
+# `lib.strings.removePrefix` usage example
 
 ```nix
 removePrefix "foo." "foo.bar.baz"
@@ -788,6 +861,7 @@ removePrefix "foo." "foo.bar.baz"
 removePrefix "xxx" "foo.bar.baz"
 => "foo.bar.baz"
 ```
+:::
 
 ## `lib.strings.removeSuffix` {#function-library-lib.strings.removeSuffix}
 
@@ -805,7 +879,8 @@ Return a string without the specified suffix, if the suffix matches.
 : Input string
 
 
-### lib.strings.removeSuffix usage example {#function-library-example-lib.strings.removeSuffix}
+::: {.example #function-library-example-lib.strings.removeSuffix}
+# `lib.strings.removeSuffix` usage example
 
 ```nix
 removeSuffix "front" "homefront"
@@ -813,6 +888,7 @@ removeSuffix "front" "homefront"
 removeSuffix "xxx" "homefront"
 => "homefront"
 ```
+:::
 
 ## `lib.strings.versionOlder` {#function-library-lib.strings.versionOlder}
 
@@ -828,7 +904,8 @@ Return true if string v1 denotes a version older than v2.
 : Function argument
 
 
-### lib.strings.versionOlder usage example {#function-library-example-lib.strings.versionOlder}
+::: {.example #function-library-example-lib.strings.versionOlder}
+# `lib.strings.versionOlder` usage example
 
 ```nix
 versionOlder "1.1" "1.2"
@@ -836,6 +913,7 @@ versionOlder "1.1" "1.2"
 versionOlder "1.1" "1.1"
 => false
 ```
+:::
 
 ## `lib.strings.versionAtLeast` {#function-library-lib.strings.versionAtLeast}
 
@@ -851,7 +929,8 @@ Return true if string v1 denotes a version equal to or newer than v2.
 : Function argument
 
 
-### lib.strings.versionAtLeast usage example {#function-library-example-lib.strings.versionAtLeast}
+::: {.example #function-library-example-lib.strings.versionAtLeast}
+# `lib.strings.versionAtLeast` usage example
 
 ```nix
 versionAtLeast "1.1" "1.0"
@@ -861,6 +940,7 @@ versionAtLeast "1.1" "1.1"
 versionAtLeast "1.1" "1.2"
 => false
 ```
+:::
 
 ## `lib.strings.getName` {#function-library-lib.strings.getName}
 
@@ -873,7 +953,8 @@ argument.
 : Function argument
 
 
-### lib.strings.getName usage example {#function-library-example-lib.strings.getName}
+::: {.example #function-library-example-lib.strings.getName}
+# `lib.strings.getName` usage example
 
 ```nix
 getName "youtube-dl-2016.01.01"
@@ -881,6 +962,7 @@ getName "youtube-dl-2016.01.01"
 getName pkgs.youtube-dl
 => "youtube-dl"
 ```
+:::
 
 ## `lib.strings.getVersion` {#function-library-lib.strings.getVersion}
 
@@ -893,7 +975,8 @@ argument.
 : Function argument
 
 
-### lib.strings.getVersion usage example {#function-library-example-lib.strings.getVersion}
+::: {.example #function-library-example-lib.strings.getVersion}
+# `lib.strings.getVersion` usage example
 
 ```nix
 getVersion "youtube-dl-2016.01.01"
@@ -901,6 +984,7 @@ getVersion "youtube-dl-2016.01.01"
 getVersion pkgs.youtube-dl
 => "2016.01.01"
 ```
+:::
 
 ## `lib.strings.nameFromURL` {#function-library-lib.strings.nameFromURL}
 
@@ -917,7 +1001,8 @@ supposed to start extension.
 : Function argument
 
 
-### lib.strings.nameFromURL usage example {#function-library-example-lib.strings.nameFromURL}
+::: {.example #function-library-example-lib.strings.nameFromURL}
+# `lib.strings.nameFromURL` usage example
 
 ```nix
 nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "-"
@@ -925,6 +1010,7 @@ nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2
 nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "_"
 => "nix-1.7-x86"
 ```
+:::
 
 ## `lib.strings.mesonOption` {#function-library-lib.strings.mesonOption}
 
@@ -943,12 +1029,14 @@ invocations.
 : Function argument
 
 
-### lib.strings.mesonOption usage example {#function-library-example-lib.strings.mesonOption}
+::: {.example #function-library-example-lib.strings.mesonOption}
+# `lib.strings.mesonOption` usage example
 
 ```nix
 mesonOption "engine" "opengl"
 => "-Dengine=opengl"
 ```
+:::
 
 ## `lib.strings.mesonBool` {#function-library-lib.strings.mesonBool}
 
@@ -967,7 +1055,8 @@ Meson invocations.
 : Function argument
 
 
-### lib.strings.mesonBool usage example {#function-library-example-lib.strings.mesonBool}
+::: {.example #function-library-example-lib.strings.mesonBool}
+# `lib.strings.mesonBool` usage example
 
 ```nix
 mesonBool "hardened" true
@@ -975,6 +1064,7 @@ mesonBool "hardened" true
 mesonBool "static" false
 => "-Dstatic=false"
 ```
+:::
 
 ## `lib.strings.mesonEnable` {#function-library-lib.strings.mesonEnable}
 
@@ -993,7 +1083,8 @@ typical Meson invocations.
 : Function argument
 
 
-### lib.strings.mesonEnable usage example {#function-library-example-lib.strings.mesonEnable}
+::: {.example #function-library-example-lib.strings.mesonEnable}
+# `lib.strings.mesonEnable` usage example
 
 ```nix
 mesonEnable "docs" true
@@ -1001,6 +1092,7 @@ mesonEnable "docs" true
 mesonEnable "savage" false
 => "-Dsavage=disabled"
 ```
+:::
 
 ## `lib.strings.enableFeature` {#function-library-lib.strings.enableFeature}
 
@@ -1017,7 +1109,8 @@ standard GNU Autoconf scripts.
 : Function argument
 
 
-### lib.strings.enableFeature usage example {#function-library-example-lib.strings.enableFeature}
+::: {.example #function-library-example-lib.strings.enableFeature}
+# `lib.strings.enableFeature` usage example
 
 ```nix
 enableFeature true "shared"
@@ -1025,6 +1118,7 @@ enableFeature true "shared"
 enableFeature false "shared"
 => "--disable-shared"
 ```
+:::
 
 ## `lib.strings.enableFeatureAs` {#function-library-lib.strings.enableFeatureAs}
 
@@ -1046,7 +1140,8 @@ standard GNU Autoconf scripts.
 : Function argument
 
 
-### lib.strings.enableFeatureAs usage example {#function-library-example-lib.strings.enableFeatureAs}
+::: {.example #function-library-example-lib.strings.enableFeatureAs}
+# `lib.strings.enableFeatureAs` usage example
 
 ```nix
 enableFeatureAs true "shared" "foo"
@@ -1054,6 +1149,7 @@ enableFeatureAs true "shared" "foo"
 enableFeatureAs false "shared" (throw "ignored")
 => "--disable-shared"
 ```
+:::
 
 ## `lib.strings.withFeature` {#function-library-lib.strings.withFeature}
 
@@ -1070,7 +1166,8 @@ standard GNU Autoconf scripts.
 : Function argument
 
 
-### lib.strings.withFeature usage example {#function-library-example-lib.strings.withFeature}
+::: {.example #function-library-example-lib.strings.withFeature}
+# `lib.strings.withFeature` usage example
 
 ```nix
 withFeature true "shared"
@@ -1078,6 +1175,7 @@ withFeature true "shared"
 withFeature false "shared"
 => "--without-shared"
 ```
+:::
 
 ## `lib.strings.withFeatureAs` {#function-library-lib.strings.withFeatureAs}
 
@@ -1099,7 +1197,8 @@ standard GNU Autoconf scripts.
 : Function argument
 
 
-### lib.strings.withFeatureAs usage example {#function-library-example-lib.strings.withFeatureAs}
+::: {.example #function-library-example-lib.strings.withFeatureAs}
+# `lib.strings.withFeatureAs` usage example
 
 ```nix
 withFeatureAs true "shared" "foo"
@@ -1107,6 +1206,7 @@ withFeatureAs true "shared" "foo"
 withFeatureAs false "shared" (throw "ignored")
 => "--without-shared"
 ```
+:::
 
 ## `lib.strings.fixedWidthString` {#function-library-lib.strings.fixedWidthString}
 
@@ -1133,12 +1233,14 @@ requested length.
 : Function argument
 
 
-### lib.strings.fixedWidthString usage example {#function-library-example-lib.strings.fixedWidthString}
+::: {.example #function-library-example-lib.strings.fixedWidthString}
+# `lib.strings.fixedWidthString` usage example
 
 ```nix
 fixedWidthString 5 "0" (toString 15)
 => "00015"
 ```
+:::
 
 ## `lib.strings.fixedWidthNumber` {#function-library-lib.strings.fixedWidthNumber}
 
@@ -1154,12 +1256,14 @@ Format a number adding leading zeroes up to fixed width.
 : Function argument
 
 
-### lib.strings.fixedWidthNumber usage example {#function-library-example-lib.strings.fixedWidthNumber}
+::: {.example #function-library-example-lib.strings.fixedWidthNumber}
+# `lib.strings.fixedWidthNumber` usage example
 
 ```nix
 fixedWidthNumber 5 15
 => "00015"
 ```
+:::
 
 ## `lib.strings.floatToString` {#function-library-lib.strings.floatToString}
 
@@ -1171,7 +1275,8 @@ during the conversion
 : Function argument
 
 
-### lib.strings.floatToString usage example {#function-library-example-lib.strings.floatToString}
+::: {.example #function-library-example-lib.strings.floatToString}
+# `lib.strings.floatToString` usage example
 
 ```nix
 floatToString 0.000001
@@ -1180,6 +1285,7 @@ floatToString 0.0000001
 => trace: warning: Imprecise conversion from float to string 0.000000
 "0.000000"
 ```
+:::
 
 ## `lib.strings.isCoercibleToString` {#function-library-lib.strings.isCoercibleToString}
 
@@ -1220,7 +1326,8 @@ Check whether a value is a store path.
 : Function argument
 
 
-### lib.strings.isStorePath usage example {#function-library-example-lib.strings.isStorePath}
+::: {.example #function-library-example-lib.strings.isStorePath}
+# `lib.strings.isStorePath` usage example
 
 ```nix
 isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11/bin/python"
@@ -1232,6 +1339,7 @@ isStorePath pkgs.python
 isStorePath [] || isStorePath 42 || isStorePath {} || …
 => false
 ```
+:::
 
 ## `lib.strings.toInt` {#function-library-lib.strings.toInt}
 
@@ -1245,10 +1353,10 @@ ambiguity between zero-padded and octal numbers. See toIntBase10.
 : Function argument
 
 
-### lib.strings.toInt usage example {#function-library-example-lib.strings.toInt}
+::: {.example #function-library-example-lib.strings.toInt}
+# `lib.strings.toInt` usage example
 
 ```nix
-
 toInt "1337"
 => 1337
 
@@ -1264,6 +1372,7 @@ toInt "00024"
 toInt "3.14"
 => error: floating point JSON numbers are not supported
 ```
+:::
 
 ## `lib.strings.toIntBase10` {#function-library-lib.strings.toIntBase10}
 
@@ -1276,7 +1385,8 @@ Parse a string as a base 10 int. This supports parsing of zero-padded integers.
 : Function argument
 
 
-### lib.strings.toIntBase10 usage example {#function-library-example-lib.strings.toIntBase10}
+::: {.example #function-library-example-lib.strings.toIntBase10}
+# `lib.strings.toIntBase10` usage example
 
 ```nix
 toIntBase10 "1337"
@@ -1294,6 +1404,7 @@ toIntBase10 "00024"
 toIntBase10 "3.14"
 => error: floating point JSON numbers are not supported
 ```
+:::
 
 ## `lib.strings.readPathsFromFile` {#function-library-lib.strings.readPathsFromFile}
 
@@ -1303,7 +1414,8 @@ Whitespace is significant.
 
 NOTE: This function is not performant and should be avoided.
 
-### lib.strings.readPathsFromFile usage example {#function-library-example-lib.strings.readPathsFromFile}
+::: {.example #function-library-example-lib.strings.readPathsFromFile}
+# `lib.strings.readPathsFromFile` usage example
 
 ```nix
 readPathsFromFile /prefix
@@ -1314,6 +1426,7 @@ readPathsFromFile /prefix
 "/prefix/nix-profiles-library-paths.patch"
 "/prefix/compose-search-path.patch" ]
 ```
+:::
 
 ## `lib.strings.fileContents` {#function-library-lib.strings.fileContents}
 
@@ -1326,7 +1439,8 @@ Read the contents of a file removing the trailing \n
 : Function argument
 
 
-### lib.strings.fileContents usage example {#function-library-example-lib.strings.fileContents}
+::: {.example #function-library-example-lib.strings.fileContents}
+# `lib.strings.fileContents` usage example
 
 ```nix
 $ echo "1.0" > ./version
@@ -1334,6 +1448,7 @@ $ echo "1.0" > ./version
 fileContents ./version
 => "1.0"
 ```
+:::
 
 ## `lib.strings.sanitizeDerivationName` {#function-library-lib.strings.sanitizeDerivationName}
 
@@ -1341,7 +1456,8 @@ fileContents ./version
 
 Creates a valid derivation name from a potentially invalid one.
 
-### lib.strings.sanitizeDerivationName usage example {#function-library-example-lib.strings.sanitizeDerivationName}
+::: {.example #function-library-example-lib.strings.sanitizeDerivationName}
+# `lib.strings.sanitizeDerivationName` usage example
 
 ```nix
 sanitizeDerivationName "../hello.bar # foo"
@@ -1351,6 +1467,7 @@ sanitizeDerivationName ""
 sanitizeDerivationName pkgs.hello
 => "-nix-store-2g75chlbpxlrqn15zlby2dfh8hr9qwbk-hello-2.10"
 ```
+:::
 
 ## `lib.strings.levenshtein` {#function-library-lib.strings.levenshtein}
 
@@ -1370,7 +1487,8 @@ Algorithm adjusted from https://stackoverflow.com/a/9750974/6605742
 : Function argument
 
 
-### lib.strings.levenshtein usage example {#function-library-example-lib.strings.levenshtein}
+::: {.example #function-library-example-lib.strings.levenshtein}
+# `lib.strings.levenshtein` usage example
 
 ```nix
 levenshtein "foo" "foo"
@@ -1380,6 +1498,7 @@ levenshtein "book" "hook"
 levenshtein "hello" "Heyo"
 => 3
 ```
+:::
 
 ## `lib.strings.commonPrefixLength` {#function-library-lib.strings.commonPrefixLength}
 
@@ -1416,7 +1535,8 @@ Returns the length of the suffix common to both strings.
 Returns whether the levenshtein distance between two strings is at most some value
 Complexity is O(min(n,m)) for k <= 2 and O(n*m) otherwise
 
-### lib.strings.levenshteinAtMost usage example {#function-library-example-lib.strings.levenshteinAtMost}
+::: {.example #function-library-example-lib.strings.levenshteinAtMost}
+# `lib.strings.levenshteinAtMost` usage example
 
 ```nix
 levenshteinAtMost 0 "foo" "foo"
@@ -1430,5 +1550,6 @@ levenshteinAtMost 2 "This is a sentence" "this is a sentense."
 levenshteinAtMost 3 "This is a sentence" "this is a sentense."
 => true
 ```
+:::
 
 

From 06a25cb2844ccdfa1062e4458cb6763e500dc977 Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Thu, 22 Jun 2023 19:07:31 +0200
Subject: [PATCH 4/6] add location support again

this was lost during the markdown transition.
---
 Cargo.lock                      | 104 +++++++++++++++++++++---
 Cargo.toml                      |   2 +
 src/commonmark.rs               |  12 ++-
 src/main.rs                     |  18 ++++-
 src/snapshots/nixdoc__main.snap | 136 ++++++++++++++++++++++++++++++++
 test/strings.json               |  94 ++++++++++++++++++++++
 6 files changed, 348 insertions(+), 18 deletions(-)
 create mode 100644 test/strings.json

diff --git a/Cargo.lock b/Cargo.lock
index 1f17177..d4ebbda 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -150,9 +150,9 @@ version = "0.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "64c2d913fe8ed3b6c6518eedf4538255b989945c14c2a7d5cbff62a5e2120596"
 dependencies = [
- "proc-macro2",
- "quote",
- "syn",
+ "proc-macro2 0.4.20",
+ "quote 0.6.8",
+ "syn 0.15.15",
  "synstructure",
 ]
 
@@ -189,6 +189,12 @@ dependencies = [
  "yaml-rust",
 ]
 
+[[package]]
+name = "itoa"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "453ad9f582a441959e5f0d088b02ce04cfe8d51a8eaf077f12ac6d3e94164ca6"
+
 [[package]]
 name = "lazy_static"
 version = "1.4.0"
@@ -230,6 +236,8 @@ dependencies = [
  "insta",
  "rnix",
  "rowan",
+ "serde",
+ "serde_json",
  "structopt",
  "textwrap 0.16.0",
  "xml-rs",
@@ -250,13 +258,31 @@ dependencies = [
  "unicode-xid",
 ]
 
+[[package]]
+name = "proc-macro2"
+version = "1.0.60"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dec2b086b7a862cf4de201096214fa870344cf922b2b30c167badb3af3195406"
+dependencies = [
+ "unicode-ident",
+]
+
 [[package]]
 name = "quote"
 version = "0.6.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dd636425967c33af890042c483632d33fa7a18f19ad1d7ea72e8998c6ef8dea5"
 dependencies = [
- "proc-macro2",
+ "proc-macro2 0.4.20",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ab9c7eadfd8df19006f1cf1a4aed13540ed5cbc047010ece5826e10825488"
+dependencies = [
+ "proc-macro2 1.0.60",
 ]
 
 [[package]]
@@ -325,6 +351,43 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
 
+[[package]]
+name = "ryu"
+version = "1.0.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f91339c0467de62360649f8d3e185ca8de4224ff281f66000de5eb2a77a79041"
+
+[[package]]
+name = "serde"
+version = "1.0.164"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e8c8cf938e98f769bc164923b06dce91cea1751522f46f8466461af04c9027d"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.164"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9735b638ccc51c28bf6914d90a2e9725b377144fc612c49a611fddd1b631d68"
+dependencies = [
+ "proc-macro2 1.0.60",
+ "quote 1.0.28",
+ "syn 2.0.18",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.97"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bdf3bf93142acad5821c99197022e170842cdbc1c30482b98750c688c640842a"
+dependencies = [
+ "itoa",
+ "ryu",
+ "serde",
+]
+
 [[package]]
 name = "similar"
 version = "2.2.1"
@@ -359,9 +422,9 @@ version = "0.2.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "17ff01fe96de9d16e7372ae5f19dd7ece2c703b51043c3db9ea27f9e393ea311"
 dependencies = [
- "proc-macro2",
- "quote",
- "syn",
+ "proc-macro2 0.4.20",
+ "quote 0.6.8",
+ "syn 0.15.15",
 ]
 
 [[package]]
@@ -370,20 +433,31 @@ version = "0.15.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0a9c2bf1e53c21704a7cce1b2a42768f1ae32a6777108a0d7f1faa4bfe7f7c04"
 dependencies = [
- "proc-macro2",
- "quote",
+ "proc-macro2 0.4.20",
+ "quote 0.6.8",
  "unicode-xid",
 ]
 
+[[package]]
+name = "syn"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32d41677bcbe24c20c52e7c70b0d8db04134c5d1066bf98662e2871ad200ea3e"
+dependencies = [
+ "proc-macro2 1.0.60",
+ "quote 1.0.28",
+ "unicode-ident",
+]
+
 [[package]]
 name = "synstructure"
 version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "73687139bf99285483c96ac0add482c3776528beac1d97d444f6e91f203a2015"
 dependencies = [
- "proc-macro2",
- "quote",
- "syn",
+ "proc-macro2 0.4.20",
+ "quote 0.6.8",
+ "syn 0.15.15",
  "unicode-xid",
 ]
 
@@ -424,6 +498,12 @@ dependencies = [
  "unicode-width",
 ]
 
+[[package]]
+name = "unicode-ident"
+version = "1.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b15811caf2415fb889178633e7724bad2509101cde276048e013b9def5e51fa0"
+
 [[package]]
 name = "unicode-linebreak"
 version = "0.1.4"
diff --git a/Cargo.toml b/Cargo.toml
index 6fa83c4..4458a6e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -9,6 +9,8 @@ structopt = "0.2"
 failure = "0.1"
 rnix = "0.11"
 rowan = "0.15.11"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
 textwrap = "0.16"
 
 [dev-dependencies]
diff --git a/src/commonmark.rs b/src/commonmark.rs
index 909c571..b7910d6 100644
--- a/src/commonmark.rs
+++ b/src/commonmark.rs
@@ -17,6 +17,7 @@
 //! representing a single entry in the manual.
 
 use failure::Error;
+use std::collections::HashMap;
 
 use std::io::Write;
 
@@ -97,7 +98,11 @@ pub struct ManualEntry {
 
 impl ManualEntry {
     /// Write a single CommonMark entry for a documented Nix function.
-    pub fn write_section<W: Write>(self, writer: &mut W) -> Result<(), Error> {
+    pub fn write_section<W: Write>(
+        self,
+        locs: &HashMap<String, String>,
+        writer: &mut W,
+    ) -> Result<(), Error> {
         let title = format!("lib.{}.{}", self.category, self.name);
         let ident = format!(
             "lib.{}.{}",
@@ -139,8 +144,9 @@ impl ManualEntry {
             writeln!(writer, "```nix\n{}\n```\n:::\n", example.trim())?;
         }
 
-        // TODO: add source links
-        //println!("[Source](#function-location-{})", ident);
+        if let Some(loc) = locs.get(&ident) {
+            writeln!(writer, "Located at {loc}.\n")?;
+        }
 
         Ok(())
     }
diff --git a/src/main.rs b/src/main.rs
index 176c201..0291a91 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -53,6 +53,10 @@ struct Options {
     #[structopt(short = "f", long = "file", parse(from_os_str))]
     file: PathBuf,
 
+    /// Path to a file containing location data as JSON.
+    #[structopt(short = "l", long = "locs", parse(from_os_str))]
+    locs: Option<PathBuf>,
+
     /// Name of the function category (e.g. 'strings', 'attrsets').
     #[structopt(short = "c", long = "category")]
     category: String,
@@ -268,6 +272,13 @@ fn main() {
     let mut output = io::stdout();
     let opts = Options::from_args();
     let src = fs::read_to_string(&opts.file).unwrap();
+    let locs = match opts.locs {
+        None => Default::default(),
+        Some(p) => fs::read_to_string(p)
+            .map_err(|e| e.to_string())
+            .and_then(|json| serde_json::from_str(&json).map_err(|e| e.to_string()))
+            .expect("could not read location information"),
+    };
     let nix = rnix::Root::parse(&src).ok().expect("failed to parse input");
 
     // TODO: move this to commonmark.rs
@@ -280,7 +291,7 @@ fn main() {
 
     for entry in collect_entries(nix, &opts.category) {
         entry
-            .write_section(&mut output)
+            .write_section(&locs, &mut output)
             .expect("Failed to write section")
     }
 }
@@ -289,6 +300,7 @@ fn main() {
 fn test_main() {
     let mut output = Vec::new();
     let src = fs::read_to_string("test/strings.nix").unwrap();
+    let locs = serde_json::from_str(&fs::read_to_string("test/strings.json").unwrap()).unwrap();
     let nix = rnix::Root::parse(&src).ok().expect("failed to parse input");
     let desc = "string manipulation functions";
     let category = "strings";
@@ -303,7 +315,7 @@ fn test_main() {
 
     for entry in collect_entries(nix, category) {
         entry
-            .write_section(&mut output)
+            .write_section(&locs, &mut output)
             .expect("Failed to write section")
     }
 
@@ -321,7 +333,7 @@ fn test_arg_formatting() {
 
     for entry in collect_entries(nix, category) {
         entry
-            .write_section(&mut output)
+            .write_section(&Default::default(), &mut output)
             .expect("Failed to write section")
     }
 
diff --git a/src/snapshots/nixdoc__main.snap b/src/snapshots/nixdoc__main.snap
index 38e64d0..01e6edc 100644
--- a/src/snapshots/nixdoc__main.snap
+++ b/src/snapshots/nixdoc__main.snap
@@ -19,6 +19,8 @@ concatStrings ["foo" "bar"]
 ```
 :::
 
+Located at [lib/strings.nix:49](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L49) in `<nixpkgs>`.
+
 ## `lib.strings.concatMapStrings` {#function-library-lib.strings.concatMapStrings}
 
 **Type**: `concatMapStrings :: (a -> string) -> [a] -> string`
@@ -44,6 +46,8 @@ concatMapStrings (x: "a" + x) ["foo" "bar"]
 ```
 :::
 
+Located at [lib/strings.nix:59](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L59) in `<nixpkgs>`.
+
 ## `lib.strings.concatImapStrings` {#function-library-lib.strings.concatImapStrings}
 
 **Type**: `concatImapStrings :: (int -> a -> string) -> [a] -> string`
@@ -70,6 +74,8 @@ concatImapStrings (pos: x: "${toString pos}-${x}") ["foo" "bar"]
 ```
 :::
 
+Located at [lib/strings.nix:70](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L70) in `<nixpkgs>`.
+
 ## `lib.strings.intersperse` {#function-library-lib.strings.intersperse}
 
 **Type**: `intersperse :: a -> [a] -> [a]`
@@ -95,6 +101,8 @@ intersperse "/" ["usr" "local" "bin"]
 ```
 :::
 
+Located at [lib/strings.nix:80](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L80) in `<nixpkgs>`.
+
 ## `lib.strings.concatStringsSep` {#function-library-lib.strings.concatStringsSep}
 
 **Type**: `concatStringsSep :: string -> [string] -> string`
@@ -110,6 +118,8 @@ concatStringsSep "/" ["usr" "local" "bin"]
 ```
 :::
 
+Located at [lib/strings.nix:97](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L97) in `<nixpkgs>`.
+
 ## `lib.strings.concatMapStringsSep` {#function-library-lib.strings.concatMapStringsSep}
 
 **Type**: `concatMapStringsSep :: string -> (a -> string) -> [a] -> string`
@@ -142,6 +152,8 @@ concatMapStringsSep "-" (x: toUpper x)  ["foo" "bar" "baz"]
 ```
 :::
 
+Located at [lib/strings.nix:110](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L110) in `<nixpkgs>`.
+
 ## `lib.strings.concatImapStringsSep` {#function-library-lib.strings.concatImapStringsSep}
 
 **Type**: `concatIMapStringsSep :: string -> (int -> a -> string) -> [a] -> string`
@@ -173,6 +185,8 @@ concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ]
 ```
 :::
 
+Located at [lib/strings.nix:127](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L127) in `<nixpkgs>`.
+
 ## `lib.strings.concatLines` {#function-library-lib.strings.concatLines}
 
 **Type**: `concatLines :: [string] -> string`
@@ -189,6 +203,8 @@ concatLines [ "foo" "bar" ]
 ```
 :::
 
+Located at [lib/strings.nix:144](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L144) in `<nixpkgs>`.
+
 ## `lib.strings.makeSearchPath` {#function-library-lib.strings.makeSearchPath}
 
 **Type**: `makeSearchPath :: string -> [string] -> string`
@@ -217,6 +233,8 @@ makeSearchPath "bin" [""]
 ```
 :::
 
+Located at [lib/strings.nix:157](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L157) in `<nixpkgs>`.
+
 ## `lib.strings.makeSearchPathOutput` {#function-library-lib.strings.makeSearchPathOutput}
 
 **Type**: `string -> string -> [package] -> string`
@@ -250,6 +268,8 @@ makeSearchPathOutput "dev" "bin" [ pkgs.openssl pkgs.zlib ]
 ```
 :::
 
+Located at [lib/strings.nix:175](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L175) in `<nixpkgs>`.
+
 ## `lib.strings.makeLibraryPath` {#function-library-lib.strings.makeLibraryPath}
 
 Construct a library search path (such as RPATH) containing the
@@ -267,6 +287,8 @@ makeLibraryPath [ pkgs.openssl pkgs.zlib ]
 ```
 :::
 
+Located at [lib/strings.nix:193](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L193) in `<nixpkgs>`.
+
 ## `lib.strings.makeBinPath` {#function-library-lib.strings.makeBinPath}
 
 Construct a binary search path (such as $PATH) containing the
@@ -281,6 +303,8 @@ makeBinPath ["/root" "/usr" "/usr/local"]
 ```
 :::
 
+Located at [lib/strings.nix:202](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L202) in `<nixpkgs>`.
+
 ## `lib.strings.normalizePath` {#function-library-lib.strings.normalizePath}
 
 **Type**: `normalizePath :: string -> string`
@@ -301,6 +325,8 @@ normalizePath "/a//b///c/"
 ```
 :::
 
+Located at [lib/strings.nix:212](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L212) in `<nixpkgs>`.
+
 ## `lib.strings.optionalString` {#function-library-lib.strings.optionalString}
 
 **Type**: `optionalString :: bool -> string -> string`
@@ -329,6 +355,8 @@ optionalString false "some-string"
 ```
 :::
 
+Located at [lib/strings.nix:238](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L238) in `<nixpkgs>`.
+
 ## `lib.strings.hasPrefix` {#function-library-lib.strings.hasPrefix}
 
 **Type**: `hasPrefix :: string -> string -> bool`
@@ -356,6 +384,8 @@ hasPrefix "foo" "barfoo"
 ```
 :::
 
+Located at [lib/strings.nix:254](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L254) in `<nixpkgs>`.
+
 ## `lib.strings.hasSuffix` {#function-library-lib.strings.hasSuffix}
 
 **Type**: `hasSuffix :: string -> string -> bool`
@@ -383,6 +413,8 @@ hasSuffix "foo" "barfoo"
 ```
 :::
 
+Located at [lib/strings.nix:280](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L280) in `<nixpkgs>`.
+
 ## `lib.strings.hasInfix` {#function-library-lib.strings.hasInfix}
 
 **Type**: `hasInfix :: string -> string -> bool`
@@ -414,6 +446,8 @@ hasInfix "foo" "abcd"
 ```
 :::
 
+Located at [lib/strings.nix:317](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L317) in `<nixpkgs>`.
+
 ## `lib.strings.stringToCharacters` {#function-library-lib.strings.stringToCharacters}
 
 **Type**: `stringToCharacters :: string -> [string]`
@@ -444,6 +478,8 @@ stringToCharacters "🦄"
 ```
 :::
 
+Located at [lib/strings.nix:347](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L347) in `<nixpkgs>`.
+
 ## `lib.strings.stringAsChars` {#function-library-lib.strings.stringAsChars}
 
 **Type**: `stringAsChars :: (string -> string) -> string -> string`
@@ -470,6 +506,8 @@ stringAsChars (x: if x == "a" then "i" else x) "nax"
 ```
 :::
 
+Located at [lib/strings.nix:359](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L359) in `<nixpkgs>`.
+
 ## `lib.strings.charToInt` {#function-library-lib.strings.charToInt}
 
 **Type**: `charToInt :: string -> int`
@@ -492,6 +530,8 @@ charToInt "("
 ```
 :::
 
+Located at [lib/strings.nix:378](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L378) in `<nixpkgs>`.
+
 ## `lib.strings.escape` {#function-library-lib.strings.escape}
 
 **Type**: `escape :: [string] -> string -> string`
@@ -513,6 +553,8 @@ escape ["(" ")"] "(foo)"
 ```
 :::
 
+Located at [lib/strings.nix:389](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L389) in `<nixpkgs>`.
+
 ## `lib.strings.escapeC` {#function-library-lib.strings.escapeC}
 
 **Type**: `escapeC = [string] -> string -> string`
@@ -535,6 +577,8 @@ escapeC [" "] "foo bar"
 ```
 :::
 
+Located at [lib/strings.nix:402](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L402) in `<nixpkgs>`.
+
 ## `lib.strings.escapeURL` {#function-library-lib.strings.escapeURL}
 
 **Type**: `escapeURL :: string -> string`
@@ -551,6 +595,8 @@ escapeURL "foo/bar baz"
 ```
 :::
 
+Located at [lib/strings.nix:413](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L413) in `<nixpkgs>`.
+
 ## `lib.strings.escapeShellArg` {#function-library-lib.strings.escapeShellArg}
 
 **Type**: `escapeShellArg :: string -> string`
@@ -571,6 +617,8 @@ escapeShellArg "esc'ape\nme"
 ```
 :::
 
+Located at [lib/strings.nix:427](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L427) in `<nixpkgs>`.
+
 ## `lib.strings.escapeShellArgs` {#function-library-lib.strings.escapeShellArgs}
 
 **Type**: `escapeShellArgs :: [string] -> string`
@@ -586,6 +634,8 @@ escapeShellArgs ["one" "two three" "four'five"]
 ```
 :::
 
+Located at [lib/strings.nix:437](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L437) in `<nixpkgs>`.
+
 ## `lib.strings.isValidPosixName` {#function-library-lib.strings.isValidPosixName}
 
 **Type**: `string -> bool`
@@ -608,6 +658,8 @@ isValidPosixName "0-bad.jpg"
 ```
 :::
 
+Located at [lib/strings.nix:449](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L449) in `<nixpkgs>`.
+
 ## `lib.strings.toShellVar` {#function-library-lib.strings.toShellVar}
 
 **Type**: `string -> (string | listOf string | attrsOf string) -> string`
@@ -643,6 +695,8 @@ ${toShellVar "foo" "some string"}
 ```
 :::
 
+Located at [lib/strings.nix:469](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L469) in `<nixpkgs>`.
+
 ## `lib.strings.toShellVars` {#function-library-lib.strings.toShellVars}
 
 **Type**: `attrsOf (string | listOf string | attrsOf string) -> string`
@@ -669,6 +723,8 @@ ${toShellVars { inherit foo bar; }}
 ```
 :::
 
+Located at [lib/strings.nix:497](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L497) in `<nixpkgs>`.
+
 ## `lib.strings.escapeNixString` {#function-library-lib.strings.escapeNixString}
 
 **Type**: `string -> string`
@@ -689,6 +745,8 @@ escapeNixString "hello\${}\n"
 ```
 :::
 
+Located at [lib/strings.nix:507](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L507) in `<nixpkgs>`.
+
 ## `lib.strings.escapeRegex` {#function-library-lib.strings.escapeRegex}
 
 **Type**: `string -> string`
@@ -704,6 +762,8 @@ escapeRegex "[^a-z]*"
 ```
 :::
 
+Located at [lib/strings.nix:517](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L517) in `<nixpkgs>`.
+
 ## `lib.strings.escapeNixIdentifier` {#function-library-lib.strings.escapeNixIdentifier}
 
 **Type**: `string -> string`
@@ -726,6 +786,8 @@ escapeNixIdentifier "0abc"
 ```
 :::
 
+Located at [lib/strings.nix:529](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L529) in `<nixpkgs>`.
+
 ## `lib.strings.escapeXML` {#function-library-lib.strings.escapeXML}
 
 **Type**: `string -> string`
@@ -742,14 +804,20 @@ escapeXML ''"test" 'test' < & >''
 ```
 :::
 
+Located at [lib/strings.nix:543](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L543) in `<nixpkgs>`.
+
 ## `lib.strings.replaceChars` {#function-library-lib.strings.replaceChars}
 
 warning added 12-12-2022
 
+Located at [lib/strings.nix:548](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L548) in `<nixpkgs>`.
+
 ## `lib.strings.lowerChars` {#function-library-lib.strings.lowerChars}
 
 Case conversion utilities.
 
+Located at [lib/strings.nix:551](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L551) in `<nixpkgs>`.
+
 ## `lib.strings.toLower` {#function-library-lib.strings.toLower}
 
 **Type**: `toLower :: string -> string`
@@ -765,6 +833,8 @@ toLower "HOME"
 ```
 :::
 
+Located at [lib/strings.nix:562](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L562) in `<nixpkgs>`.
+
 ## `lib.strings.toUpper` {#function-library-lib.strings.toUpper}
 
 **Type**: `toUpper :: string -> string`
@@ -780,6 +850,8 @@ toUpper "home"
 ```
 :::
 
+Located at [lib/strings.nix:572](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L572) in `<nixpkgs>`.
+
 ## `lib.strings.addContextFrom` {#function-library-lib.strings.addContextFrom}
 
 Appends string context from another string.  This is an implementation
@@ -810,6 +882,8 @@ addContextFrom pkgs.coreutils "bar"
 ```
 :::
 
+Located at [lib/strings.nix:587](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L587) in `<nixpkgs>`.
+
 ## `lib.strings.splitString` {#function-library-lib.strings.splitString}
 
 Cut a string with a separator and produces a list of strings which
@@ -836,6 +910,8 @@ splitString "/" "/usr/local/bin"
 ```
 :::
 
+Located at [lib/strings.nix:598](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L598) in `<nixpkgs>`.
+
 ## `lib.strings.removePrefix` {#function-library-lib.strings.removePrefix}
 
 **Type**: `string -> string -> string`
@@ -863,6 +939,8 @@ removePrefix "xxx" "foo.bar.baz"
 ```
 :::
 
+Located at [lib/strings.nix:614](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L614) in `<nixpkgs>`.
+
 ## `lib.strings.removeSuffix` {#function-library-lib.strings.removeSuffix}
 
 **Type**: `string -> string -> string`
@@ -890,6 +968,8 @@ removeSuffix "xxx" "homefront"
 ```
 :::
 
+Located at [lib/strings.nix:647](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L647) in `<nixpkgs>`.
+
 ## `lib.strings.versionOlder` {#function-library-lib.strings.versionOlder}
 
 Return true if string v1 denotes a version older than v2.
@@ -915,6 +995,8 @@ versionOlder "1.1" "1.1"
 ```
 :::
 
+Located at [lib/strings.nix:678](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L678) in `<nixpkgs>`.
+
 ## `lib.strings.versionAtLeast` {#function-library-lib.strings.versionAtLeast}
 
 Return true if string v1 denotes a version equal to or newer than v2.
@@ -942,6 +1024,8 @@ versionAtLeast "1.1" "1.2"
 ```
 :::
 
+Located at [lib/strings.nix:690](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L690) in `<nixpkgs>`.
+
 ## `lib.strings.getName` {#function-library-lib.strings.getName}
 
 This function takes an argument that's either a derivation or a
@@ -964,6 +1048,8 @@ getName pkgs.youtube-dl
 ```
 :::
 
+Located at [lib/strings.nix:702](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L702) in `<nixpkgs>`.
+
 ## `lib.strings.getVersion` {#function-library-lib.strings.getVersion}
 
 This function takes an argument that's either a derivation or a
@@ -986,6 +1072,8 @@ getVersion pkgs.youtube-dl
 ```
 :::
 
+Located at [lib/strings.nix:719](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L719) in `<nixpkgs>`.
+
 ## `lib.strings.nameFromURL` {#function-library-lib.strings.nameFromURL}
 
 Extract name with version from URL. Ask for separator which is
@@ -1012,6 +1100,8 @@ nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2
 ```
 :::
 
+Located at [lib/strings.nix:735](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L735) in `<nixpkgs>`.
+
 ## `lib.strings.mesonOption` {#function-library-lib.strings.mesonOption}
 
 **Type**: `mesonOption :: string -> string -> string@param feature The feature to be set@param value The desired value`
@@ -1038,6 +1128,8 @@ mesonOption "engine" "opengl"
 ```
 :::
 
+Located at [lib/strings.nix:754](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L754) in `<nixpkgs>`.
+
 ## `lib.strings.mesonBool` {#function-library-lib.strings.mesonBool}
 
 **Type**: `mesonBool :: string -> bool -> string@param condition The condition to be made true or false@param flag The controlling flag of the condition`
@@ -1066,6 +1158,8 @@ mesonBool "static" false
 ```
 :::
 
+Located at [lib/strings.nix:773](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L773) in `<nixpkgs>`.
+
 ## `lib.strings.mesonEnable` {#function-library-lib.strings.mesonEnable}
 
 **Type**: `mesonEnable :: string -> bool -> string@param feature The feature to be enabled or disabled@param flag The controlling flag`
@@ -1094,6 +1188,8 @@ mesonEnable "savage" false
 ```
 :::
 
+Located at [lib/strings.nix:792](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L792) in `<nixpkgs>`.
+
 ## `lib.strings.enableFeature` {#function-library-lib.strings.enableFeature}
 
 Create an --{enable,disable}-<feat> string that can be passed to
@@ -1120,6 +1216,8 @@ enableFeature false "shared"
 ```
 :::
 
+Located at [lib/strings.nix:806](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L806) in `<nixpkgs>`.
+
 ## `lib.strings.enableFeatureAs` {#function-library-lib.strings.enableFeatureAs}
 
 Create an --{enable-<feat>=<value>,disable-<feat>} string that can be passed to
@@ -1151,6 +1249,8 @@ enableFeatureAs false "shared" (throw "ignored")
 ```
 :::
 
+Located at [lib/strings.nix:819](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L819) in `<nixpkgs>`.
+
 ## `lib.strings.withFeature` {#function-library-lib.strings.withFeature}
 
 Create an --{with,without}-<feat> string that can be passed to
@@ -1177,6 +1277,8 @@ withFeature false "shared"
 ```
 :::
 
+Located at [lib/strings.nix:830](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L830) in `<nixpkgs>`.
+
 ## `lib.strings.withFeatureAs` {#function-library-lib.strings.withFeatureAs}
 
 Create an --{with-<feat>=<value>,without-<feat>} string that can be passed to
@@ -1208,6 +1310,8 @@ withFeatureAs false "shared" (throw "ignored")
 ```
 :::
 
+Located at [lib/strings.nix:843](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L843) in `<nixpkgs>`.
+
 ## `lib.strings.fixedWidthString` {#function-library-lib.strings.fixedWidthString}
 
 **Type**: `fixedWidthString :: int -> string -> string -> string`
@@ -1242,6 +1346,8 @@ fixedWidthString 5 "0" (toString 15)
 ```
 :::
 
+Located at [lib/strings.nix:857](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L857) in `<nixpkgs>`.
+
 ## `lib.strings.fixedWidthNumber` {#function-library-lib.strings.fixedWidthNumber}
 
 Format a number adding leading zeroes up to fixed width.
@@ -1265,6 +1371,8 @@ fixedWidthNumber 5 15
 ```
 :::
 
+Located at [lib/strings.nix:874](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L874) in `<nixpkgs>`.
+
 ## `lib.strings.floatToString` {#function-library-lib.strings.floatToString}
 
 Convert a float to a string, but emit a warning when precision is lost
@@ -1287,11 +1395,15 @@ floatToString 0.0000001
 ```
 :::
 
+Located at [lib/strings.nix:886](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L886) in `<nixpkgs>`.
+
 ## `lib.strings.isCoercibleToString` {#function-library-lib.strings.isCoercibleToString}
 
 Soft-deprecated function. While the original implementation is available as
 isConvertibleWithToString, consider using isStringLike instead, if suitable.
 
+Located at [lib/strings.nix:894](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L894) in `<nixpkgs>`.
+
 ## `lib.strings.isConvertibleWithToString` {#function-library-lib.strings.isConvertibleWithToString}
 
 Check whether a list or other value can be passed to toString.
@@ -1304,6 +1416,8 @@ null, bool, list of similarly coercible values.
 : Function argument
 
 
+Located at [lib/strings.nix:903](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L903) in `<nixpkgs>`.
+
 ## `lib.strings.isStringLike` {#function-library-lib.strings.isStringLike}
 
 Check whether a value can be coerced to a string.
@@ -1317,6 +1431,8 @@ string interpolations and in most functions that expect a string.
 : Function argument
 
 
+Located at [lib/strings.nix:914](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L914) in `<nixpkgs>`.
+
 ## `lib.strings.isStorePath` {#function-library-lib.strings.isStorePath}
 
 Check whether a value is a store path.
@@ -1341,6 +1457,8 @@ isStorePath [] || isStorePath 42 || isStorePath {} || …
 ```
 :::
 
+Located at [lib/strings.nix:932](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L932) in `<nixpkgs>`.
+
 ## `lib.strings.toInt` {#function-library-lib.strings.toInt}
 
 **Type**: `string -> int`
@@ -1374,6 +1492,8 @@ toInt "3.14"
 ```
 :::
 
+Located at [lib/strings.nix:962](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L962) in `<nixpkgs>`.
+
 ## `lib.strings.toIntBase10` {#function-library-lib.strings.toIntBase10}
 
 **Type**: `string -> int`
@@ -1406,6 +1526,8 @@ toIntBase10 "3.14"
 ```
 :::
 
+Located at [lib/strings.nix:1013](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1013) in `<nixpkgs>`.
+
 ## `lib.strings.readPathsFromFile` {#function-library-lib.strings.readPathsFromFile}
 
 Read a list of paths from `file`, relative to the `rootPath`.
@@ -1428,6 +1550,8 @@ readPathsFromFile /prefix
 ```
 :::
 
+Located at [lib/strings.nix:1056](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1056) in `<nixpkgs>`.
+
 ## `lib.strings.fileContents` {#function-library-lib.strings.fileContents}
 
 **Type**: `fileContents :: path -> string`
@@ -1450,6 +1574,8 @@ fileContents ./version
 ```
 :::
 
+Located at [lib/strings.nix:1076](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1076) in `<nixpkgs>`.
+
 ## `lib.strings.sanitizeDerivationName` {#function-library-lib.strings.sanitizeDerivationName}
 
 **Type**: `sanitizeDerivationName :: String -> String`
@@ -1469,6 +1595,8 @@ sanitizeDerivationName pkgs.hello
 ```
 :::
 
+Located at [lib/strings.nix:1091](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1091) in `<nixpkgs>`.
+
 ## `lib.strings.levenshtein` {#function-library-lib.strings.levenshtein}
 
 **Type**: `levenshtein :: string -> string -> int`
@@ -1500,6 +1628,8 @@ levenshtein "hello" "Heyo"
 ```
 :::
 
+Located at [lib/strings.nix:1130](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1130) in `<nixpkgs>`.
+
 ## `lib.strings.commonPrefixLength` {#function-library-lib.strings.commonPrefixLength}
 
 Returns the length of the prefix common to both strings.
@@ -1514,6 +1644,8 @@ Returns the length of the prefix common to both strings.
 : Function argument
 
 
+Located at [lib/strings.nix:1151](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1151) in `<nixpkgs>`.
+
 ## `lib.strings.commonSuffixLength` {#function-library-lib.strings.commonSuffixLength}
 
 Returns the length of the suffix common to both strings.
@@ -1528,6 +1660,8 @@ Returns the length of the suffix common to both strings.
 : Function argument
 
 
+Located at [lib/strings.nix:1159](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1159) in `<nixpkgs>`.
+
 ## `lib.strings.levenshteinAtMost` {#function-library-lib.strings.levenshteinAtMost}
 
 **Type**: `levenshteinAtMost :: int -> string -> string -> bool`
@@ -1552,4 +1686,6 @@ levenshteinAtMost 3 "This is a sentence" "this is a sentense."
 ```
 :::
 
+Located at [lib/strings.nix:1183](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1183) in `<nixpkgs>`.
+
 
diff --git a/test/strings.json b/test/strings.json
new file mode 100644
index 0000000..c34081a
--- /dev/null
+++ b/test/strings.json
@@ -0,0 +1,94 @@
+{
+  "lib.strings.addContextFrom": "[lib/strings.nix:587](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L587) in `<nixpkgs>`",
+  "lib.strings.charToInt": "[lib/strings.nix:378](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L378) in `<nixpkgs>`",
+  "lib.strings.commonPrefixLength": "[lib/strings.nix:1151](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1151) in `<nixpkgs>`",
+  "lib.strings.commonSuffixLength": "[lib/strings.nix:1159](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1159) in `<nixpkgs>`",
+  "lib.strings.compareVersions": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.concatImapStrings": "[lib/strings.nix:70](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L70) in `<nixpkgs>`",
+  "lib.strings.concatImapStringsSep": "[lib/strings.nix:127](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L127) in `<nixpkgs>`",
+  "lib.strings.concatLines": "[lib/strings.nix:144](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L144) in `<nixpkgs>`",
+  "lib.strings.concatMapStrings": "[lib/strings.nix:59](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L59) in `<nixpkgs>`",
+  "lib.strings.concatMapStringsSep": "[lib/strings.nix:110](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L110) in `<nixpkgs>`",
+  "lib.strings.concatStrings": "[lib/strings.nix:49](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L49) in `<nixpkgs>`",
+  "lib.strings.concatStringsSep": "[lib/strings.nix:97](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L97) in `<nixpkgs>`",
+  "lib.strings.elem": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.elemAt": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.enableFeature": "[lib/strings.nix:806](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L806) in `<nixpkgs>`",
+  "lib.strings.enableFeatureAs": "[lib/strings.nix:819](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L819) in `<nixpkgs>`",
+  "lib.strings.escape": "[lib/strings.nix:389](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L389) in `<nixpkgs>`",
+  "lib.strings.escapeC": "[lib/strings.nix:402](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L402) in `<nixpkgs>`",
+  "lib.strings.escapeNixIdentifier": "[lib/strings.nix:529](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L529) in `<nixpkgs>`",
+  "lib.strings.escapeNixString": "[lib/strings.nix:507](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L507) in `<nixpkgs>`",
+  "lib.strings.escapeRegex": "[lib/strings.nix:517](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L517) in `<nixpkgs>`",
+  "lib.strings.escapeShellArg": "[lib/strings.nix:427](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L427) in `<nixpkgs>`",
+  "lib.strings.escapeShellArgs": "[lib/strings.nix:437](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L437) in `<nixpkgs>`",
+  "lib.strings.escapeURL": "[lib/strings.nix:413](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L413) in `<nixpkgs>`",
+  "lib.strings.escapeXML": "[lib/strings.nix:543](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L543) in `<nixpkgs>`",
+  "lib.strings.fileContents": "[lib/strings.nix:1076](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1076) in `<nixpkgs>`",
+  "lib.strings.filter": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.fixedWidthNumber": "[lib/strings.nix:874](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L874) in `<nixpkgs>`",
+  "lib.strings.fixedWidthString": "[lib/strings.nix:857](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L857) in `<nixpkgs>`",
+  "lib.strings.floatToString": "[lib/strings.nix:886](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L886) in `<nixpkgs>`",
+  "lib.strings.fromJSON": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.getName": "[lib/strings.nix:702](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L702) in `<nixpkgs>`",
+  "lib.strings.getVersion": "[lib/strings.nix:719](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L719) in `<nixpkgs>`",
+  "lib.strings.hasInfix": "[lib/strings.nix:317](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L317) in `<nixpkgs>`",
+  "lib.strings.hasPrefix": "[lib/strings.nix:254](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L254) in `<nixpkgs>`",
+  "lib.strings.hasSuffix": "[lib/strings.nix:280](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L280) in `<nixpkgs>`",
+  "lib.strings.head": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.intersperse": "[lib/strings.nix:80](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L80) in `<nixpkgs>`",
+  "lib.strings.isAttrs": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.isCoercibleToString": "[lib/strings.nix:894](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L894) in `<nixpkgs>`",
+  "lib.strings.isConvertibleWithToString": "[lib/strings.nix:903](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L903) in `<nixpkgs>`",
+  "lib.strings.isInt": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.isList": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.isPath": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.isStorePath": "[lib/strings.nix:932](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L932) in `<nixpkgs>`",
+  "lib.strings.isString": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.isStringLike": "[lib/strings.nix:914](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L914) in `<nixpkgs>`",
+  "lib.strings.isValidPosixName": "[lib/strings.nix:449](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L449) in `<nixpkgs>`",
+  "lib.strings.levenshtein": "[lib/strings.nix:1130](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1130) in `<nixpkgs>`",
+  "lib.strings.levenshteinAtMost": "[lib/strings.nix:1183](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1183) in `<nixpkgs>`",
+  "lib.strings.lowerChars": "[lib/strings.nix:551](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L551) in `<nixpkgs>`",
+  "lib.strings.makeBinPath": "[lib/strings.nix:202](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L202) in `<nixpkgs>`",
+  "lib.strings.makeLibraryPath": "[lib/strings.nix:193](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L193) in `<nixpkgs>`",
+  "lib.strings.makeSearchPath": "[lib/strings.nix:157](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L157) in `<nixpkgs>`",
+  "lib.strings.makeSearchPathOutput": "[lib/strings.nix:175](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L175) in `<nixpkgs>`",
+  "lib.strings.match": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.mesonBool": "[lib/strings.nix:773](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L773) in `<nixpkgs>`",
+  "lib.strings.mesonEnable": "[lib/strings.nix:792](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L792) in `<nixpkgs>`",
+  "lib.strings.mesonOption": "[lib/strings.nix:754](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L754) in `<nixpkgs>`",
+  "lib.strings.nameFromURL": "[lib/strings.nix:735](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L735) in `<nixpkgs>`",
+  "lib.strings.normalizePath": "[lib/strings.nix:212](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L212) in `<nixpkgs>`",
+  "lib.strings.optionalString": "[lib/strings.nix:238](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L238) in `<nixpkgs>`",
+  "lib.strings.parseDrvName": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.readFile": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.readPathsFromFile": "[lib/strings.nix:1056](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1056) in `<nixpkgs>`",
+  "lib.strings.removePrefix": "[lib/strings.nix:614](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L614) in `<nixpkgs>`",
+  "lib.strings.removeSuffix": "[lib/strings.nix:647](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L647) in `<nixpkgs>`",
+  "lib.strings.replaceChars": "[lib/strings.nix:548](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L548) in `<nixpkgs>`",
+  "lib.strings.replaceStrings": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.sanitizeDerivationName": "[lib/strings.nix:1091](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1091) in `<nixpkgs>`",
+  "lib.strings.split": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.splitString": "[lib/strings.nix:598](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L598) in `<nixpkgs>`",
+  "lib.strings.storeDir": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.stringAsChars": "[lib/strings.nix:359](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L359) in `<nixpkgs>`",
+  "lib.strings.stringLength": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.stringToCharacters": "[lib/strings.nix:347](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L347) in `<nixpkgs>`",
+  "lib.strings.substring": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.tail": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.toInt": "[lib/strings.nix:962](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L962) in `<nixpkgs>`",
+  "lib.strings.toIntBase10": "[lib/strings.nix:1013](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L1013) in `<nixpkgs>`",
+  "lib.strings.toJSON": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.toLower": "[lib/strings.nix:562](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L562) in `<nixpkgs>`",
+  "lib.strings.toShellVar": "[lib/strings.nix:469](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L469) in `<nixpkgs>`",
+  "lib.strings.toShellVars": "[lib/strings.nix:497](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L497) in `<nixpkgs>`",
+  "lib.strings.toUpper": "[lib/strings.nix:572](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L572) in `<nixpkgs>`",
+  "lib.strings.typeOf": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.unsafeDiscardStringContext": "[lib/strings.nix:15](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L15) in `<nixpkgs>`",
+  "lib.strings.upperChars": "[lib/strings.nix:552](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L552) in `<nixpkgs>`",
+  "lib.strings.versionAtLeast": "[lib/strings.nix:690](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L690) in `<nixpkgs>`",
+  "lib.strings.versionOlder": "[lib/strings.nix:678](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L678) in `<nixpkgs>`",
+  "lib.strings.withFeature": "[lib/strings.nix:830](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L830) in `<nixpkgs>`",
+  "lib.strings.withFeatureAs": "[lib/strings.nix:843](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L843) in `<nixpkgs>`"
+}

From 0367b506c10e3d2e33c5f362d23f3da654486449 Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Thu, 22 Jun 2023 21:25:43 +0200
Subject: [PATCH 5/6] handle inherited exports properly

previously we would ignore exported functions that were defined in let
bindings. this is obviously not ideal.
---
 src/commonmark.rs                            |   6 +-
 src/main.rs                                  | 119 +++++++++++++++----
 src/snapshots/nixdoc__inherited_exports.snap |  24 ++++
 test/inherited-exports.nix                   |  31 +++++
 4 files changed, 157 insertions(+), 23 deletions(-)
 create mode 100644 src/snapshots/nixdoc__inherited_exports.snap
 create mode 100644 test/inherited-exports.nix

diff --git a/src/commonmark.rs b/src/commonmark.rs
index b7910d6..6025889 100644
--- a/src/commonmark.rs
+++ b/src/commonmark.rs
@@ -23,7 +23,7 @@ use std::io::Write;
 
 /// Represent a single function argument name and its (optional)
 /// doc-string.
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct SingleArg {
     pub name: String,
     pub doc: Option<String>,
@@ -31,7 +31,7 @@ pub struct SingleArg {
 
 /// Represent a function argument, which is either a flat identifier
 /// or a pattern set.
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub enum Argument {
     /// Flat function argument (e.g. `n: n * 2`).
     Flat(SingleArg),
@@ -73,7 +73,7 @@ impl Argument {
 }
 
 /// Represents a single manual section describing a library function.
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct ManualEntry {
     /// Name of the function category (e.g. 'strings', 'trivial', 'attrsets')
     pub category: String,
diff --git a/src/main.rs b/src/main.rs
index 0291a91..87514e9 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -30,12 +30,13 @@ mod commonmark;
 
 use self::commonmark::*;
 use rnix::{
-    ast::{AstToken, AttrSet, AttrpathValue, Comment, Expr, Lambda, Param},
+    ast::{AstToken, Attr, AttrpathValue, Comment, Expr, Inherit, Lambda, LetIn, Param},
     SyntaxKind, SyntaxNode,
 };
 use rowan::{ast::AstNode, WalkEvent};
 use std::fs;
 
+use std::collections::HashMap;
 use std::io;
 use std::io::Write;
 
@@ -85,6 +86,24 @@ struct DocItem {
     args: Vec<Argument>,
 }
 
+impl DocItem {
+    fn to_entry(self, category: &str) -> ManualEntry {
+        ManualEntry {
+            category: category.to_string(),
+            name: self.name,
+            description: self
+                .comment
+                .doc
+                .split("\n\n")
+                .map(|s| s.to_string())
+                .collect(),
+            fn_type: self.comment.doc_type,
+            example: self.comment.example,
+            args: self.args,
+        }
+    }
+}
+
 /// Retrieve documentation comments.
 fn retrieve_doc_comment(node: &SyntaxNode) -> Option<String> {
     // if the current node has a doc comment it'll be immediately preceded by that comment,
@@ -246,26 +265,68 @@ fn collect_entry_information(entry: AttrpathValue) -> Option<DocItem> {
     }
 }
 
+fn collect_bindings(
+    node: &SyntaxNode,
+    category: &str,
+    scope: HashMap<String, ManualEntry>,
+) -> Vec<ManualEntry> {
+    for ev in node.preorder() {
+        match ev {
+            WalkEvent::Enter(n) if n.kind() == SyntaxKind::NODE_ATTR_SET => {
+                let mut entries = vec![];
+                for child in n.children() {
+                    if let Some(apv) = AttrpathValue::cast(child.clone()) {
+                        entries
+                            .extend(collect_entry_information(apv).map(|di| di.to_entry(category)));
+                    } else if let Some(inh) = Inherit::cast(child) {
+                        // `inherit (x) ...` needs much more handling than we can
+                        // reasonably do here
+                        if inh.from().is_some() {
+                            continue;
+                        }
+                        entries.extend(inh.attrs().filter_map(|a| match a {
+                            Attr::Ident(i) => scope.get(&i.syntax().text().to_string()).cloned(),
+                            // ignore non-ident keys. these aren't useful as lib
+                            // functions in general anyway.
+                            _ => None,
+                        }));
+                    }
+                }
+                return entries;
+            }
+            _ => (),
+        }
+    }
+
+    vec![]
+}
+
 fn collect_entries(root: rnix::Root, category: &str) -> Vec<ManualEntry> {
-    root.syntax()
-        .preorder()
-        .filter_map(|ev| match ev {
-            WalkEvent::Enter(n) => Some(n),
-            _ => None,
-        })
-        .filter_map(AttrSet::cast)
-        .flat_map(|n| n.syntax().children())
-        .filter_map(AttrpathValue::cast)
-        .filter_map(collect_entry_information)
-        .map(|d| ManualEntry {
-            category: category.to_string(),
-            name: d.name,
-            description: d.comment.doc.split("\n\n").map(|s| s.to_string()).collect(),
-            fn_type: d.comment.doc_type,
-            example: d.comment.example,
-            args: d.args,
-        })
-        .collect()
+    // we will look into the top-level let and its body for function docs.
+    // we only need a single level of scope for this.
+    // since only the body can export a function we don't need to implement
+    // mutually recursive resolution.
+    for ev in root.syntax().preorder() {
+        match ev {
+            WalkEvent::Enter(n) if n.kind() == SyntaxKind::NODE_LET_IN => {
+                return collect_bindings(
+                    LetIn::cast(n.clone()).unwrap().body().unwrap().syntax(),
+                    category,
+                    n.children()
+                        .filter_map(AttrpathValue::cast)
+                        .filter_map(collect_entry_information)
+                        .map(|di| (di.name.to_string(), di.to_entry(category)))
+                        .collect(),
+                );
+            }
+            WalkEvent::Enter(n) if n.kind() == SyntaxKind::NODE_ATTR_SET => {
+                return collect_bindings(&n, category, Default::default());
+            }
+            _ => (),
+        }
+    }
+
+    vec![]
 }
 
 fn main() {
@@ -341,3 +402,21 @@ fn test_arg_formatting() {
 
     insta::assert_snapshot!(output);
 }
+
+#[test]
+fn test_inherited_exports() {
+    let mut output = Vec::new();
+    let src = fs::read_to_string("test/inherited-exports.nix").unwrap();
+    let nix = rnix::Root::parse(&src).ok().expect("failed to parse input");
+    let category = "let";
+
+    for entry in collect_entries(nix, category) {
+        entry
+            .write_section(&Default::default(), &mut output)
+            .expect("Failed to write section")
+    }
+
+    let output = String::from_utf8(output).expect("not utf8");
+
+    insta::assert_snapshot!(output);
+}
diff --git a/src/snapshots/nixdoc__inherited_exports.snap b/src/snapshots/nixdoc__inherited_exports.snap
new file mode 100644
index 0000000..ff6cbbc
--- /dev/null
+++ b/src/snapshots/nixdoc__inherited_exports.snap
@@ -0,0 +1,24 @@
+---
+source: src/main.rs
+expression: output
+---
+## `lib.let.concatStrings` {#function-library-lib.let.concatStrings}
+
+**Type**: `concatStrings :: [string] -> string`
+
+Concatenate a list of strings.
+
+::: {.example #function-library-example-lib.let.concatStrings}
+# `lib.let.concatStrings` usage example
+
+```nix
+concatStrings ["foo" "bar"]
+=> "foobar"
+```
+:::
+
+## `lib.let.foo2` {#function-library-lib.let.foo2}
+
+this should be found
+
+
diff --git a/test/inherited-exports.nix b/test/inherited-exports.nix
new file mode 100644
index 0000000..64e457a
--- /dev/null
+++ b/test/inherited-exports.nix
@@ -0,0 +1,31 @@
+{ lib }:
+
+let
+  /* Concatenate a list of strings.
+
+    Type: concatStrings :: [string] -> string
+
+     Example:
+       concatStrings ["foo" "bar"]
+       => "foobar"
+  */
+  concatStrings = builtins.concatStringsSep "";
+
+  /* this should be ignored because it's inherited from an explicit source */
+  from = a: a;
+in {
+  inherit concatStrings;
+  inherit ({}) from;
+
+  foo1 = {
+    /* this should be ignored because it's in a nested attrset */
+    bar = a: a;
+  };
+
+  /* this should be found */
+  foo2 =
+    let
+      /* this should be ignored because it's in a nested let */
+      bar = a: a;
+    in bar;
+}

From 53d73965cdf0400c6d3e7839b65662d1135c5ad1 Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Thu, 22 Jun 2023 23:33:36 +0200
Subject: [PATCH 6/6] ignore line comments on attributes

line comments on attributes (rather than lambda arguments) are usually
used to convey todos or deprecation information. we should probably not
include those in the docs.
---
 src/main.rs                              | 85 +++++++++++++++++-------
 src/snapshots/nixdoc__line_comments.snap | 24 +++++++
 src/snapshots/nixdoc__main.snap          | 12 ----
 test/line-comments.nix                   | 15 +++++
 4 files changed, 100 insertions(+), 36 deletions(-)
 create mode 100644 src/snapshots/nixdoc__line_comments.snap
 create mode 100644 test/line-comments.nix

diff --git a/src/main.rs b/src/main.rs
index 87514e9..6e40469 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -105,10 +105,10 @@ impl DocItem {
 }
 
 /// Retrieve documentation comments.
-fn retrieve_doc_comment(node: &SyntaxNode) -> Option<String> {
+fn retrieve_doc_comment(node: &SyntaxNode, allow_line_comments: bool) -> Option<String> {
     // if the current node has a doc comment it'll be immediately preceded by that comment,
     // or there will be a whitespace token and *then* the comment tokens before it. we merge
-    // multiple single-line comments into one large comment if they are on adjacent lines for
+    // multiple line comments into one large comment if they are on adjacent lines for
     // documentation simplicity.
     let mut token = node.first_token()?.prev_token()?;
     if token.kind() == SyntaxKind::TOKEN_WHITESPACE {
@@ -118,36 +118,55 @@ fn retrieve_doc_comment(node: &SyntaxNode) -> Option<String> {
         return None;
     }
 
-    // backtrack to the start of the doc comment, allowing only a single multi-line comment
-    // or adjacent single-line comments.
-    // we don't care much about optimization here, doc comments aren't long enough for that.
+    // if we want to ignore line comments (eg because they may contain deprecation
+    // comments on attributes) we'll backtrack to the first preceding multiline comment.
+    while !allow_line_comments && token.text().starts_with("#") {
+        token = token.prev_token()?;
+        if token.kind() == SyntaxKind::TOKEN_WHITESPACE {
+            token = token.prev_token()?;
+        }
+        if token.kind() != SyntaxKind::TOKEN_COMMENT {
+            return None;
+        }
+    }
+
     if token.text().starts_with("/*") {
         return Some(Comment::cast(token)?.text().to_string());
     }
-    let mut result = String::new();
-    while let Some(comment) = Comment::cast(token) {
-        result.insert_str(0, comment.text());
-        let ws = match comment.syntax().prev_token() {
-            Some(t) if t.kind() == SyntaxKind::TOKEN_WHITESPACE => t,
-            _ => break,
-        };
-        // only adjacent lines continue a doc comment, empty lines do not.
-        match ws.text().strip_prefix("\n") {
-            Some(trail) if !trail.contains("\n") => result.insert_str(0, ws.text()),
-            _ => break,
+
+    // backtrack to the start of the doc comment, allowing only adjacent line comments.
+    // we don't care much about optimization here, doc comments aren't long enough for that.
+    if token.text().starts_with("#") {
+        let mut result = String::new();
+        while let Some(comment) = Comment::cast(token) {
+            if !comment.syntax().text().starts_with("#") {
+                break;
+            }
+            result.insert_str(0, comment.text().trim());
+            let ws = match comment.syntax().prev_token() {
+                Some(t) if t.kind() == SyntaxKind::TOKEN_WHITESPACE => t,
+                _ => break,
+            };
+            // only adjacent lines continue a doc comment, empty lines do not.
+            match ws.text().strip_prefix("\n") {
+                Some(trail) if !trail.contains("\n") => result.insert_str(0, " "),
+                _ => break,
+            }
+            token = match ws.prev_token() {
+                Some(c) => c,
+                _ => break,
+            };
         }
-        token = match ws.prev_token() {
-            Some(c) => c,
-            _ => break,
-        };
+        return Some(result);
     }
-    Some(result)
+
+    None
 }
 
 /// Transforms an AST node into a `DocItem` if it has a leading
 /// documentation comment.
 fn retrieve_doc_item(node: &AttrpathValue) -> Option<DocItem> {
-    let comment = retrieve_doc_comment(node.syntax())?;
+    let comment = retrieve_doc_comment(node.syntax(), false)?;
     let ident = node.attrpath().unwrap();
     // TODO this should join attrs() with '.' to handle whitespace, dynamic attrs and string
     // attrs. none of these happen in nixpkgs lib, and the latter two should probably be
@@ -219,7 +238,7 @@ fn collect_lambda_args(mut lambda: Lambda) -> Vec<Argument> {
             Param::IdentParam(id) => {
                 args.push(Argument::Flat(SingleArg {
                     name: id.to_string(),
-                    doc: retrieve_doc_comment(id.syntax()),
+                    doc: retrieve_doc_comment(id.syntax(), true),
                 }));
             }
             Param::Pattern(pat) => {
@@ -227,7 +246,7 @@ fn collect_lambda_args(mut lambda: Lambda) -> Vec<Argument> {
                     .pat_entries()
                     .map(|entry| SingleArg {
                         name: entry.ident().unwrap().to_string(),
-                        doc: retrieve_doc_comment(entry.syntax()),
+                        doc: retrieve_doc_comment(entry.syntax(), true),
                     })
                     .collect();
 
@@ -420,3 +439,21 @@ fn test_inherited_exports() {
 
     insta::assert_snapshot!(output);
 }
+
+#[test]
+fn test_line_comments() {
+    let mut output = Vec::new();
+    let src = fs::read_to_string("test/line-comments.nix").unwrap();
+    let nix = rnix::Root::parse(&src).ok().expect("failed to parse input");
+    let category = "let";
+
+    for entry in collect_entries(nix, category) {
+        entry
+            .write_section(&Default::default(), &mut output)
+            .expect("Failed to write section")
+    }
+
+    let output = String::from_utf8(output).expect("not utf8");
+
+    insta::assert_snapshot!(output);
+}
diff --git a/src/snapshots/nixdoc__line_comments.snap b/src/snapshots/nixdoc__line_comments.snap
new file mode 100644
index 0000000..2b9ed97
--- /dev/null
+++ b/src/snapshots/nixdoc__line_comments.snap
@@ -0,0 +1,24 @@
+---
+source: src/main.rs
+expression: output
+---
+## `lib.let.shown` {#function-library-lib.let.shown}
+
+is a doc comment
+
+`a`
+
+: a doc comment
+
+
+`b`
+
+: also a doc comment
+
+
+`c`
+
+: a doc comment with continuation
+
+
+
diff --git a/src/snapshots/nixdoc__main.snap b/src/snapshots/nixdoc__main.snap
index 01e6edc..e686ef1 100644
--- a/src/snapshots/nixdoc__main.snap
+++ b/src/snapshots/nixdoc__main.snap
@@ -806,18 +806,6 @@ escapeXML ''"test" 'test' < & >''
 
 Located at [lib/strings.nix:543](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L543) in `<nixpkgs>`.
 
-## `lib.strings.replaceChars` {#function-library-lib.strings.replaceChars}
-
-warning added 12-12-2022
-
-Located at [lib/strings.nix:548](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L548) in `<nixpkgs>`.
-
-## `lib.strings.lowerChars` {#function-library-lib.strings.lowerChars}
-
-Case conversion utilities.
-
-Located at [lib/strings.nix:551](https://github.com/NixOS/nixpkgs/blob/580dd2124db98c13c3798af23c2ecf6277ec7d9e/lib/strings.nix#L551) in `<nixpkgs>`.
-
 ## `lib.strings.toLower` {#function-library-lib.strings.toLower}
 
 **Type**: `toLower :: string -> string`
diff --git a/test/line-comments.nix b/test/line-comments.nix
new file mode 100644
index 0000000..2d7378e
--- /dev/null
+++ b/test/line-comments.nix
@@ -0,0 +1,15 @@
+{
+  # not a doc comment
+  hidden = a: a;
+
+  /* is a doc comment */
+  shown =
+    # a doc comment
+    a:
+    /* also a doc comment */
+    b:
+    # a doc comment
+    # with continuation
+    c:
+    {};
+}