Migrate documentation to Antora.

Closes #2304

.gitignore

@@ -12,3 +12,7 @@ target/
 vf.gf.*
 out/
 _site
+node_modules
+package-lock.json
+package.json
+node

README.adoc

@@ -2,7 +2,7 @@
 
 The goal of the project is to provide a flexible and configurable mechanism for writing simple services that can be exposed over HTTP.
 
-The first exporter implemented is a JPA Repository exporter. This takes your JPA repositories and front-ends them with HTTP, allowing you full CRUD capability over your entities, to include managing associations.
+This takes your Spring Data repositories and front-ends them with HTTP, allowing you full CRUD capability over your entities, to include managing associations.
 
 == Features
 
@@ -15,7 +15,7 @@ The first exporter implemented is a JPA Repository exporter. This takes your JPA
 * https://docs.spring.io/spring-data/rest/docs/current/reference/html/#metadata[Exposes metadata] about the model discovered as ALPS and JSON Schema.
 * Allows to define client specific representations through https://docs.spring.io/spring-data/rest/docs/current/reference/html/#projections-excerpts[projections].
 * Ships the latest release of https://docs.spring.io/spring-data/rest/docs/current/reference/html/#tools.hal-explorer[HAL Explorer] to easily explore HAL and HAL-FORMS based HTTP responses.
-* Currently supports JPA, MongoDB, Neo4j, Solr, Cassandra, Gemfire.
+* Supports JPA, MongoDB, Neo4j, Solr, Cassandra, Gemfire.
 * Allows https://docs.spring.io/spring-data/rest/docs/current/reference/html/#customizing-sdr[advanced customizations] of the default resources exposed.
 
 == Code of Conduct

spring-data-rest-distribution/pom.xml

@@ -19,18 +19,38 @@
 
 	<properties>
 		<project.root>${basedir}/..</project.root>
-		<dist.key>SDREST</dist.key>
+		<antora.playbook>${project.basedir}/../src/main/antora/antora-playbook.yml</antora.playbook>
 	</properties>
 
 	<build>
+		<resources>
+			<resource>
+				<directory>${project.basedir}/../src/main/antora/resources/antora-resources</directory>
+				<filtering>true</filtering>
+			</resource>
+		</resources>
 		<plugins>
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-assembly-plugin</artifactId>
 			</plugin>
+
 			<plugin>
-				<groupId>org.asciidoctor</groupId>
-				<artifactId>asciidoctor-maven-plugin</artifactId>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-resources-plugin</artifactId>
+				<executions>
+					<execution>
+						<goals>
+							<goal>resources</goal>
+						</goals>
+					</execution>
+				</executions>
+
+			</plugin>
+
+			<plugin>
+				<groupId>io.spring.maven.antora</groupId>
+				<artifactId>antora-maven-plugin</artifactId>
 			</plugin>
 		</plugins>
 	</build>

src/main/antora/antora-playbook.yml

@@ -0,0 +1,37 @@
+# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2
+#
+# The purpose of this Antora playbook is to build the docs in the current branch.
+antora:
+  extensions:
+    - '@antora/collector-extension'
+    - require: '@springio/antora-extensions/root-component-extension'
+      root_component_name: 'data-rest'
+site:
+  title: Spring Data REST
+  url: https://docs.spring.io/spring-data-rest/reference/
+content:
+  sources:
+    - url: ./../../..
+      branches: HEAD
+      start_path: src/main/antora
+      worktrees: true
+asciidoc:
+  attributes:
+    page-pagination: ''
+    hide-uri-scheme: '@'
+    tabs-sync-option: '@'
+    chomp: 'all'
+  extensions:
+    - '@asciidoctor/tabs'
+    - '@springio/asciidoctor-extensions'
+  sourcemap: true
+urls:
+  latest_version_segment: ''
+runtime:
+  log:
+    failure_level: warn
+    format: pretty
+ui:
+  bundle:
+    url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip
+    snapshot: true

src/main/antora/antora.yml

@@ -0,0 +1,12 @@
+name: data-rest
+version: true
+title: Spring Data REST
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    - run:
+        command: ./mvnw validate process-resources -pl :spring-data-rest-distribution -am -Pantora-process-resources
+        local: true
+      scan:
+        dir: spring-data-rest-distribution/target/classes/

src/main/antora/modules/ROOT/examples/mongodb

@@ -0,0 +1 @@
+../../../../../../spring-data-rest-tests/spring-data-rest-tests-mongodb/src/main/java/org/springframework/data/rest/tests/mongodb

