From 920a5065dad4cdfb3003831bb2eae00b89dd7b95 Mon Sep 17 00:00:00 2001
From: Patrick McFadin <pmcfadin@gmail.com>
Date: Thu, 14 May 2026 15:05:26 -0700
Subject: [PATCH 1/6] Fix module-prefix xrefs to cassandra: with current paths

Eleven xrefs across nine files used bare or partial paths that no longer
resolve. Each had a target page that exists at a cassandra: qualified
path on trunk; all anchors were verified present before edit.

- architecture/index.adoc      snitch.adoc      -> managing/operating/snitch.adoc
- developing/cql/ddl.adoc      transientreplication.adoc -> managing/operating/transientreplication.adoc
- getting-started/production.adoc  compaction/index.adoc -> managing/operating/compaction/index.adoc
- getting-started/querying.adoc    tools/cqlsh.adoc -> managing/tools/cqlsh.adoc
- reference/cql-commands/alter-table.adoc  cql-commands/alter-table.adoc#alter-compression (self-page; now qualified)
- reference/static.adoc        developing/batch/batch-good-example.adoc -> developing/cql/batch/batch-good-example.adoc
- troubleshooting/finding_nodes.adoc  reading_logs.adoc / use_tools.adoc (qualified) + stealth typo use_nodetooladoc -> use_nodetool.adoc
- troubleshooting/use_tools.adoc  use_tools.adoc#use-bcc-tools / #use-vmtouch (self-page; now qualified)
- partials/compact-subproperties.adoc  operating/compaction/twcs.adoc#twcs_options -> managing/operating/compaction/twcs.adoc#twcs_options

 patch by Patrick McFadin; reviewed by TBD for CASSANDRA-21342
---
 doc/modules/cassandra/pages/architecture/index.adoc           | 2 +-
 doc/modules/cassandra/pages/developing/cql/ddl.adoc           | 2 +-
 doc/modules/cassandra/pages/getting-started/production.adoc   | 2 +-
 doc/modules/cassandra/pages/getting-started/querying.adoc     | 2 +-
 .../cassandra/pages/reference/cql-commands/alter-table.adoc   | 2 +-
 doc/modules/cassandra/pages/reference/static.adoc             | 2 +-
 .../cassandra/pages/troubleshooting/finding_nodes.adoc        | 4 ++--
 doc/modules/cassandra/pages/troubleshooting/use_tools.adoc    | 4 ++--
 doc/modules/cassandra/partials/compact-subproperties.adoc     | 2 +-
 9 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/doc/modules/cassandra/pages/architecture/index.adoc b/doc/modules/cassandra/pages/architecture/index.adoc
index 893c2f78076d..7c4d949491d1 100644
--- a/doc/modules/cassandra/pages/architecture/index.adoc
+++ b/doc/modules/cassandra/pages/architecture/index.adoc
@@ -6,5 +6,5 @@ This section describes the general architecture of Apache Cassandra.
 * xref:architecture/dynamo.adoc[Dynamo]
 * xref:architecture/storage-engine.adoc[Storage Engine]
 * xref:architecture/guarantees.adoc[Guarantees]
-* xref:architecture/snitch.adoc[Snitches]
+* xref:cassandra:managing/operating/snitch.adoc[Snitches]
 * xref:architecture/accord.adoc[Accord]
diff --git a/doc/modules/cassandra/pages/developing/cql/ddl.adoc b/doc/modules/cassandra/pages/developing/cql/ddl.adoc
index 616bcfa06bef..0f248282a062 100644
--- a/doc/modules/cassandra/pages/developing/cql/ddl.adoc
+++ b/doc/modules/cassandra/pages/developing/cql/ddl.adoc
@@ -166,7 +166,7 @@ will result in:
 include::cassandra:example$RESULTS/autoexpand_exclude_dc.result[]
 ----
 
-If xref:new/transientreplication.adoc[transient replication] has been enabled, transient replicas can be
+If xref:cassandra:managing/operating/transientreplication.adoc[transient replication] has been enabled, transient replicas can be
 configured for both `SimpleStrategy` and `NetworkTopologyStrategy` by
 defining replication factors in the format
 `'<total_replicas>/<transient_replicas>'`
diff --git a/doc/modules/cassandra/pages/getting-started/production.adoc b/doc/modules/cassandra/pages/getting-started/production.adoc
index ad28a35f5638..475c1f7fb8f1 100644
--- a/doc/modules/cassandra/pages/getting-started/production.adoc
+++ b/doc/modules/cassandra/pages/getting-started/production.adoc
@@ -118,7 +118,7 @@ https://thelastpickle.com/blog/2018/08/08/compression_performance.html[The Last
 
 == Compaction
 
-There are different xref:compaction/index.adoc[compaction] strategies available
+There are different xref:cassandra:managing/operating/compaction/index.adoc[compaction] strategies available
 for different workloads.
 We recommend reading about the different strategies to understand which is the
 best for your environment.
diff --git a/doc/modules/cassandra/pages/getting-started/querying.adoc b/doc/modules/cassandra/pages/getting-started/querying.adoc
index 78866cef0e69..2e1fe2361bea 100644
--- a/doc/modules/cassandra/pages/getting-started/querying.adoc
+++ b/doc/modules/cassandra/pages/getting-started/querying.adoc
@@ -22,7 +22,7 @@ include::cassandra:example$BASH/cqlsh_localhost.sh[]
 ----
 include::cassandra:example$RESULTS/cqlsh_localhost.result[]
 ----
