diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 47aa6b824292..59c4ece07c7c 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -516,7 +516,7 @@ external tools may wish to use them in a consistent fashion, such as referring
to the data in `workspace.metadata` if data is missing from `package.metadata`,
if that makes sense for the tool in question.
-[workspace-metadata]: workspaces.md#the-workspacemetadata-table
+[workspace-metadata]: workspaces.md#the-metadata-table
#### The `default-run` field
diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md
index 15c705d68337..d6b4c6449dbb 100644
--- a/src/doc/src/reference/specifying-dependencies.md
+++ b/src/doc/src/reference/specifying-dependencies.md
@@ -489,7 +489,7 @@ rand = { workspace = true, optional = true }
[crates.io]: https://crates.io/
[dev-dependencies]: #development-dependencies
-[workspace.dependencies]: workspaces.md#the-workspacedependencies-table
+[workspace.dependencies]: workspaces.md#the-dependencies-table
[optional]: features.md#optional-dependencies
[features]: features.md
diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index a04c51fdc769..6570a61e52e3 100644
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -1358,7 +1358,7 @@ for more information.
### Workspace Inheritance
Workspace Inheritance has been stabilized in the 1.64 release.
-See [workspace.package](workspaces.md#the-workspacepackage-table),
-[workspace.dependencies](workspaces.md#the-workspacedependencies-table),
+See [workspace.package](workspaces.md#the-package-table),
+[workspace.dependencies](workspaces.md#the-dependencies-table),
and [inheriting-a-dependency-from-a-workspace](specifying-dependencies.md#inheriting-a-dependency-from-a-workspace)
-for more information.
\ No newline at end of file
+for more information.
diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
index bb3872265d15..b09d1861d0a4 100644
--- a/src/doc/src/reference/workspaces.md
+++ b/src/doc/src/reference/workspaces.md
@@ -6,36 +6,87 @@ various settings such as profiles. Packages that are part of a workspaces are
called *workspace members*. There are two flavours of workspaces: as root
package or as virtual manifest.
-### Root package
+The key points of workspaces are:
+
+* All packages share a common `Cargo.lock` file which resides in the
+ *workspace root*.
+* All packages share a common [output directory], which defaults to a
+ directory named `target` in the *workspace root*.
+* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
+ sections in `Cargo.toml` are only recognized in the *root* manifest, and
+ ignored in member crates' manifests.
+
+
+In a workspace, package-related cargo commands like [`cargo build`] can use
+the `-p` / `--package` or `--workspace` command-line flags to determine which
+packages to operate on. If neither of those flags are specified, Cargo will
+use the package in the current working directory. If the current directory is
+a virtual workspace, it will apply to all members (as if `--workspace` were
+specified on the command-line).
+
+See also [`default-members`](#the-default-members-field)
+
+The `[workspace]` table supports the following sections:
+
+* [`[workspace]`](#the-workspace-section) — Defines a workspace.
+ * [`members`](#the-members-and-exclude-fields) — Packages to include in the workspace.
+ * [`exclude`](#the-members-and-exclude-fields) — Packages to exclude from the workspace.
+ * [`default-members`](#the-default-members-field) — Packages to operate on when a specific package wasn't selected.
+ * [`metadata`](#the-metadata-table) — Extra settings for external tools.
+ * [`package`](#the-package-table) — Keys for inheriting in packages.
+ * [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies.
-A workspace can be created by adding a [`[workspace]`
-section](#the-workspace-section) to `Cargo.toml`. This can be added to a
-`Cargo.toml` that already defines a `[package]`, in which case the package is
+### The `[workspace]` section
+
+To create a workspace, you add the `[workspace]` table to a `Cargo.toml`:
+```toml
+[workspace]
+# ...
+```
+
+At minimum, a workspace has to have a member, either with a root package or as
+a virtual manifest.
+
+#### Root package
+
+If the [`[workspace]` section](#the-workspace-section) is added to a
+`Cargo.toml` that already defines a `[package]`, the package is
the *root package* of the workspace. The *workspace root* is the directory
where the workspace's `Cargo.toml` is located.
-### Virtual manifest
+```toml
+[workspace]
+
+[package]
+name = "hello_world" # the name of the package
+version = "0.1.0" # the current version, obeying semver
+authors = ["Alice ", "Bob "]
+```
+
+#### Virtual manifest
Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section
but without a [`[package]` section][package]. This is called a *virtual
manifest*. This is typically useful when there isn't a "primary" package, or
you want to keep all the packages organized in separate directories.
-### Key features
-
-The key points of workspaces are:
+```toml
+# [PROJECT_DIR]/Cargo.toml
+[workspace]
+members = ["hello_world"]
+```
-* All packages share a common `Cargo.lock` file which resides in the
- *workspace root*.
-* All packages share a common [output directory], which defaults to a
- directory named `target` in the *workspace root*.
-* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
- sections in `Cargo.toml` are only recognized in the *root* manifest, and
- ignored in member crates' manifests.
+```toml
+# [PROJECT_DIR]/hello_world/Cargo.toml
+[package]
+name = "hello_world" # the name of the package
+version = "0.1.0" # the current version, obeying semver
+authors = ["Alice ", "Bob "]
+```
-### The `[workspace]` section
+### The `members` and `exclude` fields
-The `[workspace]` table in `Cargo.toml` defines which packages are members of
+The `[members]` and `exclude` fields define which packages are members of
the workspace:
```toml
@@ -56,11 +107,6 @@ workspace. This can be useful if some path dependencies aren't desired to be
in the workspace at all, or using a glob pattern and you want to remove a
directory.
-An empty `[workspace]` table can be used with a `[package]` to conveniently
-create a workspace with the package and all of its path dependencies.
-
-### Workspace selection
-
When inside a subdirectory within the workspace, Cargo will automatically
search the parent directories for a `Cargo.toml` file with a `[workspace]`
definition to determine which workspace to use. The [`package.workspace`]
@@ -68,14 +114,7 @@ manifest key can be used in member crates to point at a workspace's root to
override this automatic search. The manual setting can be useful if the member
is not inside a subdirectory of the workspace root.
-### Package selection
-
-In a workspace, package-related cargo commands like [`cargo build`] can use
-the `-p` / `--package` or `--workspace` command-line flags to determine which
-packages to operate on. If neither of those flags are specified, Cargo will
-use the package in the current working directory. If the current directory is
-a virtual workspace, it will apply to all members (as if `--workspace` were
-specified on the command-line).
+### The `default-members` field
The optional `default-members` key can be specified to set the members to
operate on when in the workspace root and the package selection flags are not
@@ -89,7 +128,7 @@ default-members = ["path/to/member2", "path/to/member3/foo"]
When specified, `default-members` must expand to a subset of `members`.
-### The `workspace.metadata` table
+### The `metadata` table
The `workspace.metadata` table is ignored by Cargo and will not be warned
about. This section can be used for tools that would like to store workspace
@@ -112,7 +151,7 @@ external tools may wish to use them in a consistent fashion, such as referring
to the data in `workspace.metadata` if data is missing from `package.metadata`,
if that makes sense for the tool in question.
-### The `workspace.package` table
+### The `package` table
The `workspace.package` table is where you define keys that can be
inherited by members of a workspace. These keys can be inherited by
@@ -157,7 +196,7 @@ description.workspace = true
documentation.workspace = true
```
-### The `workspace.dependencies` table
+### The `dependencies` table
The `workspace.dependencies` table is where you define dependencies to be
inherited by members of a workspace.