src/main/antora/modules/ROOT/examples/security

@@ -0,0 +1 @@
+../../../../../../spring-data-rest-tests/spring-data-rest-tests-security/src/test/java/org/springframework/data/rest/tests/security

src/main/antora/modules/ROOT/examples/support

@@ -0,0 +1 @@
+../../../../../../spring-data-rest-webmvc/src/test/java/org/springframework/data/rest/webmvc/support

src/main/antora/modules/ROOT/nav.adoc

@@ -0,0 +1,30 @@
+* xref:index.adoc[]
+
+* xref:intro.adoc[]
+** xref:introduction/upgrade.adoc[]
+** xref:introduction/getting-started.adoc[]
+** xref:introduction/example-api-usage-with-curl.adoc[]
+** xref:introduction/spring-data-rest-examples.adoc[]
+
+* xref:repository-resources.adoc[]
+** xref:paging-and-sorting.adoc[]
+** xref:projections-excerpts.adoc[]
+
+* xref:representations.adoc[Representations]
+* xref:etags-and-other-conditionals.adoc[Conditional Operations]
+* xref:validation.adoc[]
+* xref:events.adoc[]
+* xref:integration.adoc[]
+* xref:metadata.adoc[]
+* xref:security.adoc[]
+* xref:tools.adoc[]
+
+* xref:customizing-sdr.adoc[]
+** xref:customizing/configuring-the-rest-url-path.adoc[]
+** xref:customizing/adding-sdr-to-spring-mvc-app.adoc[]
+** xref:customizing/overriding-sdr-response-handlers.adoc[]
+** xref:customizing/customizing-json-output.adoc[]
+** xref:customizing/custom-jackson-deserialization.adoc[]
+** xref:customizing/configuring-cors.adoc[]
+
+* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

src/main/antora/modules/ROOT/pages/customizing-sdr.adoc

@@ -68,7 +68,7 @@ Notice how `getResourceIdentifier(…)` returns the username to be used by the U
 [[customizing-sdr.repository-exposure]]
 == Customizing repository exposure
 
-By default, all public Spring Data repositories are used to expose HTTP resources as described in <<repository-resources>>.
+By default, all public Spring Data repositories are used to expose HTTP resources as described in xref:repository-resources.adoc[Repository resources].
 Package protected repository interfaces are excluded from this list, as you express its functionality is only visible to the package internally.
 This can be customized by explicitly setting a `RepositoryDetectionStrategy` (usually through the enum `RepositoryDetectionStrategies`) on `RepositoryRestConfiguration`.
 The following values can be configured:
@@ -86,12 +86,12 @@ If you need custom rules to apply, simply implement `RepositoryDetectionStrategy
 [[customizing-sdr.http-methods.default-exposure]]
 === Customizing default exposure
 
-By default, Spring Data REST exposes HTTP resources and methods as described in <<repository-resources>> based on which CRUD methods the repository exposes.
+By default, Spring Data REST exposes HTTP resources and methods as described in xref:repository-resources.adoc[Repository resources] based on which CRUD methods the repository exposes.
 The repositories don't need to extend `CrudRepository` but can also selectively declare methods described in aforementioned section and the resource exposure will follow.
 E.g. if a repository does not expose a `delete(…)` method, an HTTP `DELETE` will not be supported for item resources.
 
 If you need to declare a method for internal use but don't want it to trigger the HTTP method exposure, the repository method can be annotated with `@RestResource(exported = false)`.
-Which methods to annotate like that to remove support for which HTTP method is described in <<repository-resources>>.
+Which methods to annotate like that to remove support for which HTTP method is described in xref:repository-resources.adoc[Repository resources].
 
 Sometimes managing the exposure on the method level is not fine-grained enough.
 E.g. the `save(…)` method is used to back `POST` on collection resources, as well as `PUT` and `PATCH` on item resources.
@@ -110,9 +110,3 @@ config.withItemExposure((metadata, httpMethods) -> httpMethods.disable(HttpMetho
 <2> Disables the support for HTTP `PATCH` on all item resources.
 
 
-include::configuring-the-rest-url-path.adoc[leveloffset=+1]
-include::adding-sdr-to-spring-mvc-app.adoc[leveloffset=+1]
-include::overriding-sdr-response-handlers.adoc[leveloffset=+1]
-include::customizing-json-output.adoc[leveloffset=+1]
-include::custom-jackson-deserialization.adoc[leveloffset=+1]
-include::configuring-cors.adoc[leveloffset=+1]

src/main/antora/modules/ROOT/pages/etags-and-other-conditionals.adoc

@@ -1,6 +1,5 @@
 [[conditional]]
 = Conditional Operations with Headers
-:spring-data-rest-root: ../../..
 
 This section shows how Spring Data REST uses standard HTTP headers to enhance performance, conditionalize operations, and contribute to a more sophisticated frontend.
 
@@ -15,7 +14,7 @@ Consider the following example:
 ====
 [source,java,indent=0]
 ----
-include::{spring-data-rest-root}/spring-data-rest-webmvc/src/test/java/org/springframework/data/rest/webmvc/support/ETagUnitTests.java[tag=versioned-sample]
+include::example$support/ETagUnitTests.java[tag=versioned-sample]
 ----
 
 <1> The `@Version` annotation (the JPA one in case you're using Spring Data JPA, the Spring Data `org.springframework.data.annotation.Version` one for all other modules) flags this field as a version marker.
@@ -56,7 +55,7 @@ The https://tools.ietf.org/html/rfc7232#section-3.3[`If-Modified-Since` header]
 ====
 [source,java]
 ----
-include::{spring-data-rest-root}/spring-data-rest-tests/spring-data-rest-tests-mongodb/src/main/java/org/springframework/data/rest/tests/mongodb/Receipt.java[tag=code]
+include::example$mongodb/Receipt.java[tag=code]
 ----
 
 <1> Spring Data Commons's `@LastModifiedDate` annotation allows capturing this information in multiple formats (JodaTime's `DateTime`, legacy Java `Date` and `Calendar`, JDK8 date/time types, and `long`/`Long`).

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

@@ -0,0 +1,27 @@
+[[spring-data-rest-reference-documentation]]
+= Spring Data REST
+:feature-scroll: true
+
+_Spring Data REST exports Spring Data repositories as REST resources through WebMVC.
+It eases development of applications with a consistent programming model backed by Spring Data modules sources._
+
+[horizontal]
+xref:intro.adoc[Introduction] :: Introduction to Spring Data REST and Examples
+xref:repository-resources.adoc[Repository Resources] :: Exporting Repositories as REST Resources
+xref:representations.adoc[Representations] :: Domain Object Representations (Object Mapping)
+xref:etags-and-other-conditionals.adoc[Conditionals] :: Conditional Operations with ETag and other Headers
+xref:validation.adoc[Validation] :: Validator Integration
+xref:events.adoc[Events] :: Listening to REST Events
+xref:integration.adoc[Integration] :: Integration with Spring Data REST components
+xref:metadata.adoc[Metadata] :: ALPS and JSON Schema
+xref:security.adoc[Security] :: Spring Security Integration
+xref:tools.adoc[Tools] :: HAL Explorer
+xref:customizing-sdr.adoc[Customizing] :: Tutorials and Recipes to customize Spring Data REST
+https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New,
+Upgrade Notes, Supported Versions, additional cross-version information.
+
+Jon Brisbin, Oliver Drotbohm, Greg Turnquist, Jay Bryant
+
+(C) 2008-2023 VMware, Inc.
+
+Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

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

@@ -1,6 +1,5 @@
 [[integration]]
 = Integration
-:spring-data-rest-root: ../../../..
 
 This section details various ways to integrate with Spring Data REST components, whether from a Spring application that is using Spring Data REST or from other means.
 

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

@@ -1,5 +1,6 @@
 [[intro-chapter]]
 = Introduction
+:page-section-summary-toc: 1
 
 REST web services have become the number one means for application integration on the web. In its core, REST defines that a system that consists of resources with which clients interact. These resources are implemented in a hypermedia-driven way. link:{springDocsUrl}/web.html#spring-web[Spring MVC] and link:{springDocsUrl}/web-reactive.html#spring-webflux[Spring WebFlux] each offer a solid foundation to build theses kinds of services. However, implementing even the simplest tenet of REST web services for a multi-domain object system can be quite tedious and result in a lot of boilerplate code.
 

src/main/antora/modules/ROOT/pages/introduction/example-api-usage-with-curl.adoc

@@ -1,6 +1,8 @@
 [[example-api-usage-with-curl]]
 [appendix]
+[[using-curl-to-talk-to-spring-data-rest]]
 = Using cURL to talk to Spring Data REST
+:page-section-summary-toc: 1
 
 This appendix contains a list of guides that demonstrate interacting with a Spring Data REST service over cURL:
 

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

@@ -89,9 +89,9 @@ Make sure you also configure Spring Data repositories for the store you use. For
 
 This section covers the basic settings that you can manipulate when you configure a Spring Data REST application, including:
 
-* <<getting-started.setting-repository-detection-strategy>>
-* <<getting-started.changing-base-uri>>
-* <<getting-started.changing-other-properties>>
+* xref:introduction/getting-started.adoc#getting-started.setting-repository-detection-strategy[Setting the Repository Detection Strategy]
+* xref:introduction/getting-started.adoc#getting-started.changing-base-uri[Changing the Base URI]
+* xref:introduction/getting-started.adoc#getting-started.changing-other-properties[Changing Other Spring Data REST Properties]
 
 [[getting-started.setting-repository-detection-strategy]]
 === Setting the Repository Detection Strategy
@@ -209,4 +209,4 @@ You can run your application as either a Spring Boot app (with the links shown e
 
 NOTE: In general, Spring Data REST does not add functionality to a given data store. This means that, by definition, it should work with any Spring Data project that supports the repository programming model. The data stores listed above are the ones for which we have written integration tests to verify that Spring Data REST works with them.
 
-From this point, you can  <<customizing-sdr,customize Spring Data REST>> with various options.
+From this point, you can  xref:customizing-sdr.adoc[customize Spring Data REST] with various options.

src/main/antora/modules/ROOT/pages/introduction/spring-data-rest-examples.adoc

@@ -1,5 +1,6 @@
 [[spring-data-examples]]
 [appendix]
+[[spring-data-rest-example-projects]]
 = Spring Data REST example projects
 
 This appendix contains a list of Spring Data REST sample applications. The exact version of each example is not guaranteed to match the version of this reference manual.
@@ -14,7 +15,7 @@ https://github.com/spring-projects/spring-data-examples/tree/master/rest/multi-s
 [[spring-data-examples.projections]]
 == Projections
 
-https://github.com/spring-projects/spring-data-examples/tree/master/rest/projections[This example] contains more detailed code you can use to explore <<projections-excerpts,projections>>.
+https://github.com/spring-projects/spring-data-examples/tree/master/rest/projections[This example] contains more detailed code you can use to explore xref:projections-excerpts.adoc[projections].
 
 [[spring-data-examples.spring-security]]
 == Spring Data REST with Spring Security

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

@@ -0,0 +1,8 @@
+[[new-features]]
+[[upgrading]]
+= Upgrading Spring Data
+
+Instructions for how to upgrade from earlier versions of Spring Data are provided on the project https://github.com/spring-projects/spring-data-commons/wiki[wiki].
+Follow the links in the https://github.com/spring-projects/spring-data-commons/wiki#release-notes[release notes section] to find the version that you want to upgrade to.
+
+Upgrading instructions are always the first item in the release notes. If you are more than one release behind, please make sure that you also review the release notes of the versions that you jumped.

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

@@ -178,7 +178,7 @@ shown in the preceding table.
 === ALPS with Projections
 
 If you define any projections, they are also listed in the ALPS metadata. Assuming we also defined `inlineAddress` and `noAddresses`, they
-would appear inside the relevant operations. (See "`<<projections-excerpts.projections>>`" for the definitions and discussion of these two projections.) That is *GET* would appear in the operations for the whole collection, and *GET* would appear in the operations for a single resource. The following example shows
+would appear inside the relevant operations. (See "`xref:projections-excerpts.adoc#projections-excerpts.projections[Projections]`" for the definitions and discussion of these two projections.) That is *GET* would appear in the operations for the whole collection, and *GET* would appear in the operations for a single resource. The following example shows
 the alternate version of the `get-persons` subsection:
 
 ====