-If the command is used without specifying a node, `localhost` is the default. See the xref:tools/cqlsh.adoc[`cqlsh` section] for full documentation.
+If the command is used without specifying a node, `localhost` is the default. See the xref:cassandra:managing/tools/cqlsh.adoc[`cqlsh` section] for full documentation.
 
 == Client drivers
 
diff --git a/doc/modules/cassandra/pages/reference/cql-commands/alter-table.adoc b/doc/modules/cassandra/pages/reference/cql-commands/alter-table.adoc
index 700a7b0063b5..45bfb909586d 100644
--- a/doc/modules/cassandra/pages/reference/cql-commands/alter-table.adoc
+++ b/doc/modules/cassandra/pages/reference/cql-commands/alter-table.adoc
@@ -190,7 +190,7 @@ To change an existing table's properties, use `ALTER TABLE` and `WITH`.
 You can specify a:
 
 * Single property name and value.
-* Property map to set the names and values, as shown in the xref:cql-commands/alter-table.adoc#alter-compression[next section on compression and compaction].
+* Property map to set the names and values, as shown in the xref:cassandra:reference/cql-commands/alter-table.adoc#alter-compression[next section on compression and compaction].
 
 For example, to add a comment to the xref:cassandra:cyclist_base-table.adoc[cyclist_base] table using WITH:
 
diff --git a/doc/modules/cassandra/pages/reference/static.adoc b/doc/modules/cassandra/pages/reference/static.adoc
index d27adc76ea5f..96a9f7bf13ef 100644
--- a/doc/modules/cassandra/pages/reference/static.adoc
+++ b/doc/modules/cassandra/pages/reference/static.adoc
@@ -48,7 +48,7 @@ The table that does not have clustering columns has a one-row partition in which
 * A column designated to be the partition key cannot be static.
 ====
 
-You can do xref:developing/batch/batch-good-example.adoc[batch conditional updates to a static column].
+You can do xref:cassandra:developing/cql/batch/batch-good-example.adoc[batch conditional updates to a static column].
 
 Use the `DISTINCT` keyword to select static columns.
 In this case, the database retrieves only the beginning (static column) of the partition.
diff --git a/doc/modules/cassandra/pages/troubleshooting/finding_nodes.adoc b/doc/modules/cassandra/pages/troubleshooting/finding_nodes.adoc
index d2e9a9b10a93..a9b9b3484eec 100644
--- a/doc/modules/cassandra/pages/troubleshooting/finding_nodes.adoc
+++ b/doc/modules/cassandra/pages/troubleshooting/finding_nodes.adoc
@@ -128,6 +128,6 @@ exhaust significant CPU capacitity with a "single" query.
 
 Once you have narrowed down the problem as much as possible (datacenter,
 rack , node), login to one of the nodes using SSH and proceed to debug
-using xref:reading_logs.adoc[`logs`], xref:use_nodetooladoc[`nodetool`], and
-xref:use_tools.adoc[`os tools`].
+using xref:cassandra:troubleshooting/reading_logs.adoc[`logs`], xref:cassandra:troubleshooting/use_nodetool.adoc[`nodetool`], and
+xref:cassandra:troubleshooting/use_tools.adoc[`os tools`].
 If you are not able to login you may still have access to `logs` and `nodetool` remotely.
diff --git a/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc b/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc
index ed72f5433d72..198dc2eef774 100644
--- a/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc
+++ b/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc
@@ -232,8 +232,8 @@ Cassandra performance can suffer significantly. This is why Cassandra
 starts with a reasonably small amount of memory reserved for the heap.
 
 If you suspect that you are missing the OS page cache frequently you can
-use advanced tools like xref:use_tools.adoc#use-bcc-tools[cachestat] or
-xref:use_tools.adoc#use-vmtouch[vmtouch] to dive deeper.
+use advanced tools like xref:cassandra:troubleshooting/use_tools.adoc#use-bcc-tools[cachestat] or
+xref:cassandra:troubleshooting/use_tools.adoc#use-vmtouch[vmtouch] to dive deeper.
 
 === Network Latency and Reliability
 
diff --git a/doc/modules/cassandra/partials/compact-subproperties.adoc b/doc/modules/cassandra/partials/compact-subproperties.adoc
index 1e5a4148beb8..7bd54c6520f4 100644
--- a/doc/modules/cassandra/partials/compact-subproperties.adoc
+++ b/doc/modules/cassandra/partials/compact-subproperties.adoc
@@ -162,7 +162,7 @@ TWCS creates a new time window within each successive time period.
 During the active time window, TWCS compacts all SSTables flushed from memory into larger SSTables using STCS.
 At the end of the time period, all of these SSTables are compacted into a single SSTable.
 Then the next time window starts and the process repeats.
-See xref:operating/compaction/twcs.adoc#twcs_options[TimeWindowCompactionStrategy (TWCS)].
+See xref:cassandra:managing/operating/compaction/twcs.adoc#twcs_options[TimeWindowCompactionStrategy (TWCS)].
 
 [NOTE]
 ====

From 9c6d9f794a81902dbafa9f14fdeb0f9a242f9fcd Mon Sep 17 00:00:00 2001
From: Patrick McFadin <pmcfadin@gmail.com>
Date: Thu, 14 May 2026 15:06:41 -0700
Subject: [PATCH 2/6] Retarget moved-page xrefs to their current homes on trunk

Ten xref destinations pointed at paths that no longer exist after page
moves. Each was retargeted to the page's current location; target
existence and (where present) anchors were verified.

