Package server guides (#9568)

Closes #9567

docs/guides/assembly.xml

@@ -0,0 +1,16 @@
+<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
+    <id>asciidoc</id>
+    <formats>
+        <format>zip</format>
+    </formats>
+    <fileSets>
+        <fileSet>
+            <directory>${project.build.directory}</directory>
+            <outputDirectory>/</outputDirectory>
+            <includes>
+                <include>generated-guides/**</include>
+            </includes>
+        </fileSet>
+    </fileSets>
+</assembly>

docs/guides/pom.xml

@@ -28,12 +28,13 @@
     <name>Keycloak Guides</name>
     <artifactId>keycloak-guides</artifactId>
     <description>Keycloak Guides</description>
+    <packaging>pom</packaging>
 
     <dependencies>
         <dependency>
             <groupId>org.keycloak</groupId>
             <artifactId>keycloak-guides-maven-plugin</artifactId>
-            <version>17.0.0-SNAPSHOT</version>
+            <version>${project.version}</version>
         </dependency>
     </dependencies>
 
@@ -42,6 +43,7 @@
             <plugin>
                 <groupId>org.keycloak</groupId>
                 <artifactId>keycloak-guides-maven-plugin</artifactId>
+                <version>${project.version}</version>
                 <executions>
                     <execution>
                         <id>generate-asciidoc</id>
@@ -82,6 +84,23 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <artifactId>maven-assembly-plugin</artifactId>
+                <configuration>
+                    <descriptors>
+                        <descriptor>assembly.xml</descriptor>
+                    </descriptors>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>create-archive</id>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>single</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 

docs/guides/src/main/server/all-config.adoc

@@ -10,6 +10,7 @@ summary="All the configuration you will ever need and want">
 == ${category.heading}
 |===
 |Key|CLI|ENV|Description|Default|Values
+
 <#list categoryOptions as option>
 |${option.key}
 |${option.keyCli}

docs/guides/src/main/server/db.adoc

@@ -5,6 +5,7 @@
 <@tmpl.guide
     title="Relational database setup"
     summary="Understand how to configure different relational databases for Keycloak"
+    priority=10
     includedOptions="db db.* hostname">
 
 First step is to decide which database vendor you are going to use. Keycloak has support for a number of different vendors.

docs/guides/src/main/server/proxy.adoc

@@ -5,6 +5,7 @@
 <@tmpl.guide
 title="Configuring Keycloak to run behind a reverse proxy"
 summary="Understand how to configure Keycloak when using a reverse proxy"
+priority=20
 includedOptions="proxy proxy.*">
 
 It is pretty common nowadays to use a reverse proxy in distributed environments. If you want to use Keycloak together with such a proxy, you can use different proxy modes depending on the proxy and TLS termination in your specific environment:

docs/guides/src/main/templates/guide.adoc

@@ -1,11 +1,13 @@
-<#macro guide title summary includedOptions="">
-:title: ${title}
-:summary: ${summary}
+<#macro guide title summary priority=999 includedOptions="">
+:guide-id: ${id}
+:guide-title: ${title}
+:guide-summary: ${summary}
+:guide-priority: ${priority}
 
-[[${ctx.getAnchor(title)}]]
-= {title}
+[[${id}]]
+= ${title}
 
-{summary}
+${summary}
 
 <#nested>
 
@@ -14,6 +16,7 @@
 
 |===
 |Key|CLI|ENV|Description|Default|Values
+
 <#list ctx.options.getOptions(includedOptions) as option>
 |${option.key}
 |${option.keyCli}

docs/maven-plugin/src/main/java/org/keycloak/guides/maven/Context.java

@@ -14,10 +14,6 @@ public class Context {
         this.serverGuides = new File(srcDir, "server").list((dir, f) -> f.endsWith(".adoc") && !f.equals("index.adoc"));
     }
 
-    public String getAnchor(String title) {
-        return title.toLowerCase().replace(' ', '_');
-    }
-
     public Options getOptions() {
         return options;
     }

docs/maven-plugin/src/main/java/org/keycloak/guides/maven/FreeMarker.java

@@ -9,6 +9,7 @@ import java.io.File;
 import java.io.FileWriter;
 import java.io.IOException;
 import java.io.Writer;
+import java.util.HashMap;
 import java.util.Map;
 
 public class FreeMarker {
@@ -37,8 +38,11 @@ public class FreeMarker {
             parent.mkdir();
         }
 
+        HashMap<String, Object> attrs = new HashMap<>(attributes);
+        attrs.put("id", template.split("/")[1].replace(".adoc", ""));
+
         Writer w = new FileWriter(out);
-        t.process(attributes, w);
+        t.process(attrs, w);
     }
 
 }