Migrate docs to Antora

Issue gh-1295

.gitignore

@@ -37,3 +37,4 @@ out/
 
 ### Mac ###
 .DS_Store
+cached-antora-playbook.yml

docs/.github/workflows/deploy-docs.yml

@@ -0,0 +1,33 @@
+name: Deploy Docs
+on:
+  push:
+    branches-ignore: [ gh-pages ]
+    tags: '**'
+  repository_dispatch:
+    types: request-build-reference # legacy
+  #schedule:
+  #- cron: '0 10 * * *' # Once per day at 10am UTC
+  workflow_dispatch:
+permissions:
+  actions: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # FIXME enable when pushed to spring-projects
+    # if: github.repository_owner == 'spring-projects'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          ref: docs-build
+          fetch-depth: 1
+      - name: Dispatch (partial build)
+        if: github.ref_type == 'branch'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }}
+      - name: Dispatch (full build)
+        if: github.ref_type == 'tag'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)

docs/antora-playbook.yml

@@ -0,0 +1,39 @@
+# 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/tabs-migration-extension'
+      unwrap_example_block: always
+    - require: '@springio/antora-extensions/root-component-extension'
+      root_component_name: 'authorization-server'
+    - '@antora/atlas-extension'
+site:
+  title: Spring Authorization Server
+  url: https://https://rwinch.github.io/spring-authorization-server/
+content:
+  sources:
+    - url: ..
+      branches: antora
+      start_path: docs
+      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
+ui:
+  bundle:
+    url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip
+    snapshot: true

docs/antora.yml

@@ -0,0 +1,23 @@
+name: authorization-server
+version: true
+title: Spring Authorization Server
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-authorization-server-docs:generateAntoraYml
+      local: true
+    scan:
+      dir: ./build/generated-antora-resources
+
+asciidoc:
+  attributes:
+    attribute-missing: 'warn'
+    chomp: 'all'
+    spring-security-reference-base-url: "https://docs.spring.io/spring-security/reference"
+    spring-security-api-base-url: "https://docs.spring.io/spring-security/site/docs/current/api"
+    spring-boot-reference-base-url: "https://docs.spring.io/spring-boot/docs/current/reference/html"
+    examples-dir: example$docs-src
+    samples-dir: example$samples
+    docs-java: '{examples-dir}/main/java'

docs/modules/ROOT/examples/docs-src

@@ -0,0 +1 @@
+../../../src

docs/modules/ROOT/examples/samples

@@ -0,0 +1 @@
+../../../../samples

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,12 @@
+* xref:index.adoc[]
+* xref:getting-help.adoc[]
+* xref:getting-started.adoc[]
+* xref:configuration-model.adoc[]
+* xref:core-model-components.adoc[]
+* xref:protocol-endpoints.adoc[]
+* xref:how-to.adoc[]
+** xref:guides/how-to-ext-grant-type.adoc[]
+** xref:guides/how-to-jpa.adoc[]
+** xref:guides/how-to-pkce.adoc[]
+** xref:guides/how-to-social-login.adoc[]
+** xref:guides/how-to-userinfo.adoc[]

docs/src/docs/asciidoc/configuration-model.adoc → docs/modules/ROOT/pages/configuration-model.adoc

@@ -6,7 +6,7 @@
 
 `OAuth2AuthorizationServerConfiguration` is a `@Configuration` that provides the minimal default configuration for an OAuth2 authorization server.
 
-`OAuth2AuthorizationServerConfiguration` uses <<customizing-the-configuration, `OAuth2AuthorizationServerConfigurer`>> to apply the default configuration and registers a `SecurityFilterChain` `@Bean` composed of all the infrastructure components supporting an OAuth2 authorization server.
+`OAuth2AuthorizationServerConfiguration` uses xref:configuration-model.adoc#customizing-the-configuration[`OAuth2AuthorizationServerConfigurer`] to apply the default configuration and registers a `SecurityFilterChain` `@Bean` composed of all the infrastructure components supporting an OAuth2 authorization server.
 
 [TIP]
 `OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(HttpSecurity)` is a convenience (`static`) utility method that applies the default OAuth2 security configuration to `HttpSecurity`.
@@ -135,9 +135,9 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
 <1> `registeredClientRepository()`: The xref:core-model-components.adoc#registered-client-repository[`RegisteredClientRepository`] (*REQUIRED*) for managing new and existing clients.
 <2> `authorizationService()`: The xref:core-model-components.adoc#oauth2-authorization-service[`OAuth2AuthorizationService`] for managing new and existing authorizations.
 <3> `authorizationConsentService()`: The xref:core-model-components.adoc#oauth2-authorization-consent-service[`OAuth2AuthorizationConsentService`] for managing new and existing authorization consents.
-<4> `authorizationServerSettings()`: The <<configuring-authorization-server-settings, `AuthorizationServerSettings`>> (*REQUIRED*) for customizing configuration settings for the OAuth2 authorization server.
+<4> `authorizationServerSettings()`: The xref:configuration-model.adoc#configuring-authorization-server-settings[`AuthorizationServerSettings`] (*REQUIRED*) for customizing configuration settings for the OAuth2 authorization server.
 <5> `tokenGenerator()`: The xref:core-model-components.adoc#oauth2-token-generator[`OAuth2TokenGenerator`] for generating tokens supported by the OAuth2 authorization server.