@@ -319,7 +319,7 @@ https://json-schema.org/[JSON Schema] is another form of metadata supported by S
 * Clear, human- and machine-readable documentation
 * Complete structural validation, useful for automated testing and validating client-submitted data
 
-As shown in the <<metadata.alps,previous section>>, you can reach this data by navigating from the root URI to the `profile` link.
+As shown in the xref:metadata.adoc#metadata.alps[previous section], you can reach this data by navigating from the root URI to the `profile` link.
 
 ====
 [source,javascript]
@@ -417,7 +417,7 @@ You can also find a `profile` link in the collection of `_links` when you examin
 <2> It has a *profile* link to the same URI for metadata.
 ====
 
-Again, the `profile` link serves <<metadata.alps,ALPS>> by default. If you supply it with an https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1[`Accept` header] of `application/schema+json`, it renders the JSON Schema representation.
+Again, the `profile` link serves xref:metadata.adoc#metadata.alps[ALPS] by default. If you supply it with an https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1[`Accept` header] of `application/schema+json`, it renders the JSON Schema representation.
 
 //= JSON Patch
 

src/main/antora/modules/ROOT/pages/projections-excerpts.adoc

@@ -142,7 +142,7 @@ NOTE: The value supplied to the `projection` query parameter is the same as that
 
 You can have multiple projections.
 