- developing/collections/{list,map,set}.adoc -> developing/cql/collections/{list,map,set}.adoc (3 sites in create-custom-index.adoc)
- developing/cql/operating/backups.adoc -> managing/operating/backups.adoc (bulk_loading.adoc)
- developing/cql/tools/cqlsh.adoc#cqlshrc -> managing/tools/cqlsh.adoc#cqlshrc (self-link in cqlsh.adoc)
- developing/cql/troubleshooting/use_tools.adoc#use-bcc-tools -> troubleshooting/use_tools.adoc#use-bcc-tools (self-link in use_tools.adoc)
- developing/indexing/2i/2i-when-to-use.adoc -> developing/cql/indexing/2i/2i-when-to-use.adoc (create-table.adoc)
- developing/cql/indexing/sai/overview.adoc -> developing/cql/indexing/sai/sai-overview.adoc (vector-search/concepts.adoc)
- developing/cql/indexing/create-custom-index.adoc -> developing/cql/create-custom-index.adoc (create-index.adoc and sai/_sai-create.adoc)
- managing/tools/cassandra_stress.adoc -> tooling/cassandra-stress.adoc (nav.adoc; underscore-to-dash plus path)

 patch by Patrick McFadin; reviewed by TBD for CASSANDRA-21342
---
 doc/modules/cassandra/nav.adoc                              | 2 +-
 .../cassandra/pages/developing/cql/create-custom-index.adoc | 6 +++---
 .../cassandra/pages/developing/cql/create-index.adoc        | 2 +-
 .../pages/developing/cql/indexing/sai/_sai-create.adoc      | 2 +-
 .../cassandra/pages/managing/operating/bulk_loading.adoc    | 2 +-
 doc/modules/cassandra/pages/managing/tools/cqlsh.adoc       | 2 +-
 .../pages/reference/cql-commands/create-table.adoc          | 2 +-
 doc/modules/cassandra/pages/troubleshooting/use_tools.adoc  | 2 +-
 doc/modules/cassandra/pages/vector-search/concepts.adoc     | 2 +-
 9 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/doc/modules/cassandra/nav.adoc b/doc/modules/cassandra/nav.adoc
index 0cb64e03134f..52f8677c97f4 100644
--- a/doc/modules/cassandra/nav.adoc
+++ b/doc/modules/cassandra/nav.adoc
@@ -117,7 +117,7 @@
 **** xref:cassandra:managing/tools/cqlsh.adoc[cqlsh: the CQL shell]
 **** xref:cassandra:managing/tools/nodetool/nodetool.adoc[nodetool]
 **** xref:cassandra:managing/tools/sstable/index.adoc[SSTable tools]
-**** xref:cassandra:managing/tools/cassandra_stress.adoc[cassandra-stress]
+**** xref:cassandra:tooling/cassandra-stress.adoc[cassandra-stress]
 
 
 ** xref:cassandra:troubleshooting/index.adoc[Troubleshooting]
