add configurable nix-manual references

flake.lock

@@ -52,6 +52,22 @@
         "type": "github"
       }
     },
+    "flake-compat_3": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1673956053,
+        "narHash": "sha256-4gtG9iQuiKITOjNQQeQIpoIB6b16fm+504Ch3sNKLd8=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "35bb57c0c8d8b62bbfd284272c928ceb64ddbde9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
     "flake-parts": {
       "inputs": {
         "nixpkgs-lib": [
@@ -131,6 +147,22 @@
         "type": "github"
       }
     },
+    "libgit2": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1697646580,
+        "narHash": "sha256-oX4Z3S9WtJlwvj0uH9HlYcWv+x1hqp8mhXl7HsLu2f0=",
+        "owner": "libgit2",
+        "repo": "libgit2",
+        "rev": "45fd9ed7ae1a9b74b957ef4f337bc3c8b3df01b5",
+        "type": "github"
+      },
+      "original": {
+        "owner": "libgit2",
+        "repo": "libgit2",
+        "type": "github"
+      }
+    },
     "lowdown-src": {
       "flake": false,
       "locked": {
@@ -169,6 +201,28 @@
         "type": "github"
       }
     },
+    "nix-master": {
+      "inputs": {
+        "flake-compat": "flake-compat_2",
+        "libgit2": "libgit2",
+        "nixpkgs": "nixpkgs_2",
+        "nixpkgs-regression": "nixpkgs-regression_2"
+      },
+      "locked": {
+        "lastModified": 1704445904,
+        "narHash": "sha256-bvpPdHEx3p1157sKL5fjiwmCqvBtIzPixeEb2hCQWFk=",
+        "owner": "NixOS",
+        "repo": "nix",
+        "rev": "cbf99c71c6f58579174c1c7649a5421c1d2ba9b0",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "master",
+        "repo": "nix",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
         "lastModified": 1695283060,
@@ -216,6 +270,22 @@
         "type": "github"
       }
     },
+    "nixpkgs-regression_2": {
+      "locked": {
+        "lastModified": 1643052045,
+        "narHash": "sha256-uGJ0VXIhWKGXxkeNnq4TvV3CIOkUJ3PAoLZ3HMzNVMw=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "215d4d0fd80ca5163643b03a33fde804a29cc1e2",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "215d4d0fd80ca5163643b03a33fde804a29cc1e2",
+        "type": "github"
+      }
+    },
     "nixpkgs-stable": {
       "locked": {
         "lastModified": 1685801374,
@@ -233,6 +303,22 @@
       }
     },
     "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1704018918,
