wip: site refactor

docs/concepts/flox-vs-containers.md → docs/comparisons/flox-vs-containers.md

@@ -439,14 +439,14 @@ 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
-[services]: ../concepts/services.md
-[manifest]: ../concepts/environments.md#manifesttoml
+[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]: ../explanations/services.md
+[manifest]: ../explanations/environments.md#manifesttoml
 [early]: https://flox.dev/early/
 [ci-cd]: ../tutorials/ci-cd.md

docs/concepts/activation.md → docs/explanations/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

docs/concepts/builds.md → docs/explanations/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

docs/concepts/environments.md → docs/explanations/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

docs/concepts/floxhub.md → docs/explanations/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
-[generation_concept]: ../concepts/generations.md
-[manifest_concept]: ../concepts/environments.md#manifesttoml
-[environments_concept]: ../concepts/environments.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]: ../explanations/generations.md
+[manifest_concept]: ../explanations/environments.md#manifesttoml
+[environments_concept]: ../explanations/environments.md

docs/concepts/generations.md → docs/explanations/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

docs/concepts/manifest-builds.md → docs/explanations/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

docs/concepts/nix-expression-builds.md → docs/explanations/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

docs/concepts/packages-and-catalog.md → docs/explanations/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

docs/concepts/publishing.md → docs/explanations/publishing.md

@@ -75,9 +75,9 @@ This means that individual users will not be able to share packages they've publ
 
 [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

docs/concepts/services.md → docs/explanations/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:

docs/flox-5-minutes.md

@@ -634,21 +634,21 @@ you can activate _both_ environments to do that work.
 [configuring your environment][manifest].
 
 [install_flox]: ./install-flox/install.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
-[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
-[multi-arch]: ./tutorials/multi-arch-environments.md
-[config]: ./reference/command-reference/flox-config.md
-[services]: ./concepts/services.md
+[create_guide]: ./guides/getting-started/creating-environments.md
+[share_guide]: ./guides/getting-started/sharing-environments.md
+[init]: ./man/flox-init.md
+[search]: ./man/flox-search.md
+[show]: ./man/flox-show.md
+[catalog]: ./explanations/packages-and-catalog.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]: ./guides/getting-started/multi-arch-environments.md
+[config]: ./man/flox-config.md
+[services]: ./explanations/services.md

docs/tutorials/creating-environments.md → docs/guides/getting-started/creating-environments.md

@@ -228,17 +228,17 @@ 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
-[environment_concept]: ../concepts/environments.md
+[manifest_concept]: ../explanations/environments.md#manifesttoml
+[environment_concept]: ../explanations/environments.md
 [customizing_guide]: ./customizing-environments.md
 
 ## Where to next?

docs/tutorials/customizing-environments.md → docs/guides/getting-started/customizing-environments.md

@@ -173,11 +173,11 @@ mycli
 
 - :simple-readme:{ .flox-purple .flox-heart } [Multiple architecture environments][multi-arch-guide]
 
-[environment_concept]: ../concepts/environments.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
+[environment_concept]: ../explanations/environments.md
+[flox_activate]: ../man/flox-activate.md
 [multi-arch-guide]: ./multi-arch-environments.md
 [rust_guide]: ../cookbook/languages/rust.md
-[flox_init]: ../reference/command-reference/flox-init.md
-[activation_concept]: ../concepts/activation.md
+[flox_init]: ../man/flox-init.md
+[activation_concept]: ../explanations/activation.md
 [fish_shell]: https://fishshell.com/
-[flox_install]: ../reference/command-reference/flox-install.md
+[flox_install]: ../man/flox-install.md

docs/tutorials/default-environment.md → docs/guides/getting-started/default-environment.md

@@ -247,6 +247,6 @@ Flox has you covered.
 Even better, if you want both a package manager _and_ developer environments,
 with Flox you only need to learn one tool.
 
-[init]: ../reference/command-reference/flox-init.md
-[push]: ../reference/command-reference/flox-push.md
-[pull]: ../reference/command-reference/flox-pull.md
+[init]: ../man/flox-init.md
+[push]: ../man/flox-push.md
+[pull]: ../man/flox-pull.md

docs/tutorials/multi-arch-environments.md → docs/guides/getting-started/multi-arch-environments.md

@@ -136,10 +136,10 @@ get the `systemd` package.
 
 - :simple-readme:{ .flox-purple .flox-heart } [Environment concept][environment_concept]
 
-[environment_concept]: ../concepts/environments.md
+[environment_concept]: ../explanations/environments.md
 [sharing_guide]: ./sharing-environments.md
-[flox_search]: ../reference/command-reference/flox-search.md
-[flox_show]: ../reference/command-reference/flox-show.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_search]: ../man/flox-search.md
+[flox_show]: ../man/flox-show.md
+[flox_edit]: ../man/flox-edit.md
+[flox_push]: ../man/flox-push.md
+[flox_pull]: ../man/flox-pull.md