-<6> `clientAuthentication()`: The configurer for <<configuring-client-authentication, OAuth2 Client Authentication>>.
+<6> `clientAuthentication()`: The configurer for xref:configuration-model.adoc#configuring-client-authentication[OAuth2 Client Authentication].
 <7> `authorizationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[OAuth2 Authorization endpoint].
 <8> `deviceAuthorizationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-device-authorization-endpoint[OAuth2 Device Authorization endpoint].
 <9> `deviceVerificationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[OAuth2 Device Verification endpoint].
@@ -186,7 +186,7 @@ public final class AuthorizationServerSettings extends AbstractSettings {
 `AuthorizationServerSettings` is a *REQUIRED* component.
 
 [TIP]
-<<default-configuration, `@Import(OAuth2AuthorizationServerConfiguration.class)`>> automatically registers an `AuthorizationServerSettings` `@Bean`, if not already provided.
+xref:configuration-model.adoc#default-configuration[`@Import(OAuth2AuthorizationServerConfiguration.class)`] automatically registers an `AuthorizationServerSettings` `@Bean`, if not already provided.
 
 The following example shows how to customize the configuration settings and register an `AuthorizationServerSettings` `@Bean`:
 

docs/src/docs/asciidoc/core-model-components.adoc → docs/modules/ROOT/pages/core-model-components.adoc

@@ -141,7 +141,7 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi
 [[oauth2-authorization]]
 == OAuth2Authorization
 
-An `OAuth2Authorization` is a representation of an OAuth2 authorization, which holds state related to the authorization granted to a <<registered-client, client>>, by the resource owner or itself in the case of the `client_credentials` authorization grant type.
+An `OAuth2Authorization` is a representation of an OAuth2 authorization, which holds state related to the authorization granted to a xref:core-model-components.adoc#registered-client[client], by the resource owner or itself in the case of the `client_credentials` authorization grant type.
 
 [TIP]
 The corresponding authorization model in Spring Security's OAuth2 Client support is {spring-security-reference-base-url}/servlet/oauth2/client/core.html#oauth2Client-authorized-client[OAuth2AuthorizedClient].
@@ -174,7 +174,7 @@ public class OAuth2Authorization implements Serializable {
 }
 ----
 <1> `id`: The ID that uniquely identifies the `OAuth2Authorization`.
-<2> `registeredClientId`: The ID that uniquely identifies the <<registered-client, RegisteredClient>>.
+<2> `registeredClientId`: The ID that uniquely identifies the xref:core-model-components.adoc#registered-client[RegisteredClient].
 <3> `principalName`: The principal name of the resource owner (or client).
 <4> `authorizationGrantType`: The `AuthorizationGrantType` used.
 <5> `authorizedScopes`: The `Set` of scope(s) authorized for the client.
@@ -236,7 +236,7 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi
 [[oauth2-authorization-consent]]
 == OAuth2AuthorizationConsent
 
-An `OAuth2AuthorizationConsent` is a representation of an authorization "consent" (decision) from an https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1[OAuth2 authorization request flow] – for example, the `authorization_code` grant, which holds the authorities granted to a <<registered-client, client>> by the resource owner.
+An `OAuth2AuthorizationConsent` is a representation of an authorization "consent" (decision) from an https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1[OAuth2 authorization request flow] – for example, the `authorization_code` grant, which holds the authorities granted to a xref:core-model-components.adoc#registered-client[client] by the resource owner.
 
 When authorizing access to a client, the resource owner may grant only a subset of the authorities requested by the client.
 The typical use case is the `authorization_code` grant flow, in which the client requests scope(s) and the resource owner grants (or denies) access to the requested scope(s).
@@ -256,7 +256,7 @@ public final class OAuth2AuthorizationConsent implements Serializable {
 
 }
 ----
-<1> `registeredClientId`: The ID that uniquely identifies the <<registered-client, RegisteredClient>>.
+<1> `registeredClientId`: The ID that uniquely identifies the xref:core-model-components.adoc#registered-client[RegisteredClient].
 <2> `principalName`: The principal name of the resource owner.
 <3> `authorities`: The authorities granted to the client by the resource owner. An authority can represent a scope, a claim, a permission, a role, and others.
 
@@ -308,7 +308,7 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi
 [[oauth2-token-context]]
 == OAuth2TokenContext
 
-An `OAuth2TokenContext` is a context object that holds information associated with an `OAuth2Token` and is used by an <<oauth2-token-generator, OAuth2TokenGenerator>> and <<oauth2-token-customizer, OAuth2TokenCustomizer>>.
+An `OAuth2TokenContext` is a context object that holds information associated with an `OAuth2Token` and is used by an xref:core-model-components.adoc#oauth2-token-generator[OAuth2TokenGenerator] and xref:core-model-components.adoc#oauth2-token-customizer[OAuth2TokenCustomizer].
 
 `OAuth2TokenContext` provides the following accessors:
 
@@ -337,10 +337,10 @@ public interface OAuth2TokenContext extends Context {
 
 }
 ----
-<1> `getRegisteredClient()`: The <<registered-client, RegisteredClient>> associated with the authorization grant.
+<1> `getRegisteredClient()`: The xref:core-model-components.adoc#registered-client[RegisteredClient] associated with the authorization grant.
 <2> `getPrincipal()`: The `Authentication` instance of the resource owner (or client).
 <3> `getAuthorizationServerContext()`: The xref:configuration-model.adoc#configuring-authorization-server-settings[`AuthorizationServerContext`] object that holds information of the Authorization Server runtime environment.
-<4> `getAuthorization()`: The <<oauth2-authorization, OAuth2Authorization>> associated with the authorization grant.
+<4> `getAuthorization()`: The xref:core-model-components.adoc#oauth2-authorization[OAuth2Authorization] associated with the authorization grant.
 <5> `getAuthorizedScopes()`: The scope(s) authorized for the client.
 <6> `getTokenType()`: The `OAuth2TokenType` to generate. The supported values are `code`, `access_token`, `refresh_token`, and `id_token`.
 <7> `getAuthorizationGrantType()`: The `AuthorizationGrantType` associated with the authorization grant.
@@ -349,7 +349,7 @@ public interface OAuth2TokenContext extends Context {
 [[oauth2-token-generator]]
 == OAuth2TokenGenerator
 
-An `OAuth2TokenGenerator` is responsible for generating an `OAuth2Token` from the information contained in the provided <<oauth2-token-context, OAuth2TokenContext>>.
+An `OAuth2TokenGenerator` is responsible for generating an `OAuth2Token` from the information contained in the provided xref:core-model-components.adoc#oauth2-token-context[OAuth2TokenContext].
 
 The `OAuth2Token` generated primarily depends on the type of `OAuth2TokenType` specified in the `OAuth2TokenContext`.
 
@@ -360,11 +360,11 @@ For example, when the `value` for `OAuth2TokenType` is:
 * `refresh_token`, then `OAuth2RefreshToken` is generated.
 * `id_token`, then `OidcIdToken` is generated.
 
-Furthermore, the format of the generated `OAuth2AccessToken` varies, depending on the `TokenSettings.getAccessTokenFormat()` configured for the <<registered-client, RegisteredClient>>.
+Furthermore, the format of the generated `OAuth2AccessToken` varies, depending on the `TokenSettings.getAccessTokenFormat()` configured for the xref:core-model-components.adoc#registered-client[RegisteredClient].
 If the format is `OAuth2TokenFormat.SELF_CONTAINED` (the default), then a `Jwt` is generated.
 If the format is `OAuth2TokenFormat.REFERENCE`, then an "opaque" token is generated.
 
-Finally, if the generated `OAuth2Token` has a set of claims and implements `ClaimAccessor`, the claims are made accessible from <<oauth2-authorization, OAuth2Authorization.Token.getClaims()>>.
+Finally, if the generated `OAuth2Token` has a set of claims and implements `ClaimAccessor`, the claims are made accessible from xref:core-model-components.adoc#oauth2-authorization[OAuth2Authorization.Token.getClaims()].
 
 The `OAuth2TokenGenerator` is primarily used by components that implement authorization grant processing – for example, `authorization_code`, `client_credentials`, and `refresh_token`.
 
@@ -419,8 +419,8 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi
 [[oauth2-token-customizer]]
 == OAuth2TokenCustomizer
 
-An `OAuth2TokenCustomizer` provides the ability to customize the attributes of an `OAuth2Token`, which are accessible in the provided <<oauth2-token-context, OAuth2TokenContext>>.
-It is used by an <<oauth2-token-generator, OAuth2TokenGenerator>> to let it customize the attributes of the `OAuth2Token` before it is generated.
+An `OAuth2TokenCustomizer` provides the ability to customize the attributes of an `OAuth2Token`, which are accessible in the provided xref:core-model-components.adoc#oauth2-token-context[OAuth2TokenContext].
+It is used by an xref:core-model-components.adoc#oauth2-token-generator[OAuth2TokenGenerator] to let it customize the attributes of the `OAuth2Token` before it is generated.
 
 An `OAuth2TokenCustomizer<OAuth2TokenClaimsContext>` declared with a generic type of `OAuth2TokenClaimsContext` (`implements OAuth2TokenContext`) provides the ability to customize the claims of an "opaque" `OAuth2AccessToken`.
 `OAuth2TokenClaimsContext.getClaims()` provides access to the `OAuth2TokenClaimsSet.Builder`, allowing the ability to add, replace, and remove claims.
@@ -492,7 +492,7 @@ public OAuth2TokenCustomizer<JwtEncodingContext> jwtCustomizer() {
 If the `OAuth2TokenGenerator` is not provided as a `@Bean` or is not configured through the `OAuth2AuthorizationServerConfigurer`, an `OAuth2TokenCustomizer<JwtEncodingContext>` `@Bean` will automatically be configured with a `JwtGenerator`.
 
 [TIP]
-For an example showing how you can xref:guides/how-to-userinfo.adoc#customize-id-token[customize the ID token], see the guide xref:guides/how-to-userinfo.adoc#how-to-userinfo[How-to: Customize the OpenID Connect 1.0 UserInfo response].
+For an example showing how you can xref:guides/how-to-userinfo.adoc#customize-id-token[customize the ID token], see the guide xref:guides/how-to-userinfo.adoc[How-to: Customize the OpenID Connect 1.0 UserInfo response].
 
 [[session-registry]]
 == SessionRegistry

docs/src/docs/asciidoc/getting-help.adoc → docs/modules/ROOT/pages/getting-help.adoc

@@ -1,5 +1,6 @@
 [[getting-help]]
 = Getting Help
+:page-section-summary-toc: 1
 
 [[community]]
 == Community

docs/src/docs/asciidoc/getting-started.adoc → docs/modules/ROOT/pages/getting-started.adoc

@@ -1,4 +1,3 @@
-include::attributes.adoc[]
 
 [[getting-started]]
 = Getting Started
@@ -19,8 +18,11 @@ The easiest way to begin using Spring Authorization Server is by creating a http
 You can use https://start.spring.io[start.spring.io] to generate a basic project or use the https://github.com/spring-projects/spring-authorization-server/tree/main/samples/default-authorizationserver[default authorization server sample] as a guide.
 Then add Spring Boot's starter for Spring Authorization Server as a dependency:
 
+[tabs]
+======
+Maven::
++
 [[spring-boot-maven-dependency]]
-.Maven
 [source,xml,role="primary",subs="attributes,verbatim"]
 ----
 <dependency>
@@ -29,19 +31,24 @@ Then add Spring Boot's starter for Spring Authorization Server as a dependency:
 </dependency>
 ----
 
+Gradle::
++
 [[spring-boot-gradle-dependency]]
-.Gradle
 [source,gradle,role="secondary",subs="attributes,verbatim"]
 ----
 implementation "org.springframework.boot:spring-boot-starter-oauth2-authorization-server"
 ----
+======
 
 TIP: See https://docs.spring.io/spring-boot/docs/current/reference/html/getting-started.html#getting-started.installing[Installing Spring Boot] for more information on using Spring Boot with Maven or Gradle.
 
 Alternatively, you can add Spring Authorization Server without Spring Boot using the following example:
 
+[tabs]
+======
+Maven::
++
 [[maven-dependency]]
-.Maven
 [source,xml,role="primary",subs="attributes,verbatim"]
 ----
 <dependency>
@@ -51,12 +58,14 @@ Alternatively, you can add Spring Authorization Server without Spring Boot using
 </dependency>
 ----
 
+Gradle::
++
 [[gradle-dependency]]
-.Gradle
 [source,gradle,role="secondary",subs="attributes,verbatim"]
 ----
 implementation "org.springframework.security:spring-security-oauth2-authorization-server:{spring-authorization-server-version}"
 ----
+======
 
 [[developing-your-first-application]]
 == Developing Your First Application
@@ -67,10 +76,10 @@ To get started, you need the minimum required components defined as a `@Bean`. W
 .application.yml
 [source,yaml]
 ----
-include::{docs-java}/sample/gettingStarted/application.yml[]
+include::{docs-java}/sample/gettingstarted/application.yml[]
 ----
 
-TIP: Beyond the Getting Started experience, most users will want to customize the default configuration. The <<defining-required-components,next section>> demonstrates providing all of the necessary beans yourself.
+TIP: Beyond the Getting Started experience, most users will want to customize the default configuration. The xref:getting-started.adoc#defining-required-components[next section] demonstrates providing all of the necessary beans yourself.
 
 [[defining-required-components]]
 == Defining Required Components
@@ -83,7 +92,7 @@ These components can be defined as follows:
 .SecurityConfig.java
 [source,java]
 ----
-include::{docs-java}/sample/gettingStarted/SecurityConfig.java[]
+include::{docs-java}/sample/gettingstarted/SecurityConfig.java[]
 ----
 
 This is a minimal configuration for getting started quickly. To understand what each component is used for, see the following descriptions:

docs/src/docs/asciidoc/guides/how-to-ext-grant-type.adoc → docs/modules/ROOT/pages/guides/how-to-ext-grant-type.adoc

@@ -1,20 +1,19 @@
-include::attributes.adoc[]
 
 [[how-to-extension-grant-type]]
 = How-to: Implement an Extension Authorization Grant Type
 :index-link: ../how-to.html
 :docs-dir: ..
 
-This guide shows how to extend xref:{docs-dir}/index.adoc#top[Spring Authorization Server] with an https://datatracker.ietf.org/doc/html/rfc6749#section-4.5[extension authorization grant type].
-The purpose of this guide is to demonstrate how to implement an extension authorization grant type and configure it at the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint].
+This guide shows how to extend xref:index.adoc[Spring Authorization Server] with an https://datatracker.ietf.org/doc/html/rfc6749#section-4.5[extension authorization grant type].
+The purpose of this guide is to demonstrate how to implement an extension authorization grant type and configure it at the xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint].
 
-Extending Spring Authorization Server with a new authorization grant type requires implementing an `AuthenticationConverter` and `AuthenticationProvider`, and configuring both components at the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint].
+Extending Spring Authorization Server with a new authorization grant type requires implementing an `AuthenticationConverter` and `AuthenticationProvider`, and configuring both components at the xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint].
 In addition to the component implementations, a unique absolute URI needs to be assigned for use with the `grant_type` parameter.
 
-* <<implement-authentication-converter>>
-* <<implement-authentication-provider>>
-* <<configure-token-endpoint>>
-* <<request-access-token>>
+* xref:guides/how-to-ext-grant-type.adoc#implement-authentication-converter[Implement AuthenticationConverter]
+* xref:guides/how-to-ext-grant-type.adoc#implement-authentication-provider[Implement AuthenticationProvider]
+* xref:guides/how-to-ext-grant-type.adoc#configure-token-endpoint[Configure OAuth2 Token Endpoint]
+* xref:guides/how-to-ext-grant-type.adoc#request-access-token[Request the Access Token]
 
 [[implement-authentication-converter]]
 == Implement AuthenticationConverter
@@ -24,14 +23,14 @@ Assuming the absolute URI for the `grant_type` parameter is `urn:ietf:params:oau
 .AuthenticationConverter
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationConverter.java[]
+include::{examples-dir}/main/java/sample/extgrant/CustomCodeGrantAuthenticationConverter.java[]
 ----
 
 TIP: Click on the "Expand folded text" icon in the code sample above to display the full example.
 
 <1> If the `grant_type` parameter is *not* `urn:ietf:params:oauth:grant-type:custom_code`, then return `null`, allowing another `AuthenticationConverter` to process the token request.
 <2> The `code` parameter contains the authorization grant.
