From c7dbbdc0b5600a8dcca3754a0589e545f99788ed Mon Sep 17 00:00:00 2001
From: Dan Carley <dan@flox.dev>
Date: Thu, 15 May 2025 10:02:57 +0100
Subject: [PATCH 1/5] concepts: Update manifest.lock example

The previous contents were a v0 pkgdb lock which is no longer in use or
supported. I've extracted a small subset of relevant fields from a
current lockfile that installs NodeJS.
---
 docs/concepts/environments.md | 27 +++++++++++----------------
 1 file changed, 11 insertions(+), 16 deletions(-)

diff --git a/docs/concepts/environments.md b/docs/concepts/environments.md
index 1819044..ac5e5b2 100644
--- a/docs/concepts/environments.md
+++ b/docs/concepts/environments.md
@@ -74,23 +74,18 @@ were built and activated at a particular point in time.
 
 ``` json title="manifest.lock"
 {
-  "lockfile-version": 0,
- ...
-        "input": {
-          "attrs": {
-            "lastModified": 1703581207,
-            "narHash": "3ef...",
-            "owner": "NixOS",
-            "repo": "nixpkgs",
-            "rev": "3ef...",
-            "type": "github"
-          },
-          "fingerprint": "3ef...",
-          "url": "github:NixOS/nixpkgs/3ef..."
-        },
-        "priority": 5
+  …
+  "packages": [
+    {
+      "install_id": "nodejs",
+      "version": "24.0.1",
+      "system": "aarch64-darwin",
+      "outputs": {
+        "dev": "/nix/store/by9av8x8vmk8lpw4cxhhxfbf7s1h4xzx-nodejs-24.0.1-dev",
+        "libv8": "/nix/store/li49fpxxlgzaz20sahhfj6n8cbkqi7m1-nodejs-24.0.1-libv8",
+        "out": "/nix/store/naafq480zhq05xbi2d3kzpnna2rdqsfb-nodejs-24.0.1"
       },
-      "nodejs": {    
+  …
 }
 ```
 

From f4a5b0c3ae218796a89a72f18da2b33afebc89b3 Mon Sep 17 00:00:00 2001
From: Dan Carley <dan@flox.dev>
Date: Thu, 15 May 2025 10:04:50 +0100
Subject: [PATCH 2/5] tutorials: Remove unused links.

---
 docs/tutorials/customizing-environments.md | 1 -
 docs/tutorials/multi-arch-environments.md  | 3 ---
 2 files changed, 4 deletions(-)

diff --git a/docs/tutorials/customizing-environments.md b/docs/tutorials/customizing-environments.md
index 71215e4..7c27a56 100644
--- a/docs/tutorials/customizing-environments.md
+++ b/docs/tutorials/customizing-environments.md
@@ -147,6 +147,5 @@ Success. You can now start the database server using:
 [flox_activate]: ../reference/command-reference/flox-activate.md
 [create_enviornments_guide]: ./creating-environments.md
 [multi-arch-guide]: ./multi-arch-environments.md
-[manifest_concept]: ../concepts/manifest.md
 [environment_concept]: ../concepts/environments.md
 [hook_concept]: ../concepts/manifest.md#hook-section
diff --git a/docs/tutorials/multi-arch-environments.md b/docs/tutorials/multi-arch-environments.md
index 23a0c9c..8d187af 100644
--- a/docs/tutorials/multi-arch-environments.md
+++ b/docs/tutorials/multi-arch-environments.md
@@ -137,10 +137,7 @@ get the `systemd` package.
 - :simple-readme:{ .flox-purple .flox-heart } [Environment concept][environment_concept]
 
 [environment_concept]: ../concepts/environments.md
-[install_concept]: ../concepts/manifest.md#install-section
 [sharing_guide]: ./sharing-environments.md
-[manifest_toml]: ../concepts/manifest.md
-[environment_concept]: ../concepts/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

From d9945f29b4c68f805e658a6c52f9841ee0d0d369 Mon Sep 17 00:00:00 2001
From: Dan Carley <dan@flox.dev>
Date: Thu, 15 May 2025 10:05:19 +0100
Subject: [PATCH 3/5] Link to manifest.toml sections

