This is an automated email from the ASF dual-hosted git repository.
erose pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new 3c3b327a HDDS-10885. Add a landing page for each section of the
documentation. (#92)
3c3b327a is described below
commit 3c3b327a43212ac5b1f1aabd171a51911a8fca14
Author: Ethan Rose <[email protected]>
AuthorDate: Wed Aug 21 11:16:17 2024 -0400
HDDS-10885. Add a landing page for each section of the documentation. (#92)
---
.github/resource/category.schema.json | 17 -------
.github/resource/sidebar_tips.md | 8 ++++
.github/scripts/file_names.sh | 2 +-
.github/scripts/sidebar.sh | 29 ++++++------
.github/scripts/spelling.sh | 2 +-
.github/workflows/static.yml | 4 ++
.licenserc.yaml | 2 +-
.markdownlint.yaml | 2 +
CONTRIBUTING.md | 26 ++++++----
cspell.yaml | 1 +
docs/02-quick-start/01-installation/README.mdx | 11 +++++
docs/02-quick-start/01-installation/_category_.yml | 1 -
docs/02-quick-start/README.mdx | 11 +++++
docs/02-quick-start/_category_.yml | 1 -
docs/03-core-concepts/02-replication/README.mdx | 11 +++++
.../03-core-concepts/02-replication/_category_.yml | 1 -
.../03-namespace/01-volumes/README.mdx | 11 +++++
.../03-namespace/01-volumes/_category_.yml | 1 -
.../03-namespace/02-buckets/04-layouts/README.mdx | 11 +++++
.../02-buckets/04-layouts/_category_.yml | 1 -
.../03-namespace/02-buckets/README.mdx | 11 +++++
.../03-namespace/02-buckets/_category_.yml | 1 -
docs/03-core-concepts/03-namespace/README.mdx | 11 +++++
docs/03-core-concepts/03-namespace/_category_.yml | 1 -
.../04-security/01-authentication/02-knox.md | 7 ---
.../01-authentication/03-s3-credentials.md | 7 ---
.../04-security/01-authentication/_category_.yml | 1 -
.../{01-authentication => }/01-kerberos.md | 2 +-
.../01-native-acls.md | 0
.../02-ranger-acls.md | 0
.../04-security/02-acls/README.mdx | 11 +++++
.../04-security/02-authorization/_category_.yml | 1 -
docs/03-core-concepts/04-security/README.mdx | 11 +++++
docs/03-core-concepts/04-security/_category_.yml | 1 -
docs/03-core-concepts/05-configuration-files.md | 11 -----
docs/03-core-concepts/README.mdx | 11 +++++
docs/03-core-concepts/_category_.yml | 1 -
docs/04-user-guide/01-client-interfaces/04-s3a.md | 2 +-
docs/04-user-guide/01-client-interfaces/README.mdx | 7 +++
.../01-client-interfaces/_category_.yml | 1 -
docs/04-user-guide/02-clients/01-ozone.md | 13 +++++
docs/04-user-guide/02-clients/02-hdfs.md | 9 ++++
docs/04-user-guide/02-clients/03-s3.md | 13 +++++
docs/04-user-guide/02-clients/README.mdx | 11 +++++
docs/04-user-guide/02-integrations/_category_.yml | 1 -
.../01-hive.md | 0
.../{02-integrations => 03-integrations}/02-hue.md | 0
.../03-iceberg.md | 0
.../04-impala.md | 0
.../05-oozie.md | 0
.../06-spark.md | 0
.../07-trino.md | 0
docs/04-user-guide/03-integrations/README.mdx | 11 +++++
docs/04-user-guide/README.mdx | 7 +++
docs/04-user-guide/_category_.yml | 1 -
.../01-installation/README.mdx | 11 +++++
.../01-installation/_category_.yml | 1 -
.../01-basic/01-configuration-files.md | 5 ++
.../01-basic/01-network/_category_.yml | 1 -
.../01-basic/02-directories/_category_.yml | 1 -
.../{01-network => 02-network}/01-ozone-manager.md | 0
.../02-storage-container-manager.md | 0
.../{01-network => 02-network}/03-datanode.md | 0
.../{01-network => 02-network}/04-recon.md | 0
.../{01-network => 02-network}/05-s3-gateway.md | 0
.../{01-network => 02-network}/07-default-ports.md | 0
.../01-basic/02-network/README.mdx | 11 +++++
.../01-ozone-manager.md | 0
.../02-storage-container-manager.md | 0
.../03-datanode.md | 0
.../{02-directories => 03-directories}/04-recon.md | 0
.../01-basic/03-directories/README.mdx | 11 +++++
.../02-configuration/01-basic/README.mdx | 11 +++++
.../02-configuration/01-basic/_category_.yml | 1 -
.../02-logging/01-application-logs.md | 15 ++++++
.../02-configuration/02-logging/01-placeholder.md | 5 --
.../02-configuration/02-logging/02-audit-logs.md | 15 ++++++
.../02-configuration/02-logging/README.mdx | 11 +++++
.../02-configuration/02-logging/_category_.yml | 1 -
.../03-security/{01-kerberos.md => 02-kerberos.md} | 0
.../01-network-encryption/_category_.yml | 1 -
.../03-security/04-encryption/_category_.yml | 1 -
.../03-security/{02-knox.md => 04-knox.md} | 0
.../01-network-encryption/01-hadoop-rpc.md | 0
.../01-network-encryption/02-grpc.md | 0
.../01-network-encryption/03-https.md | 0
.../05-encryption/01-network-encryption/README.mdx | 11 +++++
.../02-transparent-data-encryption.md | 0
.../03-security/05-encryption/README.mdx | 11 +++++
.../02-configuration/03-security/README.mdx | 11 +++++
.../02-configuration/03-security/_category_.yml | 1 -
.../{01-topology.md => 02-topology.md} | 0
.../02-configuration/04-performance/README.mdx | 11 +++++
.../02-configuration/04-performance/_category_.yml | 1 -
.../02-configuration/05-appendix.md | 7 +++
.../02-configuration/README.mdx | 11 +++++
.../02-configuration/_category_.yml | 1 -
.../README.mdx | 11 +++++
.../_category_.yml | 1 -
.../03-operations/04-disk-replacement/README.mdx | 7 +++
.../04-disk-replacement/_category_.yml | 1 -
.../03-operations/05-balancing-datanodes.md | 3 --
.../05-data-balancing.md} | 4 +-
.../09-observability/02-recon/02-recon-rest-api.md | 2 +-
.../09-observability/02-recon/README.mdx | 7 +++
.../09-observability/02-recon/_category_.yml | 1 -
.../03-operations/09-observability/README.mdx | 7 +++
.../03-operations/09-observability/_category_.yml | 1 -
.../03-operations/README.mdx | 11 +++++
.../03-operations/_category_.yml | 1 -
docs/05-administrator-guide/README.mdx | 11 +++++
docs/05-administrator-guide/_category_.yml | 1 -
docs/06-troubleshooting/07-integrations/README.mdx | 11 +++++
.../07-integrations/_category_.yml | 1 -
docs/06-troubleshooting/08-security/README.mdx | 11 +++++
docs/06-troubleshooting/08-security/_category_.yml | 1 -
docs/06-troubleshooting/README.mdx | 7 +++
docs/06-troubleshooting/_category_.yml | 1 -
.../01-components/01-ozone-manager/README.mdx | 11 +++++
.../01-components/01-ozone-manager/_category_.yml | 1 -
.../02-storage-container-manager/README.mdx | 11 +++++
.../02-storage-container-manager/_category_.yml | 1 -
.../01-components/03-datanode/README.mdx | 11 +++++
.../01-components/03-datanode/_category_.yml | 1 -
.../01-components/04-recon/README.mdx | 11 +++++
.../01-components/04-recon/_category_.yml | 1 -
.../01-components/05-s3-gateway/README.mdx | 11 +++++
.../01-components/05-s3-gateway/_category_.yml | 1 -
.../01-components/06-client/README.mdx | 11 +++++
.../01-components/06-client/_category_.yml | 1 -
docs/07-system-internals/01-components/README.mdx | 11 +++++
.../01-components/_category_.yml | 1 -
.../02-data-operations/README.mdx | 11 +++++
.../02-data-operations/_category_.yml | 1 -
.../03-data-integrity/README.mdx | 11 +++++
.../03-data-integrity/_category_.yml | 1 -
.../{01-metadata-replication.md => 01-metadata.md} | 6 ++-
.../01-write-pipelines/_category_.yml | 1 -
.../02-containers/_category_.yml | 1 -
.../02-data-replication/_category_.yml | 1 -
.../01-write-pipelines/01-overview.md | 0
.../01-write-pipelines/02-types.md | 0
.../01-write-pipelines/03-states.md | 0
.../01-write-pipelines/04-reports.md | 0
.../01-write-pipelines/05-creation.md | 0
.../01-write-pipelines/06-persistence.md | 0
.../01-write-pipelines/07-destruction.md | 0
.../02-data/01-write-pipelines/README.mdx | 11 +++++
.../02-containers/01-overview.md | 0
.../02-containers/02-types.md | 0
.../02-containers/03-states.md | 0
.../02-containers/04-reports.md | 0
.../02-containers/05-creation.md | 0
.../02-containers/06-persistence.md | 0
.../02-containers/07-destruction.md | 0
.../02-containers/08-replication.md | 0
.../02-containers/09-offline-reconstruction.md | 0
.../02-data/02-containers/README.mdx | 11 +++++
.../03-replication-manager.md | 0
.../04-container-balancer.md | 0
.../04-replication/02-data/README.mdx | 11 +++++
docs/07-system-internals/04-replication/README.mdx | 11 +++++
.../04-replication/_category_.yml | 1 -
docs/07-system-internals/05-security/README.mdx | 11 +++++
.../07-system-internals/05-security/_category_.yml | 1 -
.../06-network-protocols/README.mdx | 11 +++++
.../06-network-protocols/_category_.yml | 1 -
docs/07-system-internals/07-features/README.mdx | 11 +++++
.../07-system-internals/07-features/_category_.yml | 1 -
docs/07-system-internals/README.mdx | 7 +++
docs/07-system-internals/_category_.yml | 1 -
docs/08-developer-guide/01-build/README.mdx | 11 +++++
docs/08-developer-guide/01-build/_category_.yml | 1 -
docs/08-developer-guide/02-run/README.mdx | 11 +++++
docs/08-developer-guide/02-run/_category_.yml | 1 -
docs/08-developer-guide/03-test/README.mdx | 11 +++++
docs/08-developer-guide/03-test/_category_.yml | 1 -
docs/08-developer-guide/04-project/README.mdx | 11 +++++
docs/08-developer-guide/04-project/_category_.yml | 1 -
docs/08-developer-guide/README.mdx | 7 +++
docs/08-developer-guide/_category_.yml | 1 -
docusaurus.config.js | 11 ++---
package.json | 1 -
pnpm-lock.yaml | 55 +++++++---------------
sidebars.js | 40 ----------------
src/pages/index.js | 2 +-
186 files changed, 731 insertions(+), 225 deletions(-)
diff --git a/.github/resource/category.schema.json
b/.github/resource/category.schema.json
deleted file mode 100644
index afa67b90..00000000
--- a/.github/resource/category.schema.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
- "$schema": "http://json-schema.org/draft-07/schema#";,
- "$id": "https://ozone.apache.org/category.schema.json";,
- "title": "Category",
- "description": "Validates an allowed subset of keys in Docusaurus
_category_.yml files.",
- "type": "object",
- "properties": {
- "label": {
- "description": "The name of this section shown in the docs sidebar.",
- "type": "string"
- }
- },
- "required": [
- "label"
- ],
- "additionalProperties": false
-}
diff --git a/.github/resource/sidebar_tips.md b/.github/resource/sidebar_tips.md
new file mode 100644
index 00000000..7d8a914e
--- /dev/null
+++ b/.github/resource/sidebar_tips.md
@@ -0,0 +1,8 @@
+# Documentation Sidebar Check Failed
+
+Every docs directory must have a `README.mdx` file to configure how it is
displayed in the documentation sidebar. This file must contain a generated
index of pages in the section by adding the following lines:
+
+1. Add `import DocCardList from '@theme/DocCardList';` anywhere in the
*README.mdx* file.
+2. Add the `<DocCardList/>` tag at the end of the file.
+
+For more information on documentation sidebar configuration, see the
[contributing
guide](https://github.com/apache/ozone-site/blob/HDDS-9225-website-v2/CONTRIBUTING.md#documentation-sidebar).
diff --git a/.github/scripts/file_names.sh b/.github/scripts/file_names.sh
index 62303ed2..1bda3fa7 100755
--- a/.github/scripts/file_names.sh
+++ b/.github/scripts/file_names.sh
@@ -49,7 +49,7 @@ for file in $(find "$root"/docs/*); do
if [ -d "$file" ]; then
# Check docs directories.
check_regex "$file" "$doc_dir_regex"
- elif is_markdown "$file"; then
+ elif is_markdown "$file" && [ "$(basename "$file")" != README.mdx ]; then
# Check docs files.
check_regex "$file" "$doc_file_regex"
fi
diff --git a/.github/scripts/sidebar.sh b/.github/scripts/sidebar.sh
index 330ccc5b..2699afcd 100755
--- a/.github/scripts/sidebar.sh
+++ b/.github/scripts/sidebar.sh
@@ -16,31 +16,30 @@
# specific language governing permissions and limitations
# under the License.
-# Validates docusaurus _category_.yml files used to configure the docs sidebar.
-# Each docs subdirectory should have a _category_.yml file, and it must follow
the defined schema.
-# The schema is more restrictive than what Docusaurus allows, and can be used
to disallow keys or require all category
-# files to define the same keys.
+# Validates docusaurus README.mdx files used to configure sections in the docs
sidebar.
+# Each docs subdirectory should have a README.mdx file, and the file should
contain a generated index of pages or
+# subsections using the `<DocCardList/>` tag as its last line.
rc=0
+missing_index=0
root="$(git rev-parse --show-toplevel)"
-schema="$root"/.github/resource/category.schema.json
+index_name='README.mdx'
-# Make sure all docs directories have a category sidebar file.
+# Make sure all docs directories have an index file that contains an index of
subsections.
for child in $(find "$root"/docs/* -type d); do
- category_file="$child/_category_.yml"
- if [ ! -f "$category_file" ]; then
- echo "_category_.yml is required for docs subdirectory $child" 1>&2
+ index_file="$child/$index_name"
+ if [ ! -f "$index_file" ]; then
+ echo "A $index_name index file is required in the docs subdirectory
$child" 1>&2
+ rc=1
+ elif [ "$(tail -n1 "$index_file")" != '<DocCardList/>' ]; then
+ echo "$index_file is missing an index of sidebar items." 1>&2
rc=1
fi
done
-[ "$rc" = 0 ] || exit $rc
-
-# If all category files are present, make sure they follow the schema.
-if ! pnpm ajv validate -s "$schema" -d "$root/docs/**/_category_.yml"
1>/dev/null; then
- rc=1
- echo "Sidebar configuration validation failed against JSON schema $schema"
1>&2
+if [ "$rc" != 0 ]; then
+ printf '\n%s\n' 'For help with documentation sidebar configuration see
https://github.com/apache/ozone-site/blob/HDDS-9225-website-v2/CONTRIBUTING.md#documentation-sidebar'
1>&2
fi
exit "$rc"
diff --git a/.github/scripts/spelling.sh b/.github/scripts/spelling.sh
index 5bb0c506..687cd62f 100755
--- a/.github/scripts/spelling.sh
+++ b/.github/scripts/spelling.sh
@@ -21,7 +21,7 @@ root="$(git rev-parse --show-toplevel)"
rc=0
printf '%s\n' 'Checking document content...'
-pnpm cspell lint --root="$root" --no-progress --show-context '**/*.md'
'**/_category_.yml' || rc="$?"
+pnpm cspell lint --root="$root" --no-progress --show-context '**/*.md'
'**/*.mdx' || rc="$?"
printf '\n%s\n' 'Checking file names...'
find "$root"/docs "$root"/src/pages | pnpm cspell --no-progress --show-context
stdin://'File Name' || rc="$?"
diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml
index 25753879..d50d4b43 100644
--- a/.github/workflows/static.yml
+++ b/.github/workflows/static.yml
@@ -110,6 +110,10 @@ jobs:
working-directory: ${{ env.script_dir }}
run: |
./sidebar.sh
+ - name: Output sidebar check tips
+ if: ${{ failure() }}
+ run: |
+ cat ${{ env.resource_dir }}/sidebar_tips.md >> $GITHUB_STEP_SUMMARY
lint-yaml:
runs-on: ubuntu-latest
steps:
diff --git a/.licenserc.yaml b/.licenserc.yaml
index 6c584481..284f25f5 100644
--- a/.licenserc.yaml
+++ b/.licenserc.yaml
@@ -30,7 +30,7 @@ header:
# See examples on https://github.com/apache/www-site and the skywalking-eyes
recommended configuration for
# Apache projects at
https://github.com/apache/skywalking-eyes?tab=readme-ov-file#github-actions
- "**/*.md"
- - "**/_category_.yml"
+ - "**/*.mdx"
- pnpm-lock.yaml
# Do not comment on pull requests.
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
index cb218b36..b390d359 100644
--- a/.markdownlint.yaml
+++ b/.markdownlint.yaml
@@ -41,6 +41,7 @@ no-inline-html:
- br
- Tabs
- TabItem
+ - DocCardList
# Allow bare URLs since wrapping URLs in <> is invalid mdx.
no-bare-urls: false
@@ -96,6 +97,7 @@ proper-names:
- RocksDB
- Jira
- Java
+ - JVM
- Maven
- GPG
- Netty
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index eedbbb81..00e4aa1e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -56,14 +56,6 @@ The Apache Ozone Website uses
[Docusaurus](https://docusaurus.io/) as a static s
- Contains older versions of the documentation.
- Only update files in this directory if you need to backport a fix to older
versions of the documentation.
-- [sidebars.js](https://docusaurus.io/docs/sidebar/autogenerated)
- - Configuration of the documentation menu sidebars.
- - This file should not need to be modified since the menu will be
auto-generated from the directory and file layout.
-
-- [versioned_sidebars](https://docusaurus.io/docs/versioning)
- - Contains older versions of the documentation sidebars.
- - Only update files in this directory if you need to backport a fix to older
versions of the documentation.
-
- [versions.json](https://docusaurus.io/docs/versioning)
- Contains a list of all versions of the documentation.
@@ -113,8 +105,6 @@ Docusaurus provides many options for laying out
documentation pages and their me
- [Number
prefixes](https://docusaurus.io/docs/sidebar/autogenerated#using-number-prefixes)
should be used for all file and sidebar directory names to enforce their order
in the website and local editors.
- Number prefixes will be automatically removed from links in the Docusaurus
build.
-- [Category links](https://docusaurus.io/docs/sidebar/items#category-link)
should not be used. They make it easy to miss pages when looking at the sidebar
since it is unclear if they are just a dropdown or also contain documentation.
-
- Let Docusaurus automatically generate a webpage URL from the file name.
- File names and therefore generated URLs should all be `kebab-case`.
@@ -199,6 +189,22 @@ The file names and content of all markdown pages are
checked for spelling mistak
- **Option 2:** If the word is only relevant for one specific page, add an
[inline directive](https://cspell.org/configuration/document-settings/) as a
comment in the markdown front matter of that page only.
+#### Documentation Sidebar
+
+Docusaurus provides a few different options to configure the documentation
sidebar that organizes documentation pages into dropdown sections. The Ozone
website configures this using a *README.mdx* file in each documentation
directory. This gives a one to one mapping of subdirectories of the *docs*
directory to sidebar dropdown sections.
+
+When creating a new *docs* subdirectory (which will be rendered as a sidebar
section), add a *README.mdx* file to that directory. In this file:
+
+1. Use the `sidebar_label` front matter key to give the section a brief title
that will be shown in the sidebar.
+2. Add a descriptive title on the markdown page itself.
+ - This should be more verbose than the sidebar label as described in [Best
Practices](#best-practices) for documentation pages.
+3. Write a brief summary (usually just one sentence) about the content in that
section.
+ - Avoid placing actual documentation on these pages, since it may be
missed by readers clicking through the sidebar.
+ - If an overview of content in a section is required, add a dedicated
"Overview" page to the section.
+4. Add an automatically generated index of the content in this section as the
last line in the markdown file. Adding this index is described in the
[Docusaurus
docs](https://docusaurus.io/docs/sidebar/items#embedding-generated-index-in-doc-page),
but in summary it only requires two lines:
+ 1. Add `import DocCardList from '@theme/DocCardList';` anywhere in the
*README.mdx* file.
+ 2. Add the `<DocCardList/>` tag at the end of the file.
+
### Updating Graphics
When adding or updating graphics in the Ozone website, please follow these
guidelines:
diff --git a/cspell.yaml b/cspell.yaml
index f58115e4..68515b9f 100644
--- a/cspell.yaml
+++ b/cspell.yaml
@@ -90,6 +90,7 @@ words:
- sed
- mds
- javadoc
+- JVM
# Misc words
- acking
- dashboarding
diff --git a/docs/02-quick-start/01-installation/README.mdx
b/docs/02-quick-start/01-installation/README.mdx
new file mode 100644
index 00000000..cbf05164
--- /dev/null
+++ b/docs/02-quick-start/01-installation/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Installation
+---
+
+# Ozone Installation Quick Start
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions to quickly install an Ozone instance on
your local machine that can be used for testing and evaluation. For
instructions to install a production Ozone instance, see the [Administrator
Guide](../../administrator-guide/installation).
+
+<DocCardList/>
diff --git a/docs/02-quick-start/01-installation/_category_.yml
b/docs/02-quick-start/01-installation/_category_.yml
deleted file mode 100644
index f8e427f3..00000000
--- a/docs/02-quick-start/01-installation/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Installation
diff --git a/docs/02-quick-start/README.mdx b/docs/02-quick-start/README.mdx
new file mode 100644
index 00000000..66546a4e
--- /dev/null
+++ b/docs/02-quick-start/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Quick Start
+---
+
+# Quick Start
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions to quickly start an Ozone instance on your
local machine and run basic operations against it.
+
+<DocCardList/>
diff --git a/docs/02-quick-start/_category_.yml
b/docs/02-quick-start/_category_.yml
deleted file mode 100644
index 47aaff2d..00000000
--- a/docs/02-quick-start/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Quick Start
diff --git a/docs/03-core-concepts/02-replication/README.mdx
b/docs/03-core-concepts/02-replication/README.mdx
new file mode 100644
index 00000000..41904c82
--- /dev/null
+++ b/docs/03-core-concepts/02-replication/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Replication
+---
+
+# Data and Metadata Replication
+
+import DocCardList from '@theme/DocCardList';
+
+This section describes how data and metadata are replicated consistently
within Ozone.
+
+<DocCardList/>
diff --git a/docs/03-core-concepts/02-replication/_category_.yml
b/docs/03-core-concepts/02-replication/_category_.yml
deleted file mode 100644
index 7fbd19da..00000000
--- a/docs/03-core-concepts/02-replication/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Replication
diff --git a/docs/03-core-concepts/03-namespace/01-volumes/README.mdx
b/docs/03-core-concepts/03-namespace/01-volumes/README.mdx
new file mode 100644
index 00000000..260fd860
--- /dev/null
+++ b/docs/03-core-concepts/03-namespace/01-volumes/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Volumes
+---
+
+# Volumes
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents configuration and use cases for volumes: Ozone's
highest level of namespace organization.
+
+<DocCardList/>
diff --git a/docs/03-core-concepts/03-namespace/01-volumes/_category_.yml
b/docs/03-core-concepts/03-namespace/01-volumes/_category_.yml
deleted file mode 100644
index adc35671..00000000
--- a/docs/03-core-concepts/03-namespace/01-volumes/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Volumes
diff --git
a/docs/03-core-concepts/03-namespace/02-buckets/04-layouts/README.mdx
b/docs/03-core-concepts/03-namespace/02-buckets/04-layouts/README.mdx
new file mode 100644
index 00000000..04ff0e18
--- /dev/null
+++ b/docs/03-core-concepts/03-namespace/02-buckets/04-layouts/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Layouts
+---
+
+# Bucket Layouts
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the different bucket layouts supported by Ozone and
their use cases.
+
+<DocCardList/>
diff --git
a/docs/03-core-concepts/03-namespace/02-buckets/04-layouts/_category_.yml
b/docs/03-core-concepts/03-namespace/02-buckets/04-layouts/_category_.yml
deleted file mode 100644
index a30ed1ef..00000000
--- a/docs/03-core-concepts/03-namespace/02-buckets/04-layouts/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Layouts
diff --git a/docs/03-core-concepts/03-namespace/02-buckets/README.mdx
b/docs/03-core-concepts/03-namespace/02-buckets/README.mdx
new file mode 100644
index 00000000..4c2df2c8
--- /dev/null
+++ b/docs/03-core-concepts/03-namespace/02-buckets/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Buckets
+---
+
+# Buckets
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents configuration and use cases for buckets: the second
level of organization in Ozone's namespace.
+
+<DocCardList/>
diff --git a/docs/03-core-concepts/03-namespace/02-buckets/_category_.yml
b/docs/03-core-concepts/03-namespace/02-buckets/_category_.yml
deleted file mode 100644
index 45ac4cbb..00000000
--- a/docs/03-core-concepts/03-namespace/02-buckets/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Buckets
diff --git a/docs/03-core-concepts/03-namespace/README.mdx
b/docs/03-core-concepts/03-namespace/README.mdx
new file mode 100644
index 00000000..7d7a88c4
--- /dev/null
+++ b/docs/03-core-concepts/03-namespace/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Namespace
+---
+
+# Namespace Layout
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the layout of Ozone's namespace.
+
+<DocCardList/>
diff --git a/docs/03-core-concepts/03-namespace/_category_.yml
b/docs/03-core-concepts/03-namespace/_category_.yml
deleted file mode 100644
index 36308627..00000000
--- a/docs/03-core-concepts/03-namespace/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Namespace
diff --git a/docs/03-core-concepts/04-security/01-authentication/02-knox.md
b/docs/03-core-concepts/04-security/01-authentication/02-knox.md
deleted file mode 100644
index dd8718b3..00000000
--- a/docs/03-core-concepts/04-security/01-authentication/02-knox.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-sidebar_label: Apache Knox
----
-
-# Authenticating with Apache Knox
-
-**TODO:** File a subtask under
[HDDS-9857](https://issues.apache.org/jira/browse/HDDS-9857) and complete this
page or section.
diff --git
a/docs/03-core-concepts/04-security/01-authentication/03-s3-credentials.md
b/docs/03-core-concepts/04-security/01-authentication/03-s3-credentials.md
deleted file mode 100644
index 2cd03d63..00000000
--- a/docs/03-core-concepts/04-security/01-authentication/03-s3-credentials.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-sidebar_label: S3 Credentials
----
-
-# Authenticating with S3 Credentials
-
-**TODO:** File a subtask under
[HDDS-9857](https://issues.apache.org/jira/browse/HDDS-9857) and complete this
page or section.
diff --git a/docs/03-core-concepts/04-security/01-authentication/_category_.yml
b/docs/03-core-concepts/04-security/01-authentication/_category_.yml
deleted file mode 100644
index f40bb4f6..00000000
--- a/docs/03-core-concepts/04-security/01-authentication/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Authentication
diff --git a/docs/03-core-concepts/04-security/01-authentication/01-kerberos.md
b/docs/03-core-concepts/04-security/01-kerberos.md
similarity index 87%
rename from docs/03-core-concepts/04-security/01-authentication/01-kerberos.md
rename to docs/03-core-concepts/04-security/01-kerberos.md
index 7661225a..1c87e740 100644
--- a/docs/03-core-concepts/04-security/01-authentication/01-kerberos.md
+++ b/docs/03-core-concepts/04-security/01-kerberos.md
@@ -2,7 +2,7 @@
sidebar_label: Kerberos
---
-# Authenticating with Kerberos
+# Authentication with Kerberos
**TODO:** File a subtask under
[HDDS-9857](https://issues.apache.org/jira/browse/HDDS-9857) and complete this
page or section.
diff --git
a/docs/03-core-concepts/04-security/02-authorization/01-native-acls.md
b/docs/03-core-concepts/04-security/02-acls/01-native-acls.md
similarity index 100%
rename from docs/03-core-concepts/04-security/02-authorization/01-native-acls.md
rename to docs/03-core-concepts/04-security/02-acls/01-native-acls.md
diff --git
a/docs/03-core-concepts/04-security/02-authorization/02-ranger-acls.md
b/docs/03-core-concepts/04-security/02-acls/02-ranger-acls.md
similarity index 100%
rename from docs/03-core-concepts/04-security/02-authorization/02-ranger-acls.md
rename to docs/03-core-concepts/04-security/02-acls/02-ranger-acls.md
diff --git a/docs/03-core-concepts/04-security/02-acls/README.mdx
b/docs/03-core-concepts/04-security/02-acls/README.mdx
new file mode 100644
index 00000000..8423fefc
--- /dev/null
+++ b/docs/03-core-concepts/04-security/02-acls/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: ACLs
+---
+
+# Authorization With ACLs
+
+import DocCardList from '@theme/DocCardList';
+
+This section covers Ozone's ACL support, which can be used to restrict access
to different portions of the namespace once a user has authenticated with
[Kerberos](../kerberos). To configure access for administrator operations that
do not involve the Ozone namespace, see the [Administrator
Guide](../../../administrator-guide/configuration/security/administrators).
+
+<DocCardList/>
diff --git a/docs/03-core-concepts/04-security/02-authorization/_category_.yml
b/docs/03-core-concepts/04-security/02-authorization/_category_.yml
deleted file mode 100644
index a11c44a8..00000000
--- a/docs/03-core-concepts/04-security/02-authorization/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Authorization
diff --git a/docs/03-core-concepts/04-security/README.mdx
b/docs/03-core-concepts/04-security/README.mdx
new file mode 100644
index 00000000..7b0006bb
--- /dev/null
+++ b/docs/03-core-concepts/04-security/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Security
+---
+
+# Using a Secure Ozone Cluster
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the primary mechanisms Ozone uses for authentication
and authorization of users and administrators. To configure encryption and
other security mechanisms within an Ozone cluster, see the [Administrator
Guide](../../administrator-guide/configuration/security).
+
+<DocCardList/>
diff --git a/docs/03-core-concepts/04-security/_category_.yml
b/docs/03-core-concepts/04-security/_category_.yml
deleted file mode 100644
index 76a1b343..00000000
--- a/docs/03-core-concepts/04-security/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Security
diff --git a/docs/03-core-concepts/05-configuration-files.md
b/docs/03-core-concepts/05-configuration-files.md
deleted file mode 100644
index 37314dbe..00000000
--- a/docs/03-core-concepts/05-configuration-files.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Configuration Files
-
-**TODO:** File a subtask under
[HDDS-9857](https://issues.apache.org/jira/browse/HDDS-9857) and complete this
page or section.
-
-Covers what configuration files exist in the system, their basic format, and
where they are read from. Does not cover specific config keys to use.
-
-- ozone-site.xml
-- core-site.xml
-- application log4j
-- audit log4j
-- client log4j
diff --git a/docs/03-core-concepts/README.mdx b/docs/03-core-concepts/README.mdx
new file mode 100644
index 00000000..b129e86e
--- /dev/null
+++ b/docs/03-core-concepts/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Core Concepts
+---
+
+# Core Concepts
+
+import DocCardList from '@theme/DocCardList';
+
+This section covers Ozone concepts that are helpful for both users and
administrators to understand. Topics in this section will be referenced
throughout the documentation.
+
+<DocCardList/>
diff --git a/docs/03-core-concepts/_category_.yml
b/docs/03-core-concepts/_category_.yml
deleted file mode 100644
index 7807cb0c..00000000
--- a/docs/03-core-concepts/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Core Concepts
diff --git a/docs/04-user-guide/01-client-interfaces/04-s3a.md
b/docs/04-user-guide/01-client-interfaces/04-s3a.md
index 9ca8b8d6..ccf6ae85 100644
--- a/docs/04-user-guide/01-client-interfaces/04-s3a.md
+++ b/docs/04-user-guide/01-client-interfaces/04-s3a.md
@@ -2,6 +2,6 @@
sidebar_label: s3a
---
-# Accessing Ozone with s3a
+# s3a and Ozone
**TODO:** File a subtask under
[HDDS-9858](https://issues.apache.org/jira/browse/HDDS-9858) and complete this
page or section.
diff --git a/docs/04-user-guide/01-client-interfaces/README.mdx
b/docs/04-user-guide/01-client-interfaces/README.mdx
new file mode 100644
index 00000000..c7697e5e
--- /dev/null
+++ b/docs/04-user-guide/01-client-interfaces/README.mdx
@@ -0,0 +1,7 @@
+# Client Interfaces
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the interfaces that clients can use to communicate with
Ozone.
+
+<DocCardList/>
diff --git a/docs/04-user-guide/01-client-interfaces/_category_.yml
b/docs/04-user-guide/01-client-interfaces/_category_.yml
deleted file mode 100644
index 3cfa4069..00000000
--- a/docs/04-user-guide/01-client-interfaces/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Client Interfaces
diff --git a/docs/04-user-guide/02-clients/01-ozone.md
b/docs/04-user-guide/02-clients/01-ozone.md
new file mode 100644
index 00000000..8ad169b9
--- /dev/null
+++ b/docs/04-user-guide/02-clients/01-ozone.md
@@ -0,0 +1,13 @@
+---
+sidebar_label: Ozone
+---
+
+# The Ozone Client
+
+Document how to install, configure and run Ozone's client. This should also
include
+
+- Which interfaces it supports (ofs, o3, Java).
+- Information about configuration files it reads (core-site.xml, client log4j).
+- Environment variables and common JVM flags (`-D`) that can be used at the
CLI.
+
+**TODO:** File a subtask under
[HDDS-9858](https://issues.apache.org/jira/browse/HDDS-9858) and complete this
page or section.
diff --git a/docs/04-user-guide/02-clients/02-hdfs.md
b/docs/04-user-guide/02-clients/02-hdfs.md
new file mode 100644
index 00000000..03100864
--- /dev/null
+++ b/docs/04-user-guide/02-clients/02-hdfs.md
@@ -0,0 +1,9 @@
+---
+sidebar_label: HDFS
+---
+
+# Using an HDFS Client With Ozone
+
+Link to HDFS documentation to install and configure an HDFS client. Document
how to configure it to work against Ozone. This should also include which
interfaces it supports (ofs, s3a).
+
+**TODO:** File a subtask under
[HDDS-9858](https://issues.apache.org/jira/browse/HDDS-9858) and complete this
page or section.
diff --git a/docs/04-user-guide/02-clients/03-s3.md
b/docs/04-user-guide/02-clients/03-s3.md
new file mode 100644
index 00000000..25c4328d
--- /dev/null
+++ b/docs/04-user-guide/02-clients/03-s3.md
@@ -0,0 +1,13 @@
+---
+sidebar_label: S3
+---
+
+# Using an S3 Client With Ozone
+
+Document how to set it up an S3 client to run against Ozone (access key and
secret key).
+
+- Any S3 compatible client should work against Ozone's S3 interface.
+- The Ozone Java client is not required to be present, but can be used to
generate secrets.
+- A kerberos principal is required to initially generate a secret.
+
+**TODO:** File a subtask under
[HDDS-9858](https://issues.apache.org/jira/browse/HDDS-9858) and complete this
page or section.
diff --git a/docs/04-user-guide/02-clients/README.mdx
b/docs/04-user-guide/02-clients/README.mdx
new file mode 100644
index 00000000..4d8a31e3
--- /dev/null
+++ b/docs/04-user-guide/02-clients/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Clients
+---
+
+# Ozone Clients
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions to install, configure, and run various
clients to read and write data to Ozone.
+
+<DocCardList/>
diff --git a/docs/04-user-guide/02-integrations/_category_.yml
b/docs/04-user-guide/02-integrations/_category_.yml
deleted file mode 100644
index 08b3b4a1..00000000
--- a/docs/04-user-guide/02-integrations/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Integrations
diff --git a/docs/04-user-guide/02-integrations/01-hive.md
b/docs/04-user-guide/03-integrations/01-hive.md
similarity index 100%
rename from docs/04-user-guide/02-integrations/01-hive.md
rename to docs/04-user-guide/03-integrations/01-hive.md
diff --git a/docs/04-user-guide/02-integrations/02-hue.md
b/docs/04-user-guide/03-integrations/02-hue.md
similarity index 100%
rename from docs/04-user-guide/02-integrations/02-hue.md
rename to docs/04-user-guide/03-integrations/02-hue.md
diff --git a/docs/04-user-guide/02-integrations/03-iceberg.md
b/docs/04-user-guide/03-integrations/03-iceberg.md
similarity index 100%
rename from docs/04-user-guide/02-integrations/03-iceberg.md
rename to docs/04-user-guide/03-integrations/03-iceberg.md
diff --git a/docs/04-user-guide/02-integrations/04-impala.md
b/docs/04-user-guide/03-integrations/04-impala.md
similarity index 100%
rename from docs/04-user-guide/02-integrations/04-impala.md
rename to docs/04-user-guide/03-integrations/04-impala.md
diff --git a/docs/04-user-guide/02-integrations/05-oozie.md
b/docs/04-user-guide/03-integrations/05-oozie.md
similarity index 100%
rename from docs/04-user-guide/02-integrations/05-oozie.md
rename to docs/04-user-guide/03-integrations/05-oozie.md
diff --git a/docs/04-user-guide/02-integrations/06-spark.md
b/docs/04-user-guide/03-integrations/06-spark.md
similarity index 100%
rename from docs/04-user-guide/02-integrations/06-spark.md
rename to docs/04-user-guide/03-integrations/06-spark.md
diff --git a/docs/04-user-guide/02-integrations/07-trino.md
b/docs/04-user-guide/03-integrations/07-trino.md
similarity index 100%
rename from docs/04-user-guide/02-integrations/07-trino.md
rename to docs/04-user-guide/03-integrations/07-trino.md
diff --git a/docs/04-user-guide/03-integrations/README.mdx
b/docs/04-user-guide/03-integrations/README.mdx
new file mode 100644
index 00000000..01c133a5
--- /dev/null
+++ b/docs/04-user-guide/03-integrations/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Integrations
+---
+
+# Integrating Ozone Storage With Other Systems
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions to configure other systems to use Ozone for
storage.
+
+<DocCardList/>
diff --git a/docs/04-user-guide/README.mdx b/docs/04-user-guide/README.mdx
new file mode 100644
index 00000000..0033a113
--- /dev/null
+++ b/docs/04-user-guide/README.mdx
@@ -0,0 +1,7 @@
+# User Guide
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions for end users to read and write data to an
existing Ozone system.
+
+<DocCardList/>
diff --git a/docs/04-user-guide/_category_.yml
b/docs/04-user-guide/_category_.yml
deleted file mode 100644
index 14dc26c6..00000000
--- a/docs/04-user-guide/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: User Guide
diff --git a/docs/05-administrator-guide/01-installation/README.mdx
b/docs/05-administrator-guide/01-installation/README.mdx
new file mode 100644
index 00000000..14e1b390
--- /dev/null
+++ b/docs/05-administrator-guide/01-installation/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Installation
+---
+
+# Installing Ozone In Production
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents how to install a production Ozone system.
+
+<DocCardList/>
diff --git a/docs/05-administrator-guide/01-installation/_category_.yml
b/docs/05-administrator-guide/01-installation/_category_.yml
deleted file mode 100644
index f8e427f3..00000000
--- a/docs/05-administrator-guide/01-installation/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Installation
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/01-configuration-files.md
b/docs/05-administrator-guide/02-configuration/01-basic/01-configuration-files.md
new file mode 100644
index 00000000..efe1346d
--- /dev/null
+++
b/docs/05-administrator-guide/02-configuration/01-basic/01-configuration-files.md
@@ -0,0 +1,5 @@
+# Configuration Files
+
+**TODO:** File a subtask under
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this
page or section.
+
+Document `ozone-site.xml` and `core-site.xml` configuration files for the
Ozone server, their basic format, and where they are read from. Specific config
keys will be documented in later sections.
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/01-network/_category_.yml
b/docs/05-administrator-guide/02-configuration/01-basic/01-network/_category_.yml
deleted file mode 100644
index 47237dd2..00000000
---
a/docs/05-administrator-guide/02-configuration/01-basic/01-network/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Network
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/02-directories/_category_.yml
b/docs/05-administrator-guide/02-configuration/01-basic/02-directories/_category_.yml
deleted file mode 100644
index d95ed7ec..00000000
---
a/docs/05-administrator-guide/02-configuration/01-basic/02-directories/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Directories
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/01-network/01-ozone-manager.md
b/docs/05-administrator-guide/02-configuration/01-basic/02-network/01-ozone-manager.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/01-basic/01-network/01-ozone-manager.md
rename to
docs/05-administrator-guide/02-configuration/01-basic/02-network/01-ozone-manager.md
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/01-network/02-storage-container-manager.md
b/docs/05-administrator-guide/02-configuration/01-basic/02-network/02-storage-container-manager.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/01-basic/01-network/02-storage-container-manager.md
rename to
docs/05-administrator-guide/02-configuration/01-basic/02-network/02-storage-container-manager.md
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/01-network/03-datanode.md
b/docs/05-administrator-guide/02-configuration/01-basic/02-network/03-datanode.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/01-basic/01-network/03-datanode.md
rename to
docs/05-administrator-guide/02-configuration/01-basic/02-network/03-datanode.md
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/01-network/04-recon.md
b/docs/05-administrator-guide/02-configuration/01-basic/02-network/04-recon.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/01-basic/01-network/04-recon.md
rename to
docs/05-administrator-guide/02-configuration/01-basic/02-network/04-recon.md
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/01-network/05-s3-gateway.md
b/docs/05-administrator-guide/02-configuration/01-basic/02-network/05-s3-gateway.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/01-basic/01-network/05-s3-gateway.md
rename to
docs/05-administrator-guide/02-configuration/01-basic/02-network/05-s3-gateway.md
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/01-network/07-default-ports.md
b/docs/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/01-basic/01-network/07-default-ports.md
rename to
docs/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/02-network/README.mdx
b/docs/05-administrator-guide/02-configuration/01-basic/02-network/README.mdx
new file mode 100644
index 00000000..4ec0e1b6
--- /dev/null
+++
b/docs/05-administrator-guide/02-configuration/01-basic/02-network/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Network
+---
+
+# Network Related Configurations
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents configurations for network communication between Ozone
components.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/02-directories/01-ozone-manager.md
b/docs/05-administrator-guide/02-configuration/01-basic/03-directories/01-ozone-manager.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/01-basic/02-directories/01-ozone-manager.md
rename to
docs/05-administrator-guide/02-configuration/01-basic/03-directories/01-ozone-manager.md
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/02-directories/02-storage-container-manager.md
b/docs/05-administrator-guide/02-configuration/01-basic/03-directories/02-storage-container-manager.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/01-basic/02-directories/02-storage-container-manager.md
rename to
docs/05-administrator-guide/02-configuration/01-basic/03-directories/02-storage-container-manager.md
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/02-directories/03-datanode.md
b/docs/05-administrator-guide/02-configuration/01-basic/03-directories/03-datanode.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/01-basic/02-directories/03-datanode.md
rename to
docs/05-administrator-guide/02-configuration/01-basic/03-directories/03-datanode.md
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/02-directories/04-recon.md
b/docs/05-administrator-guide/02-configuration/01-basic/03-directories/04-recon.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/01-basic/02-directories/04-recon.md
rename to
docs/05-administrator-guide/02-configuration/01-basic/03-directories/04-recon.md
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/03-directories/README.mdx
b/docs/05-administrator-guide/02-configuration/01-basic/03-directories/README.mdx
new file mode 100644
index 00000000..64924451
--- /dev/null
+++
b/docs/05-administrator-guide/02-configuration/01-basic/03-directories/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Directories
+---
+
+# Directory Related Configurations
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents configurations for directories that Ozone components
will store their data in.
+
+<DocCardList/>
diff --git a/docs/05-administrator-guide/02-configuration/01-basic/README.mdx
b/docs/05-administrator-guide/02-configuration/01-basic/README.mdx
new file mode 100644
index 00000000..aaa55ae2
--- /dev/null
+++ b/docs/05-administrator-guide/02-configuration/01-basic/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Basic
+---
+
+# Basic Ozone Configuration
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the minimal set of configurations required for Ozone to
run.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/_category_.yml
b/docs/05-administrator-guide/02-configuration/01-basic/_category_.yml
deleted file mode 100644
index d22ee36e..00000000
--- a/docs/05-administrator-guide/02-configuration/01-basic/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Basic
diff --git
a/docs/05-administrator-guide/02-configuration/02-logging/01-application-logs.md
b/docs/05-administrator-guide/02-configuration/02-logging/01-application-logs.md
new file mode 100644
index 00000000..8e12f64a
--- /dev/null
+++
b/docs/05-administrator-guide/02-configuration/02-logging/01-application-logs.md
@@ -0,0 +1,15 @@
+---
+sidebar_label: Application Logs
+---
+
+# Configuring Application Logs
+
+Document Ozone's use of log4j for application logging, including:
+
+- Default configuration
+- Examples of common configurations
+- Where Ozone looks for log4j configuration files.
+
+Link to existing Log4j docs as necessary.
+
+**TODO:** File a subtask under
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this
page or section.
diff --git
a/docs/05-administrator-guide/02-configuration/02-logging/01-placeholder.md
b/docs/05-administrator-guide/02-configuration/02-logging/01-placeholder.md
deleted file mode 100644
index dff86927..00000000
--- a/docs/05-administrator-guide/02-configuration/02-logging/01-placeholder.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# PLACEHOLDER
-
-**TODO:** File a subtask under
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this
page or section.
-
-There will be multiple pages on performance under this section. Not sure what
is required yet.
diff --git
a/docs/05-administrator-guide/02-configuration/02-logging/02-audit-logs.md
b/docs/05-administrator-guide/02-configuration/02-logging/02-audit-logs.md
new file mode 100644
index 00000000..8f08839a
--- /dev/null
+++ b/docs/05-administrator-guide/02-configuration/02-logging/02-audit-logs.md
@@ -0,0 +1,15 @@
+---
+sidebar_label: Audit Logs
+---
+
+# Configuring Audit Logs
+
+Document Ozone's use of log4j for audit logging, including:
+
+- Default configuration
+- Examples of common configurations
+- Where Ozone looks for log4j configuration files.
+
+Link to existing Log4j docs as necessary.
+
+**TODO:** File a subtask under
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this
page or section.
diff --git a/docs/05-administrator-guide/02-configuration/02-logging/README.mdx
b/docs/05-administrator-guide/02-configuration/02-logging/README.mdx
new file mode 100644
index 00000000..47230e5b
--- /dev/null
+++ b/docs/05-administrator-guide/02-configuration/02-logging/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Logging
+---
+
+# Logging Configuration
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents configurations for various server side logs in Ozone.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/02-configuration/02-logging/_category_.yml
b/docs/05-administrator-guide/02-configuration/02-logging/_category_.yml
deleted file mode 100644
index a376e73e..00000000
--- a/docs/05-administrator-guide/02-configuration/02-logging/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Logging
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/01-kerberos.md
b/docs/05-administrator-guide/02-configuration/03-security/02-kerberos.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/03-security/01-kerberos.md
rename to
docs/05-administrator-guide/02-configuration/03-security/02-kerberos.md
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/04-encryption/01-network-encryption/_category_.yml
b/docs/05-administrator-guide/02-configuration/03-security/04-encryption/01-network-encryption/_category_.yml
deleted file mode 100644
index 6395d9ff..00000000
---
a/docs/05-administrator-guide/02-configuration/03-security/04-encryption/01-network-encryption/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Network Encryption
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/04-encryption/_category_.yml
b/docs/05-administrator-guide/02-configuration/03-security/04-encryption/_category_.yml
deleted file mode 100644
index e2fca438..00000000
---
a/docs/05-administrator-guide/02-configuration/03-security/04-encryption/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Encryption
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/02-knox.md
b/docs/05-administrator-guide/02-configuration/03-security/04-knox.md
similarity index 100%
copy from docs/05-administrator-guide/02-configuration/03-security/02-knox.md
copy to docs/05-administrator-guide/02-configuration/03-security/04-knox.md
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/04-encryption/01-network-encryption/01-hadoop-rpc.md
b/docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/01-hadoop-rpc.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/03-security/04-encryption/01-network-encryption/01-hadoop-rpc.md
rename to
docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/01-hadoop-rpc.md
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/04-encryption/01-network-encryption/02-grpc.md
b/docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/03-security/04-encryption/01-network-encryption/02-grpc.md
rename to
docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/04-encryption/01-network-encryption/03-https.md
b/docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/03-https.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/03-security/04-encryption/01-network-encryption/03-https.md
rename to
docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/03-https.md
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/README.mdx
b/docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/README.mdx
new file mode 100644
index 00000000..ce886514
--- /dev/null
+++
b/docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Network Encryption
+---
+
+# Network Encryption Configuration
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents encryption configurations for each type of network
communication in Ozone.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/04-encryption/02-transparent-data-encryption.md
b/docs/05-administrator-guide/02-configuration/03-security/05-encryption/02-transparent-data-encryption.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/03-security/04-encryption/02-transparent-data-encryption.md
rename to
docs/05-administrator-guide/02-configuration/03-security/05-encryption/02-transparent-data-encryption.md
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/05-encryption/README.mdx
b/docs/05-administrator-guide/02-configuration/03-security/05-encryption/README.mdx
new file mode 100644
index 00000000..9ca98d11
--- /dev/null
+++
b/docs/05-administrator-guide/02-configuration/03-security/05-encryption/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Encryption
+---
+
+# Encryption Configuration
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the different types of encryption supported by Ozone
and how to configure them.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/README.mdx
b/docs/05-administrator-guide/02-configuration/03-security/README.mdx
new file mode 100644
index 00000000..b91f8f69
--- /dev/null
+++ b/docs/05-administrator-guide/02-configuration/03-security/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Security
+---
+
+# Security Configuration
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents how to configure a secure Ozone cluster in a production
environment.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/_category_.yml
b/docs/05-administrator-guide/02-configuration/03-security/_category_.yml
deleted file mode 100644
index 76a1b343..00000000
--- a/docs/05-administrator-guide/02-configuration/03-security/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Security
diff --git
a/docs/05-administrator-guide/02-configuration/04-performance/01-topology.md
b/docs/05-administrator-guide/02-configuration/04-performance/02-topology.md
similarity index 100%
rename from
docs/05-administrator-guide/02-configuration/04-performance/01-topology.md
rename to
docs/05-administrator-guide/02-configuration/04-performance/02-topology.md
diff --git
a/docs/05-administrator-guide/02-configuration/04-performance/README.mdx
b/docs/05-administrator-guide/02-configuration/04-performance/README.mdx
new file mode 100644
index 00000000..544de04a
--- /dev/null
+++ b/docs/05-administrator-guide/02-configuration/04-performance/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Performance
+---
+
+# Performance Related Configurations
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents how to configure Ozone to optimize performance.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/02-configuration/04-performance/_category_.yml
b/docs/05-administrator-guide/02-configuration/04-performance/_category_.yml
deleted file mode 100644
index 49a3a542..00000000
--- a/docs/05-administrator-guide/02-configuration/04-performance/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Performance
diff --git a/docs/05-administrator-guide/02-configuration/05-appendix.md
b/docs/05-administrator-guide/02-configuration/05-appendix.md
new file mode 100644
index 00000000..3d63dad8
--- /dev/null
+++ b/docs/05-administrator-guide/02-configuration/05-appendix.md
@@ -0,0 +1,7 @@
+---
+sidebar_label: Appendix
+---
+
+# Configuration Key Appendix
+
+**TODO** [HDDS-10683](https://issues.apache.org/jira/browse/HDDS-10683) Fill
in this page with a table of all configuration keys.
diff --git a/docs/05-administrator-guide/02-configuration/README.mdx
b/docs/05-administrator-guide/02-configuration/README.mdx
new file mode 100644
index 00000000..aa1d3032
--- /dev/null
+++ b/docs/05-administrator-guide/02-configuration/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Configuration
+---
+
+# Configuring Ozone For Production
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents how to configure Ozone in a production environment.
+
+<DocCardList/>
diff --git a/docs/05-administrator-guide/02-configuration/_category_.yml
b/docs/05-administrator-guide/02-configuration/_category_.yml
deleted file mode 100644
index b219a3af..00000000
--- a/docs/05-administrator-guide/02-configuration/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Configuration
diff --git
a/docs/05-administrator-guide/03-operations/03-node-decommissioning-and-maintenance/README.mdx
b/docs/05-administrator-guide/03-operations/03-node-decommissioning-and-maintenance/README.mdx
new file mode 100644
index 00000000..95fb60ed
--- /dev/null
+++
b/docs/05-administrator-guide/03-operations/03-node-decommissioning-and-maintenance/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Decommissioning and Maintenance
+---
+
+# Node Decommissioning and Maintenance
+
+import DocCardList from '@theme/DocCardList';
+
+This section contains instructions to remove Ozone nodes from the cluster in a
controlled manner.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/03-operations/03-node-decommissioning-and-maintenance/_category_.yml
b/docs/05-administrator-guide/03-operations/03-node-decommissioning-and-maintenance/_category_.yml
deleted file mode 100644
index 6b8e2a63..00000000
---
a/docs/05-administrator-guide/03-operations/03-node-decommissioning-and-maintenance/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Node Decommissioning and Maintenance
diff --git
a/docs/05-administrator-guide/03-operations/04-disk-replacement/README.mdx
b/docs/05-administrator-guide/03-operations/04-disk-replacement/README.mdx
new file mode 100644
index 00000000..95b64199
--- /dev/null
+++ b/docs/05-administrator-guide/03-operations/04-disk-replacement/README.mdx
@@ -0,0 +1,7 @@
+# Disk Replacement
+
+import DocCardList from '@theme/DocCardList';
+
+This section contains instructions to replace disks on Ozone nodes.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/03-operations/04-disk-replacement/_category_.yml
b/docs/05-administrator-guide/03-operations/04-disk-replacement/_category_.yml
deleted file mode 100644
index 292171e0..00000000
---
a/docs/05-administrator-guide/03-operations/04-disk-replacement/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Disk Replacement
diff --git
a/docs/05-administrator-guide/03-operations/05-balancing-datanodes.md
b/docs/05-administrator-guide/03-operations/05-balancing-datanodes.md
deleted file mode 100644
index d4b98e02..00000000
--- a/docs/05-administrator-guide/03-operations/05-balancing-datanodes.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Balancing Datanodes
-
-**TODO:** File a subtask under
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this
page or section.
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/02-knox.md
b/docs/05-administrator-guide/03-operations/05-data-balancing.md
similarity index 68%
rename from docs/05-administrator-guide/02-configuration/03-security/02-knox.md
rename to docs/05-administrator-guide/03-operations/05-data-balancing.md
index 7ccb2f12..18e3aeba 100644
--- a/docs/05-administrator-guide/02-configuration/03-security/02-knox.md
+++ b/docs/05-administrator-guide/03-operations/05-data-balancing.md
@@ -1,7 +1,7 @@
---
-sidebar_label: Apache Knox
+sidebar_label: Data Balancing
---
-# Configuring Apache Knox
+# Balancing Data Among Datanodes
**TODO:** File a subtask under
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this
page or section.
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/02-recon-rest-api.md
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/02-recon-rest-api.md
index aec34944..bdb31956 100644
---
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/02-recon-rest-api.md
+++
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/02-recon-rest-api.md
@@ -1,3 +1,3 @@
# Recon REST API
-**TODO:** File a subtask under
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this
page or section.
+**TODO:** [HDDS-10684](https://issues.apache.org/jira/browse/HDDS-10684) Embed
a Swagger API spec into this page.
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/README.mdx
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/README.mdx
new file mode 100644
index 00000000..73bcc470
--- /dev/null
+++
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/README.mdx
@@ -0,0 +1,7 @@
+# Recon
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents Recon. Recon is Ozone's observability server that
provides a web UI and REST APIs to gain insight about a running Ozone system.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/_category_.yml
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/_category_.yml
deleted file mode 100644
index 3b40c251..00000000
---
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Recon
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/README.mdx
b/docs/05-administrator-guide/03-operations/09-observability/README.mdx
new file mode 100644
index 00000000..7b74befb
--- /dev/null
+++ b/docs/05-administrator-guide/03-operations/09-observability/README.mdx
@@ -0,0 +1,7 @@
+# Observability
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents tools that can be used to monitor or inspect the state
of a running Ozone cluster.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/_category_.yml
b/docs/05-administrator-guide/03-operations/09-observability/_category_.yml
deleted file mode 100644
index cebf0fd8..00000000
--- a/docs/05-administrator-guide/03-operations/09-observability/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Observability
diff --git a/docs/05-administrator-guide/03-operations/README.mdx
b/docs/05-administrator-guide/03-operations/README.mdx
new file mode 100644
index 00000000..8aa7c6d4
--- /dev/null
+++ b/docs/05-administrator-guide/03-operations/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Operations
+---
+
+# Administrator Operations
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents operations required by administrators to maintain an
Ozone system in a production environment.
+
+<DocCardList/>
diff --git a/docs/05-administrator-guide/03-operations/_category_.yml
b/docs/05-administrator-guide/03-operations/_category_.yml
deleted file mode 100644
index 5f4faaac..00000000
--- a/docs/05-administrator-guide/03-operations/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Operations
diff --git a/docs/05-administrator-guide/README.mdx
b/docs/05-administrator-guide/README.mdx
new file mode 100644
index 00000000..8ca5d523
--- /dev/null
+++ b/docs/05-administrator-guide/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Administrator Guide
+---
+
+# Administrator Guide
+
+import DocCardList from '@theme/DocCardList';
+
+This section contains instructions for administrators to install and maintain
a production Ozone system.
+
+<DocCardList/>
diff --git a/docs/05-administrator-guide/_category_.yml
b/docs/05-administrator-guide/_category_.yml
deleted file mode 100644
index 71635757..00000000
--- a/docs/05-administrator-guide/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Administrator Guide
diff --git a/docs/06-troubleshooting/07-integrations/README.mdx
b/docs/06-troubleshooting/07-integrations/README.mdx
new file mode 100644
index 00000000..3264ecf3
--- /dev/null
+++ b/docs/06-troubleshooting/07-integrations/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Integrations
+---
+
+# Troubleshooting Ozone Integration With Other Components
+
+import DocCardList from '@theme/DocCardList';
+
+This section contains guides to help troubleshoot Ozone integration with other
systems.
+
+<DocCardList/>
diff --git a/docs/06-troubleshooting/07-integrations/_category_.yml
b/docs/06-troubleshooting/07-integrations/_category_.yml
deleted file mode 100644
index 08b3b4a1..00000000
--- a/docs/06-troubleshooting/07-integrations/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Integrations
diff --git a/docs/06-troubleshooting/08-security/README.mdx
b/docs/06-troubleshooting/08-security/README.mdx
new file mode 100644
index 00000000..240b455d
--- /dev/null
+++ b/docs/06-troubleshooting/08-security/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Security
+---
+
+# Troubleshooting Security
+
+import DocCardList from '@theme/DocCardList';
+
+This section contains guides to help troubleshoot security related issues in
an Ozone deployment.
+
+<DocCardList/>
diff --git a/docs/06-troubleshooting/08-security/_category_.yml
b/docs/06-troubleshooting/08-security/_category_.yml
deleted file mode 100644
index 76a1b343..00000000
--- a/docs/06-troubleshooting/08-security/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Security
diff --git a/docs/06-troubleshooting/README.mdx
b/docs/06-troubleshooting/README.mdx
new file mode 100644
index 00000000..88bbd415
--- /dev/null
+++ b/docs/06-troubleshooting/README.mdx
@@ -0,0 +1,7 @@
+# Troubleshooting
+
+import DocCardList from '@theme/DocCardList';
+
+This section contains guides to help troubleshoot common issues in an Ozone
deployment.
+
+<DocCardList/>
diff --git a/docs/06-troubleshooting/_category_.yml
b/docs/06-troubleshooting/_category_.yml
deleted file mode 100644
index ff677b93..00000000
--- a/docs/06-troubleshooting/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Troubleshooting
diff --git a/docs/07-system-internals/01-components/01-ozone-manager/README.mdx
b/docs/07-system-internals/01-components/01-ozone-manager/README.mdx
new file mode 100644
index 00000000..ebef0422
--- /dev/null
+++ b/docs/07-system-internals/01-components/01-ozone-manager/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Ozone Manager
+---
+
+# Ozone Manager Internals
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the internal workings of the Ozone Manager.
+
+<DocCardList/>
diff --git
a/docs/07-system-internals/01-components/01-ozone-manager/_category_.yml
b/docs/07-system-internals/01-components/01-ozone-manager/_category_.yml
deleted file mode 100644
index cfe73022..00000000
--- a/docs/07-system-internals/01-components/01-ozone-manager/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Ozone Manager
diff --git
a/docs/07-system-internals/01-components/02-storage-container-manager/README.mdx
b/docs/07-system-internals/01-components/02-storage-container-manager/README.mdx
new file mode 100644
index 00000000..0f474274
--- /dev/null
+++
b/docs/07-system-internals/01-components/02-storage-container-manager/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Storage Container Manager
+---
+
+# Storage Container Manager Internals
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the internal workings of the Storage Container Manager.
+
+<DocCardList/>
diff --git
a/docs/07-system-internals/01-components/02-storage-container-manager/_category_.yml
b/docs/07-system-internals/01-components/02-storage-container-manager/_category_.yml
deleted file mode 100644
index 394a949e..00000000
---
a/docs/07-system-internals/01-components/02-storage-container-manager/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Storage Container Manager
diff --git a/docs/07-system-internals/01-components/03-datanode/README.mdx
b/docs/07-system-internals/01-components/03-datanode/README.mdx
new file mode 100644
index 00000000..55277090
--- /dev/null
+++ b/docs/07-system-internals/01-components/03-datanode/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Datanode
+---
+
+# Datanode Internals
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the internal workings of the Datanode.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/01-components/03-datanode/_category_.yml
b/docs/07-system-internals/01-components/03-datanode/_category_.yml
deleted file mode 100644
index 1d962cd3..00000000
--- a/docs/07-system-internals/01-components/03-datanode/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Datanode
diff --git a/docs/07-system-internals/01-components/04-recon/README.mdx
b/docs/07-system-internals/01-components/04-recon/README.mdx
new file mode 100644
index 00000000..7630e5a8
--- /dev/null
+++ b/docs/07-system-internals/01-components/04-recon/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Recon
+---
+
+# Recon Internals
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the internal workings of Recon.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/01-components/04-recon/_category_.yml
b/docs/07-system-internals/01-components/04-recon/_category_.yml
deleted file mode 100644
index 3b40c251..00000000
--- a/docs/07-system-internals/01-components/04-recon/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Recon
diff --git a/docs/07-system-internals/01-components/05-s3-gateway/README.mdx
b/docs/07-system-internals/01-components/05-s3-gateway/README.mdx
new file mode 100644
index 00000000..21476b54
--- /dev/null
+++ b/docs/07-system-internals/01-components/05-s3-gateway/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: S3 Gateway
+---
+
+# S3 Gateway Internals
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the internal workings of the S3 Gateway.
+
+<DocCardList/>
diff --git
a/docs/07-system-internals/01-components/05-s3-gateway/_category_.yml
b/docs/07-system-internals/01-components/05-s3-gateway/_category_.yml
deleted file mode 100644
index d65d10bc..00000000
--- a/docs/07-system-internals/01-components/05-s3-gateway/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: S3 Gateway
diff --git a/docs/07-system-internals/01-components/06-client/README.mdx
b/docs/07-system-internals/01-components/06-client/README.mdx
new file mode 100644
index 00000000..73ada338
--- /dev/null
+++ b/docs/07-system-internals/01-components/06-client/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Client
+---
+
+# Ozone Client Internals
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the internal workings of the Ozone Java client.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/01-components/06-client/_category_.yml
b/docs/07-system-internals/01-components/06-client/_category_.yml
deleted file mode 100644
index 8999223b..00000000
--- a/docs/07-system-internals/01-components/06-client/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Client
diff --git a/docs/07-system-internals/01-components/README.mdx
b/docs/07-system-internals/01-components/README.mdx
new file mode 100644
index 00000000..c3783513
--- /dev/null
+++ b/docs/07-system-internals/01-components/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Components
+---
+
+# Ozone Components
+
+import DocCardList from '@theme/DocCardList';
+
+The internal workings of each Ozone component are documented in this section.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/01-components/_category_.yml
b/docs/07-system-internals/01-components/_category_.yml
deleted file mode 100644
index 93fd4ef9..00000000
--- a/docs/07-system-internals/01-components/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Components
diff --git a/docs/07-system-internals/02-data-operations/README.mdx
b/docs/07-system-internals/02-data-operations/README.mdx
new file mode 100644
index 00000000..c4243e6b
--- /dev/null
+++ b/docs/07-system-internals/02-data-operations/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Data Operations
+---
+
+# Implementation of Data Operations
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents how read, write, and delete operations are implemented
within Ozone.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/02-data-operations/_category_.yml
b/docs/07-system-internals/02-data-operations/_category_.yml
deleted file mode 100644
index bdf7b506..00000000
--- a/docs/07-system-internals/02-data-operations/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Data Operations
diff --git a/docs/07-system-internals/03-data-integrity/README.mdx
b/docs/07-system-internals/03-data-integrity/README.mdx
new file mode 100644
index 00000000..f9176cc7
--- /dev/null
+++ b/docs/07-system-internals/03-data-integrity/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Data Integrity
+---
+
+# Implementation of Data Integrity Checks
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the implementation of Ozone's data integrity checks.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/03-data-integrity/_category_.yml
b/docs/07-system-internals/03-data-integrity/_category_.yml
deleted file mode 100644
index cb84fad5..00000000
--- a/docs/07-system-internals/03-data-integrity/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Data Integrity
diff --git a/docs/07-system-internals/04-replication/01-metadata-replication.md
b/docs/07-system-internals/04-replication/01-metadata.md
similarity index 78%
rename from docs/07-system-internals/04-replication/01-metadata-replication.md
rename to docs/07-system-internals/04-replication/01-metadata.md
index 66105176..907ec8d2 100644
--- a/docs/07-system-internals/04-replication/01-metadata-replication.md
+++ b/docs/07-system-internals/04-replication/01-metadata.md
@@ -1,4 +1,8 @@
-# Metadata Replication
+---
+sidebar_label: Metadata
+---
+
+# Implementation of Metadata Replication
**TODO:** File a subtask under
[HDDS-9862](https://issues.apache.org/jira/browse/HDDS-9862) and complete this
page or section.
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/_category_.yml
b/docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/_category_.yml
deleted file mode 100644
index abaaba69..00000000
---
a/docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Write Pipelines
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/_category_.yml
b/docs/07-system-internals/04-replication/02-data-replication/02-containers/_category_.yml
deleted file mode 100644
index 8909b2ef..00000000
---
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Containers
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/_category_.yml
b/docs/07-system-internals/04-replication/02-data-replication/_category_.yml
deleted file mode 100644
index dd6353b4..00000000
--- a/docs/07-system-internals/04-replication/02-data-replication/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Data Replication
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/01-overview.md
b/docs/07-system-internals/04-replication/02-data/01-write-pipelines/01-overview.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/01-overview.md
rename to
docs/07-system-internals/04-replication/02-data/01-write-pipelines/01-overview.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/02-types.md
b/docs/07-system-internals/04-replication/02-data/01-write-pipelines/02-types.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/02-types.md
rename to
docs/07-system-internals/04-replication/02-data/01-write-pipelines/02-types.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/03-states.md
b/docs/07-system-internals/04-replication/02-data/01-write-pipelines/03-states.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/03-states.md
rename to
docs/07-system-internals/04-replication/02-data/01-write-pipelines/03-states.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/04-reports.md
b/docs/07-system-internals/04-replication/02-data/01-write-pipelines/04-reports.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/04-reports.md
rename to
docs/07-system-internals/04-replication/02-data/01-write-pipelines/04-reports.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/05-creation.md
b/docs/07-system-internals/04-replication/02-data/01-write-pipelines/05-creation.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/05-creation.md
rename to
docs/07-system-internals/04-replication/02-data/01-write-pipelines/05-creation.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/06-persistence.md
b/docs/07-system-internals/04-replication/02-data/01-write-pipelines/06-persistence.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/06-persistence.md
rename to
docs/07-system-internals/04-replication/02-data/01-write-pipelines/06-persistence.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/07-destruction.md
b/docs/07-system-internals/04-replication/02-data/01-write-pipelines/07-destruction.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/01-write-pipelines/07-destruction.md
rename to
docs/07-system-internals/04-replication/02-data/01-write-pipelines/07-destruction.md
diff --git
a/docs/07-system-internals/04-replication/02-data/01-write-pipelines/README.mdx
b/docs/07-system-internals/04-replication/02-data/01-write-pipelines/README.mdx
new file mode 100644
index 00000000..bf825d8c
--- /dev/null
+++
b/docs/07-system-internals/04-replication/02-data/01-write-pipelines/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Write Pipelines
+---
+
+# Write Pipeline Implementation
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the implementation of pipelines: groups of datanodes
that Ozone uses to write data.
+
+<DocCardList/>
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/01-overview.md
b/docs/07-system-internals/04-replication/02-data/02-containers/01-overview.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/02-containers/01-overview.md
rename to
docs/07-system-internals/04-replication/02-data/02-containers/01-overview.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/02-types.md
b/docs/07-system-internals/04-replication/02-data/02-containers/02-types.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/02-containers/02-types.md
rename to
docs/07-system-internals/04-replication/02-data/02-containers/02-types.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/03-states.md
b/docs/07-system-internals/04-replication/02-data/02-containers/03-states.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/02-containers/03-states.md
rename to
docs/07-system-internals/04-replication/02-data/02-containers/03-states.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/04-reports.md
b/docs/07-system-internals/04-replication/02-data/02-containers/04-reports.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/02-containers/04-reports.md
rename to
docs/07-system-internals/04-replication/02-data/02-containers/04-reports.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/05-creation.md
b/docs/07-system-internals/04-replication/02-data/02-containers/05-creation.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/02-containers/05-creation.md
rename to
docs/07-system-internals/04-replication/02-data/02-containers/05-creation.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/06-persistence.md
b/docs/07-system-internals/04-replication/02-data/02-containers/06-persistence.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/02-containers/06-persistence.md
rename to
docs/07-system-internals/04-replication/02-data/02-containers/06-persistence.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/07-destruction.md
b/docs/07-system-internals/04-replication/02-data/02-containers/07-destruction.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/02-containers/07-destruction.md
rename to
docs/07-system-internals/04-replication/02-data/02-containers/07-destruction.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/08-replication.md
b/docs/07-system-internals/04-replication/02-data/02-containers/08-replication.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/02-containers/08-replication.md
rename to
docs/07-system-internals/04-replication/02-data/02-containers/08-replication.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/02-containers/09-offline-reconstruction.md
b/docs/07-system-internals/04-replication/02-data/02-containers/09-offline-reconstruction.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/02-containers/09-offline-reconstruction.md
rename to
docs/07-system-internals/04-replication/02-data/02-containers/09-offline-reconstruction.md
diff --git
a/docs/07-system-internals/04-replication/02-data/02-containers/README.mdx
b/docs/07-system-internals/04-replication/02-data/02-containers/README.mdx
new file mode 100644
index 00000000..43d3f246
--- /dev/null
+++ b/docs/07-system-internals/04-replication/02-data/02-containers/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Containers
+---
+
+# Storage Container Implementation
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the implementation of storage containers: Ozone's unit
of data replication.
+
+<DocCardList/>
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/03-replication-manager.md
b/docs/07-system-internals/04-replication/02-data/03-replication-manager.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/03-replication-manager.md
rename to
docs/07-system-internals/04-replication/02-data/03-replication-manager.md
diff --git
a/docs/07-system-internals/04-replication/02-data-replication/04-container-balancer.md
b/docs/07-system-internals/04-replication/02-data/04-container-balancer.md
similarity index 100%
rename from
docs/07-system-internals/04-replication/02-data-replication/04-container-balancer.md
rename to
docs/07-system-internals/04-replication/02-data/04-container-balancer.md
diff --git a/docs/07-system-internals/04-replication/02-data/README.mdx
b/docs/07-system-internals/04-replication/02-data/README.mdx
new file mode 100644
index 00000000..61033c24
--- /dev/null
+++ b/docs/07-system-internals/04-replication/02-data/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Data
+---
+
+# Implementation of Data Replication
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the implementation of data replication in Ozone's block
storage layer.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/04-replication/README.mdx
b/docs/07-system-internals/04-replication/README.mdx
new file mode 100644
index 00000000..41f587db
--- /dev/null
+++ b/docs/07-system-internals/04-replication/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Replication
+---
+
+# Implementation of Metadata and Data Replication
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the implementation of metadata and data replication.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/04-replication/_category_.yml
b/docs/07-system-internals/04-replication/_category_.yml
deleted file mode 100644
index 7fbd19da..00000000
--- a/docs/07-system-internals/04-replication/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Replication
diff --git a/docs/07-system-internals/05-security/README.mdx
b/docs/07-system-internals/05-security/README.mdx
new file mode 100644
index 00000000..2cafec51
--- /dev/null
+++ b/docs/07-system-internals/05-security/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Security
+---
+
+# Security Within Ozone
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the various security features used within Ozone.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/05-security/_category_.yml
b/docs/07-system-internals/05-security/_category_.yml
deleted file mode 100644
index 76a1b343..00000000
--- a/docs/07-system-internals/05-security/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Security
diff --git a/docs/07-system-internals/06-network-protocols/README.mdx
b/docs/07-system-internals/06-network-protocols/README.mdx
new file mode 100644
index 00000000..fbedccc2
--- /dev/null
+++ b/docs/07-system-internals/06-network-protocols/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Network Protocols
+---
+
+# Network Protocols Within Ozone
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the various network protocols used within Ozone.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/06-network-protocols/_category_.yml
b/docs/07-system-internals/06-network-protocols/_category_.yml
deleted file mode 100644
index bc20dd51..00000000
--- a/docs/07-system-internals/06-network-protocols/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Network Protocols
diff --git a/docs/07-system-internals/07-features/README.mdx
b/docs/07-system-internals/07-features/README.mdx
new file mode 100644
index 00000000..6d07f75e
--- /dev/null
+++ b/docs/07-system-internals/07-features/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Features
+---
+
+# Implementation of Ozone Features
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the implementations of various Ozone features.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/07-features/_category_.yml
b/docs/07-system-internals/07-features/_category_.yml
deleted file mode 100644
index 8b114ea5..00000000
--- a/docs/07-system-internals/07-features/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Features
diff --git a/docs/07-system-internals/README.mdx
b/docs/07-system-internals/README.mdx
new file mode 100644
index 00000000..72681f21
--- /dev/null
+++ b/docs/07-system-internals/README.mdx
@@ -0,0 +1,7 @@
+# System Internals
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the internal workings of Ozone for developers.
Familiarity with this section is not required for users or administrators to
work with Ozone.
+
+<DocCardList/>
diff --git a/docs/07-system-internals/_category_.yml
b/docs/07-system-internals/_category_.yml
deleted file mode 100644
index d4928d28..00000000
--- a/docs/07-system-internals/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: System Internals
diff --git a/docs/08-developer-guide/01-build/README.mdx
b/docs/08-developer-guide/01-build/README.mdx
new file mode 100644
index 00000000..e44a98a8
--- /dev/null
+++ b/docs/08-developer-guide/01-build/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Build
+---
+
+# Building Ozone
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions for developers to build Ozone from source.
+
+<DocCardList/>
diff --git a/docs/08-developer-guide/01-build/_category_.yml
b/docs/08-developer-guide/01-build/_category_.yml
deleted file mode 100644
index 43397727..00000000
--- a/docs/08-developer-guide/01-build/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Build
diff --git a/docs/08-developer-guide/02-run/README.mdx
b/docs/08-developer-guide/02-run/README.mdx
new file mode 100644
index 00000000..ac95aa4f
--- /dev/null
+++ b/docs/08-developer-guide/02-run/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Run
+---
+
+# Running a Custom Ozone Build
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents various ways to run a custom build of Ozone on a local
machine.
+
+<DocCardList/>
diff --git a/docs/08-developer-guide/02-run/_category_.yml
b/docs/08-developer-guide/02-run/_category_.yml
deleted file mode 100644
index 13acac7a..00000000
--- a/docs/08-developer-guide/02-run/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Run
diff --git a/docs/08-developer-guide/03-test/README.mdx
b/docs/08-developer-guide/03-test/README.mdx
new file mode 100644
index 00000000..45b16e24
--- /dev/null
+++ b/docs/08-developer-guide/03-test/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Test
+---
+
+# Testing Ozone
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents how to run and modify tests against Ozone.
+
+<DocCardList/>
diff --git a/docs/08-developer-guide/03-test/_category_.yml
b/docs/08-developer-guide/03-test/_category_.yml
deleted file mode 100644
index a5bdf6dd..00000000
--- a/docs/08-developer-guide/03-test/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Test
diff --git a/docs/08-developer-guide/04-project/README.mdx
b/docs/08-developer-guide/04-project/README.mdx
new file mode 100644
index 00000000..944d4f68
--- /dev/null
+++ b/docs/08-developer-guide/04-project/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Project
+---
+
+# Project Guide
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents how various aspects of the Apache Ozone project are
managed.
+
+<DocCardList/>
diff --git a/docs/08-developer-guide/04-project/_category_.yml
b/docs/08-developer-guide/04-project/_category_.yml
deleted file mode 100644
index 2f6712d4..00000000
--- a/docs/08-developer-guide/04-project/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Project
diff --git a/docs/08-developer-guide/README.mdx
b/docs/08-developer-guide/README.mdx
new file mode 100644
index 00000000..b75901eb
--- /dev/null
+++ b/docs/08-developer-guide/README.mdx
@@ -0,0 +1,7 @@
+# Developer Guide
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides a guide for developers looking to contribute to the
Ozone project.
+
+<DocCardList/>
diff --git a/docs/08-developer-guide/_category_.yml
b/docs/08-developer-guide/_category_.yml
deleted file mode 100644
index 3fc43263..00000000
--- a/docs/08-developer-guide/_category_.yml
+++ /dev/null
@@ -1 +0,0 @@
-label: Developer Guide
diff --git a/docusaurus.config.js b/docusaurus.config.js
index 1748ac7f..e96914cc 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -118,7 +118,7 @@ const config = {
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
- sidebarPath: require.resolve('./sidebars.js'),
+ sidebarPath: undefined,
// TODO update this link when the new website's branch is merged.
editUrl:
'https://github.com/apache/ozone-site/tree/HDDS-9225-website-v2',
@@ -196,7 +196,6 @@ const config = {
{
label: 'Docs',
to: 'docs',
- position: 'left',
},
{
to: 'download',
@@ -210,6 +209,10 @@ const config = {
to: 'faq',
label: 'FAQ',
},
+ {
+ to: 'community/blogs',
+ label: 'Blogs',
+ },
{
label: 'Community',
items: [
@@ -233,10 +236,6 @@ const config = {
to: 'community/events-and-media',
label: 'Events and Media',
},
- {
- to: 'community/blogs',
- label: 'Blogs',
- },
]
},
{
diff --git a/package.json b/package.json
index 18ef98e6..3166fcd0 100644
--- a/package.json
+++ b/package.json
@@ -32,7 +32,6 @@
"@cspell/dict-java": "^5.0.6",
"@cspell/dict-markdown": "^2.0.1",
"@cspell/dict-shell": "^1.0.6",
- "ajv-cli": "^5.0.0",
"markdownlint-cli": "^0.39.0"
},
"browserslist": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 854b6d4c..c25469af 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -49,9 +49,6 @@ devDependencies:
'@docusaurus/module-type-aliases':
specifier: 3.3.2
version: 3.3.2([email protected])([email protected])
- ajv-cli:
- specifier: ^5.0.0
- version: 5.0.0
cspell:
specifier: ^8.2.1
version: 8.4.1
@@ -3602,24 +3599,6 @@ packages:
indent-string: 4.0.0
dev: false
- /[email protected]:
- resolution: {integrity:
sha512-LY4m6dUv44HTyhV+u2z5uX4EhPYTM38Iv1jdgDJJJCyOOuqB8KtZEGjPZ2T+sh5ZIJrXUfgErYx/j3gLd3+PlQ==}
- hasBin: true
- peerDependencies:
- ts-node: '>=9.0.0'
- peerDependenciesMeta:
- ts-node:
- optional: true
- dependencies:
- ajv: 8.12.0
- fast-json-patch: 2.2.1
- glob: 7.2.3
- js-yaml: 3.14.1
- json-schema-migrate: 2.0.0
- json5: 2.2.3
- minimist: 1.2.8
- dev: true
-
/[email protected]([email protected]):
resolution: {integrity:
sha512-Wx0Kx52hxE7C18hkMEggYlEifqWZtYaRgouJor+WMdPnQyEK13vgEWyVNup7SoeeoLMsr4kf5h6dOW11I15MUA==}
peerDependencies:
@@ -3662,6 +3641,7 @@ packages:
json-schema-traverse: 1.0.0
require-from-string: 2.0.2
uri-js: 4.4.1
+ dev: false
/[email protected]([email protected]):
resolution: {integrity:
sha512-6EVhAmVug0+hdRHWbubF7hLHHhLoQ8NjLk6iS6d4k5chWawpS5EDexrF6Jx/hPZvUKIeNrzsbTpjAkcvrjNLHg==}
@@ -3745,6 +3725,7 @@ packages:
resolution: {integrity:
sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==}
dependencies:
sprintf-js: 1.0.3
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
@@ -3958,6 +3939,7 @@ packages:
dependencies:
balanced-match: 1.0.2
concat-map: 0.0.1
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==}
@@ -4324,6 +4306,7 @@ packages:
/[email protected]:
resolution: {integrity:
sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==}
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-qj+f8APARXHrM0hraqXYb2/bOVSV4PvJQlNZ/DVj0QrmNM2q2euizkeuVckQ57J+W0mRH6Hvi+k50M4Jul2VRQ==}
@@ -5391,10 +5374,6 @@ packages:
/[email protected]:
resolution: {integrity:
sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
- /[email protected]:
- resolution: {integrity:
sha512-bCK/2Z4zLidyB4ReuIsvALH6w31YfAQDmXMqMx6FyfHqvBxtjC0eRumeSu4Bs3XtXwpyIywtSTrVT99BxY1f9w==}
- dev: true
-
/[email protected]:
resolution: {integrity:
sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
@@ -5413,13 +5392,6 @@ packages:
merge2: 1.4.1
micromatch: 4.0.5
- /[email protected]:
- resolution: {integrity:
sha512-4j5uBaTnsYAV5ebkidvxiLUYOwjQ+JSFljeqfTxCrH9bDmlCQaOJFS84oDJ2rAXZq2yskmk3ORfoP9DCwqFNig==}
- engines: {node: '>= 0.4.0'}
- dependencies:
- fast-deep-equal: 2.0.1
- dev: true
-
/[email protected]:
resolution: {integrity:
sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==}
@@ -5668,6 +5640,7 @@ packages:
/[email protected]:
resolution: {integrity:
sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==}
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
@@ -5780,6 +5753,7 @@ packages:
minimatch: 3.1.2
once: 1.4.0
path-is-absolute: 1.0.1
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-wHTUcDUoZ1H5/0iVqEudYW4/kAlN5cZ3j/bXn0Dpbizl9iaUVeWSHqiOjsgk6OW2bkLclbBjzewBz6weQ1zA2Q==}
@@ -6325,6 +6299,7 @@ packages:
dependencies:
once: 1.4.0
wrappy: 1.0.2
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-x00IRNXNy63jwGkJmzPigoySHbaqpNuzKbBOmzK+g2OdZpQ9w+sxCN+VSB3ja7IAge2OP2qpfxTjeNcyjmW1uw==}
@@ -6332,6 +6307,7 @@ packages:
/[email protected]:
resolution: {integrity:
sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==}
@@ -6730,6 +6706,7 @@ packages:
dependencies:
argparse: 1.0.10
esprima: 4.0.1
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==}
@@ -6754,17 +6731,12 @@ packages:
/[email protected]:
resolution: {integrity:
sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==}
- /[email protected]:
- resolution: {integrity:
sha512-r38SVTtojDRp4eD6WsCqiE0eNDt4v1WalBXb9cyZYw9ai5cGtBwzRNWjHzJl38w6TxFkXAIA7h+fyX3tnrAFhQ==}
- dependencies:
- ajv: 8.12.0
- dev: true
-
/[email protected]:
resolution: {integrity:
sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==}
/[email protected]:
resolution: {integrity:
sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA==}
@@ -6774,6 +6746,7 @@ packages:
resolution: {integrity:
sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
engines: {node: '>=6'}
hasBin: true
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-AilxAyFOAcK5wA1+LeaySVBrHsGQvUFCDWXKpZjzaL0PqW+xfBOttn8GNtWKFWqneyMZj41MWF9Kl6iPWLwgOA==}
@@ -7673,6 +7646,7 @@ packages:
resolution: {integrity:
sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==}
dependencies:
brace-expansion: 1.1.11
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g==}
@@ -7834,6 +7808,7 @@ packages:
resolution: {integrity:
sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==}
dependencies:
wrappy: 1.0.2
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==}
@@ -8022,6 +7997,7 @@ packages:
/[email protected]:
resolution: {integrity:
sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==}
engines: {node: '>=0.10.0'}
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-DUWJr3+ULp4zXmol/SZkFf3JGsS9/SIv+Y3Rt93/UjPpDpklB5f1er4O3POIbUuUJ3FXgqte2Q7SrU6zAqwk8w==}
@@ -9023,6 +8999,7 @@ packages:
/[email protected]:
resolution: {integrity:
sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
engines: {node: '>=0.10.0'}
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-oyrU88skkMtDdauHDuKVrgR+zuItqr6/c//FXzvmxRGMexSDc6hNvJInGW3LL46n+8b50RykrvwSUIIQH2LQ5A==}
@@ -9517,6 +9494,7 @@ packages:
/[email protected]:
resolution: {integrity:
sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==}
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-wvLeHgcVHKO8Sc/H/5lkGreJQVeYMm9rlmt8PuR1xE31rIuXhuzznUUqAt8MqLhB3MqJdFzlNAfpcWnxiFUcPw==}
@@ -10549,6 +10527,7 @@ packages:
/[email protected]:
resolution: {integrity:
sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
+ dev: false
/[email protected]:
resolution: {integrity:
sha512-AvHcyZ5JnSfq3ioSyjrBkH9yW4m7Ayk8/9My/DD9onKeu/94fwrMocemO2QAJFAlnnDN+ZDS+ZjAR5ua1/PV/Q==}
diff --git a/sidebars.js b/sidebars.js
deleted file mode 100644
index d6de6651..00000000
--- a/sidebars.js
+++ /dev/null
@@ -1,40 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-
-/**
- * Creating a sidebar enables you to:
- - create an ordered group of docs
- - render a sidebar for each doc of that group
- - provide next/previous navigation
-
- The sidebars can be generated from the filesystem, or explicitly defined here.
-
- Create as many sidebars as you want.
- */
-
-// @ts-check
-
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
-const sidebars = {
- // Generate sidebar of docs page from document tree structure automatically.
- tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
-
-};
-
-module.exports = sidebars;
diff --git a/src/pages/index.js b/src/pages/index.js
index 0f2371e3..54f8db38 100644
--- a/src/pages/index.js
+++ b/src/pages/index.js
@@ -24,7 +24,7 @@ import Logo from '@site/static/img/ozone-logo.svg';
export default function Home() {
const {siteConfig} = useDocusaurusContext();
- const getStartedHref = `docs/quick-start/installation/docker`
+ const getStartedHref = `docs/quick-start`
return (
<Layout
title="Home"
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