-NOTE: See <<spring-data-examples.projections>> to see an example project. We encourage you to experiment with it.
+NOTE: See xref:introduction/spring-data-rest-examples.adoc#spring-data-examples.projections[Projections] to see an example project. We encourage you to experiment with it.
 
 Spring Data REST finds projection definitions as follows:
 
@@ -154,7 +154,7 @@ In either case, the projection interface must have the `@Projection` annotation.
 [[projections-excerpts.finding-projections]]
 === Finding Existing Projections
 
-Spring Data REST exposes <<metadata.alps>> documents, a micro metadata format. To view the ALPS metadata, follow the `profile` link exposed by the root resource. If you navigate down to the ALPS document for `Person` resources (which would be `/alps/persons`), you can find many details about `Person` resources. Projections are listed, along with the details about the `GET` REST transition, in blocks similar to the following example:
+Spring Data REST exposes xref:metadata.adoc#metadata.alps[Application-Level Profile Semantics (ALPS)] documents, a micro metadata format. To view the ALPS metadata, follow the `profile` link exposed by the root resource. If you navigate down to the ALPS document for `Person` resources (which would be `/alps/persons`), you can find many details about `Person` resources. Projections are listed, along with the details about the `GET` REST transition, in blocks similar to the following example:
 
 ====
 [source,javascript]

src/main/antora/modules/ROOT/pages/repository-resources.adoc

@@ -13,9 +13,9 @@ public interface OrderRepository extends CrudRepository<Order, Long> { }
 ----
 ====
 
-For this repository, Spring Data REST exposes a collection resource at `/orders`. The path is derived from the uncapitalized, pluralized, simple class name of the domain class being managed. It also exposes an item resource for each of the items managed by the repository under the URI template `/orders/{id}`.
+For this repository, Spring Data REST exposes a collection resource at `/orders`. The path is derived from the uncapitalized, pluralized, simple class name of the domain class being managed. It also exposes an item resource for each of the items managed by the repository under the URI template `/orders/\{id}`.
 
-By default the HTTP methods to interact with these resources map to the according methods of `CrudRepository`. Read more on that in the sections on <<repository-resources.collection-resource, collection resources>> and <<repository-resources.item-resource, item resources>>.
+By default, the HTTP methods to interact with these resources map to the according methods of `CrudRepository`. Read more on that in the sections on xref:repository-resources.adoc#repository-resources.collection-resource[collection resources] and xref:repository-resources.adoc#repository-resources.item-resource[item resources].
 
 [[repository-resources.methods]]
 === Repository methods exposure
@@ -26,7 +26,7 @@ If you extend `CrudRepository` you usually expose all methods required to expose
 Each of the resources listed below will define which of the methods need to be present so that a particular HTTP method can be exposed for each of the resources.
 That means, that repositories that are not exposing those methods -- either by not declaring them at all or explicitly using `@RestResource(exported = false)` -- won't expose those HTTP methods on those resources.
 
-For details on how to tweak the default method exposure or dedicated HTTP methods individually see <<customizing-sdr.http-methods>>.
+For details on how to tweak the default method exposure or dedicated HTTP methods individually see xref:customizing-sdr.adoc#customizing-sdr.http-methods[Customizing supported HTTP methods].
 
 [[repository-resources.default-status-codes]]
 === Default Status Codes
@@ -39,7 +39,7 @@ For the resources exposed, we use a set of default status codes:
 If the configuration value is set to include responses for `PUT`, `200 OK` is returned for updates, and `201 Created` is returned for resource created through `PUT`.
 
 If the configuration values (`RepositoryRestConfiguration.returnBodyOnUpdate(…)` and `RepositoryRestConfiguration.returnBodyCreate(…)`) are explicitly set to `null` -- which they are by default --, the presence of the HTTP Accept header is used to determine the response code.
