KEYCLOAK-11918 Add latest and archive builds to documentation

README.md

@@ -36,6 +36,10 @@ Or to build a specific guide run:
 
     mvn clean install -f GUIDE_DIR
     
+By default an archive version of the documentation is built. To build a latest build run:
+
+    mvn clean install -Dlatest
+
 You can then view the documentation by opening GUIDE_DIR/target/generated-docs/index.html.
 
 

aggregation/navbar-head.html

@@ -13,6 +13,44 @@
 #tocbot a.toc-link.node-name--H4{ display:none }
 }
 
+.versionarchive {
+    display: inline-block;
+}
+
+.versionarchive p {
+    background-color: #eee;
+    border-radius: 5px;
+    margin: 0;
+    padding: 2px 5px 2px 10px;
+}
+
+.versionarchive a {
+    background-color: #ffdd57;
+    padding: 0 5px;
+    font-style: normal;
+    border-radius: 5px;
+    margin-left: 10px;
+}
+
+.versionlatest {
+    display: inline-block;
+}
+
+.versionlatest p {
+    background-color: #eee;
+    border-radius: 5px;
+    margin: 0;
+    padding: 2px 5px 2px 10px;
+}
+
+.versionlatest em {
+    background-color: #23d160;
+    padding: 0 5px;
+    font-style: normal;
+    border-radius: 5px;
+    margin-left: 10px;
+}
+
 /* Fix scroll to anchor hides title */
 h1::before, h2::before, h3::before, h4::before, h5::before, h6::before {
     display: block;

authorization_services/index.adoc

@@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
 
 = {authorizationguide_name}
 
+:release_header_latest_link: {authorizationguide_link_latest}
+include::topics/templates/release-header.adoc[]
+
 include::topics.adoc[]

getting_started/index.adoc

@@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
 
 = {gettingstarted_name}
 
+:release_header_latest_link: {gettingstarted_link_latest}
+include::topics/templates/release-header.adoc[]
+
 include::topics.adoc[]

pom.xml

@@ -22,9 +22,10 @@
         <version.jar.plugin>3.0.2</version.jar.plugin>
         <version.install.plugin>2.5.2</version.install.plugin>
 
-
         <maven.compiler.target>1.8</maven.compiler.target>
         <maven.compiler.source>1.8</maven.compiler.source>
+
+        <buildType>archive</buildType>
     </properties>
 
     <modules>
@@ -56,6 +57,17 @@
                 <imagesDir>rhsso-images</imagesDir>
             </properties>
         </profile>
+        <profile>
+            <id>latest</id>
+            <activation>
+                <property>
+                    <name>latest</name>
+                </property>
+            </activation>
+            <properties>
+                <buildType>latest</buildType>
+            </properties>
+        </profile>
     </profiles>
 
     <build>
@@ -93,7 +105,7 @@
                             </goals>
                             <configuration>
                                 <target>
-                                    <echo>OUTPUT: file://${project.build.directory}/generated-docs/${masterFile}.html</echo>
+                                    <echo>OUTPUT: file://${project.build.directory}/generated-docs/${masterFile}.html ${projectLatestBuild}</echo>
                                 </target>
                             </configuration>
                         </execution>
@@ -117,7 +129,6 @@
                             <configuration>
                                 <masterFile>${masterFile}</masterFile>
                             </configuration>
-
                         </execution>
                     </executions>
                 </plugin>
@@ -148,6 +159,7 @@
                                     <idseparator>-</idseparator>
                                     <docinfo1>true</docinfo1>
                                     <masterFile>${masterFile}</masterFile>
+                                    <project_buildType>${buildType}</project_buildType>
                                 </attributes>
                                 <resources>
                                     <resource>

release_notes/index.adoc

@@ -9,6 +9,9 @@ include::topics/templates/document-attributes-community.adoc[]
 
 = {releasenotes_name}
 
+:release_header_latest_link: {releasenotes_link_latest}
+include::topics/templates/release-header.adoc[]
+
 == {project_name_full} 7.0.1.Final
 include::topics/7_0_1_final.adoc[leveloffset=2]
 

securing_apps/index.adoc

@@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
 
 = {adapterguide_name}
 
+:release_header_latest_link: {adapterguide_link_latest}
+include::topics/templates/release-header.adoc[]
+
 include::topics.adoc[]

server_admin/index.adoc

@@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
 
 = {adminguide_name}
 
+:release_header_latest_link: {adminguide_link_latest}
+include::topics/templates/release-header.adoc[]
+
 include::topics.adoc[]

server_development/index.adoc

@@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
 
 = {developerguide_name}
 
+:release_header_latest_link: {developerguide_link_latest}
+include::topics/templates/release-header.adoc[]
+
 include::topics.adoc[]

server_installation/index.adoc

@@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
 
 = {installguide_name}
 
+:release_header_latest_link: {installguide_link_latest}
+include::topics/templates/release-header.adoc[]
+
 include::topics.adoc[]

server_installation/topics/operating-mode/crossdc.adoc

@@ -755,7 +755,7 @@ For the environments with slower network between data centers and probability of
 
 * It is recommended to keep the `sessions` and `clientSessions` caches in `SYNC`. Switching them to `ASYNC` is possible only if you are sure that user requests and backchannel requests (requests from client applications to {project_name} as described in <<requestprocessing>>) will be always processed on same site. This is true, for example, if:
 ** You use active/passive mode as described <<modes>>.
-** All your client applications are using the {project_name} link:https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter[JavaScript Adapter]. The JavaScript adapter sends the backchannel requests within the browser and hence they participate on the browser sticky session and will end on same cluster node (hence on same site) as the other browser requests of this user.
+** All your client applications are using the {project_name} {adapterguide_link_js_adapter}[JavaScript Adapter]. The JavaScript adapter sends the backchannel requests within the browser and hence they participate on the browser sticky session and will end on same cluster node (hence on same site) as the other browser requests of this user.
 ** Your load balancer is able to serve the requests based on client IP address (location) and the client applications are deployed on both sites.
 +
 For example you have 2 sites LON and NYC. As long as your applications are deployed in both LON and NYC sites too, you can ensure that all the user requests from London users will be redirected to the applications in LON site and also to the {project_name} servers in LON site. Backchannel requests from the LON site client deployments will end on {project_name} servers in LON site too. On the other hand, for the American users, all the {project_name} requests, application requests and backchannel requests will be processed on NYC site.

tests/pom.xml

@@ -106,6 +106,12 @@
             <version>1.2.17</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.asciidoctor</groupId>
+            <artifactId>asciidoctorj</artifactId>
+            <version>2.1.0</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <profiles>

tests/src/test/java/org/keycloak/documentation/test/Config.java

@@ -1,8 +1,11 @@
 package org.keycloak.documentation.test;
 
-import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.IOUtils;
 import org.apache.log4j.Logger;
+import org.asciidoctor.Asciidoctor;
+import org.asciidoctor.AttributesBuilder;
+import org.asciidoctor.OptionsBuilder;
+import org.asciidoctor.ast.Document;
 
 import java.io.File;
 import java.io.IOException;
@@ -50,7 +53,7 @@ public class Config {
         }
 
         documentAttributes = loadDocumentAttributes();
-        docBaseUrl = documentAttributes.get("project_doc_base_url").replace("{project_versionDoc}", documentAttributes.get("project_versionDoc"));
+        docBaseUrl = documentAttributes.get("project_doc_base_url");
 
         guideBaseUrl = System.getProperty("guideBaseUrl");
         if (guideBaseUrl != null) {
@@ -62,7 +65,7 @@ public class Config {
 
         if (isLoadFromFiles()) {
             // Ignore api-docs link in unpublished docs
-            String apiDocsLink = documentAttributes.get("apidocs_link").replace("{project_doc_base_url}", docBaseUrl);
+            String apiDocsLink = documentAttributes.get("apidocs_link");
             ignoredLinks.add(apiDocsLink);
         }
 
@@ -142,24 +145,21 @@ public class Config {
                 f = new File(docsRootDir, "/topics/templates/document-attributes-product.adoc");
             }
 
+            String buildType = System.getProperty("latest") != null ? "latest" : "archive";
+
+            Asciidoctor asciidoctor = Asciidoctor.Factory.create();
+
+            Map<String, Object> options = OptionsBuilder.options()
+                    .inPlace(true)
+                    .attributes(AttributesBuilder.attributes().backend("html5").attribute("project_buildType", buildType).asMap())
+                    .asMap();
+
+            Document document = asciidoctor.loadFile(f, options);
+
             Map<String, String> attributes = new HashMap<>();
 
-            // Slight work around to CD block overriding attribute values
+            for (Map.Entry<String, Object> a : document.getAttributes().entrySet()) {
-            boolean useFirstAttribute = true;
+                attributes.put(a.getKey(), a.getValue().toString());
-
-            for (String l : FileUtils.readLines(f, "utf-8")) {
-                if (l.startsWith(":")) {
-                    String[] s = l.split(": ");
-                    String key = s[0].substring(1).trim();
-                    String value = s[1].trim();
-                    if (!attributes.containsKey(key) || !useFirstAttribute) {
-                        attributes.put(key, value);
-                    }
-
-                    if (key.equals("project_product_cd") && value.equals("true")) {
-                        useFirstAttribute = false;
-                    }
-                }
             }
 
             return attributes;

topics/templates/document-attributes-community.adoc

@@ -6,8 +6,17 @@
 :project_versionMvn: 8.0.0
 :project_versionNpm: 8.0.0
 :project_versionDoc: 8.0
+
+ifeval::["{project_buildType}" == "latest"]
+:project_versionLinks: latest
+endif::[]
+ifeval::["{project_buildType}" == "archive"]
+:project_versionLinks: {project_versionDoc}
+endif::[]
+
 :project_images: keycloak-images
-:project_doc_base_url: https://www.keycloak.org/docs/{project_versionDoc}
+:project_doc_base_url: https://www.keycloak.org/docs/{project_versionLinks}
+:project_doc_base_url_latest: https://www.keycloak.org/docs/latest
 :project_dirref: KEYCLOAK_HOME
 :project_openshift_product_name: Keycloak for OpenShift
 
@@ -17,11 +26,15 @@
 
 :authorizationguide_name: Authorization Services Guide
 :authorizationguide_link: {project_doc_base_url}/authorization_services/
+:authorizationguide_link_latest: {project_doc_base_url_latest}/authorization_services/
 :adapterguide_name: Securing Applications and Services Guide
 :adapterguide_link: {project_doc_base_url}/securing_apps/
+:adapterguide_link_js_adapter: {adapterguide_link}#_javascript_adapter
+:adapterguide_link_latest: {project_doc_base_url_latest}/securing_apps/
 :adapterguide_logout_link: {adapterguide_link}#_java_adapter_logout
 :adminguide_name: Server Administration Guide
 :adminguide_link: {project_doc_base_url}/server_admin/
+:adminguide_link_latest: {project_doc_base_url_latest}/server_admin/
 :adminguide_bruteforce_name: Password guess: brute force attacks
 :adminguide_bruteforce_link: {adminguide_link}#password-guess-brute-force-attacks
 :adminguide_timeouts_name: Timeouts
@@ -29,22 +42,27 @@
 :adminguide_clearcache_name: Clearing Server Caches
 :adminguide_clearcache_link: {adminguide_link}#_clear-cache
 :apidocs_name: API Documentation
-:apidocs_link: {project_doc_base_url}/api_documentation/
+:apidocs_link: https://www.keycloak.org/docs/{project_versionDoc}/api_documentation/
 :developerguide_name: Server Developer Guide
 :developerguide_link: {project_doc_base_url}/server_development/
+:developerguide_link_latest: {project_doc_base_url_latest}/server_development/
 :developerguide_actiontoken_name: Action Token SPI
 :developerguide_actiontoken_link: {developerguide_link}#_action_token_spi
 :developerguide_jsproviders_name: JavaScript Providers
 :developerguide_jsproviders_link: {developerguide_link}#_script_providers
 :gettingstarted_name: Getting Started Guide
 :gettingstarted_link: {project_doc_base_url}/getting_started/
+:gettingstarted_link_latest: {project_doc_base_url_latest}/getting_started/
 :upgradingguide_name: Upgrading Guide
 :upgradingguide_link: {project_doc_base_url}/upgrading/
+:upgradingguide_link_latest: {project_doc_base_url_latest}/upgrading/
 :releasenotes_name: Release Notes
 :releasenotes_link: {project_doc_base_url}/release_notes/
+:releasenotes_link_latest: {project_doc_base_url_latest}/release_notes/
 
 :installguide_name: Server Installation and Configuration Guide
 :installguide_link: {project_doc_base_url}/server_installation/
+:installguide_link_latest: {project_doc_base_url_latest}/server_installation/
 :installguide_clustering_name: Clustering
 :installguide_clustering_link: {installguide_link}#_clustering
 :installguide_database_name: Database

topics/templates/document-attributes-product.adoc

@@ -38,6 +38,7 @@ endif::[]
 :authorizationguide_link: {project_doc_base_url}/authorization_services_guide/
 :adapterguide_name: Securing Applications and Services Guide
 :adapterguide_link: {project_doc_base_url}/securing_applications_and_services_guide/
+:adapterguide_link_js_adapter: {adapterguide_link}#_javascript_adapter
 :adapterguide_logout_link: {adapterguide_link}#_java_adapter_logout
 :adminguide_name: Server Administration Guide
 :adminguide_link: {project_doc_base_url}/server_administration_guide/

topics/templates/release-header.adoc

@@ -0,0 +1,8 @@
+ifeval::["{project_buildType}" == "latest"]
+[.versionlatest]
+Version *{project_version}* _Latest_
+endif::[]
+ifeval::["{project_buildType}" == "archive"]
+[.versionarchive]
+Version *{project_version}* _{release_header_latest_link}[Click here for latest]_
+endif::[]

upgrading/index.adoc

@@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
 
 = {upgradingguide_name}
 
+:release_header_latest_link: {upgradingguide_link_latest}
+include::topics/templates/release-header.adoc[]
+
 include::topics.adoc[]