diff --git a/doc/modules/cassandra/pages/developing/cql/create-custom-index.adoc b/doc/modules/cassandra/pages/developing/cql/create-custom-index.adoc
index 4424b8695e28..9568ae8b7021 100644
--- a/doc/modules/cassandra/pages/developing/cql/create-custom-index.adoc
+++ b/doc/modules/cassandra/pages/developing/cql/create-custom-index.adoc
@@ -119,7 +119,7 @@ Also refer xref:cassandra:developing/cql/indexing/sai/sai-query.adoc[Examine SAI
 === SAI collection map examples with keys, values, and entries
 
 The following examples demonstrate using collection maps of multiple types (`keys`, `values`, `entries`) in SAI indexes.
-For related information, see xref:cassandra:developing/cql/collections/collection-create.adoc[Creating collections] and xref:cassandra:developing/collections/map.adoc[Using map type].
+For related information, see xref:cassandra:developing/cql/collections/collection-create.adoc[Creating collections] and xref:cassandra:developing/cql/collections/map.adoc[Using map type].
 
 Also refer to the SAI collection examples of type xref:#saiCreateCustomIndexCollectionsListAndSetExamples[list and set] in this topic.
 
@@ -294,8 +294,8 @@ These examples demonstrate using collections with the `list` and `set` types in
 For related information, see:
 
 * xref:cassandra:developing/cql/collections/collection-create.adoc[Creating collections]
-* xref:cassandra:developing/collections/list.adoc[Using list type]
-* xref:cassandra:developing/collections/set.adoc[Using set type]
+* xref:cassandra:developing/cql/collections/list.adoc[Using list type]
+* xref:cassandra:developing/cql/collections/set.adoc[Using set type]
 
 [source,language-cql]
 ----
diff --git a/doc/modules/cassandra/pages/developing/cql/create-index.adoc b/doc/modules/cassandra/pages/developing/cql/create-index.adoc
index d8a0006d4c38..d3114d6610e1 100644
--- a/doc/modules/cassandra/pages/developing/cql/create-index.adoc
+++ b/doc/modules/cassandra/pages/developing/cql/create-index.adoc
@@ -8,7 +8,7 @@ After an index has been created, it is automatically updated when data in the co
 Indexing via this `CREATE INDEX` command can impact performance.
 Before creating an index, be aware of when and xref:cassandra:developing/cql/indexing/2i/2i-when-to-use.adoc#when-no-index[when not to create an index].
 
-Use xref:cassandra:developing/cql/indexing/create-custom-index.adoc[CREATE CUSTOM INDEX] for Storage-Attached Indexes (SAI).
+Use xref:cassandra:developing/cql/create-custom-index.adoc[CREATE CUSTOM INDEX] for Storage-Attached Indexes (SAI).
 
 *Restriction:* Indexing counter columns is not supported.
 For maps, index the key, value, or entries.
diff --git a/doc/modules/cassandra/pages/developing/cql/indexing/sai/_sai-create.adoc b/doc/modules/cassandra/pages/developing/cql/indexing/sai/_sai-create.adoc
index 1e5c4760b8a7..45e9362837d0 100644
--- a/doc/modules/cassandra/pages/developing/cql/indexing/sai/_sai-create.adoc
+++ b/doc/modules/cassandra/pages/developing/cql/indexing/sai/_sai-create.adoc
@@ -76,4 +76,4 @@ include::cassandra:example$CQL/sai/index-sai-similarity-function.cql[]
 '''
 Other resources
 
-See xref:developing/cql/indexing/create-custom-index.adoc[CREATE CUSTOM INDEX] for more information about creating SAI indexes.
\ No newline at end of file
+See xref:cassandra:developing/cql/create-custom-index.adoc[CREATE CUSTOM INDEX] for more information about creating SAI indexes.
\ No newline at end of file
diff --git a/doc/modules/cassandra/pages/managing/operating/bulk_loading.adoc b/doc/modules/cassandra/pages/managing/operating/bulk_loading.adoc
index 939d0fc58c49..51a871b01bf7 100644
--- a/doc/modules/cassandra/pages/managing/operating/bulk_loading.adoc
+++ b/doc/modules/cassandra/pages/managing/operating/bulk_loading.adoc
@@ -25,7 +25,7 @@ The `sstableloader` and `nodetool import` are accessible if the
 Cassandra installation `bin` directory is in the `PATH` environment
 variable.
 Or these may be accessed directly from the `bin` directory.
-The examples use the keyspaces and tables created in xref:cassandra:developing/cql/operating/backups.adoc[Backups].
+The examples use the keyspaces and tables created in xref:cassandra:managing/operating/backups.adoc[Backups].
 
 == Using sstableloader
 
diff --git a/doc/modules/cassandra/pages/managing/tools/cqlsh.adoc b/doc/modules/cassandra/pages/managing/tools/cqlsh.adoc
index 5918d2f3ffae..e6f23d3683bd 100644
--- a/doc/modules/cassandra/pages/managing/tools/cqlsh.adoc
+++ b/doc/modules/cassandra/pages/managing/tools/cqlsh.adoc
@@ -22,7 +22,7 @@ of `cqlsh`.
 
 By default, `cqlsh` displays all timestamps with a UTC timezone.
 For Python 3.9 or higher, timestamps can be displayed in different timezones by modifying the
-`timezone` option in xref:cassandra:developing/cql/tools/cqlsh.adoc#cqlshrc[cqlshrc] or by setting the environment
+`timezone` option in xref:cassandra:managing/tools/cqlsh.adoc#cqlshrc[cqlshrc] or by setting the environment
 variable `TZ`.
 Python 3.8 or lower, however, will also require the installation of http://pytz.sourceforge.net/[pytz] library.
 
diff --git a/doc/modules/cassandra/pages/reference/cql-commands/create-table.adoc b/doc/modules/cassandra/pages/reference/cql-commands/create-table.adoc
index 69cb7cc7431a..0b428187e7dc 100644
--- a/doc/modules/cassandra/pages/reference/cql-commands/create-table.adoc
+++ b/doc/modules/cassandra/pages/reference/cql-commands/create-table.adoc
@@ -88,7 +88,7 @@ If the column already contains data, it is indexed during the execution of this
 After an index has been created, it is automatically updated when data in the column changes.
 
 Indexing with the `CREATE INDEX` command can impact performance.
-Before creating an index, be aware of when and xref:cassandra:developing/indexing/2i/2i-when-to-use.adoc#when-no-index[when not to create an index].
+Before creating an index, be aware of when and xref:cassandra:developing/cql/indexing/2i/2i-when-to-use.adoc#when-no-index[when not to create an index].
 
 *Restriction:* Indexing counter columns is not supported.
 
diff --git a/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc b/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc
index 198dc2eef774..4a66f08adb99 100644
--- a/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc
+++ b/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc
@@ -483,7 +483,7 @@ $ ./vmtouch /var/lib/cassandra/data/
 
 In this case almost the entire dataset is hot in OS page Cache.
 Generally speaking the percentage doesn't really matter unless reads are
-missing the cache (per e.g. xref:cassandra:developing/cql/troubleshooting/use_tools.adoc#use-bcc-tools[cachestat] in which case
+missing the cache (per e.g. xref:cassandra:troubleshooting/use_tools.adoc#use-bcc-tools[cachestat] in which case
 having additional memory may help read performance.
 
 === CPU Flamegraphs
diff --git a/doc/modules/cassandra/pages/vector-search/concepts.adoc b/doc/modules/cassandra/pages/vector-search/concepts.adoc
index 05c97e4c1d02..ba194779043f 100644
--- a/doc/modules/cassandra/pages/vector-search/concepts.adoc
+++ b/doc/modules/cassandra/pages/vector-search/concepts.adoc
@@ -4,7 +4,7 @@
 
 Vector Search is a new feature added to {cass-50}.
 It is a powerful technique for finding relevant content within large datasets and is particularly useful for AI applications. 
-Vector Search also makes use of xref:cassandra:developing/cql/indexing/sai/overview.adoc[Storage-Attached Indexes(SAI)], leveraging the new modularity of the latter feature.
+Vector Search also makes use of xref:cassandra:developing/cql/indexing/sai/sai-overview.adoc[Storage-Attached Indexes(SAI)], leveraging the new modularity of the latter feature.
 Vector Search is the first instance of validating the extensibility of SAI.
 
 Data stored in a database is useful, but the context of that data is critical to applications.

From 55e6df420ea6703964a84af16f5396b7e6623a4f Mon Sep 17 00:00:00 2001
From: Patrick McFadin <pmcfadin@gmail.com>
Date: Thu, 14 May 2026 15:07:56 -0700
Subject: [PATCH 3/6] Fix definitions.adoc self-link typo (defintions ->
 definitions)

A single self-page xref in developing/cql/definitions.adoc had a
filename typo (missing the second i: defintions instead of
definitions). The anchor #constants resolves once the typo is fixed.

 patch by Patrick McFadin; reviewed by TBD for CASSANDRA-21342
---
 doc/modules/cassandra/pages/developing/cql/definitions.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/modules/cassandra/pages/developing/cql/definitions.adoc b/doc/modules/cassandra/pages/developing/cql/definitions.adoc
index e139c28ef9f8..8153468d86d4 100644
--- a/doc/modules/cassandra/pages/developing/cql/definitions.adoc
+++ b/doc/modules/cassandra/pages/developing/cql/definitions.adoc
@@ -118,7 +118,7 @@ include::cassandra:example$BNF/term.bnf[]
 
 A term is thus one of:
 
-* A xref:cassandra:developing/cql/defintions.adoc#constants[constant]
+* A xref:cassandra:developing/cql/definitions.adoc#constants[constant]
 * A literal for either a xref:cassandra:developing/cql/types.adoc#collections[collection], a xref:cassandra:developing/cql/types.adoc#vectors[vector],
 a xref:cassandra:developing/cql/types.adoc#udts[user-defined type] or a xref:cassandra:developing/cql/types.adoc#tuples[tuple]
 * A xref:cassandra:developing/cql/functions.adoc#cql-functions[function] call, either a xref:cassandra:developing/cql/functions.adoc#scalar-native-functions[native function]

From dec49ce4146f9e28c408d0265e22e4adc3d75cf1 Mon Sep 17 00:00:00 2001
From: Patrick McFadin <pmcfadin@gmail.com>
Date: Thu, 14 May 2026 15:08:21 -0700
Subject: [PATCH 4/6] Replace .html with .adoc in xref targets; retarget
 writetime to functions.adoc

Two xrefs used .html extensions that Antora does not resolve.

- new/index.adoc referenced developing/cql/dml.html#writetime-and-ttl-function.
  The dml.adoc page has no writetime anchor; the actual anchor
  [[writetime-and-ttl-functions]] (plural) lives in functions.adoc.
  Retargeted to cassandra:developing/cql/functions.adoc#writetime-and-ttl-functions.

- installing/installing.adoc referenced troubleshooting/index.html.
  The page exists at troubleshooting/index.adoc; the .html extension
  was a copy-paste from rendered-site URLs.

 patch by Patrick McFadin; reviewed by TBD for CASSANDRA-21342
---
 doc/modules/cassandra/pages/installing/installing.adoc | 2 +-
 doc/modules/cassandra/pages/new/index.adoc             | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/modules/cassandra/pages/installing/installing.adoc b/doc/modules/cassandra/pages/installing/installing.adoc
index 1c1aa88d2200..2b33acc9dac4 100644
--- a/doc/modules/cassandra/pages/installing/installing.adoc
+++ b/doc/modules/cassandra/pages/installing/installing.adoc
@@ -279,4 +279,4 @@ include::cassandra:partial$nodetool_and_cqlsh_nobin.adoc[]
 
 == Further installation info
 
-For help with installation issues, see the xref:cassandra:troubleshooting/index.html[Troubleshooting] section.
+For help with installation issues, see the xref:cassandra:troubleshooting/index.adoc[Troubleshooting] section.
diff --git a/doc/modules/cassandra/pages/new/index.adoc b/doc/modules/cassandra/pages/new/index.adoc
index 991ffd490ef3..1f639bf578a4 100644
--- a/doc/modules/cassandra/pages/new/index.adoc
+++ b/doc/modules/cassandra/pages/new/index.adoc
@@ -19,7 +19,7 @@ This section covers the new features in Apache Cassandra 5.0.
 * Trie SSTables: https://cwiki.apache.org/confluence/display/CASSANDRA/CEP-25%3A+Trie-indexed+SSTable+format[CEP-25], https://issues.apache.org/jira/browse/CASSANDRA-18398[JIRA ticket]
 * JDK 17: xref:cassandra:reference/java17.adoc[Docs], https://issues.apache.org/jira/browse/CASSANDRA-16895[JIRA ticket]
 * More guardrails: https://github.com/apache/cassandra/blob/trunk/NEWS.txt[NEWS.txt]
-* TTL and writetime on collections and UDTs: xref:cassandra:developing/cql/dml.html#writetime-and-ttl-function[Docs], https://issues.apache.org/jira/browse/CASSANDRA-8877[JIRA ticket]
+* TTL and writetime on collections and UDTs: xref:cassandra:developing/cql/functions.adoc#writetime-and-ttl-functions[Docs], https://issues.apache.org/jira/browse/CASSANDRA-8877[JIRA ticket]
 * New vector data type: xref:cassandra:reference/vector-data-type.adoc[Docs], https://cwiki.apache.org/confluence/display/CASSANDRA/CEP-30%3A+Approximate+Nearest+Neighbor%28ANN%29+Vector+Search+via+Storage-Attached+Indexes[CEP-30], https://issues.apache.org/jira/browse/CASSANDRA-18504[JIRA ticket]
 * New vector similarity functions: xref:cassandra:vector-search/overview.adoc[Docs], https://cwiki.apache.org/confluence/display/CASSANDRA/CEP-30%3A+Approximate+Nearest+Neighbor%28ANN%29+Vector+Search+via+Storage-Attached+Indexes[CEP-30], https://issues.apache.org/jira/browse/CASSANDRA-18640[JIRA ticket]
 * Unified Compaction Strategy: xref:cassandra:managing/operating/compaction/ucs.adoc[Docs], https://cwiki.apache.org/confluence/display/CASSANDRA/CEP-26%3A+Unified+Compaction+Strategy[CEP-26], https://issues.apache.org/jira/browse/CASSANDRA-18397[JIRA ticket]

From 6aa9589114941b37a54bd47bd5d0a997d0426a65 Mon Sep 17 00:00:00 2001
From: Patrick McFadin <pmcfadin@gmail.com>
Date: Thu, 14 May 2026 15:08:55 -0700
Subject: [PATCH 5/6] Qualify nodetool xrefs to
 cassandra:managing/tools/nodetool

Four xrefs to nodetool subcommand pages used non-existent module
prefixes or paths. The nodetool subcommand pages are generated at
build time by the gen-asciidoc Ant target; the canonical xref form
used elsewhere on trunk (e.g. nav.adoc:118) is
cassandra:managing/tools/nodetool/<command>.adoc.

- architecture/storage-engine.adoc  managing:tools/nodetool/drain.adoc
- architecture/storage-engine.adoc  managing:tools/nodetool/flush.adoc
- developing/cql/indexing/2i/operations/2i-build.adoc  cassandra:tools/nodetool/rebuild_index.adoc
- managing/operating/security.adoc  tools/nodetool/nodetools.adoc (also a typo: plural -> singular nodetool.adoc)

Generated targets cannot be grep-verified from a static checkout;
relying on the convention used by adjacent xrefs in nav.adoc that
have shipped without complaint. If any fail at the next Antora 3
build, fix in a follow-up.

 patch by Patrick McFadin; reviewed by TBD for CASSANDRA-21342
---
 doc/modules/cassandra/pages/architecture/storage-engine.adoc  | 4 ++--
 .../pages/developing/cql/indexing/2i/operations/2i-build.adoc | 2 +-
 doc/modules/cassandra/pages/managing/operating/security.adoc  | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/modules/cassandra/pages/architecture/storage-engine.adoc b/doc/modules/cassandra/pages/architecture/storage-engine.adoc
index 1494fa5154f3..7a194c156b1a 100644
--- a/doc/modules/cassandra/pages/architecture/storage-engine.adoc
+++ b/doc/modules/cassandra/pages/architecture/storage-engine.adoc
@@ -30,7 +30,7 @@ Once the defined size is reached, a new commit log segment is created.
 Commit log segments can be archived, deleted, or recycled once all the data is flushed to
 https://cassandra.apache.org/_/glossary.html#sstable[SSTables].
 Commit log segments are truncated when Cassandra has written data older than a certain point to the SSTables.
-Running xref:managing:tools/nodetool/drain.adoc[`nodetool drain`] before stopping Cassandra will write everything in the memtables
+Running xref:cassandra:managing/tools/nodetool/drain.adoc[`nodetool drain`] before stopping Cassandra will write everything in the memtables
 to SSTables and remove the need to sync with the commit logs on startup.
 
 * xref:cassandra:managing/configuration/cass_yaml_file.adoc#commitlog_segment_size [`commitlog_segment_size`]: The default size is 32MiB, which is almost always fine, but if you are archiving commitlog segments (see commitlog_archiving.properties), then you probably want a finer granularity of archiving; 8 or 16 MiB is reasonable.
@@ -105,7 +105,7 @@ A partition index is also created on the disk that maps the tokens to a location
 
 The queue can be configured with either the xref:cassandra:managing/configuration/cass_yaml_file.adoc#memtable_heap_space[`memtable_heap_space`] or xref:cassandra:managing/configuration/cass_yaml_file.adoc#memtable_offheap_space[`memtable_offheap_space`] setting in the `cassandra.yaml` file.
 If the data to be flushed exceeds the `memtable_cleanup_threshold`, Cassandra blocks writes until the next flush succeeds.
-You can manually flush a table using xref:managing:tools/nodetool/flush.adoc[`nodetool flush`] or `nodetool drain` (flushes memtables without listening for connections to other nodes). 
+You can manually flush a table using xref:cassandra:managing/tools/nodetool/flush.adoc[`nodetool flush`] or `nodetool drain` (flushes memtables without listening for connections to other nodes).
 To reduce the commit log replay time, the recommended best practice is to flush the memtable before you restart the nodes. 
 If a node stops working, replaying the commit log restores writes to the memtable that were there before it stopped.
 
diff --git a/doc/modules/cassandra/pages/developing/cql/indexing/2i/operations/2i-build.adoc b/doc/modules/cassandra/pages/developing/cql/indexing/2i/operations/2i-build.adoc
index 80201b133834..37caa0977542 100644
--- a/doc/modules/cassandra/pages/developing/cql/indexing/2i/operations/2i-build.adoc
+++ b/doc/modules/cassandra/pages/developing/cql/indexing/2i/operations/2i-build.adoc
@@ -7,4 +7,4 @@ Indexes are built in the background automatically, without blocking reads or wri
 Client-maintained _tables as indexes_ must be created manually;
 for example, if the artists column had been indexed by creating a table such as `songs_by_artist`, your client application would have to populate the table with data from the songs table.
 
-To perform a hot rebuild of an index, use the xref:cassandra:tools/nodetool/rebuild_index.adoc[nodetool rebuild_index] command.
+To perform a hot rebuild of an index, use the xref:cassandra:managing/tools/nodetool/rebuild_index.adoc[nodetool rebuild_index] command.
diff --git a/doc/modules/cassandra/pages/managing/operating/security.adoc b/doc/modules/cassandra/pages/managing/operating/security.adoc
index 6fbf11429e46..8abf888296c0 100644
--- a/doc/modules/cassandra/pages/managing/operating/security.adoc
+++ b/doc/modules/cassandra/pages/managing/operating/security.adoc
@@ -465,7 +465,7 @@ If enabling remote connections, it is recommended to also use
 xref:cassandra:managing/operating/security.adoc#jmx-with-ssl[`SSL`] connections.
 
 Finally, after enabling auth and/or SSL, ensure that tools which use
-JMX, such as xref:tools/nodetool/nodetools.adoc[`nodetool`] are correctly configured and working
+JMX, such as xref:cassandra:managing/tools/nodetool/nodetool.adoc[`nodetool`] are correctly configured and working
 as expected.
 
 === Standard JMX Auth

From cac55a5835fdc84e04fc0bb4252fd0b522e6c91d Mon Sep 17 00:00:00 2001
From: Patrick McFadin <pmcfadin@gmail.com>
Date: Thu, 14 May 2026 15:10:20 -0700
Subject: [PATCH 6/6] Add missing anchors and retarget anchored xrefs

Seven xrefs failed because their named anchors did not exist on the
referenced page. Three anchors are added (matching the existing
[[anchor]] convention used elsewhere on each page) and the affected
xrefs are retargeted or qualified.

Anchors added:
- reference/cql-commands/create-table.adoc gains [[table_options]]
  before the "Optional parameters" heading (referenced from
  alter-table.adoc:101).
- developing/cql/indexing/sai/operations/configuring.adoc gains
  [[saiConfigure__saiCompactionStrategies]] before the "Compaction
  strategies" heading (referenced from compact-subproperties.adoc in
  both pages/ and partials/).
- troubleshooting/use_tools.adoc gains [[packet-capture]] before the
  "Packet Capture" section (referenced from reading_logs.adoc:247).

Xrefs retargeted:
- alter-table.adoc -> cassandra:reference/cql-commands/create-table.adoc#table_options
- sai/operations/configuring.adoc -> cassandra:reference/cql-commands/compact-subproperties.adoc#TWCS and #LCS (these are the anchors that actually exist on the compact-subproperties page; the create-table.adoc#compactSubprop__LCS/TWCS targets do not exist)
- pages/.../compact-subproperties.adoc -> cassandra:developing/cql/indexing/sai/operations/configuring.adoc#saiConfigure__saiCompactionStrategies (path was sai/configuring not sai/operations/configuring)
- partials/compact-subproperties.adoc -> same as above
- troubleshooting/reading_logs.adoc -> cassandra:troubleshooting/use_tools.adoc#packet-capture (path was developing/cql/troubleshooting/use_tools.adoc)
- troubleshooting/use_tools.adoc self-link -> cassandra:troubleshooting/use_tools.adoc#use-bcc-tools (anchor was #bcc-tools which never existed; #use-bcc-tools is the actual anchor at line 333)

 patch by Patrick McFadin; reviewed by TBD for CASSANDRA-21342
---
 .../cql/indexing/sai/operations/configuring.adoc           | 7 ++++---
 .../pages/reference/cql-commands/alter-table.adoc          | 2 +-
 .../reference/cql-commands/compact-subproperties.adoc      | 2 +-
 .../pages/reference/cql-commands/create-table.adoc         | 1 +
 .../cassandra/pages/troubleshooting/reading_logs.adoc      | 2 +-
 doc/modules/cassandra/pages/troubleshooting/use_tools.adoc | 3 ++-
 doc/modules/cassandra/partials/compact-subproperties.adoc  | 2 +-
 7 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/doc/modules/cassandra/pages/developing/cql/indexing/sai/operations/configuring.adoc b/doc/modules/cassandra/pages/developing/cql/indexing/sai/operations/configuring.adoc
index 0acd114746cd..7293c099abcd 100644
--- a/doc/modules/cassandra/pages/developing/cql/indexing/sai/operations/configuring.adoc
+++ b/doc/modules/cassandra/pages/developing/cql/indexing/sai/operations/configuring.adoc
@@ -3,8 +3,9 @@
 
 // LLP: *NOT DONE*
 
-Configuring your {product} environment for Storage-Attached Indexing (SAI) may require some customization of the `cassandra.yaml` file. 
+Configuring your {product} environment for Storage-Attached Indexing (SAI) may require some customization of the `cassandra.yaml` file.
 
+[[saiConfigure__saiCompactionStrategies]]
 == Compaction strategies
 
 Read queries perform better with compaction strategies that produce fewer SSTables.
@@ -20,13 +21,13 @@ While in a time window, TWCS compacts all SSTables flushed from memory into larg
 At the end of the time window, all of these SSTables are compacted into a single SSTable.
 Then the next time window starts and the process repeats.
 The duration of the time window is the only setting required.
-See xref:reference:cql-commands/create-table.adoc#compactSubprop__TWCS[TimeWindowCompactionStrategy].
+See xref:cassandra:reference/cql-commands/compact-subproperties.adoc#TWCS[TimeWindowCompactionStrategy].
 For more information about TWCS, see xref:cassandra:managing/operating/compaction/twcs.adoc[Time Window Compaction Strategy].
 
 In general, do not use `LeveledCompactionStrategy` (LCS) unless your index queries restrict the token range, either directly or by providing a restriction on the partition key.
 However, if you decide to use LCS, use the following guidelines:
 
-* The `160` MB default for the `CREATE TABLE` command's `sstable_size_in_mb` option, described in this xref:reference:cql-commands/create-table.adoc#compactSubprop__LCS[topic], may result in suboptimal performance for index queries that do not restrict on token range or partition key.
+* The `160` MB default for the `CREATE TABLE` command's `sstable_size_in_mb` option, described in this xref:cassandra:reference/cql-commands/compact-subproperties.adoc#LCS[topic], may result in suboptimal performance for index queries that do not restrict on token range or partition key.
 * While even higher values may be appropriate, depending on your hardware, we recommend at least doubling the default value of `sstable_size_in_mb`. 
 
 Example:
diff --git a/doc/modules/cassandra/pages/reference/cql-commands/alter-table.adoc b/doc/modules/cassandra/pages/reference/cql-commands/alter-table.adoc
index 45bfb909586d..f1e55eb1df6b 100644
--- a/doc/modules/cassandra/pages/reference/cql-commands/alter-table.adoc
+++ b/doc/modules/cassandra/pages/reference/cql-commands/alter-table.adoc
@@ -98,7 +98,7 @@ Enclose the value for a string property in single quotation marks.
 +
 Other table properties are set using a JSON map: `+option_name = { <subproperty_name> : <value> [ , ... ] }+`
 +
-See xref:reference:cql-commands/create-table.adoc#table_options[table_options] for more details.
+See xref:cassandra:reference/cql-commands/create-table.adoc#table_options[table_options] for more details.
 
 == Usage notes
 
diff --git a/doc/modules/cassandra/pages/reference/cql-commands/compact-subproperties.adoc b/doc/modules/cassandra/pages/reference/cql-commands/compact-subproperties.adoc
index 3df664bbc172..91763fd0e790 100644
--- a/doc/modules/cassandra/pages/reference/cql-commands/compact-subproperties.adoc
+++ b/doc/modules/cassandra/pages/reference/cql-commands/compact-subproperties.adoc
@@ -235,7 +235,7 @@ Default: `160`
 ==== 
 The default value, 160 MB, may be inefficient and negatively impact database indexing and the queries that rely on indexes.
 For example, consider the benefit of using higher values for sstable_size_in_mb in tables that use (SAI) indexes.
-For related information, see xref:developing:indexing/sai/configuring.adoc#saiConfigure__saiCompactionStrategies[Compaction strategies].
+For related information, see xref:cassandra:developing/cql/indexing/sai/operations/configuring.adoc#saiConfigure__saiCompactionStrategies[Compaction strategies].
 ====
 
 fanout_size::
diff --git a/doc/modules/cassandra/pages/reference/cql-commands/create-table.adoc b/doc/modules/cassandra/pages/reference/cql-commands/create-table.adoc
index 0b428187e7dc..5b21af328c4e 100644
--- a/doc/modules/cassandra/pages/reference/cql-commands/create-table.adoc
+++ b/doc/modules/cassandra/pages/reference/cql-commands/create-table.adoc
@@ -67,6 +67,7 @@ include::cassandra:partial$compress-subproperties.adoc[]
 
 include::cassandra:partial$compact-subproperties.adoc[]
 
+[[table_options]]
 == Optional parameters
 
 // Table Keywords
diff --git a/doc/modules/cassandra/pages/troubleshooting/reading_logs.adoc b/doc/modules/cassandra/pages/troubleshooting/reading_logs.adoc
index 3f2f1a8ddcb4..d1a3a93cd55f 100644
--- a/doc/modules/cassandra/pages/troubleshooting/reading_logs.adoc
+++ b/doc/modules/cassandra/pages/troubleshooting/reading_logs.adoc
@@ -244,4 +244,4 @@ index b2c5b10..71b0a49 100644
 
 Note that if you want more information than this tool provides, there
 are other live capture options available such as
-xref:cassandra:developing/cql/troubleshooting/use_tools.adoc#packet-capture[`packet-capture`].
+xref:cassandra:troubleshooting/use_tools.adoc#packet-capture[`packet-capture`].
diff --git a/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc b/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc
index 4a66f08adb99..5b883cfd3ae6 100644
--- a/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc
+++ b/doc/modules/cassandra/pages/troubleshooting/use_tools.adoc
@@ -208,7 +208,7 @@ when it syncs the commit log. This typically enters into the very high
 percentiles of write latency.
 
 Note that to get detailed latency breakdowns you will need a more
-advanced tool such as xref:use_tools.adoc#bcc-tools[`bcc-tools`].
+advanced tool such as xref:cassandra:troubleshooting/use_tools.adoc#use-bcc-tools[`bcc-tools`].
 
 === OS page Cache Usage
 
@@ -544,6 +544,7 @@ $ cat cassandra_stacks | ./stackcollapse-perf.pl | grep -v cpu_idle | \
 The resulting SVG is searchable, zoomable, and generally easy to
 introspect using a browser.
 
+[[packet-capture]]
 === Packet Capture
 
 Sometimes you have to understand what queries a Cassandra node is
diff --git a/doc/modules/cassandra/partials/compact-subproperties.adoc b/doc/modules/cassandra/partials/compact-subproperties.adoc
index 7bd54c6520f4..1ca766211385 100644
--- a/doc/modules/cassandra/partials/compact-subproperties.adoc
+++ b/doc/modules/cassandra/partials/compact-subproperties.adoc
@@ -228,7 +228,7 @@ Default: `160`
 ====
 The default value, 160 MB, may be inefficient and negatively impact database indexing and the queries that rely on indexes.
 For example, consider the benefit of using higher values for sstable_size_in_mb in tables that use (SAI) indexes.
-For related information, see xref:developing/cql/indexing/sai/configuring.adoc#saiConfigure__saiCompactionStrategies[Compaction strategies].
+For related information, see xref:cassandra:developing/cql/indexing/sai/operations/configuring.adoc#saiConfigure__saiCompactionStrategies[Compaction strategies].
 ====
 
 ==== DateTieredCompactionStrategy (deprecated)