Fix cross references

src/main/antora/modules/ROOT/pages/preface.adoc

@@ -48,7 +48,7 @@ In terms of document stores, you need at least version 3.6 of https://www.mongod
 
 The following compatibility matrix summarizes Spring Data versions to MongoDB driver/database versions.
 Database versions show the highest supported server version that pass the Spring Data test suite.
-You can use newer server versions unless your application uses functionality that is affected by <<compatibility.changes,changes in the MongoDB server>>.
+You can use newer server versions unless your application uses functionality that is affected by xref:preface.adoc#compatibility.changes[changes in the MongoDB server].
 See also the https://www.mongodb.com/docs/drivers/java/sync/current/compatibility/[official MongoDB driver compatibility matrix] for driver- and server version compatibility.
 
 [cols="h,m,m,m", options="header"]

src/main/antora/modules/ROOT/pages/reference/aggregation-framework.adoc

@@ -257,7 +257,7 @@ bucketAuto("price", 5).andOutput("title").push().as("titles");
 ----
 ====
 
-To create output fields in buckets, bucket operations can use `AggregationExpression` through `andOutput()` and <<mongo.aggregation.projection.expressions, SpEL expressions>> through `andOutputExpression()`.
+To create output fields in buckets, bucket operations can use `AggregationExpression` through `andOutput()` and xref:reference/aggregation-framework.adoc#mongo.aggregation.projection.expressions[SpEL expressions] through `andOutputExpression()`.
 
 Note that further details regarding bucket expressions can be found in the https://docs.mongodb.org/manual/reference/operator/aggregation/bucket/[`$bucket` section] and
 https://docs.mongodb.org/manual/reference/operator/aggregation/bucketAuto/[`$bucketAuto` section] of the MongoDB Aggregation Framework reference documentation.
@@ -296,7 +296,7 @@ Note that further details regarding facet operation can be found in the https://
 [[mongo.aggregation.sort-by-count]]
 === Sort By Count
 
-Sort by count operations group incoming documents based on the value of a specified expression, compute the count of documents in each distinct group, and sort the results by count. It offers a handy shortcut to apply sorting when using <<mongo.aggregation.facet>>. Sort by count operations require a grouping field or grouping expression. The following listing shows a sort by count example:
+Sort by count operations group incoming documents based on the value of a specified expression, compute the count of documents in each distinct group, and sort the results by count. It offers a handy shortcut to apply sorting when using xref:reference/aggregation-framework.adoc#mongo.aggregation.facet[Faceted Classification]. Sort by count operations require a grouping field or grouping expression. The following listing shows a sort by count example:
 
 .Sort by count example
 ====
@@ -341,7 +341,7 @@ The preceding expression is translated into the following projection expression
 }]}
 ----
 
-You can see examples in more context in <<mongo.aggregation.examples.example5>> and <<mongo.aggregation.examples.example6>>. You can find more usage examples for supported SpEL expression constructs in `SpelExpressionTransformerUnitTests`. The following table shows the SpEL transformations supported by Spring Data MongoDB:
+You can see examples in more context in xref:reference/aggregation-framework.adoc#mongo.aggregation.examples.example5[Aggregation Framework Example 5] and xref:reference/aggregation-framework.adoc#mongo.aggregation.examples.example6[Aggregation Framework Example 6]. You can find more usage examples for supported SpEL expression constructs in `SpelExpressionTransformerUnitTests`. The following table shows the SpEL transformations supported by Spring Data MongoDB:
 
 .Supported SpEL transformations
 [%header,cols="2"]

src/main/antora/modules/ROOT/pages/reference/client-session-transactions.adoc

@@ -93,7 +93,7 @@ NOTE: Reactive use of `ClientSession` is limited to Template API usage. There's
 [[mongo.transactions]]
 = MongoDB Transactions
 
-As of version 4, MongoDB supports https://www.mongodb.com/transactions[Transactions]. Transactions are built on top of <<mongo.sessions,Sessions>> and, consequently, require an active `ClientSession`.
+As of version 4, MongoDB supports https://www.mongodb.com/transactions[Transactions]. Transactions are built on top of xref:reference/client-session-transactions.adoc[Sessions] and, consequently, require an active `ClientSession`.
 
 NOTE: Unless you specify a `MongoTransactionManager` within your application context, transaction support is *DISABLED*. You can use `setSessionSynchronization(ALWAYS)` to participate in ongoing non-native MongoDB transactions.
 

src/main/antora/modules/ROOT/pages/reference/document-references.adoc

