Merge pull request #343 from flox/dcarley/merge-preview-main

stahnma · web-flow · commit 5b868c7b65ea · 2025-10-21T16:22:54.000-05:00
Merge preview into main
diff --git a/.flox/env/manifest.lock b/.flox/env/manifest.lock
diff --git a/.flox/env/manifest.toml b/.flox/env/manifest.toml
@@ -52,7 +52,7 @@ if [ ! -d "$FLOX_SRC_DIR" ]; then
 fi
 echo "4. 👉 Extracted Flox source archive"
 
-export FLOX_MAN_PAGES_DIR="$PWD/docs/reference/command-reference"
+export FLOX_MAN_PAGES_DIR="$PWD/docs/man"
 if [ -d "$FLOX_MAN_PAGES_DIR" ]; then
   rm -rf "$FLOX_MAN_PAGES_DIR/*"
 fi
diff --git a/.gitignore b/.gitignore
@@ -2,7 +2,7 @@
 .direnv/
 site/
 /include/
-docs/reference/command-reference
+docs/man
 result
 result-*
 bin/
diff --git a/docs/concepts/activation.md b/docs/concepts/activation.md
@@ -310,7 +310,7 @@ attach to this new version of the environment.
 
 ## Development vs. runtime mode
 
-See the [`options.activate.mode`](../reference/command-reference/manifest.toml.md#options) option in the manifest.
+See the [`options.activate.mode`](../man/manifest.toml.md#options) option in the manifest.
 
 ## Conclusion
 
@@ -329,6 +329,6 @@ that prepare your environment just how you like them.
 
 [environment-concept]: ./services.md
 [bash-func-export]: https://www.gnu.org/software/bash/manual/html_node/Bourne-Shell-Builtins.html#index-export
-[vars-section]: ../reference/command-reference/manifest.toml.md#vars
-[hook-section]: ../reference/command-reference/manifest.toml.md#hook
-[profile-section]: ../reference/command-reference/manifest.toml.md#profile
+[vars-section]: ../man/manifest.toml.md#vars
+[hook-section]: ../man/manifest.toml.md#hook
+[profile-section]: ../man/manifest.toml.md#profile
diff --git a/docs/concepts/builds.md b/docs/concepts/builds.md
@@ -42,5 +42,5 @@ One way to accomplish this is to run your builds in [CI][flox-ci-cd].
 
 [manifest-builds-concept]: ./manifest-builds.md
 [nix-expression-builds-concept]: ./nix-expression-builds.md
-[flox-build]: ../reference/command-reference/flox-build.md
+[flox-build]: ../man/flox-build.md
 [flox-ci-cd]: ../tutorials/ci-cd.md
diff --git a/docs/concepts/environments.md b/docs/concepts/environments.md
@@ -110,21 +110,21 @@ version. Flox manages this file for you.
 }
 ```
 
-[flox_init]: ../reference/command-reference/flox-init.md
-[flox_show]: ../reference/command-reference/flox-show.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_search]: ../reference/command-reference/flox-search.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
-[flox_push]: ../reference/command-reference/flox-push.md
-[flox_pull]: ../reference/command-reference/flox-pull.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
+[flox_init]: ../man/flox-init.md
+[flox_show]: ../man/flox-show.md
+[flox_edit]: ../man/flox-edit.md
+[flox_install]: ../man/flox-install.md
+[flox_search]: ../man/flox-search.md
+[flox_edit]: ../man/flox-edit.md
+[flox_push]: ../man/flox-push.md
+[flox_pull]: ../man/flox-pull.md
+[flox_activate]: ../man/flox-activate.md
 [sharing_guide]: ../tutorials/sharing-environments.md
 [create_guide]: ../tutorials/creating-environments.md
 [customizing_environments_guide]: ../tutorials/customizing-environments.md
 [generation_concept]: ./generations.md
 [floxhub_concept]: ./floxhub.md
 [discourse]: https://discourse.flox.dev/
-[manifest]: ../reference/command-reference/manifest.toml.md
+[manifest]: ../man/manifest.toml.md
 [nix-expression-builds-concept]: ./nix-expression-builds.md
 [toml_spec]: https://toml.io/en/v1.0.0
diff --git a/docs/concepts/flox-vs-containers.md b/docs/concepts/flox-vs-containers.md
@@ -439,13 +439,13 @@ you need to build a container so that it can be deployed.
 
 ---
 
-[init]: ../reference/command-reference/flox-init.md
-[edit]: ../reference/command-reference/flox-edit.md
-[install]: ../reference/command-reference/flox-install.md
-[push]: ../reference/command-reference/flox-push.md
-[containerize]: ../reference/command-reference/flox-containerize.md
-[activate]: ../reference/command-reference/flox-activate.md
-[services-start]: ../reference/command-reference/flox-services-start.md
+[init]: ../man/flox-init.md
+[edit]: ../man/flox-edit.md
+[install]: ../man/flox-install.md
+[push]: ../man/flox-push.md
+[containerize]: ../man/flox-containerize.md
+[activate]: ../man/flox-activate.md
+[services-start]: ../man/flox-services-start.md
 [services]: ../concepts/services.md
 [manifest]: ../concepts/environments.md#manifesttoml
 [early]: https://flox.dev/early/
diff --git a/docs/concepts/floxhub.md b/docs/concepts/floxhub.md
@@ -97,13 +97,13 @@ flox pull example-owner/example-env
 Run the [`flox auth logout`][flox_auth] command.
 
 [flox_website]: https://flox.dev
-[flox_push]: ../reference/command-reference/flox-push.md
-[flox_pull]: ../reference/command-reference/flox-pull.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
-[flox_auth]: ../reference/command-reference/flox-auth.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_uninstall]: ../reference/command-reference/flox-uninstall.md
+[flox_push]: ../man/flox-push.md
+[flox_pull]: ../man/flox-pull.md
+[flox_activate]: ../man/flox-activate.md
+[flox_auth]: ../man/flox-auth.md
+[flox_edit]: ../man/flox-edit.md
+[flox_install]: ../man/flox-install.md
+[flox_uninstall]: ../man/flox-uninstall.md
 [generation_concept]: ../concepts/generations.md
 [manifest_concept]: ../concepts/environments.md#manifesttoml
 [environments_concept]: ../concepts/environments.md
diff --git a/docs/concepts/generations.md b/docs/concepts/generations.md
@@ -79,9 +79,9 @@ This allows this environment to advance to newer generations explicitly on the
 next [`flox pull`][flox_pull].
 
 [floxhub_concept]: .//floxhub.md
-[flox_push]: ../reference/command-reference/flox-push.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
-[flox_pull]: ../reference/command-reference/flox-pull.md
+[flox_push]: ../man/flox-push.md
+[flox_install]: ../man/flox-install.md
+[flox_edit]: ../man/flox-edit.md
+[flox_pull]: ../man/flox-pull.md
 [sharing_guide]: ../tutorials/sharing-environments.md
 [environment_guide]: ../tutorials/creating-environments.md
diff --git a/docs/concepts/manifest-builds.md b/docs/concepts/manifest-builds.md
@@ -190,11 +190,11 @@ Each language guide in the Languages section of the Cookbook contains an example
 For example, [this section][go-example] contains an example build for the Go language.
 
 [builds-concept]: ./builds.md
-[manifest-reference]: ../reference/command-reference/manifest.toml.md#build
+[manifest-reference]: ../man/manifest.toml.md#build
 [services-concept]: ./services.md
 [publish-concept]: ./publishing.md
 [fhs-docs]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard
-[pkg-groups]: ../reference/command-reference/manifest.toml.md#package-descriptors
+[pkg-groups]: ../man/manifest.toml.md#package-descriptors
 [grpc]: https://grpc.io/
 [organizations-concept]: ./organizations.md
-[go-example]: ../cookbook/languages/go.md#build-with-flox
+[go-example]: ../languages/go.md#build-with-flox
diff --git a/docs/concepts/nix-expression-builds.md b/docs/concepts/nix-expression-builds.md
@@ -242,4 +242,4 @@ error: hash mismatch in fixed-output derivation '/nix/store/srm7s6pyckifs52ikyfa
 
 [builds-concept]: ./builds.md
 [manifest-builds-concept]: ./manifest-builds.md
-[pkg-groups]: ../reference/command-reference/manifest.toml.md#package-descriptors
+[pkg-groups]: ../man/manifest.toml.md#package-descriptors
diff --git a/docs/concepts/packages-and-catalog.md b/docs/concepts/packages-and-catalog.md
@@ -38,10 +38,10 @@ Source by the Open Source Initiative (OSI).
 * **broken**: indicates if the package is marked as broken in
 [nixpkgs][nixpkgs].
 
-[flox_search]: ../reference/command-reference/flox-search.md
-[flox_show]: ../reference/command-reference/flox-show.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_update]: ../reference/command-reference/flox-update.md
+[flox_search]: ../man/flox-search.md
+[flox_show]: ../man/flox-show.md
+[flox_install]: ../man/flox-install.md
+[flox_update]: ../man/flox-update.md
 [manifest_concept]: ./environments.md#manifesttoml
 [nixpkgs]: https://github.com/NixOS/nixpkgs
 [builds]: ./builds.md
diff --git a/docs/concepts/publishing.md b/docs/concepts/publishing.md
@@ -83,9 +83,9 @@ For anyone in the organization, published packages become available in
 
 [builds-concept]: ./builds.md
 [catalog-concept]: ./packages-and-catalog.md
-[flox-build]: ../reference/command-reference/flox-build.md
-[flox-publish]: ../reference/command-reference/flox-publish.md
-[flox-search]: ../reference/command-reference/flox-search.md
-[flox-show]: ../reference/command-reference/flox-show.md
-[flox-install]: ../reference/command-reference/flox-install.md
+[flox-build]: ../man/flox-build.md
+[flox-publish]: ../man/flox-publish.md
+[flox-search]: ../man/flox-search.md
+[flox-show]: ../man/flox-show.md
+[flox-install]: ../man/flox-install.md
 [organizations-concept]: ./organizations.md
diff --git a/docs/concepts/services.md b/docs/concepts/services.md
@@ -28,7 +28,7 @@ Services have a very simple schema consisting of a `command` to run to start
 the service,
 any `vars` you want set specifically for the service,
 and whether the service spawns a background process.
-See [`manifest-toml(1)`](../reference/command-reference/manifest.toml.md) for
+See [`manifest-toml(1)`](../man/manifest.toml.md) for
 more details on the exact format of the `[services]` section of the manfiest.
 
 An example service definition is shown below:
diff --git a/docs/flox-5-minutes.md b/docs/flox-5-minutes.md
@@ -252,23 +252,23 @@ There are _so_ many things we didn't have time to cover, so here's some addition
 [install_flox]: ./install-flox/install.md
 [create_guide]: ./tutorials/creating-environments.md
 [sharing]: ./tutorials/sharing-environments.md
-[init]: ./reference/command-reference/flox-init.md
-[search]: ./reference/command-reference/flox-search.md
-[show]: ./reference/command-reference/flox-show.md
+[init]: ./man/flox-init.md
+[search]: ./man/flox-search.md
+[show]: ./man/flox-show.md
 [catalog]: ./concepts/packages-and-catalog.md
-[install]: ./reference/command-reference/flox-install.md
-[activate]: ./reference/command-reference/flox-activate.md
-[edit]: ./reference/command-reference/flox-edit.md
-[push]: ./reference/command-reference/flox-push.md
-[list]: ./reference/command-reference/flox-list.md
-[manifest]: ./reference/command-reference/manifest.toml.md
+[install]: ./man/flox-install.md
+[activate]: ./man/flox-activate.md
+[edit]: ./man/flox-edit.md
+[push]: ./man/flox-push.md
+[list]: ./man/flox-list.md
+[manifest]: ./man/manifest.toml.md
 [multi-arch]: ./tutorials/multi-arch-environments.md
 [services]: ./concepts/services.md
 [bun]: https://bun.sh/
 [zig]: https://ziglang.org/
 [floxhub]: https://hub.flox.dev
 [sleep-issue]: https://github.com/flox/flox/pull/1931
-[install-section]: ./reference/command-reference/manifest.toml.md#install
+[install-section]: ./man/manifest.toml.md#install
 [activation-tutorial]: ./tutorials/customizing-environments.md
 [ci]: ./tutorials/ci-cd.md
 [composition]: ./tutorials/composition.md
diff --git a/docs/index.md b/docs/index.md
@@ -53,7 +53,7 @@ Flox makes it easy to work locally, test in CI, and deploy to production—all w
 
     [:octicons-arrow-right-24: Install Flox with flakes or profiles](install-flox/install.md#__tabbed_1_5){:target="_blank"}
 
-    [:octicons-arrow-right-24: Flox brings Nix to your teams](https://flox.dev/blog/its-time-to-bring-nix-to-work/){:target="_blank"}
+    [:octicons-arrow-right-24: Flox brings Nix to your teams](https://flox.dev/blog/enterprise-nix-its-time-to-bring-nix-to-work/){:target="_blank"}
 
     [:octicons-arrow-right-24: Use flakes in Flox](https://flox.dev/blog/extending-flox-with-nix-flakes/){:target="_blank"}
 
@@ -108,7 +108,7 @@ If you're already using Homebrew, you can easily [migrate or use Homebrew and Fl
 Flox lets you define what an environment _is_ in a way that can be reused across local dev, CI, and production.
 Leverage [pre-built integrations](https://flox.dev/docs/tutorials/ci-cd/?h=ci) for GitHub Actions, CircleCI, and GitLab to pull and activate the same environments locally, in CI and in production.
 
-Or use Flox [containerize](https://flox.dev/docs/reference/command-reference/flox-containerize/?h=containerize) to package your environments as OCI images—fully pinned and runnable anywhere.
+Or use Flox [containerize](https://flox.dev/docs/man/flox-containerize/?h=containerize) to package your environments as OCI images—fully pinned and runnable anywhere.
 From bare metal to VMs, from Docker Swarm to Kubernetes to AWS Lambda—the runtime context might change, but Flox environments run and behave the same everywhere.
 
 Need an example? See how [the Flox Docs team uses Flox in CI](https://flox.dev/blog/integrating-flox-with-ci-for-consistent-reproducible-dev-environments/) to build, test and deploy this docs site.
@@ -131,20 +131,20 @@ The Flox product and engineering teams love to hear directly from users. Your qu
 [flox_5_minutes]: ./flox-5-minutes.md
 [create_guide]: ./tutorials/creating-environments.md
 [share_guide]: ./tutorials/sharing-environments.md
-[init]: ./reference/command-reference/flox-init.md
-[search]: ./reference/command-reference/flox-search.md
-[show]: ./reference/command-reference/flox-show.md
+[init]: ./man/flox-init.md
+[search]: ./man/flox-search.md
+[show]: ./man/flox-show.md
 [catalog]: ./concepts/packages-and-catalog.md
-[install]: ./reference/command-reference/flox-install.md
-[activate]: ./reference/command-reference/flox-activate.md
-[edit]: ./reference/command-reference/flox-edit.md
-[push]: ./reference/command-reference/flox-push.md
-[pull]: ./reference/command-reference/flox-pull.md
-[delete]: ./reference/command-reference/flox-delete.md
-[list]: ./reference/command-reference/flox-list.md
-[manifest]: ./reference/command-reference/manifest.toml.md
-[rust-cookbook]: ./cookbook/languages/rust.md
+[install]: ./man/flox-install.md
+[activate]: ./man/flox-activate.md
+[edit]: ./man/flox-edit.md
+[push]: ./man/flox-push.md
+[pull]: ./man/flox-pull.md
+[delete]: ./man/flox-delete.md
+[list]: ./man/flox-list.md
+[manifest]: ./man/manifest.toml.md
+[rust-cookbook]: ./languages/rust.md
 [multi-arch]: ./tutorials/multi-arch-environments.md
-[config]: ./reference/command-reference/flox-config.md
+[config]: ./man/flox-config.md
 [services]: ./concepts/services.md
 [floxhub_packages]: https://hub.flox.dev/packages
diff --git a/docs/languages/c.md b/docs/languages/c.md
@@ -55,4 +55,4 @@ clangStdenv.mkDerivation {
 }
 ```
 
-[build-concept]: ../../concepts/builds.md
+[build-concept]: ../concepts/builds.md
diff --git a/docs/languages/go.md b/docs/languages/go.md
@@ -107,6 +107,6 @@ buildGoModule {
 }
 ```
 
-[build-concept]: ../../concepts/builds.md
-[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds
-[nix-expression-hashes]: ../../concepts/nix-expression-builds.md#generating-hashes
+[build-concept]: ../concepts/builds.md
+[pure-builds-section]: ../concepts/manifest-builds.md#pure-builds
+[nix-expression-hashes]: ../concepts/nix-expression-builds.md#generating-hashes
diff --git a/docs/languages/jvm.md b/docs/languages/jvm.md
@@ -44,4 +44,4 @@ Note that `pwd` will return the location from which the built artifact is run, n
 
 [gradle]: https://gradle.org/
 [shadow]: https://gradleup.com/shadow/
-[build-concept]: ../../concepts/builds.md
+[build-concept]: ../concepts/builds.md
diff --git a/docs/languages/nodejs.md b/docs/languages/nodejs.md
@@ -97,5 +97,5 @@ buildNpmPackage (final: {
 });
 ```
 
-[build-concept]: ../../concepts/builds.md
-[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds
+[build-concept]: ../concepts/builds.md
+[pure-builds-section]: ../concepts/manifest-builds.md#pure-builds
diff --git a/docs/languages/python.md b/docs/languages/python.md
@@ -355,4 +355,4 @@ runtime-packages = [
 ]
 ```
 
-[build-concept]: ../../concepts/builds.md
+[build-concept]: ../concepts/builds.md
diff --git a/docs/languages/ruby.md b/docs/languages/ruby.md
@@ -82,5 +82,5 @@ command = """
 sandbox = "pure"
 ```
 
-[build-concept]: ../../concepts/builds.md
-[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds
+[build-concept]: ../concepts/builds.md
+[pure-builds-section]: ../concepts/manifest-builds.md#pure-builds
diff --git a/docs/languages/rust.md b/docs/languages/rust.md
@@ -289,5 +289,5 @@ rustPlatform.buildRustPackage {
 [custom-toolchains]: https://github.com/zmitchell/rust-toolchains
 [esp32]: https://www.espressif.com/en/products/socs/esp32
 [risc-v]: https://en.wikipedia.org/wiki/RISC-V
-[build-concept]: ../../concepts/builds.md
-[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds
+[build-concept]: ../concepts/builds.md
+[pure-builds-section]: ../concepts/manifest-builds.md#pure-builds
diff --git a/docs/tutorials/build-and-publish.md b/docs/tutorials/build-and-publish.md
@@ -256,15 +256,15 @@ The story doesn't end here though.
 In this guide we've shown you how to build and distribute programs, but you can also use it to distribute configuration files (or any other file).
 See the [builds][extra-builds] concept page for examples of what else you can build and publish with Flox.
 
-[flox-manifest-build-section]: ../reference/command-reference/manifest.toml.md#build
+[flox-manifest-build-section]: ../man/manifest.toml.md#build
 [build-concept]: ../concepts/builds.md
 [fhs]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard
-[flox-install]: ../reference/command-reference/flox-install.md
-[flox-show]: ../reference/command-reference/flox-show.md
-[flox-search]: ../reference/command-reference/flox-search.md
-[flox-edit]: ../reference/command-reference/flox-edit.md
-[flox-build]: ../reference/command-reference/flox-build.md
-[flox-publish]: ../reference/command-reference/flox-publish.md
+[flox-install]: ../man/flox-install.md
+[flox-show]: ../man/flox-show.md
+[flox-search]: ../man/flox-search.md
+[flox-edit]: ../man/flox-edit.md
+[flox-build]: ../man/flox-build.md
+[flox-publish]: ../man/flox-publish.md
 [extra-builds]: ../concepts/manifest-builds.md#example-configuration-files
 [publish-concept]: ../concepts/publishing.md
 [organizations-concept]: ../concepts/organizations.md
diff --git a/docs/tutorials/ci-cd.md b/docs/tutorials/ci-cd.md
@@ -121,4 +121,4 @@ Here are some suggestions for things you can do with your Flox environment in CI
 [sharing_guide]: ./sharing-environments.md
 [layering_guide]: ./layering-multiple-environments.md
 [customizing_guide]: ./customizing-environments.md
-[containerize]: ../reference/command-reference/flox-containerize.md
+[containerize]: ../man/flox-containerize.md
diff --git a/docs/tutorials/composition.md b/docs/tutorials/composition.md
@@ -297,10 +297,10 @@ This means you can spend less time getting started, and more time developing you
 Similarly, since you're treating environments like dependencies, if you make an improvement to a template environment while working on one project, the improvement will become available to all of your other projects that use that environment as soon as they run `flox include upgrade`.
 
 [poetry]: https://python-poetry.org/
-[flox-init]: ../reference/command-reference/flox-init.md
-[flox-pull]: ../reference/command-reference/flox-pull.md
-[flox-install]: ../reference/command-reference/flox-install.md
-[flox-edit]: ../reference/command-reference/flox-edit.md
-[flox-list]: ../reference/command-reference/flox-list.md
+[flox-init]: ../man/flox-init.md
+[flox-pull]: ../man/flox-pull.md
+[flox-install]: ../man/flox-install.md
+[flox-edit]: ../man/flox-edit.md
+[flox-list]: ../man/flox-list.md
 [floxhub]: ../concepts/floxhub.md
 [hypothesis]: https://hypothesis.readthedocs.io/en/latest/
diff --git a/docs/tutorials/creating-environments.md b/docs/tutorials/creating-environments.md
@@ -228,13 +228,13 @@ flox [example-project] $ exit
 $
 ```
 
-[flox_init]: ../reference/command-reference/flox-init.md
-[flox_search]: ../reference/command-reference/flox-search.md
-[flox_show]: ../reference/command-reference/flox-show.md
-[flox_install]: ../reference/command-reference/flox-install.md
+[flox_init]: ../man/flox-init.md
+[flox_search]: ../man/flox-search.md
+[flox_show]: ../man/flox-show.md
+[flox_install]: ../man/flox-install.md
 [discourse]: https://discourse.floxdev.com/
-[flox_activate]: ../reference/command-reference/flox-activate.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
+[flox_activate]: ../man/flox-activate.md
+[flox_edit]: ../man/flox-edit.md
 [sharing_guide]: ./sharing-environments.md
 [layering_guide]: ./layering-multiple-environments.md
 [manifest_concept]: ../concepts/environments.md#manifesttoml
diff --git a/docs/tutorials/customizing-environments.md b/docs/tutorials/customizing-environments.md
diff --git a/docs/tutorials/default-environment.md b/docs/tutorials/default-environment.md
diff --git a/docs/tutorials/layering-multiple-environments.md b/docs/tutorials/layering-multiple-environments.md
diff --git a/docs/tutorials/migrations/homebrew.md b/docs/tutorials/migrations/homebrew.md
diff --git a/docs/tutorials/migrations/nvm.md b/docs/tutorials/migrations/nvm.md
diff --git a/docs/tutorials/multi-arch-environments.md b/docs/tutorials/multi-arch-environments.md
diff --git a/docs/tutorials/sharing-environments.md b/docs/tutorials/sharing-environments.md
diff --git a/mkdocs.yml b/mkdocs.yml