-Read more on this in the detailed description of <<repository-resources.collection-resource.supported-methods.post, collection>> and <<repository-resources.item-resource.supported-methods.put, item resources>>.
+Read more on this in the detailed description of xref:repository-resources.adoc#repository-resources.collection-resource.supported-methods.post[collection] and xref:repository-resources.adoc#repository-resources.item-resource.supported-methods.put[item resources].
 
 [[repository-resources.resource-discoverability]]
 === Resource Discoverability
@@ -72,7 +72,7 @@ curl -v http://localhost:8080/
 
 The property of the result document is an object that consists of keys representing the relation type, with nested link objects as specified in HAL.
 
-NOTE: For more details about the `profile` link, see <<metadata.alps>>.
+NOTE: For more details about the `profile` link, see xref:metadata.adoc#metadata.alps[Application-Level Profile Semantics (ALPS)].
 
 [[repository-resources.collection-resource]]
 == The Collection Resource
@@ -90,6 +90,7 @@ Collections resources support both `GET` and `POST`. All other HTTP methods caus
 Returns all entities the repository servers through its `findAll(…)` method.
 If the repository is a paging repository we include the pagination links if necessary and additional page metadata.
 
+
 ===== Methods used for invocation
 
 The following methods are used if present (descending order):
@@ -98,8 +99,9 @@ The following methods are used if present (descending order):
 - `findAll(Sort)`
 - `findAll()`
 
-For more information on the default exposure of methods, see <<repository-resources.methods>>.
+For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure].
 
+[[parameters]]
 ===== Parameters
 
 If the repository has pagination capabilities, the resource takes the following parameters:
@@ -114,6 +116,7 @@ The `GET` method has only one custom status code:
 
 * `405 Method Not Allowed`: If the `findAll(…)` methods were not exported (through `@RestResource(exported = false)`) or are not present in the repository.
 
+[[supported-media-types]]
 ===== Supported Media Types
 
 The `GET` method supports the following media types:
@@ -121,11 +124,12 @@ The `GET` method supports the following media types:
 * `application/hal+json`
 * `application/json`
 
+[[related-resources]]
 ===== Related Resources
 
 The `GET` method supports a single link for discovering related resources:
 
-* `search`: A <<repository-resources.search-resource,search resource>> is exposed if the backing repository exposes query methods.
+* `search`: A xref:repository-resources.adoc#repository-resources.search-resource[search resource] is exposed if the backing repository exposes query methods.
 
 [[repository-resources.collection-resource.supported-methods.head]]
 ==== `HEAD`
@@ -140,7 +144,7 @@ The following methods are used if present (descending order):
 - `findAll(Sort)`
 - `findAll()`
 
-For more information on the default exposure of methods, see <<repository-resources.methods>>.
+For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure].
 
 [[repository-resources.collection-resource.supported-methods.post]]
 ==== `POST`
@@ -157,7 +161,7 @@ The following methods are used if present (descending order):
 
 - `save(…)`
 
-For more information on the default exposure of methods, see <<repository-resources.methods>>.
+For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure].
 
 ===== Custom Status Codes
 
@@ -180,20 +184,21 @@ Spring Data REST exposes a resource for individual collection items as sub-resou
 [[repository-resources.item-resource.supported-methods]]
 === Supported HTTP Methods
 
-Item resources generally support `GET`, `PUT`, `PATCH`, and `DELETE`, unless explicit configuration prevents that (see "`<<repository-resources.association-resource>>`" for details).
+Item resources generally support `GET`, `PUT`, `PATCH`, and `DELETE`, unless explicit configuration prevents that (see "`xref:repository-resources.adoc#repository-resources.association-resource[The Association Resource]`" for details).
 
 [[repository-resources.item-resource.supported-methods.get]]
 ==== GET
 
 The `GET` method returns a single entity.
 
+
 ===== Methods used for invocation
 
 The following methods are used if present (descending order):
 
 - `findById(…)`
 
-For more information on the default exposure of methods, see <<repository-resources.methods>>.
+For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure].
 
 ===== Custom Status Codes
 
@@ -210,20 +215,21 @@ The `GET` method supports the following media types:
 
 ===== Related Resources
 
-For every association of the domain type, we expose links named after the association property. You can customize this behavior by using `@RestResource` on the property. The related resources are of the <<repository-resources.association-resource,association resource>> type.
+For every association of the domain type, we expose links named after the association property. You can customize this behavior by using `@RestResource` on the property. The related resources are of the xref:repository-resources.adoc#repository-resources.association-resource[association resource] type.
 
 [[repository-resources.item-resource.supported-methods.head]]
 ==== `HEAD`
 
 The `HEAD` method returns whether the item resource is available. It has no status codes, media types, or related resources.
 
