Flatten the Cookbook and Reference sections of the nav

.flox/env/manifest.lock

@@ -40,7 +40,7 @@
       }
     },
     "hook": {
-      "on-activate": "\n#\n# Python environment activation and installation\n#\nexport POETRY_VIRTUALENVS_PATH=\"$FLOX_ENV_CACHE/poetry/virtualenvs\"\nif [ -z \"$(poetry env info --path)\" ]; then\n  poetry env use \"$(which python)\" &> /dev/null\nfi\neval \"$(poetry env activate)\" &> /dev/null\npoetry install --quiet &> /dev/null\necho \"1. 👉 Python environment activated\"\n\n# \n# Set the version of Flox to the latest stable version\n#\nexport FLOX_VERSION=$(cat FLOX_VERSION | xargs)\necho \"2. 👉 FLOX_VERSION set to $FLOX_VERSION\"\n\n# \n# Copy and process Flox man pages\n# \nexport FLOX_SRC_ARCHIVE=\"$FLOX_ENV_CACHE/flox-v$FLOX_VERSION.tar.gz\"\nif [ ! -e \"$FLOX_SRC_ARCHIVE\" ]; then\n  curl -sL \"https://github.com/flox/flox/archive/refs/tags/v$FLOX_VERSION.tar.gz\" -o $FLOX_SRC_ARCHIVE\nfi\necho \"3. 👉 Downloaded Flox source archive\"\n\nexport FLOX_SRC_DIR=\"$FLOX_ENV_CACHE/flox-src-$FLOX_VERSION\"\nif [ ! -d \"$FLOX_SRC_DIR\" ]; then\n  mkdir -p $FLOX_SRC_DIR\n  tar -zx --strip-components=1 --file=$FLOX_SRC_ARCHIVE --directory=$FLOX_SRC_DIR;\nfi\necho \"4. 👉 Extracted Flox source archive\"\n\nexport FLOX_MAN_PAGES_DIR=\"$PWD/docs/reference/command-reference\"\nif [ -d \"$FLOX_MAN_PAGES_DIR\" ]; then\n  rm -rf \"$FLOX_MAN_PAGES_DIR/*\"\nfi\nmkdir -p $FLOX_MAN_PAGES_DIR\npushd \"$FLOX_SRC_DIR/cli/flox/doc\" > /dev/null\n  find . -maxdepth 1 -iname \"*.md\" -exec \\\n    sh -c \"\n      pandoc -t gfm \\\n        -L $FLOX_SRC_DIR/pkgs/flox-manpages/pandoc-filters/include-files.lua \\\n        --standalone \\\n        {} |\n        # remove current title\n        tail -n +6 |\n        # indent all markdown levels by one, e.g. \"#\" -> \"##\"\n        sed -e 's/^#/##/' > \\\"$FLOX_MAN_PAGES_DIR/{}\\\"\n    \" \\;\npopd > /dev/null\npushd $FLOX_MAN_PAGES_DIR > /dev/null\n  for commandPage in ./*.md; do\n    # All other man page files have names of the form\n    # 'flox*.md'\n    if [ \"$commandPage\" = \"./manifest.toml.md\" ]; then\n      continue\n    fi\n    command=$(basename $commandPage .md | sed -e \"s|-| |g\")\n    echo -e \"\\n# \\`$command\\` command\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"---\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"description: Command reference for the \\`$command\\` command.\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"title: $command\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"---\\n$(cat $commandPage)\" > $commandPage\n  done\n\n  manifestPage=\"manifest.toml.md\"\n  echo -e \"\\n# \\`manifest.toml\\`\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"---\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"description: Reference for the manifest.toml format.\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"title: manifest.toml\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"---\\n$(cat $manifestPage)\" > $manifestPage\npopd > /dev/null\necho \"5. 👉 Copy man pages from Flox source archive\"\n"
+      "on-activate": "\n#\n# Python environment activation and installation\n#\nexport POETRY_VIRTUALENVS_PATH=\"$FLOX_ENV_CACHE/poetry/virtualenvs\"\nif [ -z \"$(poetry env info --path)\" ]; then\n  poetry env use \"$(which python)\" &> /dev/null\nfi\neval \"$(poetry env activate)\" &> /dev/null\npoetry install --quiet &> /dev/null\necho \"1. 👉 Python environment activated\"\n\n# \n# Set the version of Flox to the latest stable version\n#\nexport FLOX_VERSION=$(cat FLOX_VERSION | xargs)\necho \"2. 👉 FLOX_VERSION set to $FLOX_VERSION\"\n\n# \n# Copy and process Flox man pages\n# \nexport FLOX_SRC_ARCHIVE=\"$FLOX_ENV_CACHE/flox-v$FLOX_VERSION.tar.gz\"\nif [ ! -e \"$FLOX_SRC_ARCHIVE\" ]; then\n  curl -sL \"https://github.com/flox/flox/archive/refs/tags/v$FLOX_VERSION.tar.gz\" -o $FLOX_SRC_ARCHIVE\nfi\necho \"3. 👉 Downloaded Flox source archive\"\n\nexport FLOX_SRC_DIR=\"$FLOX_ENV_CACHE/flox-src-$FLOX_VERSION\"\nif [ ! -d \"$FLOX_SRC_DIR\" ]; then\n  mkdir -p $FLOX_SRC_DIR\n  tar -zx --strip-components=1 --file=$FLOX_SRC_ARCHIVE --directory=$FLOX_SRC_DIR;\nfi\necho \"4. 👉 Extracted Flox source archive\"\n\nexport FLOX_MAN_PAGES_DIR=\"$PWD/docs/man\"\nif [ -d \"$FLOX_MAN_PAGES_DIR\" ]; then\n  rm -rf \"$FLOX_MAN_PAGES_DIR/*\"\nfi\nmkdir -p $FLOX_MAN_PAGES_DIR\npushd \"$FLOX_SRC_DIR/cli/flox/doc\" > /dev/null\n  find . -maxdepth 1 -iname \"*.md\" -exec \\\n    sh -c \"\n      pandoc -t gfm \\\n        -L $FLOX_SRC_DIR/pkgs/flox-manpages/pandoc-filters/include-files.lua \\\n        --standalone \\\n        {} |\n        # remove current title\n        tail -n +6 |\n        # indent all markdown levels by one, e.g. \"#\" -> \"##\"\n        sed -e 's/^#/##/' > \\\"$FLOX_MAN_PAGES_DIR/{}\\\"\n    \" \\;\npopd > /dev/null\npushd $FLOX_MAN_PAGES_DIR > /dev/null\n  for commandPage in ./*.md; do\n    # All other man page files have names of the form\n    # 'flox*.md'\n    if [ \"$commandPage\" = \"./manifest.toml.md\" ]; then\n      continue\n    fi\n    command=$(basename $commandPage .md | sed -e \"s|-| |g\")\n    echo -e \"\\n# \\`$command\\` command\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"---\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"description: Command reference for the \\`$command\\` command.\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"title: $command\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"---\\n$(cat $commandPage)\" > $commandPage\n  done\n\n  manifestPage=\"manifest.toml.md\"\n  echo -e \"\\n# \\`manifest.toml\\`\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"---\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"description: Reference for the manifest.toml format.\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"title: manifest.toml\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"---\\n$(cat $manifestPage)\" > $manifestPage\npopd > /dev/null\necho \"5. 👉 Copy man pages from Flox source archive\"\n"
     },
     "profile": {
       "common": "echo \"\"\necho \"     ╔═══════════════════════════════════╗\"\necho \"     ║                                   ║\"\necho \"     ║  To build a production docs run:  ║\"\necho \"     ║  > mkdocs build                   ║\"\necho \"     ║                                   ║\"\necho \"     ║  To write docs locally run:       ║\"\necho \"     ║  > mkdocs serve                   ║\"\necho \"     ║                                   ║\"\necho \"     ╚═══════════════════════════════════╝\"\necho \"\"\n",

.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

.gitignore

@@ -2,7 +2,7 @@
 .direnv/
 site/
 include/
-docs/reference/command-reference
+docs/man
 result
 result-*
 bin/

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

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

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

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/

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

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

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

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

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

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

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:

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

docs/index.md

@@ -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

docs/cookbook/languages/c.md → docs/languages/c.md

@@ -55,4 +55,4 @@ clangStdenv.mkDerivation {
 }
 ```
 
-[build-concept]: ../../concepts/builds.md
+[build-concept]: ../concepts/builds.md

docs/cookbook/languages/go.md → 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

docs/cookbook/languages/jvm.md → 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