@@ -56,7 +56,7 @@ For those cases please consider falling back to an interface type (eg. switch fr
 = Using Document References
 
 Using `@DocumentReference` offers a flexible way of referencing entities in MongoDB.
-While the goal is the same as when using <<mapping-usage-references,DBRefs>>, the store representation is different.
+While the goal is the same as when using xref:reference/document-references.adoc[DBRefs], the store representation is different.
 `DBRef` resolves to a document with a fixed structure as outlined in the https://docs.mongodb.com/manual/reference/database-references/[MongoDB Reference documentation]. +
 Document references, do not follow a specific format.
 They can be literally anything, a single value, an entire document, basically everything that can be stored in MongoDB.

src/main/antora/modules/ROOT/pages/reference/introduction.adoc

@@ -6,6 +6,6 @@
 
 This part of the reference documentation explains the core functionality offered by Spring Data MongoDB.
 
-"`<<mongo.core>>`" introduces the MongoDB module feature set.
+"`xref:reference/mongodb.adoc[MongoDB support]`" introduces the MongoDB module feature set.
 
-"`<<mongo.repositories>>`" introduces the repository support for MongoDB.
+"`xref:reference/mongo-repositories.adoc[MongoDB Repositories]`" introduces the repository support for MongoDB.

src/main/antora/modules/ROOT/pages/reference/kotlin.adoc

@@ -23,7 +23,7 @@ As in Java, `characters` in Kotlin is strongly typed, but Kotlin's clever type i
 Spring Data MongoDB provides the following extensions:
 
 * Reified generics support for `MongoOperations`, `ReactiveMongoOperations`, `FluentMongoOperations`, `ReactiveFluentMongoOperations`, and `Criteria`.
-* <<mongo.query.kotlin-support>>
+* xref:reference/mongodb/mongo-query/kotlin-support.adoc[Type-safe Queries for Kotlin]
 * <<kotlin.coroutines>> extensions for `ReactiveFluentMongoOperations`.
 
 include::../{spring-data-commons-docs}/kotlin-coroutines.adoc[leveloffset=+1]

src/main/antora/modules/ROOT/pages/reference/mapping.adoc

@@ -69,7 +69,7 @@ When querying and updating `MongoTemplate` will use the converter to handle conv
 == Data Mapping and Type Conversion
 
 This section explains how types are mapped to and from a MongoDB representation. Spring Data MongoDB supports all types that can be represented as BSON, MongoDB's internal document format.
-In addition to these types, Spring Data MongoDB provides a set of built-in converters to map additional types. You can provide your own converters to adjust type conversion. See <<mongo.custom-converters>> for further details.
+In addition to these types, Spring Data MongoDB provides a set of built-in converters to map additional types. You can provide your own converters to adjust type conversion. See xref:reference/mongo-custom-conversions.adoc[Custom Conversions - Overriding Default Mapping] for further details.
 
 The following provides samples of each available type conversion:
 
@@ -193,12 +193,12 @@ calling `get()` before the actual conversion
 
 | `LocalDate` +
 (Joda, Java 8, JSR310-BackPort)
-| converter / native (Java8)footnote:[Uses UTC zone offset. Configure via <<mapping-configuration,MongoConverterConfigurationAdapter>>]
+| converter / native (Java8)footnote:[Uses UTC zone offset. Configure via xref:reference/mapping.adoc#mapping-configuration[MongoConverterConfigurationAdapter]]
 | `{"date" : ISODate("2019-11-12T00:00:00.000Z")}`
 
 | `LocalDateTime`, `LocalTime` +
 (Joda, Java 8, JSR310-BackPort)
-| converter / native (Java8)footnote:[Uses UTC zone offset. Configure via <<mapping-configuration,MongoConverterConfigurationAdapter>>]
+| converter / native (Java8)footnote:[Uses UTC zone offset. Configure via xref:reference/mapping.adoc#mapping-configuration[MongoConverterConfigurationAdapter]]
 | `{"date" : ISODate("2019-11-12T23:00:00.809Z")}`
 
 | `DateTime` (Joda)
@@ -403,7 +403,7 @@ public class Person {
 IMPORTANT: The `@Id` annotation tells the mapper which property you want to use for the MongoDB `_id` property, and the `@Indexed` annotation tells the mapping framework to call `createIndex(…)` on that property of your document, making searches faster.
 Automatic index creation is only done for types annotated with `@Document`.
 
-WARNING: Auto index creation is **disabled** by default and needs to be enabled through the configuration (see <<mapping.index-creation>>).
+WARNING: Auto index creation is **disabled** by default and needs to be enabled through the configuration (see xref:reference/mapping.adoc#mapping.index-creation[Index Creation]).
 
 [[mapping.index-creation]]
 === Index Creation
@@ -904,7 +904,7 @@ class Nested {
 [[mapping-usage-events]]
 === Mapping Framework Events
 
-Events are fired throughout the lifecycle of the mapping process. This is described in the <<mongodb.mapping-usage.events,Lifecycle Events>> section.
+Events are fired throughout the lifecycle of the mapping process. This is described in the xref:reference/mongodb/mapping-usage-events.adoc[Lifecycle Events] section.
 
 Declaring these beans in your Spring ApplicationContext causes them to be invoked whenever the event is dispatched.
 

src/main/antora/modules/ROOT/pages/reference/mongo-custom-conversions.adoc

@@ -28,7 +28,7 @@ public class Payment {
   "date"   : ISODate("2019-04-03T12:11:01.870Z") <3>
 }
 ----
-<1> String _id_ values that represent a valid `ObjectId` are converted automatically. See <<mongo-template.id-handling>>
+<1> String _id_ values that represent a valid `ObjectId` are converted automatically. See xref:reference/mongodb/mongo-template-save-update-remove.adoc#mongo-template.id-handling[How the `_id` Field is Handled in the Mapping Layer]
 for details.
 <2> The desired target type is explicitly defined as `Decimal128` which translates to `NumberDecimal`. Otherwise the
 `BigDecimal` value would have been truned into a `String`.

src/main/antora/modules/ROOT/pages/reference/mongo-encryption.adoc

@@ -15,9 +15,9 @@ Specific data types require deterministic encryption to preserve equality compar
 == Automatic Encryption
 
 MongoDB supports https://www.mongodb.com/docs/manual/core/csfle/[Client-Side Field Level Encryption] out of the box using the MongoDB driver with its Automatic Encryption feature.
-Automatic Encryption requires a <<mongo.jsonSchema,JSON Schema>> that allows to perform encrypted read and write operations without the need to provide an explicit en-/decryption step.
+Automatic Encryption requires a xref:reference/mongo-json-schema.adoc[JSON Schema] that allows to perform encrypted read and write operations without the need to provide an explicit en-/decryption step.
 
-Please refer to the <<mongo.jsonSchema.encrypted-fields,JSON Schema>> section for more information on defining a JSON Schema that holds encryption information.
+Please refer to the xref:reference/mongo-json-schema.adoc#mongo.jsonSchema.encrypted-fields[JSON Schema] section for more information on defining a JSON Schema that holds encryption information.
 
 To make use of a the `MongoJsonSchema` it needs to be combined with `AutoEncryptionSettings` which can be done eg. via a `MongoClientSettingsBuilderCustomizer`.
 
@@ -50,7 +50,7 @@ MongoClientSettingsBuilderCustomizer customizer(MappingContext mappingContext) {
 == Explicit Encryption
 
 Explicit encryption uses the MongoDB driver's encryption library (`org.mongodb:mongodb-crypt`) to perform encryption and decryption tasks.
-The `@ExplicitEncrypted` annotation is a combination of the `@Encrypted` annotation used for <<mongo.jsonSchema.encrypted-fields,JSON Schema creation>> and a <<mongo.property-converters, Property Converter>>.
+The `@ExplicitEncrypted` annotation is a combination of the `@Encrypted` annotation used for xref:reference/mongo-json-schema.adoc#mongo.jsonSchema.encrypted-fields[JSON Schema creation] and a xref:reference/mongo-property-converters.adoc[Property Converter].
 In other words, `@ExplicitEncrypted` uses existing building blocks to combine them for simplified explicit encryption support.
 
 [NOTE]
@@ -112,7 +112,7 @@ Fields cannot be used in queries/aggregations.
 
 By default, the `@ExplicitEncrypted(value=…)` attribute references a `MongoEncryptionConverter`.
 It is possible to change the default implementation and exchange it with any `PropertyValueConverter` implementation by providing the according type reference.
-To learn more about custom `PropertyValueConverters` and the required configuration, please refer to the <<mongo.property-converters>> section.
+To learn more about custom `PropertyValueConverters` and the required configuration, please refer to the xref:reference/mongo-property-converters.adoc[Property Converters - Mapping specific fields] section.
 
 [[mongo.encryption.explicit-setup]]
 === MongoEncryptionConverter Setup

src/main/antora/modules/ROOT/pages/reference/mongo-json-schema.adoc

@@ -58,7 +58,7 @@ MongoJsonSchema.builder()                                                    <1>
 <1> Obtain a schema builder to configure the schema with a fluent API.
 <2> Configure required properties either directly as shown here or with more details as in 3.
 <3> Configure the required String-typed `firstname` field, allowing only `luke` and `han` values. Properties can be typed or untyped. Use a static import of  `JsonSchemaProperty` to make the syntax slightly more compact and to get entry points such as `string(…)`.
-<4> Build the schema object. Use the schema to create either a collection or <<mongodb-template-query.criteria,query documents>>.
+<4> Build the schema object. Use the schema to create either a collection or xref:reference/mongodb/mongo-query/template.adoc#mongodb-template-query.criteria[query documents].
 ====
 
 There are already some predefined and strongly typed schema objects (`JsonSchemaObject` and `JsonSchemaProperty`) available
@@ -94,7 +94,7 @@ It's important, schema changes can be hard.
 However, there might be times when one does not want to balked with it, and that is where `JsonSchemaCreator` comes into play.
 
 `JsonSchemaCreator` and its default implementation generates a `MongoJsonSchema` out of domain types metadata provided by the mapping infrastructure.
-This means, that <<mapping-usage-annotations, annotated properties>> as well as potential <<mapping-configuration, custom conversions>> are considered.
+This means, that xref:reference/mapping.adoc#mapping-usage-annotations[annotated properties] as well as potential xref:reference/mapping.adoc#mapping-configuration[custom conversions] are considered.
 
 .Generate Json Schema from domain type
 ====

src/main/antora/modules/ROOT/pages/reference/mongo-property-converters.adoc

@@ -1,7 +1,7 @@
 [[mongo.property-converters]]
 = Property Converters - Mapping specific fields
 
-While <<mongo.custom-converters, type-based conversion>> already offers ways to influence the conversion and representation of certain types within the target store, it has limitations when only certain values or properties of a particular type should be considered for conversion.
+While xref:reference/mongo-custom-conversions.adoc[type-based conversion] already offers ways to influence the conversion and representation of certain types within the target store, it has limitations when only certain values or properties of a particular type should be considered for conversion.
 Property-based converters allow configuring conversion rules on a per-property basis, either declaratively (via `@ValueConverter`) or programmatically (by registering a `PropertyValueConverter` for a specific property).
 
 A `PropertyValueConverter` can transform a given value into its store representation (write) and back (read) as the following listing shows.

src/main/antora/modules/ROOT/pages/reference/mongo-repositories-aggregation.adoc

@@ -1,8 +1,8 @@
 [[mongodb.repositories.queries.aggregation]]
 = Aggregation Repository Methods
 
-The repository layer offers means to interact with <<mongo.aggregation, the aggregation framework>> via annotated repository query methods.
-Similar to the <<mongodb.repositories.queries.json-based, JSON based queries>>, you can define a pipeline using the `org.springframework.data.mongodb.repository.Aggregation` annotation.
+The repository layer offers means to interact with xref:reference/aggregation-framework.adoc[the aggregation framework] via annotated repository query methods.
+Similar to the xref:reference/mongo-repositories.adoc#mongodb.repositories.queries.json-based[JSON based queries], you can define a pipeline using the `org.springframework.data.mongodb.repository.Aggregation` annotation.
 The definition may contain simple placeholders like `?0` as well as link:{springDocsUrl}/core.html#expressions[SpEL expressions] `?#{ … }`.
 
 .Aggregating Repository Method
@@ -114,7 +114,7 @@ interface PersonRepository extends CrudRepository<Person, String> {
 }
 ----
 
-TIP: You can use `@Aggregation` also with <<mongo.reactive.repositories, Reactive Repositories>>.
+TIP: You can use `@Aggregation` also with xref:reference/reactive-mongo-repositories.adoc[Reactive Repositories].
 
 [NOTE]
 ====

src/main/antora/modules/ROOT/pages/reference/mongo-repositories.adoc

@@ -31,7 +31,7 @@ public class Person {
 
 Note that the domain type shown in the preceding example has a property named `id` of type `String`.The default serialization mechanism used in `MongoTemplate` (which backs the repository support) regards properties named `id` as the document ID.
 Currently, we support `String`, `ObjectId`, and `BigInteger` as ID types.
-Please see <<mongo-template.id-handling, ID mapping>> for more information about on how the `id` field is handled in the mapping layer.
+Please see xref:reference/mongodb/mongo-template-save-update-remove.adoc#mongo-template.id-handling[ID mapping] for more information about on how the `id` field is handled in the mapping layer.
 
 Now that we have a domain object, we can define an interface that uses it, as follows:
 
@@ -359,9 +359,9 @@ public interface PersonRepository extends CrudRepository<Person, String> {
 The update is "`as is`" and does not bind any parameters.
 <2> The actual increment value is defined by the `increment` method argument that is bound to the `?1` placeholder.
 <3> Use the Spring Expression Language (SpEL) for parameter binding.
-<4> Use the `pipeline` attribute to issue <<mongo-template.aggregation-update,aggregation pipeline updates>>.
+<4> Use the `pipeline` attribute to issue xref:reference/mongodb/mongo-template-save-update-remove.adoc#mongo-template.aggregation-update[aggregation pipeline updates].
 <5> The update may contain complex objects.
-<6> Combine a <<mongodb.repositories.queries.json-based,string based query>> with an update.
+<6> Combine a xref:reference/mongo-repositories.adoc#mongodb.repositories.queries.json-based[string based query] with an update.
 ====
 
 WARNING: Repository updates do not emit persistence nor mapping lifecycle events.
@@ -655,7 +655,7 @@ public interface PersonRepository extends MongoRepository<Person, String>, Query
 === Full-text Search Queries
 
 MongoDB's full-text search feature is store-specific and, therefore, can be found on `MongoRepository` rather than on the more general `CrudRepository`.
-We need a document with a full-text index (see "`<<mapping-usage-indexes.text-index>>`" to learn how to create a full-text index).
+We need a document with a full-text index (see "`xref:reference/mapping.adoc#mapping-usage-indexes.text-index[Text Indexes]`" to learn how to create a full-text index).
 
 Additional methods on `MongoRepository` take `TextCriteria` as an input parameter.
 In addition to those explicit methods, it is also possible to add a `TextCriteria`-derived repository method.

src/main/antora/modules/ROOT/pages/reference/mongodb/connectors.adoc

@@ -152,7 +152,7 @@ public class MongoApp {
 }
 ----
 
-The code in bold highlights the use of `SimpleMongoClientDbFactory` and is the only difference between the listing shown in the <<mongodb-getting-started,getting started section>>.
+The code in bold highlights the use of `SimpleMongoClientDbFactory` and is the only difference between the listing shown in the xref:reference/mongodb/getting-started.adoc[getting started section].
 
 NOTE: Use `SimpleMongoClientDbFactory` when choosing `com.mongodb.client.MongoClient` as the entrypoint of choice.
 

src/main/antora/modules/ROOT/pages/reference/mongodb/getting-started.adoc

@@ -132,8 +132,8 @@ When you run the main program, the preceding examples produce the following outp
 
 Even in this simple example, there are few things to notice:
 
-* You can instantiate the central helper class of Spring Mongo, <<mongo-template,`MongoTemplate`>>, by using the standard `com.mongodb.client.MongoClient` object and the name of the database to use.
-* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See <<mapping-chapter,here>>.).
+* You can instantiate the central helper class of Spring Mongo, xref:reference/mongodb/mongo-template.adoc[`MongoTemplate`], by using the standard `com.mongodb.client.MongoClient` object and the name of the database to use.
+* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See xref:reference/mapping.adoc[here].).
 * Conventions are used for handling the `id` field, converting it to be an `ObjectId` when stored in the database.
 * Mapping conventions can use field access. Notice that the `Person` class has only getters.
 * If the constructor argument names match the field names of the stored document, they are used to instantiate the object

src/main/antora/modules/ROOT/pages/reference/mongodb/mongo-query-count.adoc

@@ -2,7 +2,7 @@
 = Counting Documents
 
 In pre-3.x versions of SpringData MongoDB the count operation used MongoDBs internal collection statistics.
-With the introduction of <<mongo.transactions>> this was no longer possible because statistics would not correctly reflect potential changes during a transaction requiring an aggregation-based count approach.
+With the introduction of xref:reference/client-session-transactions.adoc#mongo.transactions[MongoDB Transactions] this was no longer possible because statistics would not correctly reflect potential changes during a transaction requiring an aggregation-based count approach.
 So in version 2.x `MongoOperations.count()` would use the collection statistics if no transaction was in progress, and the aggregation variant if so.
 
 As of Spring Data MongoDB 3.x any `count` operation uses regardless the existence of filter criteria the aggregation-based count approach via MongoDBs `countDocuments`.
@@ -10,7 +10,7 @@ If the application is fine with the limitations of working upon collection stati
 
 [TIP]
 ====
-By setting `MongoTemplate#useEstimatedCount(...)` to `true` _MongoTemplate#count(...)_ operations, that use an empty filter query, will be delegated to `estimatedCount`, as long as there is no transaction active and the template is not bound to a <<mongo.sessions,session>>.
+By setting `MongoTemplate#useEstimatedCount(...)` to `true` _MongoTemplate#count(...)_ operations, that use an empty filter query, will be delegated to `estimatedCount`, as long as there is no transaction active and the template is not bound to a xref:reference/client-session-transactions.adoc[session].
 It will still be possible to obtain exact numbers via `MongoTemplate#exactCount`, but may speed up things.
 ====
 

src/main/antora/modules/ROOT/pages/reference/mongodb/mongo-query.adoc

@@ -12,5 +12,5 @@ List<Person> result = mongoTemplate.find(query, Person.class);
 ----
 ====
 
-Spring MongoDB also supports GeoSpatial queries (see the <<mongo.geospatial,GeoSpatial Queries>> section) and Map-Reduce operations (see the <<mongo.mapreduce,Map-Reduce>> section.).
+Spring MongoDB also supports GeoSpatial queries (see the xref:reference/mongodb/mongo-query/geospatial.adoc[GeoSpatial Queries] section) and Map-Reduce operations (see the xref:reference/mongodb/mongo-mapreduce.adoc[Map-Reduce] section.).
 

src/main/antora/modules/ROOT/pages/reference/mongodb/mongo-query/collation.adoc

@@ -84,7 +84,7 @@ AggregationResults<TagCount> results = template.aggregate(aggregation, "tags", T
 
 WARNING: Indexes are only used if the collation used for the operation matches the index collation.
 
-<<mongo.repositories>> support `Collations` via the `collation` attribute of the `@Query` annotation.
+xref:reference/mongo-repositories.adoc[MongoDB Repositories] support `Collations` via the `collation` attribute of the `@Query` annotation.
 
 .Collation support for Repositories
 ====

src/main/antora/modules/ROOT/pages/reference/mongodb/mongo-query/fluent-template-api.adoc

@@ -38,7 +38,7 @@ NOTE: Using projections allows `MongoTemplate` to optimize result mapping by lim
 by the projection target type. This applies as long as the `Query` itself does not contain any field restriction and the
 target type is a closed interface or DTO projection.
 
-WARNING: Projections must not be applied to <<mapping-usage-references,DBRefs>>.
+WARNING: Projections must not be applied to xref:reference/document-references.adoc[DBRefs].
 
 You can switch between retrieving a single entity and retrieving multiple entities as a `List` or a `Stream` through the terminating methods: `first()`, `one()`, `all()`, or `stream()`.
 

src/main/antora/modules/ROOT/pages/reference/mongodb/mongo-query/geospatial.adoc

@@ -3,7 +3,7 @@
 
 MongoDB supports GeoSpatial queries through the use of operators such as `$near`, `$within`, `geoWithin`, and `$nearSphere`. Methods specific to geospatial queries are available on the `Criteria` class. There are also a few shape classes (`Box`, `Circle`, and `Point`) that are used in conjunction with geospatial related `Criteria` methods.
 
-NOTE: Using GeoSpatial queries requires attention when used within MongoDB transactions, see <<mongo.transactions.behavior>>.
+NOTE: Using GeoSpatial queries requires attention when used within MongoDB transactions, see xref:reference/client-session-transactions.adoc#mongo.transactions.behavior[Special behavior inside transactions].
 
 To understand how to perform GeoSpatial queries, consider the following `Venue` class (taken from the integration tests and relying on the rich `MappingMongoConverter`):
 

src/main/antora/modules/ROOT/pages/reference/mongodb/mongo-query/template.adoc

@@ -52,11 +52,11 @@ The `Criteria` class provides the following methods, all of which correspond to
 * `Criteria` *sampleRate* `(double sampleRate)` Creates a criterion using the `$sampleRate` operator
 * `Criteria` *size* `(int s)` Creates a criterion using the `$size` operator
 * `Criteria` *type* `(int t)` Creates a criterion using the `$type` operator
-* `Criteria` *matchingDocumentStructure* `(MongoJsonSchema schema)` Creates a criterion using the `$jsonSchema` operator for <<mongo.jsonSchema,JSON schema criteria>>. `$jsonSchema` can only be applied on the top level of a query and not property specific. Use the `properties` attribute of the schema to match against nested fields.
+* `Criteria` *matchingDocumentStructure* `(MongoJsonSchema schema)` Creates a criterion using the `$jsonSchema` operator for xref:reference/mongo-json-schema.adoc[JSON schema criteria]. `$jsonSchema` can only be applied on the top level of a query and not property specific. Use the `properties` attribute of the schema to match against nested fields.
 * `Criteria` *bits()* is the gateway to https://docs.mongodb.com/manual/reference/operator/query-bitwise/[MongoDB bitwise query operators] like `$bitsAllClear`.
 
 
-The Criteria class also provides the following methods for geospatial queries (see the <<mongo.geospatial,GeoSpatial Queries>> section to see them in action):
+The Criteria class also provides the following methods for geospatial queries (see the xref:reference/mongodb/mongo-query/geospatial.adoc[GeoSpatial Queries] section to see them in action):
 
 * `Criteria` *within* `(Circle circle)` Creates a geospatial criterion using `$geoWithin $center` operators.
 * `Criteria` *within* `(Box box)` Creates a geospatial criterion using a `$geoWithin $box` operation.
@@ -140,5 +140,5 @@ query.fields()
 <4> Use SpEL along with an `AggregationExpression` to invoke expression functions. Field names are mapped to the ones used in the domain model.
 ====
 
-`@Query(fields="…")` allows usage of expression field projections at `Repository` level as described in <<mongodb.repositories.queries.json-based>>.
+`@Query(fields="…")` allows usage of expression field projections at `Repository` level as described in xref:reference/mongo-repositories.adoc#mongodb.repositories.queries.json-based[MongoDB JSON-based Query Methods and Field Restriction].
 

src/main/antora/modules/ROOT/pages/reference/mongodb/mongo-query/textsearch.adoc

@@ -6,7 +6,7 @@ Since version 2.6 of MongoDB, you can run full-text queries by using the `$text`
 [[full-text-search]]
 == Full-text Search
 
-Before you can actually use full-text search, you must set up the search index correctly. See <<mapping-usage-indexes.text-index,Text Index>> for more detail on how to create index structures. The following example shows how to set up a full-text search:
+Before you can actually use full-text search, you must set up the search index correctly. See xref:reference/mapping.adoc#mapping-usage-indexes.text-index[Text Index] for more detail on how to create index structures. The following example shows how to set up a full-text search:
 
 [source,javascript]
 ----

src/main/antora/modules/ROOT/pages/reference/mongodb/mongo-template-index-and-collections.adoc

@@ -40,7 +40,7 @@ You can create standard, geospatial, and text indexes by using the `IndexDefinit
 mongoTemplate.indexOps(Venue.class).ensureIndex(new GeospatialIndex("location"));
 ----
 
-NOTE: `Index` and `GeospatialIndex` support configuration of <<mongo.collation,collations>>.
+NOTE: `Index` and `GeospatialIndex` support configuration of xref:reference/mongodb/mongo-query/collation.adoc[collations].
 
 [[mongo-template.index-and-collections.access]]
 == Accessing Index Information
@@ -82,5 +82,5 @@ mongoTemplate.dropCollection("MyNewCollection");
 * *dropCollection*: Drops the collection.
 * *getCollection*: Gets a collection by name, creating it if it does not exist.
 
-NOTE: Collection creation allows customization with `CollectionOptions` and supports <<mongo.collation,collations>>.
+NOTE: Collection creation allows customization with `CollectionOptions` and supports xref:reference/mongodb/mongo-query/collation.adoc[collations].
 

src/main/antora/modules/ROOT/pages/reference/mongodb/mongo-template-save-update-remove.adoc

@@ -115,7 +115,7 @@ DEBUG work.data.mongodb.core.MongoTemplate: 376 - Dropped collection [database.p
 
 NOTE: The preceding example is meant to show the use of save, update, and remove operations on `MongoTemplate` and not to show complex mapping functionality.
 
-The query syntax used in the preceding example is explained in more detail in the section "`<<mongo.query>>`".
+The query syntax used in the preceding example is explained in more detail in the section "`xref:reference/mongodb/mongo-query.adoc[Querying Documents]`".
 
 [[mongo-template.id-handling]]
 == How the `_id` Field is Handled in the Mapping Layer
@@ -373,7 +373,7 @@ Most methods return the `Update` object to provide a fluent style for the API.
 * *updateFirst*: Updates the first document that matches the query document criteria with the updated document.
 * *updateMulti*: Updates all objects that match the query document criteria with the updated document.
 
-WARNING: `updateFirst` does not support ordering. Please use <<mongo-template.find-and-upsert, findAndModify>> to apply `Sort`.
+WARNING: `updateFirst` does not support ordering. Please use xref:reference/mongodb/mongo-template-save-update-remove.adoc#mongo-template.find-and-upsert[findAndModify] to apply `Sort`.
 NOTE: Index hints for the update operation can be provided via `Query.withHint(...)`.
 
 [[mongodb-template-update.update]]
@@ -430,7 +430,7 @@ template.update(Person.class)
   .upsert();
 ----
 
-WARNING: `upsert` does not support ordering. Please use <<mongo-template.find-and-upsert, findAndModify>> to apply `Sort`.
+WARNING: `upsert` does not support ordering. Please use xref:reference/mongodb/mongo-template-save-update-remove.adoc#mongo-template.find-and-upsert[findAndModify] to apply `Sort`.
 
 [[mongo-template.find-and-upsert]]
 == Finding and Upserting Documents in a Collection
@@ -499,7 +499,7 @@ assertThat(upserted.getAge()).isOne();
 [[mongo-template.aggregation-update]]
 == Aggregation Pipeline Updates
 
-Update methods exposed by `MongoOperations` and `ReactiveMongoOperations` also accept an <<mongo.aggregation, Aggregation Pipeline>> via `AggregationUpdate`.
+Update methods exposed by `MongoOperations` and `ReactiveMongoOperations` also accept an xref:reference/aggregation-framework.adoc[Aggregation Pipeline] via `AggregationUpdate`.
 Using `AggregationUpdate` allows leveraging https://docs.mongodb.com/manual/reference/method/db.collection.update/#update-with-aggregation-pipeline[MongoDB 4.2 aggregations] in an update operation.
 Using aggregations in an update allows updating one or more fields by expressing multiple stages and multiple conditions with a single operation.
 

src/main/antora/modules/ROOT/pages/reference/mongodb/mongo-template.adoc

@@ -5,17 +5,17 @@ The `MongoTemplate` class, located in the `org.springframework.data.mongodb.core
 
 NOTE: Once configured, `MongoTemplate` is thread-safe and can be reused across multiple instances.
 
-The mapping between MongoDB documents and domain classes is done by delegating to an implementation of the `MongoConverter` interface. Spring provides `MappingMongoConverter`, but you can also write your own converter. See "`<<mongo.custom-converters>>`" for more detailed information.
+The mapping between MongoDB documents and domain classes is done by delegating to an implementation of the `MongoConverter` interface. Spring provides `MappingMongoConverter`, but you can also write your own converter. See "`xref:reference/mongo-custom-conversions.adoc[Custom Conversions - Overriding Default Mapping]`" for more detailed information.
 
 The `MongoTemplate` class implements the interface `MongoOperations`. In as much as possible, the methods on `MongoOperations` are named after methods available on the MongoDB driver `Collection` object, to make the API familiar to existing MongoDB developers who are used to the driver API. For example, you can find methods such as `find`, `findAndModify`, `findAndReplace`, `findOne`, `insert`, `remove`, `save`, `update`, and `updateMulti`. The design goal was to make it as easy as possible to transition between the use of the base MongoDB driver and `MongoOperations`. A major difference between the two APIs is that `MongoOperations` can be passed domain objects instead of `Document`. Also, `MongoOperations` has fluent APIs for `Query`, `Criteria`, and `Update` operations instead of populating a `Document` to specify the parameters for those operations.
 
 NOTE: The preferred way to reference the operations on `MongoTemplate` instance is through its interface, `MongoOperations`.
 
-The default converter implementation used by `MongoTemplate` is `MappingMongoConverter`. While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names. These conventions, as well as the use of mapping annotations, are explained in the "`<<mapping-chapter>>`" chapter.
+The default converter implementation used by `MongoTemplate` is `MappingMongoConverter`. While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names. These conventions, as well as the use of mapping annotations, are explained in the "`xref:reference/mapping.adoc[Mapping]`" chapter.
 
-Another central feature of `MongoTemplate` is translation of exceptions thrown by the MongoDB Java driver into Spring's portable Data Access Exception hierarchy. See "`<<mongo.exception>>`" for more information.
+Another central feature of `MongoTemplate` is translation of exceptions thrown by the MongoDB Java driver into Spring's portable Data Access Exception hierarchy. See "`xref:reference/mongodb/mongo-exception.adoc[Exception Translation]`" for more information.
 
-`MongoTemplate` offers many convenience methods to help you easily perform common tasks. However, if you need to directly access the MongoDB driver API, you can use one of several `Execute` callback methods. The `execute` callbacks gives you a reference to either a `com.mongodb.client.MongoCollection` or a `com.mongodb.client.MongoDatabase` object. See the <<mongo.executioncallback,"`Execution Callbacks`">> section for more information.
+`MongoTemplate` offers many convenience methods to help you easily perform common tasks. However, if you need to directly access the MongoDB driver API, you can use one of several `Execute` callback methods. The `execute` callbacks gives you a reference to either a `com.mongodb.client.MongoCollection` or a `com.mongodb.client.MongoDatabase` object. See the xref:reference/mongodb/mongo-executioncallback.adoc["`Execution Callbacks`"] section for more information.
 
 The next section contains an example of how to work with the `MongoTemplate` in the context of the Spring container.
 

src/main/antora/modules/ROOT/pages/reference/query-by-example.adoc

@@ -100,7 +100,7 @@ List<Person> result = template.find(query, Person.class);
 
 [NOTE]
 ====
-`UntypedExampleMatcher` is likely the right choice for you if you are storing different entities within a single collection or opted out of writing <<mongo-template.type-mapping,type hints>>.
+`UntypedExampleMatcher` is likely the right choice for you if you are storing different entities within a single collection or opted out of writing xref:reference/mongodb/mongo-template-save-update-remove.adoc#mongo-template.type-mapping[type hints].
 
 Also, keep in mind that using `@TypeAlias` requires eager initialization of the `MappingContext`. To do so, configure `initialEntitySet` to to ensure proper alias resolution for read operations.
 ====

src/main/antora/modules/ROOT/pages/reference/reactive-mongo-repositories.adoc

@@ -44,7 +44,7 @@ public class Person {
 ====
 
 Note that the entity defined in the preceding example has a property named `id` of type `String`. The default serialization mechanism used in `MongoTemplate` (which backs the repository support) regards properties named `id` as the document ID. Currently, we support `String`, `ObjectId`, and `BigInteger` as id-types.
-Please see <<mongo-template.id-handling, ID mapping>> for more information about on how the `id` field is handled in the mapping layer.
+Please see xref:reference/mongodb/mongo-template-save-update-remove.adoc#mongo-template.id-handling[ID mapping] for more information about on how the `id` field is handled in the mapping layer.
 
 The following example shows how to create an interface that defines queries against the `Person` object from the preceding example:
 
@@ -141,22 +141,22 @@ Flux<Person> persons = repository.findByFirstnameOrderByLastname("luke", page);
 [[mongo.reactive.repositories.features]]
 == Features
 
-Spring Data's Reactive MongoDB support comes with a reduced feature set compared to the blocking <<mongo.repositories,MongoDB Repositories>>.
+Spring Data's Reactive MongoDB support comes with a reduced feature set compared to the blocking xref:reference/mongo-repositories.adoc[MongoDB Repositories].
 
 It supports the following features:
 
-* Query Methods using <<mongodb.repositories.queries,String queries and Query Derivation>>
-* <<mongodb.reactive.repositories.queries.geo-spatial>>
-* <<mongodb.repositories.queries.delete>>
-* <<mongodb.repositories.queries.json-based>>
-* <<mongodb.repositories.queries.full-text>>
-* <<mongodb.reactive.repositories.queries.type-safe>>
+* Query Methods using xref:reference/mongo-repositories.adoc#mongodb.repositories.queries[String queries and Query Derivation]
+* xref:reference/reactive-mongo-repositories.adoc#mongodb.reactive.repositories.queries.geo-spatial[Geo-spatial Repository Queries]
+* xref:reference/mongo-repositories.adoc#mongodb.repositories.queries.delete[Repository Delete Queries]
+* xref:reference/mongo-repositories.adoc#mongodb.repositories.queries.json-based[MongoDB JSON-based Query Methods and Field Restriction]
+* xref:reference/mongo-repositories.adoc#mongodb.repositories.queries.full-text[Full-text Search Queries]
+* xref:reference/reactive-mongo-repositories.adoc#mongodb.reactive.repositories.queries.type-safe[Type-safe Query Methods]
 * <<projections>>
 
 [[mongodb.reactive.repositories.queries.geo-spatial]]
 === Geo-spatial Repository Queries
 
-As you saw earlier in "`<<mongodb.reactive.repositories.queries.geo-spatial>>`", a few keywords trigger geo-spatial operations within a MongoDB query. The `Near` keyword allows some further modification, as the next few examples show.
+As you saw earlier in "`xref:reference/reactive-mongo-repositories.adoc#mongodb.reactive.repositories.queries.geo-spatial[Geo-spatial Repository Queries]`", a few keywords trigger geo-spatial operations within a MongoDB query. The `Near` keyword allows some further modification, as the next few examples show.
 
 The following example shows how to define a `near` query that finds all persons with a given distance of a given point:
 

src/main/antora/modules/ROOT/pages/reference/reactive-mongodb.adoc

@@ -127,8 +127,8 @@ Running the preceding class produces the following output:
 
 Even in this simple example, there are a few things to take notice of:
 
-* You can instantiate the central helper class of Spring Mongo (<<mongo.reactive.template,`ReactiveMongoTemplate`>>) by using the standard `com.mongodb.reactivestreams.client.MongoClient` object and the name of the database to use.
-* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See <<mapping-chapter,here>>.).
+* You can instantiate the central helper class of Spring Mongo (xref:reference/reactive-mongodb.adoc#mongo.reactive.template[`ReactiveMongoTemplate`]) by using the standard `com.mongodb.reactivestreams.client.MongoClient` object and the name of the database to use.
+* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See xref:reference/mapping.adoc[here].).
 * Conventions are used for handling the ID field, converting it to be an `ObjectId` when stored in the database.
 * Mapping conventions can use field access. Notice that the `Person` class has only getters.
 * If the constructor argument names match the field names of the stored document, they are used to instantiate the object
@@ -250,7 +250,7 @@ public class MongoApp {
 }
 ----
 
-The use of `SimpleReactiveMongoDatabaseFactory` is the only difference between the listing shown in the <<mongodb-reactive-getting-started,getting started section>>.
+The use of `SimpleReactiveMongoDatabaseFactory` is the only difference between the listing shown in the xref:reference/reactive-mongodb.adoc#mongodb-reactive-getting-started[getting started section].
 
 [[mongo.reactive.mongo-db-factory-java]]
 === Registering a ReactiveMongoDatabaseFactory Instance by Using Java-based Metadata
@@ -292,17 +292,17 @@ The `ReactiveMongoTemplate` class, located in the `org.springframework.data.mong
 
 NOTE: Once configured, `ReactiveMongoTemplate` is thread-safe and can be reused across multiple instances.
 
-The mapping between MongoDB documents and domain classes is done by delegating to an implementation of the `MongoConverter` interface. Spring provides a default implementation with `MongoMappingConverter`, but you can also write your own converter. See the <<mongo.custom-converters,section on `MongoConverter` instances>> for more detailed information.
+The mapping between MongoDB documents and domain classes is done by delegating to an implementation of the `MongoConverter` interface. Spring provides a default implementation with `MongoMappingConverter`, but you can also write your own converter. See the xref:reference/mongo-custom-conversions.adoc[section on `MongoConverter` instances] for more detailed information.
 
 The `ReactiveMongoTemplate` class implements the `ReactiveMongoOperations` interface. As much as possible, the methods on `ReactiveMongoOperations` mirror methods available on the MongoDB driver `Collection` object, to make the API familiar to existing MongoDB developers who are used to the driver API. For example, you can find methods such as `find`, `findAndModify`, `findOne`, `insert`, `remove`, `save`, `update`, and `updateMulti`. The design goal is to make it as easy as possible to transition between the use of the base MongoDB driver and `ReactiveMongoOperations`. A major difference between the two APIs is that `ReactiveMongoOperations` can be passed domain objects instead of `Document`, and there are fluent APIs for `Query`, `Criteria`, and `Update` operations instead of populating a `Document` to specify the parameters for those operations.
 
 NOTE: The preferred way to reference the operations on `ReactiveMongoTemplate` instance is through its `ReactiveMongoOperations` interface.
 
-The default converter implementation used by `ReactiveMongoTemplate` is `MappingMongoConverter`. While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names. These conventions as well as the use of mapping annotations are explained in the <<mapping-chapter,Mapping chapter>>.
+The default converter implementation used by `ReactiveMongoTemplate` is `MappingMongoConverter`. While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names. These conventions as well as the use of mapping annotations are explained in the xref:reference/mapping.adoc[Mapping chapter].
 
-Another central feature of `ReactiveMongoTemplate` is exception translation of exceptions thrown in the MongoDB Java driver into Spring's portable Data Access Exception hierarchy. See the section on <<mongo.exception,exception translation>> for more information.
+Another central feature of `ReactiveMongoTemplate` is exception translation of exceptions thrown in the MongoDB Java driver into Spring's portable Data Access Exception hierarchy. See the section on xref:reference/mongodb/mongo-exception.adoc[exception translation] for more information.
 
-There are many convenience methods on `ReactiveMongoTemplate` to help you easily perform common tasks. However, if you need to access the MongoDB driver API directly to access functionality not explicitly exposed by the MongoTemplate, you can use one of several `execute` callback methods to access underlying driver APIs. The `execute` callbacks give you a reference to either a `com.mongodb.reactivestreams.client.MongoCollection` or a `com.mongodb.reactivestreams.client.MongoDatabase` object. See <<mongo.reactive.executioncallback,Execution Callbacks>> for more information.
+There are many convenience methods on `ReactiveMongoTemplate` to help you easily perform common tasks. However, if you need to access the MongoDB driver API directly to access functionality not explicitly exposed by the MongoTemplate, you can use one of several `execute` callback methods to access underlying driver APIs. The `execute` callbacks give you a reference to either a `com.mongodb.reactivestreams.client.MongoCollection` or a `com.mongodb.reactivestreams.client.MongoDatabase` object. See xref:reference/reactive-mongodb.adoc#mongo.reactive.executioncallback[Execution Callbacks] for more information.
 
 [[mongo.reactive.template.instantiating]]
 === Instantiating ReactiveMongoTemplate
@@ -457,7 +457,7 @@ The preceding example includes implicit conversion between a `String` and `Objec
 
 NOTE: The preceding example is meant to show the use of save, update, and remove operations on `ReactiveMongoTemplate` and not to show complex mapping or chaining functionality.
 
-"`<<mongo.query,Querying Documents>>`" explains the query syntax used in the preceding example in more detail. Additional documentation can be found in <<mongo-template, the blocking `MongoTemplate`>> section.
+"`xref:reference/mongodb/mongo-query.adoc[Querying Documents]`" explains the query syntax used in the preceding example in more detail. Additional documentation can be found in xref:reference/mongodb/mongo-template.adoc[the blocking `MongoTemplate`] section.
 
 [[mongo.reactive.executioncallback]]
 == Execution Callbacks

src/main/antora/modules/ROOT/pages/reference/unwrapping-entities.adoc

@@ -256,7 +256,7 @@ db.collection.find({
 === Query By Example on unwrapped object.
 
 Unwrapped objects can be used within an `Example` probe just as any other type.
-Please review the <<query-by-example.running,Query By Example>> section, to learn more about this feature.
+Please review the xref:reference/query-by-example.adoc[Query By Example] section, to learn more about this feature.
 
 [[unwrapped-entities.queries.repository]]
 === Repository Queries on unwrapped objects.
@@ -340,7 +340,7 @@ db.collection.update({
 [[unwrapped-entities.aggregations]]
 == Aggregations on Unwrapped Objects
 
-The <<mongo.aggregation,Aggregation Framework>> will attempt to map unwrapped values of typed aggregations.
+The xref:reference/aggregation-framework.adoc[Aggregation Framework] will attempt to map unwrapped values of typed aggregations.
 Please make sure to work with the property path including the wrapper object when referencing one of its values.
 Other than that no special action is required.