+
 ===== Methods used for invocation
 
 The following methods are used if present (descending order):
 
 - `findById(…)`
 
-For more information on the default exposure of methods, see <<repository-resources.methods>>.
+For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure].
 
 [[repository-resources.item-resource.supported-methods.put]]
 ==== `PUT`
@@ -234,13 +240,14 @@ If the request header is present, a response body and a status code of `200 OK`
 If no header is present, the response body is empty and a successful request returns a status of `204 No Content`.
 This behavior can be overridden by configuring `RepositoryRestConfiguration.setReturnBodyOnUpdate(…)` accordingly.
 
+
 ===== Methods used for invocation
 
 The following methods are used if present (descending order):
 
 - `save(…)`
 
-For more information on the default exposure of methods, see <<repository-resources.methods>>.
+For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure].
 
 ===== Custom Status Codes
 
@@ -260,13 +267,14 @@ The `PUT` method supports the following media types:
 
 The `PATCH` method is similar to the `PUT` method but partially updates the resources state.
 
+
 ===== Methods used for invocation
 
 The following methods are used if present (descending order):
 
 - `save(…)`
 
-For more information on the default exposure of methods, see <<repository-resources.methods>>.
+For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure].
 
 ===== Custom Status Codes
 
@@ -292,6 +300,7 @@ If the request header is present, a response body and a status code of `200 OK`
 If no header is present, the response body is empty and a successful request returns a status of `204 No Content`.
 This behavior can be overridden by configuring `RepositoryRestConfiguration.setReturnBodyOnDelete(…)` accordingly.
 
+
 ===== Methods used for invocation
 
 The following methods are used if present (descending order):
@@ -300,7 +309,7 @@ The following methods are used if present (descending order):
 - `delete(ID)`
 - `delete(Iterable)`
 
-For more information on the default exposure of methods, see <<repository-resources.methods>>.
+For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure].
 
 ===== Custom Status Codes
 
@@ -368,6 +377,7 @@ The `POST` method supports only one media type:
 
 The `DELETE` method unbinds the association.
 
+[[custom-status-codes]]
 ===== Custom Status Codes
 
 The `POST` method has only one custom status code:
@@ -398,7 +408,7 @@ The `GET` method supports the following media types:
 
 ===== Related Resources
 
-For every query method declared in the repository, we expose a <<repository-resources.query-method-resource,query method resource>>. If the resource supports pagination, the URI pointing to it is a URI template containing the pagination parameters.
+For every query method declared in the repository, we expose a xref:repository-resources.adoc#repository-resources.query-method-resource[query method resource]. If the resource supports pagination, the URI pointing to it is a URI template containing the pagination parameters.
 
 [[repository-resources.search-resource.supported-methods.head]]
 ==== `HEAD`

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

@@ -1,6 +1,5 @@
 [[security]]
 = Security
-:spring-data-rest-root: ../../..
 :spring-security-docs: https://docs.spring.io/spring-security/reference
 
 Spring Data REST works quite well with Spring Security. This section shows examples of how to secure your Spring Data REST services with method-level security.
@@ -15,7 +14,7 @@ The following example from Spring Data REST's test suite shows Spring Security's
 [source,java]
 ----
 
-include::{spring-data-rest-root}/spring-data-rest-tests/spring-data-rest-tests-security/src/test/java/org/springframework/data/rest/tests/security/PreAuthorizedOrderRepository.java[tag=code]
+include::example$security/PreAuthorizedOrderRepository.java[tag=code]
 ----
 
 <1> This Spring Security annotation secures the entire repository. The {spring-security-docs}/servlet/authorization/expression-based.html[Spring Security SpEL expression] indicates that the principal must have `ROLE_USER` in its collection of roles.
@@ -38,7 +37,7 @@ The following example shows Spring Security's older `@Secured` annotation, which
 ====
 [source,java]
 ----
-include::{spring-data-rest-root}/spring-data-rest-tests/spring-data-rest-tests-security/src/test/java/org/springframework/data/rest/tests/security/SecuredPersonRepository.java[tag=code]
+include::example$security/SecuredPersonRepository.java[tag=code]
 ----
 
 <1> This results in the same security check as the previous example but has less flexibility. It allows only roles as the means to restrict access.
