Document flake output paths

components.d.ts

@@ -22,6 +22,7 @@ declare module '@vue/runtime-core' {
     ExternalSources: typeof import('./src/components/layout/ExternalSources.vue')['default']
     Features: typeof import('./src/components/layout/Features.vue')['default']
     FeedbackBar: typeof import('./src/components/layout/FeedbackBar.vue')['default']
+    FlakeOutputSchema: typeof import('./src/components/mdx/concepts/FlakeOutputSchema.vue')['default']
     Footer: typeof import('./src/components/layout/Footer.vue')['default']
     Grid2: typeof import('./src/components/layout/Grid2.vue')['default']
     Grid3: typeof import('./src/components/layout/Grid3.vue')['default']

src/assets/css/prose.css

@@ -44,7 +44,9 @@
     .content,
     h2,
     h3,
-    li {
+    h4,
+    li,
+    td {
       code {
         @apply inline-code;
       }
@@ -61,9 +63,8 @@
 
       /* Hoverable heading links */
       &.heading-anchor {
-        @apply float-left text-2xl text-primary no-underline opacity-0;
+        @apply float-left text-primary no-underline opacity-0;
 
-        margin-top: 0.125em;
         margin-left: -1em;
         padding-right: 0.25em;
 

src/components/mdx/concepts/FlakeOutputSchema.vue

@@ -0,0 +1,36 @@
+<template>
+  <div
+    class="not-prose rounded-lg border-1.5 border-light-gray bg-pale py-3 px-5 dark:border-gray dark:bg-inherit"
+  >
+    <div class="space-y-2 md:space-y-3 lg:space-y-4">
+      <pre
+        class="flex overflow-auto whitespace-nowrap break-keep text-base md:text-lg lg:text-xl xl:text-2xl"
+      >
+        <div class="flex flex-col md:space-y-1 lg:space-y-1.5">
+          <span class="font-mono text-lilac dark:text-cerulean">
+            {{ reference }}
+          </span>
+          <span class="font-sans text-xs tracking-tight md:text-sm lg:text-base">
+            <strong>1.</strong> Flake ref
+          </span>
+        </div>
+        <span class="text-dark-gray dark:text-light-gray">#</span>
+        <div class="flex flex-col md:space-y-1.5 lg:space-y-1.5">
+          <span class="font-mono font-light text-blue dark:text-lilac">
+            {{ outputPath }}
+          </span>
+          <span class="font-sans text-xs tracking-tight md:text-sm lg:text-base">
+            <strong>2.</strong> Output path
+          </span>
+        </div>
+      </pre>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const { reference } = defineProps<{
+  reference: string;
+  outputPath: string;
+}>();
+</script>

src/components/mdx/concepts/NixStorePath.vue

@@ -22,14 +22,14 @@
             <strong>2.</strong> Hash part
           </span>
         </div>
-        <span>-</span>
+        <span class="text-dark-gray dark:text-light-gray">-</span>
         <div class="flex flex-col md:space-y-1.5 lg:space-y-1.5">
           <span class="font-mono text-orange dark:text-rose">{{ pkg }}</span>
           <span class="font-sans text-xs tracking-tight md:text-sm lg:text-base" v-if="showExplainer">
             <strong>3.</strong> Package name
           </span>
         </div>
-        <span v-if="bin">/</span>
+        <span v-if="bin" class="text-dark-gray dark:text-light-gray">/</span>
         <div v-if="bin" class="flex flex-col md:space-y-1.5 lg:space-y-1.5">
           <span class="font-mono text-orange dark:text-rose">bin/{{ bin }}</span>
           <span class="font-sans text-xs tracking-tight md:text-sm lg:text-base" v-if="showExplainer">

src/pages/concepts/flakes.mdx

@@ -66,6 +66,7 @@ Here are some example flake references:
 
 Reference | Description
 :---------|:-----------
+`.` | The current directory
 `path:/home/nix-stuff/my-flake` | The `/home/nix-stuff/my-flake` directory on the current host
 `github:DeterminateSystems/zero-to-nix` | The [DeterminateSystems/zero-to-nix][gh-z2n] GitHub repository
 `github:DeterminateSystems/zero-to-nix/other` | The [`other`][other] branch of the [DeterminateSystems/zero-to-nix][gh-z2n] GitHub repository
@@ -194,25 +195,28 @@ Each flake can have many different outputs simultaneously, including but not lim
 
 Flake outputs are defined by a function, which takes an attribute set as input, containing each of the inputs to that flake (named after the chosen identifier in the [inputs](#inputs) section).
 
-### The `lib` output \{#lib}
+### Output paths
 
-In addition to things like packages and NixOS configurations, flakes can also output Nix functions and other values via the `lib` output.
-Here's an example flake that outputs a `sayHello` function that takes a name as an input and outputs a string saying hello to that person:
+[schema][output-schema]
 
-```nix filename=flake.nix
-{
-  outputs = { self }: {
-    lib = {
-      sayHello = name: "Hello there, ${name}!";
-    };
-  };
-}
+<FlakeOutputSchema reference="github:DeterminateSystems/riff" outputPath="packages.aarch64-darwin.riff" client:load />
+
+<FlakeOutputSchema reference="nixpkgs" outputPath="curl" client:load />
+
+```shell
+nix run nixpkgs#curl
 ```
 
-Another Nix flake could then specify this flake as an [input](#inputs) and use `sayHello` for whatever purpose.
-[Nixpkgs], for example, outputs a vast multitude of helper functions and values.
+<FlakeOutputSchema reference="nixpkgs" outputPath="packages.aarch64-darwin.curl" client:load />
 
-### System specificity
+```shell
+nix run nixpkgs#packages.aarch64-darwin.curl
+```
+
+In many cases, you don't need to specify the output type, like `packages` or `devShells`, because Nix can infer them from the command you run.
+You can run the `nix develop` command, for example, only against `devShells` outputs.
+
+#### System specificity
 
 Some flake outputs need to be [system specific][specificity], including [packages], [development environments][env], and [NixOS] configurations.
 Here's an example flake that outputs a package that can be used by `x86_64-linux` systems (64-bit AMD/Intel Linux):
@@ -259,6 +263,30 @@ You can also use Nix functions like this:
 }
 ```
 
+Some output types that don't need to be system specific:
+
+* [Flake templates](#templates)
+* Nixpkgs overlays
+* [NixOS] configurations
+
+### The `lib` output \{#lib}
+
+In addition to things like packages and NixOS configurations, flakes can also output Nix functions and other values via the `lib` output.
+Here's an example flake that outputs a `sayHello` function that takes a name as an input and outputs a string saying hello to that person:
+
+```nix filename=flake.nix
+{
+  outputs = { self }: {
+    lib = {
+      sayHello = name: "Hello there, ${name}!";
+    };
+  };
+}
+```
+
+Another Nix flake could then specify this flake as an [input](#inputs) and use `sayHello` for whatever purpose.
+[Nixpkgs], for example, outputs a vast multitude of helper functions and values.
+
 ## Flake templates \{#templates}
 
 [*Flake templates*][init] enable you to either initialize a new Nix project with pre-supplied content or add a set of files to an existing project.
@@ -296,6 +324,7 @@ If you ran `nix flake init --template <reference>` against this template definit
 [nixos]: /concepts/nixos
 [nixpkgs]: /concepts/nixpkgs
 [other]: https://github.com/DeterminateSystems/zero-to-nix/tree/other
+[output-schema]: https://nixos.wiki/wiki/Flakes#Output_schema
 [packages]: /concepts/packages
 [pinning]: /concepts/pinning
 [refs-official]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake#flake-references