Instead of the duplicate and potentially out-of-date content in the
manfiest concepts which will be removed in a subsequent commit.
---
 docs/concepts/activation.md                | 6 +++---
 docs/tutorials/customizing-environments.md | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/concepts/activation.md b/docs/concepts/activation.md
index 4e1a7f6..9e8307b 100644
--- a/docs/concepts/activation.md
+++ b/docs/concepts/activation.md
@@ -325,6 +325,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]: ../concepts/manifest.md#vars-section
-[hook-section]: ../concepts/manifest.md#hook-section
-[profile-section]: ../concepts/manifest.md#profile-section
+[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
diff --git a/docs/tutorials/customizing-environments.md b/docs/tutorials/customizing-environments.md
index 7c27a56..925a387 100644
--- a/docs/tutorials/customizing-environments.md
+++ b/docs/tutorials/customizing-environments.md
@@ -148,4 +148,4 @@ Success. You can now start the database server using:
 [create_enviornments_guide]: ./creating-environments.md
 [multi-arch-guide]: ./multi-arch-environments.md
 [environment_concept]: ../concepts/environments.md
-[hook_concept]: ../concepts/manifest.md#hook-section
+[hook_concept]: ../reference/command-reference/manifest.toml.md#hook

From 82af58ab1665797aef052cf7c8380bbcd0af9d05 Mon Sep 17 00:00:00 2001
From: Dan Carley <dan@flox.dev>
Date: Thu, 15 May 2025 10:16:09 +0100
Subject: [PATCH 4/5] concepts: Rename environment heading anchors

In preperation for linking and redirect to them. The previous versions
were quite wordy when rendered above the sections, in the side navbar,
and as anchors like `#environment-manifest-floxenvmanifesttoml`.

Technically this will break existing links in the wild but I can't see
anywhere that we currently reference the anchors ourselves.
---
 docs/concepts/environments.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/concepts/environments.md b/docs/concepts/environments.md
index ac5e5b2..ab1d463 100644
--- a/docs/concepts/environments.md
+++ b/docs/concepts/environments.md
@@ -52,7 +52,7 @@ file in a `.flox` directory wherever the [`flox init`][flox_init] command was
 run.
 Let's look closer at the files that were generated.
 
-### Environment manifest: `.flox/env/manifest.toml`
+### `manifest.toml`
 
 The manifest is a declarative specification for the environment and contains 5
 parts:
@@ -67,7 +67,7 @@ parts:
 [customizing environments guide][customizing_environments_guide] to walk through
 examples.
 
-### Manifest lock: `.flox/env/manifest.lock`
+### `manifest.lock`
 
 The lock file serves as a snapshot of the specific versions of dependencies that
 were built and activated at a particular point in time.
@@ -89,7 +89,7 @@ were built and activated at a particular point in time.
 }
 ```
 
-### Environment metadata: `.flox/env.json`
+### `env.json`
 
 A metadata file that contains the name of the environment and the environment's
 version. Flox manages this file for you.

From 20cafbd9c6e2191a832996bc5803dd8d6bbd7ef9 Mon Sep 17 00:00:00 2001
From: Dan Carley <dan@flox.dev>
Date: Thu, 15 May 2025 10:06:31 +0100
Subject: [PATCH 5/5] concepts: Merge manifest concept into environments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `/concepts/manifest` page had content that overlapped with both:

- `manifest.toml` which contains a more complete listing of all the
  currently supported sections.
- `environments` which describes the files stored in `.flox/env/`

So merge it with environments, introduce the basic format and how to
edit, then link out to `manifest.toml` for more details.

The old URL will be redirected using the functionality that was added in
91141a7. It's worth noting that this doesn't return a 301 response
because the redirect is performed client-side from static content:

    % http :8000/docs/concepts/manifest/
    HTTP/1.0 200 OK
    Content-Length: 1280
    Content-Type: text/html
    Date: Thu, 15 May 2025 09:35:46 GMT
    Server: WSGIServer/0.2 CPython/3.11.9

    <!doctype html>
    <html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Redirecting...</title>
        <link rel="canonical" href="../environments/#files-manifest-toml">
        <script>var anchor=window.location.hash.substr(1);location.href="../environments/#files-manifest-toml"+(anchor?"#"+anchor:"")</script>
        <meta http-equiv="refresh" content="0; url=../environments/#files-manifest-toml">
    </head>
    <body>
    You're being redirected to a <a href="../environments/#files-manifest-toml">new destination</a>.
    <script>
    …

However it appears that search engines do treat this is a permanent
redirect (https://stackoverflow.com/a/19717455) and we can't redirect to
a new anchor using Netlify server-side redirects because they are a
client-side only concept (not sent as part of the request).

I don't think that we necessarily need to change the link from
the `flox init` templated manifest because the original URL is more
concise, even if it doesn't fit within the structure of the docs.
---
 docs/concepts/environments.md           |  29 ++-
 docs/concepts/flox-vs-containers.md     |   2 +-
 docs/concepts/floxhub.md                |   2 +-
 docs/concepts/manifest.md               | 325 ------------------------
 docs/concepts/packages-and-catalog.md   |   2 +-
 docs/tutorials/creating-environments.md |   2 +-
 docs/tutorials/migrations/homebrew.md   |   2 +-
 docs/tutorials/sharing-environments.md  |   4 +-
 mkdocs.yml                              |   5 +-
 9 files changed, 24 insertions(+), 349 deletions(-)
 delete mode 100644 docs/concepts/manifest.md

diff --git a/docs/concepts/environments.md b/docs/concepts/environments.md
index ab1d463..13098ed 100644
--- a/docs/concepts/environments.md
+++ b/docs/concepts/environments.md
@@ -50,27 +50,29 @@ sharing and working with different types of environments.
 A Flox environment stores its metadata, declarative manifest, and manifest lock
 file in a `.flox` directory wherever the [`flox init`][flox_init] command was
 run.
+All of these files can be stored in version control when working with path environments.
+
 Let's look closer at the files that were generated.
 
 ### `manifest.toml`
 
-The manifest is a declarative specification for the environment and contains 5
-parts:
+The manifest is a declarative specification for the environment which is [TOML][toml_spec] formatted.
+
+The best way to edit the manifest is by running [`flox edit`][flox_edit] which will launch your default editor and run validation when you save changes.
 
-- **Install:** the packages installed to the environment.
-- **Vars:** environment variables for use in the activated environment.
-- **Hook:** Bash script executed before passing control to the user's shell.
-- **Profile:** Shell-specific scripts sourced by the user's shell.
-- **Options:** Environment-scoped options such as supported systems.
+See [`manifest.toml`][manifest] for a complete description of the manifest format and the [customizing environments guide][customizing_environments_guide] to walk through examples.
 
-**[Read more about the manifest][manifest_concept]** and consult the
-[customizing environments guide][customizing_environments_guide] to walk through
-examples.
+```toml title="manifest.toml"
+version  = 1
+
+[install]
+nodejs.pkg-path = "nodejs_24"
+```
 
 ### `manifest.lock`
 
-The lock file serves as a snapshot of the specific versions of dependencies that
-were built and activated at a particular point in time.
+The lock file serves as a snapshot of the specific package versions and their dependencies that were built and activated at a particular point in time.
+Flox manages this file for you.
 
 ``` json title="manifest.lock"
 {
@@ -114,6 +116,7 @@ version. Flox manages this file for you.
 [create_guide]: ../tutorials/creating-environments.md
 [customizing_environments_guide]: ../tutorials/customizing-environments.md
 [generation_concept]: ./generations.md
-[manifest_concept]: ./manifest.md
 [floxhub_concept]: ./floxhub.md
 [discourse]: https://discourse.flox.dev/
+[manifest]: ../reference/command-reference/manifest.toml.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
index 4add2e0..aaa7229 100644
--- a/docs/concepts/flox-vs-containers.md
+++ b/docs/concepts/flox-vs-containers.md
@@ -447,6 +447,6 @@ you need to build a container so that it can be deployed.
 [activate]: ../reference/command-reference/flox-activate.md
 [services-start]: ../reference/command-reference/flox-services-start.md
 [services]: ../concepts/services.md
-[manifest]: ../concepts/manifest.md
+[manifest]: ../concepts/environments.md#manifesttoml
 [early]: https://flox.dev/early/
 [ci-cd]: ../tutorials/ci-cd.md
diff --git a/docs/concepts/floxhub.md b/docs/concepts/floxhub.md
index 9af7ac0..8e7ef95 100644
--- a/docs/concepts/floxhub.md
+++ b/docs/concepts/floxhub.md
@@ -105,5 +105,5 @@ Run the [`flox auth logout`][flox_auth] command.
 [flox_install]: ../reference/command-reference/flox-install.md
 [flox_uninstall]: ../reference/command-reference/flox-uninstall.md
 [generation_concept]: ../concepts/generations.md
-[manifest_concept]: ../concepts/manifest.md
+[manifest_concept]: ../concepts/environments.md#manifesttoml
 [environments_concept]: ../concepts/environments.md
diff --git a/docs/concepts/manifest.md b/docs/concepts/manifest.md
deleted file mode 100644
index e23600f..0000000
--- a/docs/concepts/manifest.md
+++ /dev/null
@@ -1,325 +0,0 @@
----
-title: What is an environment manifest?
-description: Everything you need to know about the environment's manifest.
----
-
-# What is an environment manifest?
-
-Flox environments come with a **declarative manifest** in [TOML][toml_spec] format.
-Combined with its lockfile, the manifest can reproduce the environment on another machine.
-
-## Editing your environment's manifest
-
-The manifest contains the following sections represented as [TOML][toml_spec] tables:
-
-- **[install]:** The packages installed to the environment.
-- **[vars]:** Environment variables for use in the activated environment.
-- **[hook]:** Bash script executed before passing control to the user's shell.
-- **[profile]:** Shell-specific scripts sourced by the user's shell.
-- **[services]:** Long-running programs you can start when you activate
-- **[options]:** Environment settings.
-
-The manifest can be edited with [`flox edit`][flox_edit] which allows validation to run when saving changes. This interactive editing option is useful for quick edits or to troubleshoot issues.
-
-### [install] section
-
-The install section of the manifest is the core of the environment -- the packages that will be available inside of the environment. Packages installed with [`flox install`][flox_install] will automatically get added to the `[install]` table.
-
-Installing `curl` via
-[`flox install`](../reference/command-reference/flox-install.md)
-
-``` console
-$ flox install curl
-```
-
-results in the following manifest (view the manifest with
-[`flox edit`](../reference/command-reference/flox-edit.md)):
-
-``` toml
-[install]
-curl.pkg-path = "curl"
-```
-
-The line that's added to the manifest has the form
-`<id>.pkg-path = "<pkg-path>"`.
-
-#### Identifying packages by `pkg-path`
-
-The Flox catalog contains a hierarchy of packages where some are at the top
-level,
-and others are contained under package sets.
-The `pkg-path` is the location of the package within the catalog,
-including the package sets that it may be nested under.
-For instance,
-`pip` is nested under `python3Packages`,
-so its `pkg-path` is `python3Packages.pip`.
-The `pkg-path` is also what's displayed in search results,
-so you should be able to copy and paste a search result into your manifest
-or use it in a [`flox install`](../reference/command-reference/flox-install.md)
-command.
-
-#### Specifying package versions
-
-The manifest can **install packages by semantic version** (semver).
-The package will only be installed if it has a semantic version that falls
-within the filter provided via the `version` key.
-You use the `@` character to join the package name with the version when using
-the CLI.
-
-Let's try installing `curl` with at least version 8.
-
-```console
-$ # quoting is necessary for search terms that contain '>' or '<'
-$ flox install 'curl@>=8'
-```
-
-Notice that the manifest now contains a second line with the semantic version
-filter.
-
-```toml
-[install]
-curl.pkg-path = "curl"
-curl.version = ">=8"
-```
-
-You may also request a specific version
-Here is an example of installing `curl` version 8.1.1:
-
-``` console
-$ flox install curl@8.1.1
-```
-
-Notice that the version line now starts with `=`.
-This is how you tell Flox to install exact versions or versions that don't
-adhere to semantic versioning.
-
-``` toml
-[install]
-curl.pkg-path = "curl"
-curl.version = "=8.1.1"
-```
-
-#### Installing packages to package groups
-
-Flox will try to install packages that have been known to work together by default.
-This allows Flox to ensure maximum compatibility and has the benefit of keeping the environment as small as possible.
-However, sometimes you may need software that varies in age: For example, `packageA` you want to be from last week while `packageB` you need to be a specific older version. In these cases, you may see Flox error saying the constraints are too tight. To resolve this, you can specify a separate collection of packages using their `pkg-group` attribute.
-
-```toml
-[install]
-packageA.pkg-path = "packageA"
-
-packageB.pkg-path = "packageB"
-packageB.version = "some.old.version"
-packageB.pkg-group = "backend" # (1)!
-```
-
-1. "backend" is an arbitrary name. Try naming your pkg-group matching the logical grouping.
-
-`pkg-group` is also useful for ensuring maximum compatibility between packages.
-In this example say you're developing a new machine learning library that
-depends on the XGBoost ML library.
-XGBoost links against the popular Boost C++ collection of libraries,
-and if we want to write our own C++ code that uses Boost,
-we'll want to link against the same version of Boost that XGBoost is using.
-We can ensure this happens by placing Boost and XGBoost in the same `pkg-group`.
-
-```toml
-[install]
-boost.pkg-path = "boost"
-boost.pkg-group = "my-ml-lib"
-xgboost.pkg-path = "xgboost"
-xgboost.pkg-group = "my-ml-lib"
-```
-
-#### System specific installations
-
-Sometimes you may have a package that requires a specific CPU architecture or operating system.
-To do this, include the system types supported for this package.
-The systems specified for a package must be a subset of `options.systems`.
-
-``` toml
-[install]
-gcc.pkg-path = "gcc-unwrapped"
-gcc.systems = ["x86_64-linux", "aarch64-linux"]
-```
-
-#### Giving packages convenient names with `id`s
-
-The `<id>` in `<id>.pkg-path = "<pkg-path>"` is the name by which we refer to a
-package,
-which may be distinct from the `pkg-path` of the package.
-By default the `id` is inferred from the `pkg-path`,
-but you may explicitly set the `id` during installation with the `--id` flag.
-This allows you to provide more convenient names for package in your manifest.
-
-### [vars] section
-
-The `[vars]` section of the manifest allows for environment variables to be set
-in the activated environment.
-These variables are also made available to the scripts in the `[hook]` and
-`[profile]` sections.
-
-In the below example, `messsage` and `message2` are set, used in the
-`profile.common` script to generate `greeting`, which is then used in the
-`hook.on-activate` script to echo the final variable:
-
-``` toml
-[vars]
-message = "Howdy"
-message2 = "partner"
-
-[hook]
-on-activate = """
-    export greeting="$message $message2"
-"""
-
-[profile]
-common = """
-    cowsay "$greeting" >&2;
-"""
-```
-
-### [hook] section
-
-The `on-activate` script in the `[hook]` section is useful for performing
-initialization in a predictable Bash shell environment.
-
-#### `on-activate`
-
-The `on-activate` script is sourced from a **bash** shell,
-and it can be useful for spawning processes, dynamically setting environment
-variables, and creating files and directories to be used by the subsequent
-profile scripts, commands, and shells.
-
-Hook scripts inherit environment variables set in the `[vars]` section,
-and variables set here will in turn be inherited by the `[profile]` scripts
-described below.
-
-Any output written to `stdout` in a hook script is redirected to `stderr` to
-avoid it being mixed with the output of profile section scripts that write to
-`stdout` for "in-place" activations.
-
-```toml
-[hook]
-on-activate = """
-    # Interact with the tty as you would in any script
-    echo "Starting up $FLOX_ENV_DESCRIPTION environment ..."
-    read -e -p "Favourite colour or favorite color? " value
-
-    # Set variables, create files and directories
-    venv_dir="$(mktemp -d)"
-    export venv_dir
-
-    # Perform initialization steps, e.g. create a python venv
-    python -m venv "$venv_dir"
-
-    # Invoke apps that configure the environment via stdout
-    eval "$(ssh-agent)"
-"""
-```
-
-The `on-activate` script is not re-run when activations are nested.
-A nested activation can occur when an environment is already active and either
-`eval "$(flox activate)"` or `flox activate -- CMD` is run.
-In this scenario, `on-activate` is not re-run.
-Currently, environment variables set by the first run of the `on-activate`
-script are captured and then later set by the nested activation,
-but this behavior may change.
-
-It is best to write hooks defensively, assuming the user is using the
-environment from any directory on their machine.
-
-### [profile] section
-
-Scripts defined in the `[profile]` section are sourced by *your shell* and
-inherit environment variables set in the `[vars]` section and by the `[hook]`
-scripts.
-The `profile.common` script is sourced for every shell,
-and special care should be taken to ensure compatibility with all shells.
-The `profile.<shell>` scripts are then sourced *after* `profile.common` by the
-corresponding shell.
-
-These scripts are useful for performing shell-specific customizations such as
-setting aliases or configuring the prompt.
-
-```toml
-[profile]
-common = """
-    echo "it's gettin' flox in here"
-"""
-bash = """
-    source $venv_dir/bin/activate
-    alias foo="echo bar"
-    set -o vi
-"""
-zsh = """
-    source $venv_dir/bin/activate
-    alias foo="echo bar"
-    bindkey -v
-"""
-```
-
-Profile scripts are re-run for nested activations.
-A nested activation can occur when an environment is already active and either
-`eval "$(flox activate)"` or `flox activate -- CMD` is run.
-In this scenario, profile scripts are run a second time.
-Re-running profile scripts allows aliases to be set in subshells that inherit
-from a parent shell with an already active environment.
-
-### [options] section
-
-The options section of the manifest allows for setting configuration around system
-types.
-Environments must specify all the systems that they are meant to be used on.
-
-``` toml
-[options]
-systems = ["x86_64-linux", "aarch64-linux"]
-```
-
-### [services] section
-
-The `[services]` section is where you define services that you want to
-configure and run as part of your environment.
-This could be a local version of a web server or database that your
-application would connect to in production.
-It could also be a program that live-reloads a website while you're working
-on its CSS.
-
-In order to start these services you would use the
-`flox activate --start-services` command to start services while activating the
-environment,
-or the `flox services start` command to start services if you've already
-activated the environment.
-If you make edits to an environment after activating and you want your services
-to pick up the edits,
-you can run the `flox services restart` command.
-
-To define a service you add a new entry to the `services` table in the manifest:
-
-```toml
-[services.database]
-command = "postgres start"
-vars.PGUSER = "myuser"
-vars.PGPASSWORD = "super-secret"
-vars.PGDATABASE = "mydb"
-vars.PGPORT = "9001"
-```
-
-This entry creates a service called `database` that starts a PostgreSQL
-database,
-and configures it through service-specific environment variables.
-The `command` field specifies a command to run (interpreted by Bash) to start
-the service.
-The `vars` set as part of this definition are only set for the service,
-and aren't visible to other services or to your shell.
-
-See [`manifest.toml`](../reference/command-reference/manifest.toml.md) for more
-details on the `[service]` section of the manifest.
-
-[toml_spec]: https://toml.io/en/v1.0.0
-[flox_init]: ../reference/command-reference/flox-init.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
diff --git a/docs/concepts/packages-and-catalog.md b/docs/concepts/packages-and-catalog.md
index 4410d61..e2b9990 100644
--- a/docs/concepts/packages-and-catalog.md
+++ b/docs/concepts/packages-and-catalog.md
@@ -37,5 +37,5 @@ Source by the Open Source Initiative (OSI).
 [flox_show]: ../reference/command-reference/flox-show.md
 [flox_install]: ../reference/command-reference/flox-install.md
 [flox_update]: ../reference/command-reference/flox-update.md
-[manifest_concept]:./manifest.md
+[manifest_concept]: ./environments.md#manifesttoml
 [nixpkgs]: https://github.com/NixOS/nixpkgs
diff --git a/docs/tutorials/creating-environments.md b/docs/tutorials/creating-environments.md
index 91c4394..54b0463 100644
--- a/docs/tutorials/creating-environments.md
+++ b/docs/tutorials/creating-environments.md
@@ -237,7 +237,7 @@ $
 [flox_edit]: ../reference/command-reference/flox-edit.md
 [sharing_guide]: ./sharing-environments.md
 [layering_guide]: ./layering-multiple-environments.md
-[manifest_concept]: ../concepts/manifest.md
+[manifest_concept]: ../concepts/environments.md#manifesttoml
 [environment_concept]: ../concepts/environments.md
 [customizing_guide]: ./customizing-environments.md
 
diff --git a/docs/tutorials/migrations/homebrew.md b/docs/tutorials/migrations/homebrew.md
index 2c6c367..247c2ed 100644
--- a/docs/tutorials/migrations/homebrew.md
+++ b/docs/tutorials/migrations/homebrew.md
@@ -197,7 +197,7 @@ However, if you have the Flox default environment enabled, you should be aware o
 
 We recommend that the Flox default environment activation lines appear lowest in your dotfiles, ensuring that packages in the default environment appear in your `PATH` sooner than those from Homebrew.
 
-[manifest_concept]: ../../concepts/manifest.md
+[manifest_concept]: ../../concepts/environments.md#manifesttoml
 [default_tutorial]: ../default-environment.md
 [default_tutorial_setup]: ../default-environment.md#initial-setup
 [creating_tutorial]: ../creating-environments.md
diff --git a/docs/tutorials/sharing-environments.md b/docs/tutorials/sharing-environments.md
index 39380b9..de10353 100644
--- a/docs/tutorials/sharing-environments.md
+++ b/docs/tutorials/sharing-environments.md
@@ -16,7 +16,7 @@ Flox provides **three main ways of sharing environments** with others:
 New [environments][environment_concept] created with [`flox init`][flox_init] will create a `.flox` folder in the directory where [`flox init`][flox_init] was run. This folder contains everything required to run this environment on their system and can be sent to another user any way files are shared. It is most common to commit the `.flox` to a version controlled code repository such as git. If shared this way, the user needs only `git clone` the project and `flox activate` in the directory containing the `.flox`.  
 
 !!! note "Note"
-    If you are sharing an environment with a user on a different CPU architecture or OS from the person who created the environment, you may run into some issues where system-specific packages are not available on their OS. This can be fixed with a minor edit to the manifest, described in the [manifest concept][edit_manifest_tutorial]. If you get stumped, reach out to us on our [forum][discourse] for assistance.
+    If you are sharing an environment with a user on a different CPU architecture or OS from the person who created the environment, you may run into some issues where system-specific packages are not available on their OS. This can be fixed with a minor edit to the manifest, described in the [manifest concept][manifest_concept]. If you get stumped, reach out to us on our [forum][discourse] for assistance.
 
 Here is an example of sharing a project with files. The first person creates the environment:
 
@@ -56,7 +56,7 @@ $ flox activate
 
 [flox_init]: ../reference/command-reference/flox-init.md
 [discourse]: https://discourse.flox.dev/
-[edit_manifest_tutorial]: ../concepts/manifest.md
+[manifest_concept]: ../concepts/environments.md#manifesttoml
 
 ## Sharing environments on FloxHub
 
diff --git a/mkdocs.yml b/mkdocs.yml
index ad7c6bd..49f166a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -48,7 +48,6 @@ nav:
       - ... | flat | tutorials/migrations/*
   - Concepts:
     - Environments: concepts/environments.md
-    - Environment manifest: concepts/manifest.md
     - Activating environments: concepts/activation.md
     - FloxHub: concepts/floxhub.md
     - Generations: concepts/generations.md
@@ -297,6 +296,4 @@ plugins:
     # https://github.com/mkdocs/mkdocs-redirects
     - redirects:
         redirect_maps:
-        #  'old.md': 'new.md'
-        #  'old/file.md': 'new/file.md'
-        #  'some_file.md': 'http://external.url.com/foobar'
+            'concepts/manifest.md': 'concepts/environments.md#manifesttoml'