@@ -56,7 +55,7 @@ To configure method-level security, here is a brief snippet from Spring Data RES
 ====
 [source,java]
 ----
-include::{spring-data-rest-root}/spring-data-rest-tests/spring-data-rest-tests-security/src/test/java/org/springframework/data/rest/tests/security/SecurityConfiguration.java[tag=code]
+include::example$security/SecurityConfiguration.java[tag=code]
 	...
 }
 ----

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

@@ -1,6 +1,5 @@
 [[tools]]
 = Tools
-:spring-data-rest-root: ../../../..
 
 [[tools.hal-explorer]]
 == The HAL Explorer
@@ -48,7 +47,7 @@ The HAL Explorer understands *URI Templates*. Whenever a link contains a URI tem
 
 image::hal-explorer-3.png[]
 
-If you click *Go!* without entering anything, the variables are essentially ignored. For situations like <<projections-excerpts>> or <<paging-and-sorting>>, this can be useful.
+If you click *Go!* without entering anything, the variables are essentially ignored. For situations like xref:projections-excerpts.adoc[Projections and Excerpts] or xref:paging-and-sorting.adoc[Paging and Sorting], this can be useful.
 
 When you click on a *NON-GET* button with a `+` or a `>` sign on it, a modal dialog appears. It shows the HTTP method belonging to the clicked button. You can fill the body and submit the new JSON document.
 

src/main/antora/resources/antora-resources/antora.yml

@@ -0,0 +1,19 @@
+version: ${antora-component.version}
+prerelease: ${antora-component.prerelease}
+
+asciidoc:
+  attributes:
+    version: ${project.version}
+    springversionshort: ${spring.short}
+    springversion: ${spring}
+    attribute-missing: 'warn'
+    commons: ${springdata.commons.docs}
+    include-xml-namespaces: false
+    spring-data-commons-docs-url: https://docs.spring.io/spring-data-commons/reference
+    spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/${springdata.commons}/api/
+    springdocsurl: https://docs.spring.io/spring-framework/reference/{springversionshort}
+    springjavadocurl: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api
+    spring-framework-docs: '{springdocsurl}'
+    spring-framework-javadoc: '{springjavadocurl}'
+    springhateoasversion: ${spring-hateoas}
+    releasetrainversion: ${releasetrain}

src/main/asciidoc/index.adoc

@@ -1,40 +0,0 @@
-[[spring-data-rest-reference]]
-= Spring Data REST Reference Guide
-Jon Brisbin, Oliver Drotbohm, Greg Turnquist, Jay Bryant
-:revnumber: {version}
-:revdate: {localdate}
-ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]]
-:spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc
-
-(C) 2012-2022 Original authors
-
-NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
-
-include::preface.adoc[]
-include::{spring-data-commons-docs}/upgrade.adoc[leveloffset=+1]
-include::{spring-data-commons-docs}/dependencies.adoc[leveloffset=+1]
-
-[[reference]]
-= Reference Documentation
-
-include::intro.adoc[leveloffset=+1]
-include::getting-started.adoc[leveloffset=+1]
-include::repository-resources.adoc[leveloffset=+1]
-include::paging-and-sorting.adoc[leveloffset=+1]
-include::representations.adoc[leveloffset=+1]
-include::projections-excerpts.adoc[leveloffset=+1]
-include::etags-and-other-conditionals.adoc[leveloffset=+1]
-include::validation.adoc[leveloffset=+1]
-include::events.adoc[leveloffset=+1]
-include::integration.adoc[leveloffset=+1]
-include::metadata.adoc[leveloffset=+1]
-include::security.adoc[leveloffset=+1]
-include::tools.adoc[leveloffset=+1]
-include::customizing-sdr.adoc[leveloffset=+1]
-
-[[appendix]]
-= Appendix
-
-:numbered!:
-include::example-api-usage-with-curl.adoc[leveloffset=+1]
-include::spring-data-rest-examples.adoc[leveloffset=+1]

src/main/asciidoc/preface.adoc

@@ -1,13 +0,0 @@
-[[preface]]
-= Preface
-
-[[Project]]
-[preface]
-== Project Metadata
-
-* Version control: https://github.com/spring-projects/spring-data-rest
-* Bugtracker: https://github.com/spring-projects/spring-data-rest/issues
-* Project page: https://spring.io/projects/spring-data-rest
-* Release repository: https://repo1.maven.org/maven2/
-* Milestone repository: https://repo.spring.io/milestone/
-* Snapshot repository: https://repo.spring.io/snapshot