Add support for pinning guides to the top (#9913)

Closes #9912

docs/guides/assembly.xml

@@ -12,5 +12,12 @@
                 <include>generated-guides/**</include>
             </includes>
         </fileSet>
+        <fileSet>
+            <directory>${project.basedir}/src/main/server</directory>
+            <outputDirectory>/generated-guides/server/</outputDirectory>
+            <includes>
+                <include>pinned-guides</include>
+            </includes>
+        </fileSet>
     </fileSets>
 </assembly>

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

@@ -6,7 +6,6 @@
 <@tmpl.guide
 title="Running in a container"
 summary="Learn how to run Keycloak from a container image"
-priority=20
 includedOptions="db db-url db-username db-password features hostname https-key-store-file https-key-store-password metrics-enabled">
 
 Keycloak is handling containerized environments like Kubernetes or OpenShift as first-class-citizens. In this guide you'll learn how to run and optimize the Keycloak container image to have the best experience running a Keycloak container.

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

@@ -6,7 +6,6 @@
 <@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/pinned-guides

@@ -0,0 +1,3 @@
+containers
+all-config
+features

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

@@ -5,7 +5,6 @@
 <@tmpl.guide
 title="Configuring a reverse proxy"
 summary="Learn how to configure Keycloak together with a reverse proxy, api gateway or load balancer."
-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 TLS termination in your specific environment:

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

@@ -4,7 +4,6 @@
 <@tmpl.guide
 title="Using Kubernetes Secrets"
 summary="Learn how to use Kubernetes / OpenShift secrets in Keycloak"
-priority=30
 includedOptions="vault vault-*">
 
 Keycloak supports a file based vault implementation for Kubernetes / OpenShift secrets. Mount Kubernetes secrets into the Keycloak Container, and the data fields will be available in the mounted folder with a flat-file structure.

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

@@ -1,11 +1,14 @@
 package org.keycloak.guides.maven;
 
+import java.io.BufferedReader;
 import java.io.File;
+import java.io.FileReader;
 import java.io.IOException;
 import java.util.Collections;
-import java.util.Comparator;
+import java.util.HashMap;
 import java.util.LinkedList;
 import java.util.List;
+import java.util.Map;
 
 public class Context {
 
@@ -22,14 +25,30 @@ public class Context {
         this.guides = new LinkedList<>();
 
         GuideParser parser = new GuideParser();
-        for (File f : new File(srcDir, "server").listFiles((dir, f) -> f.endsWith(".adoc") && !f.equals("index.adoc"))) {
+        File serverDir = new File(srcDir, "server");
+
+        Map<String, Integer> guidePriorities = loadPinnedGuides(new File(serverDir, "pinned-guides"));
+
+        for (File f : serverDir.listFiles((dir, f) -> f.endsWith(".adoc") && !f.equals("index.adoc"))) {
             Guide guide = parser.parse(f);
+
+            if (guidePriorities != null) {
+                Integer priority = guidePriorities.get(guide.getId());
+                guide.setPriority(priority != null ? priority : Integer.MAX_VALUE);
+            }
+
             if (guide != null) {
                 guides.add(guide);
             }
         }
 
-        Collections.sort(guides, Comparator.comparingInt(Guide::getPriority));
+        Collections.sort(guides, (o1, o2) -> {
+            if (o1.getPriority() == o2.getPriority()) {
+                return o1.getTitle().compareTo(o2.getTitle());
+            } else {
+                return Integer.compare(o1.getPriority(), o2.getPriority());
+            }
+        });
     }
 
     public Options getOptions() {
@@ -44,4 +63,22 @@ public class Context {
         return guides;
     }
 
+    private Map<String, Integer> loadPinnedGuides(File pinnedGuides) throws IOException {
+        if (!pinnedGuides.isFile()) {
+            return null;
+        }
+        Map<String, Integer> priorities = new HashMap<>();
+        try (BufferedReader br = new BufferedReader(new FileReader(pinnedGuides))) {
+            int c = 1;
+            for (String l = br.readLine(); l != null; l = br.readLine()) {
+                l = l.trim();
+                if (!l.isEmpty()) {
+                    priorities.put(l, c);
+                }
+                c++;
+            }
+            return priorities;
+        }
+    }
+
 }