-<3> Return an instance of `CustomCodeGrantAuthenticationToken`, which is processed by <<implement-authentication-provider,`CustomCodeGrantAuthenticationProvider`>>.
+<3> Return an instance of `CustomCodeGrantAuthenticationToken`, which is processed by xref:guides/how-to-ext-grant-type.adoc#implement-authentication-provider[`CustomCodeGrantAuthenticationProvider`].
 
 [[implement-authentication-provider]]
 == Implement AuthenticationProvider
@@ -43,20 +42,20 @@ The following example shows a sample implementation of the `AuthenticationProvid
 .AuthenticationProvider
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/extgrant/CustomCodeGrantAuthenticationProvider.java[]
+include::{examples-dir}/main/java/sample/extgrant/CustomCodeGrantAuthenticationProvider.java[]
 ----
 
-NOTE: `CustomCodeGrantAuthenticationProvider` processes `CustomCodeGrantAuthenticationToken`, which is created by <<implement-authentication-converter,`CustomCodeGrantAuthenticationConverter`>>.
+NOTE: `CustomCodeGrantAuthenticationProvider` processes `CustomCodeGrantAuthenticationToken`, which is created by xref:guides/how-to-ext-grant-type.adoc#implement-authentication-converter[`CustomCodeGrantAuthenticationConverter`].
 
 [[configure-token-endpoint]]
 == Configure OAuth2 Token Endpoint
 
-The following example shows how to configure the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint] with the `AuthenticationConverter` and `AuthenticationProvider`:
+The following example shows how to configure the xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint] with the `AuthenticationConverter` and `AuthenticationProvider`:
 
 .SecurityConfig
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/extgrant/SecurityConfig.java[]
+include::{examples-dir}/main/java/sample/extgrant/SecurityConfig.java[]
 ----
 
 <1> Add the `AuthenticationConverter` to the OAuth2 Token endpoint configuration.

docs/src/docs/asciidoc/guides/how-to-jpa.adoc → docs/modules/ROOT/pages/guides/how-to-jpa.adoc

@@ -1,37 +1,36 @@
-include::attributes.adoc[]
 
 [[how-to-jpa]]
 = How-to: Implement core services with JPA
 :index-link: ../how-to.html
 :docs-dir: ..
 
-This guide shows how to implement the xref:{docs-dir}/core-model-components.adoc#core-model-components[core services] of xref:{docs-dir}/index.adoc#top[Spring Authorization Server] with JPA.
+This guide shows how to implement the xref:core-model-components.adoc[core services] of xref:index.adoc[Spring Authorization Server] with JPA.
 The purpose of this guide is to provide a starting point for implementing these services yourself, with the intention that you can make modifications to suit your needs.
 
-* <<define-data-model>>
-* <<create-jpa-entities>>
-* <<create-spring-data-repositories>>
-* <<implement-core-services>>
+* xref:guides/how-to-jpa.adoc#define-data-model[Define the data model]
+* xref:guides/how-to-jpa.adoc#create-jpa-entities[Create JPA entities]
+* xref:guides/how-to-jpa.adoc#create-spring-data-repositories[Create Spring Data repositories]
+* xref:guides/how-to-jpa.adoc#implement-core-services[Implement core services]
 
 [[define-data-model]]
 == Define the data model
 
 This guide provides a starting point for the data model and uses the simplest possible structure and data types.
-To come up with the initial schema, we begin by reviewing the xref:{docs-dir}/core-model-components.adoc#core-model-components[domain objects] used by the core services.
+To come up with the initial schema, we begin by reviewing the xref:core-model-components.adoc[domain objects] used by the core services.
 
 [NOTE]
 Except for token, state, metadata, settings, and claims values, we use the JPA default column length of 255 for all columns.
 In reality, the length and even type of columns you use may need to be customized.
 You are encouraged to experiment and test before deploying to production.
 
-* <<client-schema>>
-* <<authorization-schema>>
-* <<authorization-consent-schema>>
+* xref:guides/how-to-jpa.adoc#client-schema[Client Schema]
+* xref:guides/how-to-jpa.adoc#authorization-schema[Authorization Schema]
+* xref:guides/how-to-jpa.adoc#authorization-consent-schema[Authorization Consent Schema]
 
 [[client-schema]]
 === Client Schema
 
-The xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object contains a few multi-valued fields and some settings fields that require storing arbitrary key/value data.
+The xref:core-model-components.adoc#registered-client[`RegisteredClient`] domain object contains a few multi-valued fields and some settings fields that require storing arbitrary key/value data.
 The following listing shows the `client` schema.
 
 .Client Schema
@@ -58,7 +57,7 @@ CREATE TABLE client (
 [[authorization-schema]]
 === Authorization Schema
 
-The xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object is more complex and contains several multi-valued fields as well as numerous arbitrarily long token values, metadata, settings and claims values.
+The xref:core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object is more complex and contains several multi-valued fields as well as numerous arbitrarily long token values, metadata, settings and claims values.
 The built-in JDBC implementation utilizes a flattened structure that prefers performance over normalization, which we adopt here as well.
 
 [CAUTION]
@@ -112,7 +111,7 @@ CREATE TABLE authorization (
 [[authorization-consent-schema]]
 === Authorization Consent Schema
 
-The xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object is the simplest to model and contains only a single multi-valued field in addition to a composite key.
+The xref:core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object is the simplest to model and contains only a single multi-valued field in addition to a composite key.
 The following listing shows the `authorizationConsent` schema.
 
 .Authorization Consent Schema
@@ -135,44 +134,44 @@ The preceding schema examples provide a reference for the structure of the entit
 The following entities are minimally annotated and are just examples.
 They allow the schema to be created dynamically and therefore do not require the above sql scripts to be executed manually.
 
-* <<client-entity>>
-* <<authorization-entity>>
-* <<authorization-consent-entity>>
+* xref:guides/how-to-jpa.adoc#client-entity[Client Entity]
+* xref:guides/how-to-jpa.adoc#authorization-entity[Authorization Entity]
+* xref:guides/how-to-jpa.adoc#authorization-consent-entity[Authorization Consent Entity]
 
 [[client-entity]]
 === Client Entity
 
-The following listing shows the `Client` entity, which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object.
+The following listing shows the `Client` entity, which is used to persist information mapped from the xref:core-model-components.adoc#registered-client[`RegisteredClient`] domain object.
 
 [[sample.jpa.entity.client]]
 .Client Entity
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/jpa/entity/client/Client.java[]
+include::{examples-dir}/main/java/sample/jpa/entity/client/Client.java[]
 ----
 
 [[authorization-entity]]
 === Authorization Entity
 
-The following listing shows the `Authorization` entity, which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object.
+The following listing shows the `Authorization` entity, which is used to persist information mapped from the xref:core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object.
 
 [[sample.jpa.entity.authorization]]
 .Authorization Entity
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/jpa/entity/authorization/Authorization.java[]
+include::{examples-dir}/main/java/sample/jpa/entity/authorization/Authorization.java[]
 ----
 
 [[authorization-consent-entity]]
 === Authorization Consent Entity
 
-The following listing shows the `AuthorizationConsent` entity, which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object.
+The following listing shows the `AuthorizationConsent` entity, which is used to persist information mapped from the xref:core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object.
 
 [[sample.jpa.entity.authorizationConsent]]
 .Authorization Consent Entity
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/jpa/entity/authorizationConsent/AuthorizationConsent.java[]
+include::{examples-dir}/main/java/sample/jpa/entity/authorizationConsent/AuthorizationConsent.java[]
 ----
 
 [[create-spring-data-repositories]]
@@ -180,51 +179,51 @@ include::{examples-dir}/src/main/java/sample/jpa/entity/authorizationConsent/Aut
 
 By closely examining the interfaces of each core service and reviewing the `Jdbc` implementations, we can derive a minimal set of queries needed for supporting a JPA version of each interface.
 
-* <<client-repository>>
-* <<authorization-repository>>
-* <<authorization-consent-repository>>
+* xref:guides/how-to-jpa.adoc#client-repository[Client Repository]
+* xref:guides/how-to-jpa.adoc#authorization-repository[Authorization Repository]
+* xref:guides/how-to-jpa.adoc#authorization-consent-repository[Authorization Consent Repository]
 
 [[client-repository]]
 === Client Repository
 
-The following listing shows the `ClientRepository`, which is able to find a <<client-entity,`Client`>> by the `id` and `clientId` fields.
+The following listing shows the `ClientRepository`, which is able to find a xref:guides/how-to-jpa.adoc#client-entity[`Client`] by the `id` and `clientId` fields.
 
 [[sample.jpa.repository.client]]
 .Client Repository
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/jpa/repository/client/ClientRepository.java[]
+include::{examples-dir}/main/java/sample/jpa/repository/client/ClientRepository.java[]
 ----
 
 [[authorization-repository]]
 === Authorization Repository
 
-The following listing shows the `AuthorizationRepository`, which is able to find an <<authorization-entity,`Authorization`>> by the `id` field as well as the `state`, `authorizationCodeValue`, `accessTokenValue`, `refreshTokenValue`, `userCodeValue` and `deviceCodeValue` token fields.
+The following listing shows the `AuthorizationRepository`, which is able to find an xref:guides/how-to-jpa.adoc#authorization-entity[`Authorization`] by the `id` field as well as the `state`, `authorizationCodeValue`, `accessTokenValue`, `refreshTokenValue`, `userCodeValue` and `deviceCodeValue` token fields.
 It also allows querying a combination of token fields.
 
 [[sample.jpa.repository.authorization]]
 .Authorization Repository
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/jpa/repository/authorization/AuthorizationRepository.java[]
+include::{examples-dir}/main/java/sample/jpa/repository/authorization/AuthorizationRepository.java[]
 ----
 
 [[authorization-consent-repository]]
 === Authorization Consent Repository
 
-The following listing shows the `AuthorizationConsentRepository`, which is able to find and delete an <<authorization-consent-entity,`AuthorizationConsent`>> by the `registeredClientId` and `principalName` fields that form a composite primary key.
+The following listing shows the `AuthorizationConsentRepository`, which is able to find and delete an xref:guides/how-to-jpa.adoc#authorization-consent-entity[`AuthorizationConsent`] by the `registeredClientId` and `principalName` fields that form a composite primary key.
 
 [[sample.jpa.repository.authorizationConsent]]
 .Authorization Consent Repository
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/jpa/repository/authorizationConsent/AuthorizationConsentRepository.java[]
+include::{examples-dir}/main/java/sample/jpa/repository/authorizationConsent/AuthorizationConsentRepository.java[]
 ----
 
 [[implement-core-services]]
 == Implement core services
 
-With the above <<create-jpa-entities,entities>> and <<create-spring-data-repositories,repositories>>, we can begin implementing the core services.
+With the above xref:guides/how-to-jpa.adoc#create-jpa-entities[entities] and xref:guides/how-to-jpa.adoc#create-spring-data-repositories[repositories], we can begin implementing the core services.
 By reviewing the `Jdbc` implementations, we can derive a minimal set of internal utilities for converting to and from string values for enumerations and reading and writing JSON data for attributes, settings, metadata and claims fields.
 
 [CAUTION]
@@ -232,41 +231,41 @@ Keep in mind that writing JSON data to text columns with a fixed length has prov
 While these examples continue to do so, you may need to split these fields out into a separate table or data store that supports arbitrarily long data values.
 
 * <<registered-client-repository>>
-* <<authorization-service>>
-* <<authorization-consent-service>>
+* xref:guides/how-to-jpa.adoc#authorization-service[Authorization Service]
+* xref:guides/how-to-jpa.adoc#authorization-consent-service[Authorization Consent Service]
 
 [[registered-client-repository]]
 === Registered Client Repository
 
-The following listing shows the `JpaRegisteredClientRepository`, which uses a <<client-repository,`ClientRepository`>> for persisting a <<client-entity,`Client`>> and maps to and from the xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object.
+The following listing shows the `JpaRegisteredClientRepository`, which uses a xref:guides/how-to-jpa.adoc#client-repository[`ClientRepository`] for persisting a xref:guides/how-to-jpa.adoc#client-entity[`Client`] and maps to and from the xref:core-model-components.adoc#registered-client[`RegisteredClient`] domain object.
 
 [[sample.jpa.service.client]]
 .`RegisteredClientRepository` Implementation
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/jpa/service/client/JpaRegisteredClientRepository.java[]
+include::{examples-dir}/main/java/sample/jpa/service/client/JpaRegisteredClientRepository.java[]
 ----
 
 [[authorization-service]]
 === Authorization Service
 
-The following listing shows the `JpaOAuth2AuthorizationService`, which uses an <<authorization-repository,`AuthorizationRepository`>> for persisting an <<authorization-entity,`Authorization`>> and maps to and from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object.
+The following listing shows the `JpaOAuth2AuthorizationService`, which uses an xref:guides/how-to-jpa.adoc#authorization-repository[`AuthorizationRepository`] for persisting an xref:guides/how-to-jpa.adoc#authorization-entity[`Authorization`] and maps to and from the xref:core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object.
 
 [[sample.jpa.service.authorization]]
 .`OAuth2AuthorizationService` Implementation
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/jpa/service/authorization/JpaOAuth2AuthorizationService.java[]
+include::{examples-dir}/main/java/sample/jpa/service/authorization/JpaOAuth2AuthorizationService.java[]
 ----
 
 [[authorization-consent-service]]
 === Authorization Consent Service
 
-The following listing shows the `JpaOAuth2AuthorizationConsentService`, which uses an <<authorization-consent-repository,`AuthorizationConsentRepository`>> for persisting an <<authorization-consent-entity,`AuthorizationConsent`>> and maps to and from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object.
+The following listing shows the `JpaOAuth2AuthorizationConsentService`, which uses an xref:guides/how-to-jpa.adoc#authorization-consent-repository[`AuthorizationConsentRepository`] for persisting an xref:guides/how-to-jpa.adoc#authorization-consent-entity[`AuthorizationConsent`] and maps to and from the xref:core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object.
 
 [[sample.jpa.service.authorizationConsent]]
 .`OAuth2AuthorizationConsentService` Implementation
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/jpa/service/authorizationConsent/JpaOAuth2AuthorizationConsentService.java[]
+include::{examples-dir}/main/java/sample/jpa/service/authorizationConsent/JpaOAuth2AuthorizationConsentService.java[]
 ----

docs/src/docs/asciidoc/guides/how-to-pkce.adoc → docs/modules/ROOT/pages/guides/how-to-pkce.adoc

@@ -1,18 +1,17 @@
-include::attributes.adoc[]
 
 [[how-to-pkce]]
 = How-to: Authenticate using a Single Page Application with PKCE
 :index-link: ../how-to.html
 :docs-dir: ..
 
-This guide shows how to configure xref:{docs-dir}/index.adoc#top[Spring Authorization Server] to support a Single Page Application (SPA) with Proof Key for Code Exchange (PKCE).
+This guide shows how to configure xref:index.adoc[Spring Authorization Server] to support a Single Page Application (SPA) with Proof Key for Code Exchange (PKCE).
 The purpose of this guide is to demonstrate how to support a public client and require PKCE for client authentication.
 
 NOTE: Spring Authorization Server will not issue refresh tokens for a public client. We recommend the backend for frontend (BFF) pattern as an alternative to exposing a public client. See https://github.com/spring-projects/spring-authorization-server/issues/297#issue-896744390[gh-297] for more information.
 
-* <<enable-cors>>
-* <<configure-public-client>>
-* <<authenticate-with-client>>
+* xref:guides/how-to-pkce.adoc#enable-cors[Enable CORS]
+* xref:guides/how-to-pkce.adoc#configure-public-client[Configure a Public Client]
+* xref:guides/how-to-pkce.adoc#authenticate-with-client[Authenticate with the Client]
 
 [[enable-cors]]
 == Enable CORS
@@ -28,7 +27,7 @@ For example, if you have an Angular dev server running locally on port `4200`, y
 .Enable CORS
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/pkce/SecurityConfig.java[]
+include::{examples-dir}/main/java/sample/pkce/SecurityConfig.java[]
 ----
 
 TIP: Click on the "Expand folded text" icon in the code sample above to display the full example.
@@ -39,22 +38,27 @@ TIP: Click on the "Expand folded text" icon in the code sample above to display
 A SPA cannot securely store credentials and therefore must be treated as a https://datatracker.ietf.org/doc/html/rfc6749#section-2.1[public client^].
 Public clients should be required to use https://datatracker.ietf.org/doc/html/rfc7636#section-4[Proof Key for Code Exchange] (PKCE).
 
-Continuing the <<enable-cors-configuration,earlier>> example, you can configure Spring Authorization Server to support a public client using the Client Authentication Method `none` and require PKCE as in the following example:
+Continuing the xref:guides/how-to-pkce.adoc#enable-cors-configuration[earlier] example, you can configure Spring Authorization Server to support a public client using the Client Authentication Method `none` and require PKCE as in the following example:
 
+[tabs]
+======
+Yaml::
++
 [[configure-public-client-example]]
-.Yaml
 [source,yaml,role="primary"]
 ----
-include::{examples-dir}/src/main/java/sample/pkce/application.yml[]
+include::{examples-dir}/main/java/sample/pkce/application.yml[]
 ----
 
-.Java
+Java::
++
 [source,java,role="secondary"]
 ----
-include::{examples-dir}/src/main/java/sample/pkce/ClientConfig.java[tag=client,indent=0]
+include::{examples-dir}/main/java/sample/pkce/ClientConfig.java[tag=client,indent=0]
 ----
+======
 
-NOTE: The `requireProofKey` setting is helpful in situations where you forget to include the `code_challenge` and `code_challenge_method` query parameters because you will receive an error indicating PKCE is required during the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-authorization-endpoint[Authorization Request] instead of a general client authentication error during the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[Token Request].
+NOTE: The `requireProofKey` setting is helpful in situations where you forget to include the `code_challenge` and `code_challenge_method` query parameters because you will receive an error indicating PKCE is required during the xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[Authorization Request] instead of a general client authentication error during the xref:protocol-endpoints.adoc#oauth2-token-endpoint[Token Request].
 
 [[authenticate-with-client]]
 == Authenticate with the Client
@@ -67,11 +71,11 @@ NOTE: A SPA is a browser-based application and therefore uses the same redirecti
 A more detailed answer requires an understanding of the flow(s) involved in OAuth2 and OpenID Connect, in this case the Authorization Code flow.
 The steps of the Authorization Code flow are as follows:
 
-1. The client initiates an OAuth2 request via a redirect to the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-authorization-endpoint[Authorization Endpoint]. For a public client, this step includes generating the `code_verifier` and calculating the `code_challenge`, which is then sent as a query parameter.
+1. The client initiates an OAuth2 request via a redirect to the xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[Authorization Endpoint]. For a public client, this step includes generating the `code_verifier` and calculating the `code_challenge`, which is then sent as a query parameter.
 2. If the user is not authenticated, the authorization server will redirect to the login page. After authentication, the user is redirected back to the Authorization Endpoint again.
 3. If the user has not consented to the requested scope(s) and consent is required, the consent page is displayed.
 4. Once the user has consented, the authorization server generates an `authorization_code` and redirects back to the client via the `redirect_uri`.
-5. The client obtains the `authorization_code` via a query parameter and performs a request to the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[Token Endpoint]. For a public client, this step includes sending the `code_verifier` parameter instead of credentials for authentication.
+5. The client obtains the `authorization_code` via a query parameter and performs a request to the xref:protocol-endpoints.adoc#oauth2-token-endpoint[Token Endpoint]. For a public client, this step includes sending the `code_verifier` parameter instead of credentials for authentication.
 
 As you can see, the flow is fairly involved and this overview only scratches the surface.
 

docs/src/docs/asciidoc/guides/how-to-social-login.adoc → docs/modules/ROOT/pages/guides/how-to-social-login.adoc

@@ -1,4 +1,3 @@
-include::attributes.adoc[]
 
 [[how-to-social-login]]
 = How-to: Authenticate using Social Login
@@ -7,14 +6,14 @@ include::attributes.adoc[]
 :github-ref: main
 :github-base-url: https://github.com/spring-projects/spring-authorization-server/blob/{github-ref}
 
-This guide shows how to configure xref:{docs-dir}/index.adoc#top[Spring Authorization Server] with a social login provider (such as Google, GitHub, etc.) for {spring-security-reference-base-url}/servlet/authentication/index.html[authentication].
+This guide shows how to configure xref:index.adoc[Spring Authorization Server] with a social login provider (such as Google, GitHub, etc.) for {spring-security-reference-base-url}/servlet/authentication/index.html[authentication].
 The purpose of this guide is to demonstrate how to replace {spring-security-reference-base-url}/servlet/authentication/passwords/form.html[Form Login] with {spring-security-reference-base-url}/servlet/oauth2/login/index.html[OAuth 2.0 Login].
 
 NOTE: Spring Authorization Server is built on {spring-security-reference-base-url}/index.html[Spring Security] and we will be using Spring Security concepts throughout this guide.
 
-* <<register-social-login-provider>>
-* <<configure-oauth2-login>>
-* <<advanced-use-cases>>
+* xref:guides/how-to-social-login.adoc#register-social-login-provider[Register with Social Login Provider]
+* xref:guides/how-to-social-login.adoc#configure-oauth2-login[Configure OAuth 2.0 Login]
+* xref:guides/how-to-social-login.adoc#advanced-use-cases[Advanced Use Cases]
 
 [[register-social-login-provider]]
 == Register with Social Login Provider
@@ -46,19 +45,22 @@ In addition, you will need to reference the provider's documentation and take no
 [[configure-oauth2-login]]
 == Configure OAuth 2.0 Login
 
-Once you've <<register-social-login-provider,registered>> with a social login provider, you can proceed to configuring Spring Security for {spring-security-reference-base-url}/servlet/oauth2/login/index.html[OAuth 2.0 Login].
+Once you've xref:guides/how-to-social-login.adoc#register-social-login-provider[registered] with a social login provider, you can proceed to configuring Spring Security for {spring-security-reference-base-url}/servlet/oauth2/login/index.html[OAuth 2.0 Login].
 
-* <<configure-oauth2-login-dependency>>
-* <<configure-oauth2-login-client-registration>>
-* <<configure-oauth2-login-authentication>>
+* xref:guides/how-to-social-login.adoc#configure-oauth2-login-dependency[Add OAuth2 Client Dependency]
+* xref:guides/how-to-social-login.adoc#configure-oauth2-login-client-registration[Register a Client]
+* xref:guides/how-to-social-login.adoc#configure-oauth2-login-authentication[Configure Authentication]
 
 [[configure-oauth2-login-dependency]]
 === Add OAuth2 Client Dependency
 
 First, add the following dependency:
 
+[tabs]
+======
+Maven::
++
 [[configure-oauth2-login-maven-dependency]]
-.Maven
 [source,xml,role="primary",subs="attributes,verbatim"]
 ----
 <dependency>
@@ -67,24 +69,26 @@ First, add the following dependency:
 </dependency>
 ----
 
+Gradle::
++
 [[configure-oauth2-login-gradle-dependency]]
-.Gradle
 [source,gradle,role="secondary",subs="attributes,verbatim"]
 ----
 implementation "org.springframework.boot:spring-boot-starter-oauth2-client"
 ----
+======
 
 [[configure-oauth2-login-client-registration]]
 === Register a Client
 
-Next, configure the `ClientRegistration` with the values obtained <<register-social-login-provider,earlier>>.
+Next, configure the `ClientRegistration` with the values obtained xref:guides/how-to-social-login.adoc#register-social-login-provider[earlier].
 Using Okta as an example, configure the following properties:
 
 [[configure-oauth2-login-okta-example]]
 .application.yml
 [source,yaml]
 ----
-include::{examples-dir}/src/main/java/sample/socialLogin/application.yml[]
+include::{examples-dir}/main/java/sample/sociallogin/application.yml[]
 ----
 
 NOTE: The `registrationId` in the above example is `my-client`.
@@ -100,12 +104,12 @@ For more information about configuring the `ClientRegistration`, see {spring-sec
 Finally, to configure Spring Authorization Server to use a social login provider for authentication, you can use `oauth2Login()` instead of `formLogin()`.
 You can also automatically redirect an unauthenticated user to the provider by configuring `exceptionHandling()` with an `AuthenticationEntryPoint`.
 
-Continuing our <<configure-oauth2-login-okta-example,earlier example>>, configure Spring Security using a `@Configuration` as in the following example:
+Continuing our xref:guides/how-to-social-login.adoc#configure-oauth2-login-okta-example[earlier example], configure Spring Security using a `@Configuration` as in the following example:
 
 .Configure OAuth 2.0 Login
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/socialLogin/SecurityConfig.java[]
+include::{examples-dir}/main/java/sample/sociallogin/SecurityConfig.java[]
 ----
 
 <1> A Spring Security filter chain for the xref:{docs-dir}/protocol-endpoints.adoc[Protocol Endpoints].
@@ -113,7 +117,7 @@ include::{examples-dir}/src/main/java/sample/socialLogin/SecurityConfig.java[]
 <3> A Spring Security filter chain for https://docs.spring.io/spring-security/reference/servlet/authentication/index.html[authentication].
 <4> Configure {spring-security-reference-base-url}/servlet/oauth2/login/index.html[OAuth 2.0 Login] for authentication.
 
-If you configured a `UserDetailsService` when xref:{docs-dir}/getting-started.adoc#developing-your-first-application[getting started], you can remove it now.
+If you configured a `UserDetailsService` when xref:getting-started.adoc#developing-your-first-application[getting started], you can remove it now.
 
 [[advanced-use-cases]]
 == Advanced Use Cases
@@ -121,8 +125,8 @@ If you configured a `UserDetailsService` when xref:{docs-dir}/getting-started.ad
 The https://github.com/spring-projects/spring-authorization-server/tree/{github-ref}/samples#demo-sample[demo authorization server sample^] demonstrates advanced configuration options for federating identity providers.
 Select from the following use cases to see an example of each:
 
-* I want to <<advanced-use-cases-capture-users>>
-* I want to <<advanced-use-cases-map-claims>>
+* I want to xref:guides/how-to-social-login.adoc#advanced-use-cases-capture-users[Capture Users in a Database]
+* I want to xref:guides/how-to-social-login.adoc#advanced-use-cases-map-claims[Map Claims to an ID Token]
 
 [[advanced-use-cases-capture-users]]
 === Capture Users in a Database

docs/src/docs/asciidoc/guides/how-to-userinfo.adoc → docs/modules/ROOT/pages/guides/how-to-userinfo.adoc

@@ -1,20 +1,19 @@
-include::attributes.adoc[]
 
 [[how-to-userinfo]]
 = How-to: Customize the OpenID Connect 1.0 UserInfo response
 :index-link: ../how-to.html
 :docs-dir: ..
 
-This guide shows how to customize the xref:{docs-dir}/protocol-endpoints.adoc#oidc-user-info-endpoint[UserInfo endpoint] of the xref:{docs-dir}/index.adoc#top[Spring Authorization Server].
+This guide shows how to customize the xref:protocol-endpoints.adoc#oidc-user-info-endpoint[UserInfo endpoint] of the xref:index.adoc[Spring Authorization Server].
 The purpose of this guide is to demonstrate how to enable the endpoint and use the available customization options to produce a custom response.
 
-* <<enable-user-info>>
-* <<customize-user-info>>
+* xref:guides/how-to-userinfo.adoc#enable-user-info[Enable the User Info Endpoint]
+* xref:guides/how-to-userinfo.adoc#customize-user-info[Customize the User Info response]
 
 [[enable-user-info]]
 == Enable the User Info Endpoint
 
-The xref:{docs-dir}/protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint] is an OAuth2 protected resource, which *REQUIRES* an access token to be sent as a bearer token in the https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest[UserInfo request].
+The xref:protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint] is an OAuth2 protected resource, which *REQUIRES* an access token to be sent as a bearer token in the https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest[UserInfo request].
 
 > The Access Token obtained from an OpenID Connect Authentication Request MUST be sent as a Bearer Token, per Section 2 of https://openid.net/specs/openid-connect-core-1_0.html#RFC6750[OAuth 2.0 Bearer Token Usage] [RFC6750].
 
@@ -24,7 +23,7 @@ The following listing shows how to enable the {spring-security-reference-base-ur
 [[sample.userinfo]]
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java[]
+include::{examples-dir}/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java[]
 ----
 
 TIP: Click on the "Expand folded text" icon in the code sample above to display the full example.
@@ -40,13 +39,13 @@ This configuration provides the following:
 
 The following sections describe some options for customizing the user info response.
 
-* <<customize-id-token>>
-* <<customize-user-info-mapper>>
+* xref:guides/how-to-userinfo.adoc#customize-id-token[Customize the ID Token]
+* xref:guides/how-to-userinfo.adoc#customize-user-info-mapper[Customize the User Info Mapper]
 
 [[customize-id-token]]
 === Customize the ID Token
 
-By default, the user info response is generated by using claims from the `id_token` that are returned with the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[token response].
+By default, the user info response is generated by using claims from the `id_token` that are returned with the xref:protocol-endpoints.adoc#oauth2-token-endpoint[token response].
 Using the default strategy, https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[standard claims] are returned only with the user info response based on the https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[requested scopes] during authorization.
 
 The preferred way to customize the user info response is to add standard claims to the `id_token`.
@@ -55,36 +54,36 @@ The following listing shows how to add claims to the `id_token`.
 [[sample.userinfo.idtoken]]
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java[]
+include::{examples-dir}/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java[]
 ----
 
 This configuration provides the following:
 
-<1> An instance of xref:{docs-dir}/core-model-components.adoc#oauth2-token-customizer[`OAuth2TokenCustomizer`] for customizing the `id_token`.
+<1> An instance of xref:core-model-components.adoc#oauth2-token-customizer[`OAuth2TokenCustomizer`] for customizing the `id_token`.
 <2> A custom service used to obtain user info in a domain-specific way.
 
 The following listing shows a custom service for looking up user info in a domain-specific way:
 
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/userinfo/idtoken/OidcUserInfoService.java[]
+include::{examples-dir}/main/java/sample/userinfo/idtoken/OidcUserInfoService.java[]
 ----
 
 [[customize-user-info-mapper]]
 === Customize the User Info Mapper
 
 To fully customize the user info response, you can provide a custom user info mapper capable of generating the object used to render the response, which is an instance of the `OidcUserInfo` class from Spring Security.
-The mapper implementation receives an instance of `OidcUserInfoAuthenticationContext` with information about the current request, including the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`].
+The mapper implementation receives an instance of `OidcUserInfoAuthenticationContext` with information about the current request, including the xref:core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`].
 
 The following listing shows how to use the customization option that is available while working directly with the `OAuth2AuthorizationServerConfigurer`.
 
 [[sample.userinfo.jwt]]
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java[]
+include::{examples-dir}/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java[]
 ----
 
-This configuration maps claims from the access token (which is a JWT when using the xref:{docs-dir}/getting-started.adoc#sample.gettingStarted[Getting Started config]) to populate the user info response and provides the following:
+This configuration maps claims from the access token (which is a JWT when using the xref:getting-started.adoc#sample.gettingStarted[Getting Started config]) to populate the user info response and provides the following:
 
 <1> A Spring Security filter chain for the xref:{docs-dir}/protocol-endpoints.adoc[Protocol Endpoints].
 <2> A user info mapper that maps claims in a domain-specific way.
@@ -93,11 +92,11 @@ This configuration maps claims from the access token (which is a JWT when using
 <5> An example showing how to apply the `OAuth2AuthorizationServerConfigurer` to the Spring Security configuration.
 
 The user info mapper is not limited to mapping claims from a JWT, but this is a simple example that demonstrates the customization option.
-Similar to the <<customize-id-token,example shown earlier>> where we customize claims of the ID token, you can customize claims of the access token itself ahead of time, as in the following example:
+Similar to the xref:guides/how-to-userinfo.adoc#customize-id-token[example shown earlier] where we customize claims of the ID token, you can customize claims of the access token itself ahead of time, as in the following example:
 
 [source,java]
 ----
-include::{examples-dir}/src/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java[]
+include::{examples-dir}/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java[]
 ----
 
 Whether you customize the user info response directly or use this example and customize the access token, you can look up information in a database, perform an LDAP query, make a request to another service, or use any other means of obtaining the information you want to be presented in the user info response.

docs/src/docs/asciidoc/how-to.adoc → docs/modules/ROOT/pages/how-to.adoc

@@ -1,7 +1,7 @@
-include::attributes.adoc[]
 
 [[how-to]]
 = How-to Guides
+:page-section-summary-toc: 1
 
 [[how-to-overview]]
 == List of Guides

docs/src/docs/asciidoc/overview.adoc → docs/modules/ROOT/pages/index.adoc

@@ -1,8 +1,23 @@
-[[overview]]
+[[top]]
 = Overview
+:page-section-summary-toc: 1
+Joe Grandja, Steve Riesenberg
+v{spring-authorization-server-version}
+:docinfo: private-footer
+:nofooter:
 
 This site contains reference documentation and how-to guides for Spring Authorization Server.
 
+[horizontal]
+xref:index.adoc#introducing-spring-authorization-server[Introduction] :: Introduction and feature list
+xref:getting-help.adoc[Getting Help] :: Links to samples, questions and issues
+xref:getting-started.adoc[Getting Started] :: System requirements, dependencies and developing your first application
+xref:configuration-model.adoc[Configuration Model] :: Default configuration and customizing the configuration
+xref:core-model-components.adoc[Core Model / Components] :: Core domain model and component interfaces
+xref:protocol-endpoints.adoc[Protocol Endpoints] :: OAuth2 and OpenID Connect 1.0 protocol endpoint implementations
+xref:how-to.adoc[How-to Guides] :: Guides to get the most from Spring Authorization Server
+
+
 [[introducing-spring-authorization-server]]
 == Introducing Spring Authorization Server
 

docs/src/docs/asciidoc/protocol-endpoints.adoc → docs/modules/ROOT/pages/protocol-endpoints.adoc

@@ -572,7 +572,7 @@ public JwtDecoder jwtDecoder(JWKSource<SecurityContext> jwkSource) {
 A `JwtDecoder` `@Bean` is *REQUIRED* for the OpenID Connect 1.0 UserInfo endpoint.
 
 [TIP]
-The guide xref:guides/how-to-userinfo.adoc#how-to-userinfo[How-to: Customize the OpenID Connect 1.0 UserInfo response] contains examples of customizing the UserInfo endpoint.
+The guide xref:guides/how-to-userinfo.adoc[How-to: Customize the OpenID Connect 1.0 UserInfo response] contains examples of customizing the UserInfo endpoint.
 
 [[oidc-client-registration-endpoint]]
 == OpenID Connect 1.0 Client Registration Endpoint

docs/spring-authorization-server-docs.gradle

@@ -1,17 +1,34 @@
 plugins {
 	id "io.spring.convention.docs"
+	id 'io.spring.antora.generate-antora-yml' version '0.0.1'
+	id 'org.antora' version '1.0.0'
+	id "java"
 }
 
-asciidoctor {
-	attributes([
-			"spring-authorization-server-version": project.version,
-			"spring-security-reference-base-url": "https://docs.spring.io/spring-security/reference",
-			"spring-security-api-base-url": "https://docs.spring.io/spring-security/site/docs/current/api",
-			"spring-boot-reference-base-url": "https://docs.spring.io/spring-boot/docs/current/reference/html",
-			"chomp": "default headers packages",
-			"toc": "left",
-			"toclevels": "4"
-	])
+group = project.rootProject.group
+version = project.rootProject.version
+sourceCompatibility = "17"
+
+antora {
+	playbook = 'cached-antora-playbook.yml'
+	playbookProvider {
+		repository = 'rwinch/spring-authorization-server'
+		branch = 'docs-build'
+		path = 'lib/antora/templates/per-branch-antora-playbook.yml'
+		checkLocalBranch = true
+	}
+	options = [clean: true, fetch: !project.gradle.startParameter.offline, stacktrace: true]
+}
+
+tasks.named("generateAntoraYml") {
+	asciidocAttributes = project.provider( { generateAttributes() } )
+}
+
+
+def generateAttributes() {
+	return [
+			"spring-authorization-server-version": project.version
+	]
 }
 
 docsZip {
@@ -22,3 +39,29 @@ docsZip {
 		into "reference/html"
 	}
 }
+
+repositories {
+	mavenCentral()
+	maven { url "https://repo.spring.io/milestone" }
+}
+
+dependencies {
+	implementation(platform("org.springframework.boot:spring-boot-dependencies:3.1.0")) {
+		exclude group: "org.springframework.security", module: "spring-security-oauth2-authorization-server"
+	}
+	implementation platform("org.springframework.security:spring-security-bom:6.1.0")
+	implementation "org.springframework.boot:spring-boot-starter-web"
+	implementation "org.springframework.boot:spring-boot-starter-thymeleaf"
+	implementation "org.springframework.boot:spring-boot-starter-security"
+	implementation "org.springframework.boot:spring-boot-starter-oauth2-client"
+	implementation "org.springframework.boot:spring-boot-starter-oauth2-resource-server"
+	implementation "org.springframework.boot:spring-boot-starter-data-jpa"
+	implementation project(":spring-security-oauth2-authorization-server")
+	runtimeOnly "com.h2database:h2"
+	testImplementation "org.springframework.boot:spring-boot-starter-test"
+	testImplementation "org.springframework.security:spring-security-test"
+}
+
+tasks.named("test") {
+	useJUnitPlatform()
+}

docs/src/docs/asciidoc/attributes.adoc

@@ -1,3 +0,0 @@
-:examples-dir:                  examples
-:samples-dir:                   ../../../../samples
-:docs-java:                     {docdir}/examples/src/main/java

docs/src/docs/asciidoc/examples/spring-authorization-server-docs-examples.gradle

@@ -1,33 +0,0 @@
-plugins {
-	id "java"
-}
-
-group = project.rootProject.group
-version = project.rootProject.version
-sourceCompatibility = "17"
-
-repositories {
-	mavenCentral()
-	maven { url "https://repo.spring.io/milestone" }
-}
-
-dependencies {
-	implementation(platform("org.springframework.boot:spring-boot-dependencies:3.1.0")) {
-		exclude group: "org.springframework.security", module: "spring-security-oauth2-authorization-server"
-	}
-	implementation platform("org.springframework.security:spring-security-bom:6.1.0")
-	implementation "org.springframework.boot:spring-boot-starter-web"
-	implementation "org.springframework.boot:spring-boot-starter-thymeleaf"
-	implementation "org.springframework.boot:spring-boot-starter-security"
-	implementation "org.springframework.boot:spring-boot-starter-oauth2-client"
-	implementation "org.springframework.boot:spring-boot-starter-oauth2-resource-server"
-	implementation "org.springframework.boot:spring-boot-starter-data-jpa"
-	implementation project(":spring-security-oauth2-authorization-server")
-	runtimeOnly "com.h2database:h2"
-	testImplementation "org.springframework.boot:spring-boot-starter-test"
-	testImplementation "org.springframework.security:spring-security-test"
-}
-
-tasks.named("test") {
-	useJUnitPlatform()
-}

docs/src/docs/asciidoc/guides/attributes.adoc

@@ -1,3 +0,0 @@
-:examples-dir:                  ../examples
-:samples-dir:                   ../../../../../samples
-:docs-java:                     {docdir}/examples/src/main/java

docs/src/docs/asciidoc/index.adoc

@@ -1,15 +0,0 @@
-[[top]]
-= Spring Authorization Server Reference
-Joe Grandja, Steve Riesenberg
-v{spring-authorization-server-version}
-:docinfo: private-footer
-:nofooter:
-
-[horizontal]
-xref:overview.adoc[Overview] :: Introduction and feature list
-xref:getting-help.adoc[Getting Help] :: Links to samples, questions and issues
-xref:getting-started.adoc[Getting Started] :: System requirements, dependencies and developing your first application
-xref:configuration-model.adoc[Configuration Model] :: Default configuration and customizing the configuration
-xref:core-model-components.adoc[Core Model / Components] :: Core domain model and component interfaces
-xref:protocol-endpoints.adoc[Protocol Endpoints] :: OAuth2 and OpenID Connect 1.0 protocol endpoint implementations
-xref:how-to.adoc[How-to Guides] :: Guides to get the most from Spring Authorization Server

docs/src/docs/asciidoc/examples/src/main/java/sample/gettingStarted/SecurityConfig.java → docs/src/main/java/sample/gettingstarted/SecurityConfig.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package sample.gettingStarted;
+package sample.gettingstarted;
 
 import java.security.KeyPair;
 import java.security.KeyPairGenerator;

docs/src/docs/asciidoc/examples/src/main/java/sample/socialLogin/SecurityConfig.java → docs/src/main/java/sample/sociallogin/SecurityConfig.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package sample.socialLogin;
+package sample.sociallogin;
 
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;

docs/src/docs/asciidoc/examples/src/test/java/sample/gettingStarted/SecurityConfigTests.java → docs/src/test/java/sample/gettingstarted/SecurityConfigTests.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package sample.gettingStarted;
+package sample.gettingstarted;
 
 import java.util.Map;