+        "narHash": "sha256-erjg/HrpC9liEfm7oLqb8GXCqsxaFwIIPqCsknW5aFY=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "2c9c58e98243930f8cb70387934daa4bc8b00373",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-23.05-small",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_3": {
       "locked": {
         "lastModified": 1700390070,
         "narHash": "sha256-de9KYi8rSJpqvBfNwscWdalIJXPo8NjdIZcEJum1mH0=",
@@ -249,7 +335,7 @@
     },
     "pre-commit-hooks": {
       "inputs": {
-        "flake-compat": "flake-compat_2",
+        "flake-compat": "flake-compat_3",
         "flake-utils": "flake-utils",
         "gitignore": "gitignore",
         "nixpkgs": [
@@ -277,7 +363,8 @@
         "flake-parts": "flake-parts",
         "floco": "floco",
         "nix": "nix",
-        "nixpkgs": "nixpkgs_2",
+        "nix-master": "nix-master",
+        "nixpkgs": "nixpkgs_3",
         "nixpkgs-master": "nixpkgs-master",
         "pre-commit-hooks": "pre-commit-hooks",
         "treefmt-nix": "treefmt-nix"

flake.nix

@@ -4,6 +4,7 @@
     nixpkgs.url = "nixpkgs/nixos-unstable";
     nixpkgs-master.url = "nixpkgs/master";
 
+    nix-master.url = "github:NixOS/nix/?ref=master";
     # A custom nix version, to introspect lambda values. 
     nix.url = "github:hsjobeki/nix/?ref=feat/positions";
 

salt/flake-module.nix

@@ -1,6 +1,8 @@
-_: {
+{ inputs, ... }: {
   perSystem = { self', inputs', pkgs, ... }:
     let
+      nix-manual = "${inputs.nix-master}/doc/manual/src/language/derivations.md";
+      # https://github.com/NixOS/nix/blob/master/doc/manual/src/language/derivations.md
       salt = pkgs.stdenv.mkDerivation {
         pname = "salt-data";
         version = "0.1.0";
@@ -8,6 +10,7 @@ _: {
         installPhase = ''
           mkdir $out
           cp -rf . $out
+          cp ${nix-manual} $out
         '';
       };
     in

salt/src/manual-link.map.json

@@ -0,0 +1,6 @@
+[
+  {
+    "id": "derivation",
+    "file": "derivations.md"
+  }
+]

website/nix/pdefs.nix

@@ -9284,6 +9284,30 @@
           version = "3.0.3";
         };
       };
+      mdast-squeeze-paragraphs = {
+        "6.0.0" = {
+          depInfo = {
+            "@types/mdast" = {
+              descriptor = "^4.0.0";
+              pin = "4.0.1";
+              runtime = true;
+            };
+            unist-util-visit = {
+              descriptor = "^5.0.0";
+              pin = "5.0.0";
+              runtime = true;
+            };
+          };
+          fetchInfo = {
+            narHash = "sha256-U9UivetJDDuaqlAJYcQd10q2WhdRNTAulK8tXqzN5Bo=";
+            type = "tarball";
+            url = "https://registry.npmjs.org/mdast-squeeze-paragraphs/-/mdast-squeeze-paragraphs-6.0.0.tgz";
+          };
+          ident = "mdast-squeeze-paragraphs";
+          ltype = "file";
+          version = "6.0.0";
+        };
+      };
       mdast-util-definitions = {
         "5.1.2" = {
           depInfo = {
@@ -13391,6 +13415,11 @@
               pin = "11.0.0";
               runtime = true;
             };
+            remark-unlink = {
+              descriptor = "^5.0.0";
+              pin = "5.0.0";
+              runtime = true;
+            };
             seedrandom = {
               descriptor = "^3.0.5";
               pin = "3.0.5";
@@ -14943,6 +14972,9 @@
             "node_modules/markdown-table" = {
               key = "markdown-table/3.0.3";
             };
+            "node_modules/mdast-squeeze-paragraphs" = {
+              key = "mdast-squeeze-paragraphs/6.0.0";
+            };
             "node_modules/mdast-util-definitions" = {
               key = "mdast-util-definitions/5.1.2";
             };
@@ -15950,6 +15982,9 @@
             "node_modules/remark-stringify/node_modules/mdast-util-to-markdown" = {
               key = "mdast-util-to-markdown/2.1.0";
             };
+            "node_modules/remark-unlink" = {
+              key = "remark-unlink/5.0.0";
+            };
             "node_modules/resolve" = {
               key = "resolve/1.22.6";
             };
@@ -17942,6 +17977,35 @@
           version = "11.0.0";
         };
       };
+      remark-unlink = {
+        "5.0.0" = {
+          depInfo = {
+            "@types/mdast" = {
+              descriptor = "^4.0.0";
+              pin = "4.0.1";
+              runtime = true;
+            };
+            mdast-squeeze-paragraphs = {
+              descriptor = "^6.0.0";
+              pin = "6.0.0";
+              runtime = true;
+            };
+            unist-util-visit = {
+              descriptor = "^5.0.0";
+              pin = "5.0.0";
+              runtime = true;
+            };
+          };
+          fetchInfo = {
+            narHash = "sha256-g+s3EDrnPS/2FOA0Mi/qR1J6FP3eXP2PeQXKX0f6kp8=";
+            type = "tarball";
+            url = "https://registry.npmjs.org/remark-unlink/-/remark-unlink-5.0.0.tgz";
+          };
+          ident = "remark-unlink";
+          ltype = "file";
+          version = "5.0.0";
+        };
+      };
       resolve = {
         "1.22.6" = {
           binInfo = {

website/package-lock.json

@@ -49,6 +49,7 @@
         "remark-parse": "^11.0.0",
         "remark-rehype": "^11.0.0",
         "remark-stringify": "^11.0.0",
+        "remark-unlink": "^5.0.0",
         "seedrandom": "^3.0.5",
         "unified": "^11.0.4",
         "unist-util-visit": "^5.0.0",
@@ -5758,6 +5759,19 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/mdast-squeeze-paragraphs": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-squeeze-paragraphs/-/mdast-squeeze-paragraphs-6.0.0.tgz",
+      "integrity": "sha512-6NDbJPTg0M0Ye+TlYwX1KJ1LFbp515P2immRJyJQhc9Na9cetHzSoHNYIQcXpANEAP1sm9yd/CTZU2uHqR5A+w==",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "unist-util-visit": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/mdast-util-definitions": {
       "version": "5.1.2",
       "resolved": "https://registry.npmjs.org/mdast-util-definitions/-/mdast-util-definitions-5.1.2.tgz",
@@ -10980,6 +10994,20 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/remark-unlink": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/remark-unlink/-/remark-unlink-5.0.0.tgz",
+      "integrity": "sha512-8NFrI3SecxhOLb734tKaxcU//lNDABabz1I26MGjdlpkUg1I+Fr7lyqL9ckxaCB4kErXD10mScPD7yhCXX4Pfw==",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-squeeze-paragraphs": "^6.0.0",
+        "unist-util-visit": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/resolve": {
       "version": "1.22.6",
       "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.6.tgz",
@@ -16251,6 +16279,15 @@
       "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-3.0.3.tgz",
       "integrity": "sha512-Z1NL3Tb1M9wH4XESsCDEksWoKTdlUafKc4pt0GRwjUyXaCFZ+dc3g2erqB6zm3szA2IUSi7VnPI+o/9jnxh9hw=="
     },
+    "mdast-squeeze-paragraphs": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-squeeze-paragraphs/-/mdast-squeeze-paragraphs-6.0.0.tgz",
+      "integrity": "sha512-6NDbJPTg0M0Ye+TlYwX1KJ1LFbp515P2immRJyJQhc9Na9cetHzSoHNYIQcXpANEAP1sm9yd/CTZU2uHqR5A+w==",
+      "requires": {
+        "@types/mdast": "^4.0.0",
+        "unist-util-visit": "^5.0.0"
+      }
+    },
     "mdast-util-definitions": {
       "version": "5.1.2",
       "resolved": "https://registry.npmjs.org/mdast-util-definitions/-/mdast-util-definitions-5.1.2.tgz",
@@ -19433,6 +19470,16 @@
         }
       }
     },
+    "remark-unlink": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/remark-unlink/-/remark-unlink-5.0.0.tgz",
+      "integrity": "sha512-8NFrI3SecxhOLb734tKaxcU//lNDABabz1I26MGjdlpkUg1I+Fr7lyqL9ckxaCB4kErXD10mScPD7yhCXX4Pfw==",
+      "requires": {
+        "@types/mdast": "^4.0.0",
+        "mdast-squeeze-paragraphs": "^6.0.0",
+        "unist-util-visit": "^5.0.0"
+      }
+    },
     "resolve": {
       "version": "1.22.6",
       "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.6.tgz",

website/package.json

@@ -50,6 +50,7 @@
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.0.0",
     "remark-stringify": "^11.0.0",
+    "remark-unlink": "^5.0.0",
     "seedrandom": "^3.0.5",
     "unified": "^11.0.4",
     "unist-util-visit": "^5.0.0",

website/src/app/f/[...path]/page.tsx

@@ -1,7 +1,7 @@
 import { HighlightBaseline } from "@/components/HighlightBaseline";
 import { ShareButton } from "@/components/ShareButton";
 import { BackButton } from "@/components/BackButton";
-import { Doc, data } from "@/models/data";
+import { Doc, data, manualLinks } from "@/models/data";
 import { getPrimopDescription } from "@/models/primop";
 import { extractHeadings, mdxRenderOptions } from "@/utils";
 import { Box, Divider, Typography, Link, Chip } from "@mui/material";
@@ -136,6 +136,25 @@ const MDX = ({ source }: { source: string }) => (
   />
 );
 
+import fs from "fs";
+import path from "path";
+
+async function getManualSrc(item: Doc): Promise<string | null> {
+  // Path must be at exactly [ "builtins" ":id" ]
+  if (item?.meta?.path?.length != 2 || item?.meta?.path?.[0] !== "builtins") {
+    return null;
+  }
+  const extern = manualLinks.find((link) => link.id === item.meta.path[1]);
+  if (!extern) {
+    return null;
+  }
+  const manPath = path.join(process.cwd(), "src/models/data", extern.file);
+  const source = fs.readFileSync(manPath, { encoding: "utf-8" });
+  // const src = extern.file;
+  // console.log({ source, manPath });
+  return source;
+}
+
 // Multiple versions of this page will be statically generated
 // using the `params` returned by `generateStaticParams`
 export default async function Page(props: { params: { path: string[] } }) {
@@ -152,6 +171,10 @@ export default async function Page(props: { params: { path: string[] } }) {
     signature
   );
 
+  // Some builtins can load external documentation from the official manual
+  // This is configured via "salt" module
+  const externManualSrc = item && (await getManualSrc(item));
+
   const source = mdxSource;
   // Skip generating this builtin.
   // It is internal information of noogle.
@@ -161,7 +184,7 @@ export default async function Page(props: { params: { path: string[] } }) {
 
   return (
     <>
-      <Toc mdxSource={source} title={item?.meta.title} />
+      <Toc mdxSource={source + externManualSrc} title={item?.meta.title} />
       <Box
         component="main"
         data-pagefind-body
@@ -247,9 +270,25 @@ export default async function Page(props: { params: { path: string[] } }) {
                 variant="body1"
                 sx={{ color: "text.secondary", py: 2 }}
               >
-                No documentation found yet.
+                No reference documentation found yet.
               </Typography>
 
+              {externManualSrc && (
+                <>
+                  <Typography
+                    variant="h5"
+                    component={"div"}
+                    sx={{ color: "text.secondary", py: 2, textAlign: "center" }}
+                  >
+                    Noogle found this in the nix manual
+                  </Typography>
+                  <Box sx={{ fontStyle: "italic", p: 1 }}>
+                    <MDX source={externManualSrc} />
+                  </Box>
+                  <Divider />
+                </>
+              )}
+
               <Typography
                 variant="body1"
                 sx={{ color: "text.secondary", py: 2 }}
@@ -265,7 +304,7 @@ export default async function Page(props: { params: { path: string[] } }) {
           <MDX source={source} />
           {meta && <PositionLink meta={meta} content={item?.content} />}
           <div data-pagefind-ignore="all">
-            {(!!meta?.aliases?.length || !!signature) && (
+            {(!!meta?.aliases?.length || (!!signature && !meta?.signature)) && (
               <>
                 <Divider flexItem />
                 <Typography
@@ -275,6 +314,7 @@ export default async function Page(props: { params: { path: string[] } }) {
                     color: "text.secondary",
                     alignSelf: "center",
                     pb: 2,
+                    textAlign: "center",
                   }}
                 >
                   Noogle also knows
@@ -314,7 +354,7 @@ export default async function Page(props: { params: { path: string[] } }) {
           </div>
         </Box>
         <Divider flexItem sx={{ mt: 2 }} />
-        <Suspense fallback={""}>
+        <Suspense fallback={<div />}>
           <FilterProvider>
             <SearchNav />
           </FilterProvider>

website/src/models/data/index.ts

@@ -1,8 +1,13 @@
-// import nixTrivialBuilders from "./build_support.json" assert { type: "json" };
-// import nixBuiltins from "./builtins.json" assert { type: "json" };
-// import nixLibs from "./lib.json" assert { type: "json" };
 import all from "./data.json" assert { type: "json" };
 import types from "./builtins.types.json" assert { type: "json" };
+import links from "./manual-link.map.json" assert { type: "json" };
+
+export type ManualLink = {
+  id: string;
+  file: string;
+};
+
+export const manualLinks = links as ManualLink[];
 
 export type FilePosition = {
   file: string;

website/src/models/nix.ts

@@ -31,7 +31,7 @@ const interpretToken = (token: string): NixType | undefined => {
     return token as NixType;
   } else if (["int", "float", "double"].includes(token)) {
     return "number";
-  } else if (["derivation", "package"].includes(token)) {
+  } else if (["derivation", "package", "fileset"].includes(token)) {
     return "attrset";
   } else if (["storepath"].includes(token) || token.includes("path")) {
     return "path";

website/src/utils.ts

@@ -14,6 +14,7 @@ import rehypeStringify from "rehype-stringify";
 import remarkHeadingId from "remark-heading-id";
 import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
+import remarkUnlink from "remark-unlink";
 
 import { unified } from "unified";
 
@@ -155,6 +156,6 @@ export const mdxRenderOptions: SerializeOptions["mdxOptions"] = {
     [rehypeSlug, {}],
     [rehypeAutolinkHeadings, { behavior: "wrap" }],
   ],
-  remarkPlugins: [remarkHeadingId],
+  remarkPlugins: [remarkHeadingId, remarkUnlink],
   format: "md",
 } as SerializeOptions["mdxOptions"];