docs/tutorials/sharing-environments.md → docs/guides/getting-started/sharing-environments.md

@@ -54,9 +54,9 @@ git clone ..example-project;
 flox activate
 ```
 
-[flox_init]: ../reference/command-reference/flox-init.md
+[flox_init]: ../man/flox-init.md
 [discourse]: https://discourse.flox.dev/
-[manifest_concept]: ../concepts/environments.md#manifesttoml
+[manifest_concept]: ../explanations/environments.md#manifesttoml
 
 ## Sharing environments on FloxHub
 
@@ -128,10 +128,10 @@ $ flox push
 !!! note "Note"
     Right now, only environment owners can push edits to their environments.
 
-[flox_push]: ../reference/command-reference/flox-push.md
-[flox_pull]: ../reference/command-reference/flox-pull.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
-[floxhub_concept]: ../concepts/floxhub.md
+[flox_push]: ../man/flox-push.md
+[flox_pull]: ../man/flox-pull.md
+[flox_activate]: ../man/flox-activate.md
+[floxhub_concept]: ../explanations/floxhub.md
 
 ### Pulling a remote environment without connecting to FloxHub
 
@@ -225,7 +225,7 @@ telnet (GNU inetutils) 2.5
 - :simple-readme:{ .flox-purple .flox-heart } [Designing multiple architecture environments][multi_arch_guide]
 
 [multi_arch_guide]: ./multi-arch-environments.md
-[environment_concept]: ../concepts/environments.md
+[environment_concept]: ../explanations/environments.md
 [layering_guide]: ./layering-multiple-environments.md
 [customizing_guide]: ./customizing-environments.md
-[flox_containerize]: ../reference/command-reference/flox-containerize.md
+[flox_containerize]: ../man/flox-containerize.md

docs/tutorials/build-and-publish.md → docs/guides/going-deeper/build-and-publish.md

@@ -256,16 +256,16 @@ 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
-[build-concept]: ../concepts/builds.md
+[flox-manifest-build-section]: ../man/manifest.toml.md#build
+[build-concept]: ../explanations/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
-[extra-builds]: ../concepts/manifest-builds.md#example-configuration-files
-[publish-concept]: ../concepts/publishing.md
-[organizations-concept]: ../concepts/organizations.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]: ../explanations/manifest-builds.md#example-configuration-files
+[publish-concept]: ../explanations/publishing.md
+[organizations-concept]: ../explanations/organizations.md
 [early]: https://flox.dev/early/

docs/tutorials/ci-cd.md → docs/guides/going-deeper/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

docs/tutorials/composition.md → docs/guides/going-deeper/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
-[floxhub]: ../concepts/floxhub.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]: ../explanations/floxhub.md
 [hypothesis]: https://hypothesis.readthedocs.io/en/latest/

docs/tutorials/layering-multiple-environments.md → docs/guides/going-deeper/layering-multiple-environments.md

@@ -127,10 +127,10 @@ Inactive environments:
 - :simple-readme:{ .flox-purple .flox-heart } [Designing multiple architecture environments][multi_arch_guide]
 
 [default-env]: ./default-environment.md
-[flox_init]: ../reference/command-reference/flox-init.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
-[flox_list]: ../reference/command-reference/flox-list.md
+[flox_init]: ../man/flox-init.md
+[flox_install]: ../man/flox-install.md
+[flox_activate]: ../man/flox-activate.md
+[flox_list]: ../man/flox-list.md
 [sharing_guide]: ./sharing-environments.md
 [customizing_guide]: ./customizing-environments.md
 [multi_arch_guide]: ./multi-arch-environments.md