You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@grails.apache.org by ja...@apache.org on 2026/07/22 19:11:52 UTC

(grails-static-website) branch feature/promote-grails-8-guides created (now affa3233da2)

This is an automated email from the ASF dual-hosted git repository.

jamesfredley pushed a change to branch feature/promote-grails-8-guides
in repository https://gitbox.apache.org/repos/asf/grails-static-website.git


      at affa3233da2 Promote Grails 8 guides on the guides index and version pages

This branch includes the following new commits:

     new affa3233da2 Promote Grails 8 guides on the guides index and version pages

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.



(grails-static-website) 01/01: Promote Grails 8 guides on the guides index and version pages

Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

jamesfredley pushed a commit to branch feature/promote-grails-8-guides
in repository https://gitbox.apache.org/repos/asf/grails-static-website.git

commit affa3233da26b885e3dff90540bd0ce4cb834933
Author: James Fredley <ja...@users.noreply.github.com>
AuthorDate: Wed Jul 22 15:08:03 2026 -0400

    Promote Grails 8 guides on the guides index and version pages
    
    Surface every Grails 8 guide on /guides/ with a featured catalogue and
    a categorized grid, list the full uncapped set on /guides/versions/8.html,
    sort multi-version chips newest-first, and restore the Grails REST APIs
    track so grails-http-client is not dropped from the category grid.
    
    Assisted-by: Sisyphus:grok-4.5
---
 .../groovy/website/model/guides/GuidesPage.groovy  | 390 ++++++++++++++-------
 .../website/model/guides/GuidesPageSpec.groovy     | 272 ++++++++++++++
 2 files changed, 540 insertions(+), 122 deletions(-)

diff --git a/buildSrc/src/main/groovy/website/model/guides/GuidesPage.groovy b/buildSrc/src/main/groovy/website/model/guides/GuidesPage.groovy
index 085ca59c8c0..e9cc9bfe02f 100644
--- a/buildSrc/src/main/groovy/website/model/guides/GuidesPage.groovy
+++ b/buildSrc/src/main/groovy/website/model/guides/GuidesPage.groovy
@@ -32,7 +32,19 @@ import static website.utils.RenderUtils.renderHtml
 @CompileStatic
 class GuidesPage {
 
-    public static final Integer NUMBER_OF_LATEST_GUIDES = 8
+    /**
+     * Cap for the "Latest Guides" sidebar on the index. Sized high enough that
+     * every current Grails 8 guide still appears there when they are the newest
+     * publications - the old value of 8 silently dropped half of the modern set.
+     */
+    public static final Integer NUMBER_OF_LATEST_GUIDES = 20
+
+    /**
+     * Major version featured at the top of the guides index category grid and
+     * used as the default "modern" cut when sorting multi-version guide rows.
+     */
+    public static final String FEATURED_VERSION = '8'
+
     public static final String GUIDES_URL = 'https://grails.apache.org/guides'
 
     /**
@@ -80,17 +92,28 @@ class GuidesPage {
             spa: new Category(name: 'Frontend SPA', image: 'react.svg'),
             testing: new Category(name: 'Grails Testing', image: 'testing.svg'),
             weblayer: new Category(name: 'Web Layer', image: 'views.svg'),
+            restapis: new Category(name: 'Grails REST APIs', image: 'restapis.svg'),
     ]
-    
-    
+
+
     @CompileDynamic
-    static String renderGuide(Guide guide) {
+    static String renderGuide(Guide guide, String versionFilter = null) {
+        // Pre-resolve anything MarkupBuilder would otherwise treat as a tag name.
+        final boolean multi = guide instanceof GrailsVersionedGuide
+        final GrailsVersionedGuide multiGuide = multi ? (GrailsVersionedGuide) guide : null
+        final List<Integer> versionKeys = multi ? orderedVersionKeys(multiGuide) : Collections.emptyList()
+        final Integer filteredMajor = (multi && versionFilter?.isInteger()) ? versionFilter.toInteger() : null
+        final List<String> filteredTags = (multi && filteredMajor != null)
+                ? (multiGuide.grailsMayorVersionTags[filteredMajor] ?: []) as List<String>
+                : Collections.emptyList() as List<String>
+
         renderHtml {
             li {
                 if (guide instanceof SingleGuide) {
+                    String version = versionFilter ?: guide.versionNumber
                     a(
                             class: (guide.tags.contains('quick-cast') ? 'quick-cast guide' : 'guide'),
-                            href: "$GUIDES_URL/${guide.name}/${guide.versionNumber}/guide/index.html", guide.title
+                            href: "$GUIDES_URL/${guide.name}/${version}/guide/index.html", guide.title
                     )
                     guide.tags.each {
                         span(
@@ -98,25 +121,42 @@ class GuidesPage {
                                 class: 'tag', it
                         )
                     }
-                } else if (guide instanceof GrailsVersionedGuide) {
-                    def multiGuide = (GrailsVersionedGuide) guide
-                    div(class: (guide.tags.contains('quick-cast') ? 'quick-cast multi-guide' : 'multi-guide')) {
-                        span(class: 'title', guide.title)
-                        for (def grailsVersion :  multiGuide.grailsMayorVersionTags.keySet())  {
-                            def tagList = multiGuide.grailsMayorVersionTags[grailsVersion] as Set<String>
-                            div(class: 'align-left') {
-                                a(
-                                        class: 'grails-version',
-                                        href: "$GUIDES_URL/${multiGuide.name}/${grailsVersion}/guide/index.html"
-                                ) {
-                                    mkp.yield("grails$grailsVersion")
-                                }
-                                tagList.each {
-                                    span(
-                                            style: 'display: none',
-                                            class: 'tag',
-                                            it
-                                    )
+                } else if (multi) {
+                    // When a version filter is active (e.g. /versions/8.html), collapse
+                    // multi-version rows to a single link for that major so the page
+                    // reads as a complete modern catalogue rather than a version picker.
+                    if (versionFilter) {
+                        a(
+                                class: (filteredTags.contains('quick-cast') ? 'quick-cast guide' : 'guide'),
+                                href: "$GUIDES_URL/${multiGuide.name}/${versionFilter}/guide/index.html",
+                                multiGuide.title
+                        )
+                        filteredTags.each {
+                            span(
+                                    style: 'display: none',
+                                    class: 'tag', it
+                            )
+                        }
+                    } else {
+                        div(class: (guide.tags.contains('quick-cast') ? 'quick-cast multi-guide' : 'multi-guide')) {
+                            span(class: 'title', guide.title)
+                            // Newest majors first so Grails 8 is the first chip readers see.
+                            for (def grailsVersion : versionKeys) {
+                                def tagList = multiGuide.grailsMayorVersionTags[grailsVersion] as Set<String>
+                                div(class: 'align-left') {
+                                    a(
+                                            class: 'grails-version',
+                                            href: "$GUIDES_URL/${multiGuide.name}/${grailsVersion}/guide/index.html"
+                                    ) {
+                                        mkp.yield("grails$grailsVersion")
+                                    }
+                                    tagList.each {
+                                        span(
+                                                style: 'display: none',
+                                                class: 'tag',
+                                                it
+                                        )
+                                    }
                                 }
                             }
                         }
@@ -185,70 +225,21 @@ class GuidesPage {
                         }
                     }
                 }
-                // The two-column grid pairs a "primary" category on the left with
-                // a complementary one on the right. Reading order goes top-down by
-                // pair, so the first pair (apprentice / advanced) is the most
-                // prominent. Tags - rendered in the right-hand sidebar above -
-                // are the primary navigation; this grid is a small curated set
-                // of high-level tracks for skimming by axis.
-                div(class: 'two-columns') {
-                    div(class: 'column') {
-                        if (!(tag || category || version)) {
-                            mkp.yieldUnescaped(guideGroupByCategory(categories.apprentice, guides, true, 'margin-top: 0'))
-                        }
-                    }
-                    div(class: 'column') {
-                        if (!(tag || category || version)) {
-                            mkp.yieldUnescaped(guideGroupByCategory(categories.advanced, guides, true, 'margin-top: 0'))
-                        }
-                    }
-                }
-                div(class: 'two-columns') {
-                    div(class: 'column') {
-                        if (!(tag || category || version)) {
-                            mkp.yieldUnescaped(guideGroupByCategory(categories.weblayer, guides, true, 'margin-top: 0'))
-                        }
-                    }
-                    div(class: 'column') {
-                        if (!(tag || category || version)) {
-                            mkp.yieldUnescaped(guideGroupByCategory(categories.devops, guides, true, 'margin-top: 0'))
-                        }
-                    }
-                }
-                div(class: 'two-columns') {
-                    div(class: 'column') {
-                        if (!(tag || category || version)) {
-                            mkp.yieldUnescaped(guideGroupByCategory(categories.gorm, guides, true, 'margin-top: 0'))
-                        }
-                    }
-                    div(class: 'column') {
-                        if (!(tag || category || version)) {
-                            mkp.yieldUnescaped(guideGroupByCategory(categories.testing, guides, true, 'margin-top: 0'))
-                        }
-                    }
-                }
-                div(class: 'two-columns') {
-                    div(class: 'column') {
-                        if (!(tag || category || version)) {
-                            mkp.yieldUnescaped(guideGroupByCategory(categories.security, guides, true, 'margin-top: 0'))
-                        }
-                    }
-                    div(class: 'column') {
-                        if (!(tag || category || version)) {
-                            mkp.yieldUnescaped(guideGroupByCategory(categories.spa, guides, true, 'margin-top: 0'))
-                        }
-                    }
-                }
-                div(class: 'two-columns') {
-                    div(class: 'column') {
-                        if (!(tag || category || version)) {
-                            mkp.yieldUnescaped(guideGroupByCategory(categories.async, guides, true, 'margin-top: 0'))
-                        }
-                    }
-                    div(class: 'column') {
-                        if (!(tag || category || version)) {
-                            mkp.yieldUnescaped(guideGroupByCategory(categories.cloud, guides, true, 'margin-top: 0'))
-                        }
+                // Featured modern catalogue: every guide published for the current
+                // major, un-capped, sits above the legacy category grid so readers
+                // hit Grails 8 first. On version pages the same grid is rendered
+                // filtered to that major so /versions/8.html is a full catalogue
+                // (flat list in the sidebar + categorized body), not a partial peek.
+                if (!(tag || category)) {
+                    String featuredVersion = version ?: FEATURED_VERSION
+                    List<Guide> featured = guidesForVersionList(featuredVersion, guides)
+                    if (featured) {
+                        mkp.yieldUnescaped(featuredVersionSection(featuredVersion, featured, version != null))
+                        mkp.yieldUnescaped(categoryGrid(guides, featuredVersion, version != null))
+                    } else if (!version) {
+                        // No featured-version guides yet - fall back to the full
+                        // unfiltered category grid so the page is never empty.
+                        mkp.yieldUnescaped(categoryGrid(guides, null, false))
                     }
                 }
             }
@@ -365,8 +356,18 @@ class GuidesPage {
             Category category,
             List<Guide> guides,
             boolean linkToCategory = true,
-            String cssStyle = ''
+            String cssStyle = '',
+            String versionFilter = null,
+            boolean onlyMatchingVersion = false
     ) {
+        List<Guide> inCategory = guides.findAll { it.category == category.name }
+        if (versionFilter && onlyMatchingVersion) {
+            inCategory = inCategory.findAll { guideHasVersion(it, versionFilter) }
+        }
+        if (!inCategory) {
+            return ''
+        }
+        inCategory = sortGuidesForDisplay(inCategory, versionFilter ?: FEATURED_VERSION)
         renderHtml {
             div(class: 'guide-group', style: cssStyle) {
                 div(class: 'guide-group-header') {
@@ -383,9 +384,105 @@ class GuidesPage {
                     }
                 }
                 ul {
-                    guides
-                            .findAll { it.category == category.name }
-                            .each { mkp.yieldUnescaped(GuidesPage.renderGuide(it)) }
+                    inCategory.each {
+                        mkp.yieldUnescaped(GuidesPage.renderGuide(it, onlyMatchingVersion ? versionFilter : null))
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Two-column category grid used on the index and on version pages. When
+     * {@code onlyMatchingVersion} is true, each category only lists guides that
+     * ship the given major (so /versions/8.html surfaces the full Grails 8 set
+     * organized by track). When false, every guide stays visible but guides for
+     * {@code preferVersion} sort to the top of each category.
+     */
+    @CompileDynamic
+    static String categoryGrid(List<Guide> guides, String preferVersion, boolean onlyMatchingVersion) {
+        List<List<Category>> pairs = [
+                [categories.apprentice, categories.advanced],
+                [categories.weblayer, categories.restapis],
+                [categories.devops, categories.gorm],
+                [categories.testing, categories.security],
+                [categories.spa, categories.async],
+                [categories.cloud],
+        ]
+        StringBuilder html = new StringBuilder()
+        boolean firstPair = true
+        for (List<Category> pair : pairs) {
+            Category leftCat = pair[0]
+            Category rightCat = pair.size() > 1 ? pair[1] : null
+            String left = leftCat
+                    ? guideGroupByCategory(
+                    leftCat, guides, true, firstPair ? 'margin-top: 0' : '', preferVersion, onlyMatchingVersion)
+                    : ''
+            String right = rightCat
+                    ? guideGroupByCategory(
+                    rightCat, guides, true, firstPair ? 'margin-top: 0' : '', preferVersion, onlyMatchingVersion)
+                    : ''
+            if (!left && !right) {
+                continue
+            }
+            html << renderHtml {
+                div(class: 'two-columns') {
+                    div(class: 'column') {
+                        if (left) {
+                            mkp.yieldUnescaped(left)
+                        }
+                    }
+                    div(class: 'column') {
+                        if (right) {
+                            mkp.yieldUnescaped(right)
+                        }
+                    }
+                }
+            }
+            firstPair = false
+        }
+        html.toString()
+    }
+
+    /**
+     * Full-width "Grails N Guides" block listing every guide for that major,
+     * newest first, with no take() cap. On the index this is the featured modern
+     * catalogue; on a version page it sits under the sidebar list as the
+     * categorized companion (the sidebar list itself is still rendered by
+     * {@link #guidesForVersion}).
+     */
+    @CompileDynamic
+    static String featuredVersionSection(String version, List<Guide> featured, boolean onVersionPage) {
+        // On the version page the left column already has the flat list; the
+        // body below is the categorized grid only. On the index we lead with
+        // this flat "all of them" list so nothing modern is buried.
+        if (onVersionPage) {
+            return ''
+        }
+        renderHtml {
+            div(class: 'latest-guides featured-version-guides', style: 'margin-top: 0') {
+                h3(class: 'column-header', "Grails $version Guides")
+                p(style: 'margin: -30px 0 30px 0; padding-left: 28px;') {
+                    mkp.yield("Every guide published for Grails $version. ")
+                    a(href: "$GUIDES_URL/versions/${version}.html", "Browse by version →")
+                }
+                ul {
+                    featured.each { guide ->
+                        li {
+                            b(guide.title)
+                            span {
+                                if (guide.publicationDate) {
+                                    mkp.yield(new SimpleDateFormat('MMM dd, yyyy').format(guide.publicationDate))
+                                    mkp.yield(' - ')
+                                }
+                                mkp.yield(guide.category)
+                            }
+                            a(
+                                    href: "$GUIDES_URL/${guide.name}/${version}/guide/index.html",
+                                    'Read More'
+                            )
+                        }
+                    }
                 }
             }
         }
@@ -444,47 +541,96 @@ class GuidesPage {
      */
     @CompileDynamic
     static String guidesForVersion(String version, List<Guide> guides) {
+        List<Guide> matched = guidesForVersionList(version, guides)
         renderHtml {
             div(class: 'latest-guides') {
                 h3(class: 'column-header', "Guides for Grails $version")
+                if (matched) {
+                    p(style: 'margin: -30px 0 30px 0; padding-left: 0;') {
+                        mkp.yield("${matched.size()} guide${matched.size() == 1 ? '' : 's'} for Grails $version")
+                    }
+                }
                 ul {
-                    guides
-                            .findAll { Guide guide -> GuidesPage.guideHasVersion(guide, version) }
-                            .sort { Guide a, Guide b ->
-                                Date da = a.publicationDate
-                                Date db = b.publicationDate
-                                if (da == db) {
-                                    return 0
-                                }
-                                if (da == null) {
-                                    return 1
-                                }
-                                if (db == null) {
-                                    return -1
-                                }
-                                db <=> da
-                            }
-                            .each { guide ->
-                                li {
-                                    b(guide.title)
-                                    span {
-                                        if (guide.publicationDate) {
-                                            mkp.yield(new SimpleDateFormat('MMM dd, yyyy').format(guide.publicationDate))
-                                            mkp.yield(' - ')
-                                        }
-                                        mkp.yield(guide.category)
-                                    }
-                                    a(
-                                            href: "$GUIDES_URL/${guide.name}/${version}/guide/index.html",
-                                            'Read More'
-                                    )
+                    matched.each { guide ->
+                        li {
+                            b(guide.title)
+                            span {
+                                if (guide.publicationDate) {
+                                    mkp.yield(new SimpleDateFormat('MMM dd, yyyy').format(guide.publicationDate))
+                                    mkp.yield(' - ')
                                 }
+                                mkp.yield(guide.category)
                             }
+                            a(
+                                    href: "$GUIDES_URL/${guide.name}/${version}/guide/index.html",
+                                    'Read More'
+                            )
+                        }
+                    }
                 }
             }
         }
     }
 
+    /**
+     * Every guide published for {@code version}, newest first, no cap. Shared by
+     * the version-page sidebar, the featured index section, and tests.
+     */
+    static List<Guide> guidesForVersionList(String version, List<Guide> guides) {
+        sortGuidesByPublicationDate(
+                guides.findAll { Guide guide -> guideHasVersion(guide, version) }
+        )
+    }
+
+    /**
+     * Major-version keys for a multi-version guide, newest first, so the
+     * rendered chip row leads with Grails 8 rather than the YAML encounter order.
+     */
+    static List<Integer> orderedVersionKeys(GrailsVersionedGuide guide) {
+        List<Integer> keys = new ArrayList<Integer>(guide.grailsMayorVersionTags.keySet())
+        keys.sort { Integer a, Integer b -> b <=> a }
+        keys
+    }
+
+    /**
+     * Sort guides so those that ship {@code preferVersion} come first (newest
+     * among themselves), then the rest by publication date descending. Used by
+     * the index category grid to keep modern work at the top of each track
+     * without hiding the legacy corpus.
+     */
+    static List<Guide> sortGuidesForDisplay(List<Guide> guides, String preferVersion) {
+        List<Guide> preferred = []
+        List<Guide> rest = []
+        for (Guide guide : guides) {
+            if (preferVersion && guideHasVersion(guide, preferVersion)) {
+                preferred << guide
+            } else {
+                rest << guide
+            }
+        }
+        sortGuidesByPublicationDate(preferred) + sortGuidesByPublicationDate(rest)
+    }
+
+    static List<Guide> sortGuidesByPublicationDate(List<Guide> guides) {
+        List<Guide> sorted = new ArrayList<Guide>(guides)
+        sorted.sort { Guide a, Guide b ->
+            Date da = a.publicationDate
+            Date db = b.publicationDate
+            if (da == db) {
+                return (a.title ?: '') <=> (b.title ?: '')
+            }
+            if (da == null) {
+                return 1
+            }
+            if (db == null) {
+                return -1
+            }
+            int byDate = db <=> da
+            byDate != 0 ? byDate : (a.title ?: '') <=> (b.title ?: '')
+        }
+        sorted
+    }
+
     /**
      * The distinct Grails major versions across all guides, newest first.
      * A {@link SingleGuide} contributes its single {@code versionNumber}; a
diff --git a/buildSrc/src/test/groovy/website/model/guides/GuidesPageSpec.groovy b/buildSrc/src/test/groovy/website/model/guides/GuidesPageSpec.groovy
new file mode 100644
index 00000000000..4a562de9005
--- /dev/null
+++ b/buildSrc/src/test/groovy/website/model/guides/GuidesPageSpec.groovy
@@ -0,0 +1,272 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package website.model.guides
+
+import spock.lang.Specification
+
+class GuidesPageSpec extends Specification {
+
+    def 'orderedVersionKeys returns majors newest first'() {
+        given:
+        def guide = new GrailsVersionedGuide(
+                name: 'multi',
+                title: 'Multi',
+                category: 'Advanced Grails',
+                grailsMayorVersionTags: [
+                        3: ['old'],
+                        4: ['mid'],
+                        6: ['recent'],
+                        8: ['modern'],
+                ]
+        )
+
+        expect:
+        GuidesPage.orderedVersionKeys(guide) == [8, 6, 4, 3]
+    }
+
+    def 'renderGuide emits multi-version chips newest first'() {
+        given:
+        def guide = new GrailsVersionedGuide(
+                name: 'multi',
+                title: 'Multi Guide',
+                category: 'Advanced Grails',
+                grailsMayorVersionTags: [
+                        3: ['a'],
+                        8: ['b'],
+                        6: ['c'],
+                ]
+        )
+
+        when:
+        String html = GuidesPage.renderGuide(guide)
+
+        then:
+        html.indexOf('grails8') < html.indexOf('grails6')
+        html.indexOf('grails6') < html.indexOf('grails3')
+        html.contains('/multi/8/guide/index.html')
+        html.contains('/multi/6/guide/index.html')
+        html.contains('/multi/3/guide/index.html')
+    }
+
+    def 'renderGuide with version filter collapses multi-version row to one link'() {
+        given:
+        def guide = new GrailsVersionedGuide(
+                name: 'multi',
+                title: 'Multi Guide',
+                category: 'Advanced Grails',
+                grailsMayorVersionTags: [
+                        4: ['legacy'],
+                        8: ['modern'],
+                ]
+        )
+
+        when:
+        String html = GuidesPage.renderGuide(guide, '8')
+
+        then:
+        html.contains('/multi/8/guide/index.html')
+        html.contains('Multi Guide')
+        !html.contains('grails4')
+        !html.contains('/multi/4/guide/index.html')
+    }
+
+    def 'guidesForVersionList returns every matching guide uncapped newest first'() {
+        given:
+        List<Guide> guides = (1..12).collect { int i ->
+            new SingleGuide(
+                    name: "guide-$i",
+                    title: "Guide $i",
+                    category: 'Web Layer',
+                    versionNumber: '8',
+                    publicationDate: Date.parse('yyyy-MM-dd', "2026-05-${String.format('%02d', i)}"),
+                    tags: ['t'],
+                    authors: ['A'],
+            )
+        }
+        guides << new SingleGuide(
+                name: 'old',
+                title: 'Old Guide',
+                category: 'Web Layer',
+                versionNumber: '4',
+                publicationDate: Date.parse('yyyy-MM-dd', '2017-01-01'),
+                tags: ['t'],
+                authors: ['A'],
+        )
+
+        when:
+        List<Guide> v8 = GuidesPage.guidesForVersionList('8', guides)
+
+        then:
+        v8.size() == 12
+        v8*.name == (12..1).collect { "guide-$it" }
+        v8.every { it.name != 'old' }
+    }
+
+    def 'guidesForVersion HTML includes every guide and a count'() {
+        given:
+        List<Guide> guides = [
+                new SingleGuide(
+                        name: 'a',
+                        title: 'Alpha',
+                        category: 'GORM',
+                        versionNumber: '8',
+                        publicationDate: Date.parse('yyyy-MM-dd', '2026-06-01'),
+                        tags: [],
+                        authors: [],
+                ),
+                new SingleGuide(
+                        name: 'b',
+                        title: 'Beta',
+                        category: 'Web Layer',
+                        versionNumber: '8',
+                        publicationDate: Date.parse('yyyy-MM-dd', '2026-05-01'),
+                        tags: [],
+                        authors: [],
+                ),
+        ]
+
+        when:
+        String html = GuidesPage.guidesForVersion('8', guides)
+
+        then:
+        html.contains('2 guides for Grails 8')
+        html.contains('/a/8/guide/index.html')
+        html.contains('/b/8/guide/index.html')
+        html.contains('Alpha')
+        html.contains('Beta')
+    }
+
+    def 'sortGuidesForDisplay puts preferred version first'() {
+        given:
+        def v8 = new SingleGuide(
+                name: 'modern',
+                title: 'Modern',
+                category: 'Web Layer',
+                versionNumber: '8',
+                publicationDate: Date.parse('yyyy-MM-dd', '2026-05-01'),
+                tags: [],
+                authors: [],
+        )
+        def v4 = new SingleGuide(
+                name: 'legacy',
+                title: 'Legacy',
+                category: 'Web Layer',
+                versionNumber: '4',
+                publicationDate: Date.parse('yyyy-MM-dd', '2018-01-01'),
+                tags: [],
+                authors: [],
+        )
+        def multi = new GrailsVersionedGuide(
+                name: 'multi',
+                title: 'Multi',
+                category: 'Web Layer',
+                publicationDate: Date.parse('yyyy-MM-dd', '2020-01-01'),
+                grailsMayorVersionTags: [4: ['x'], 6: ['y']],
+        )
+
+        when:
+        List<Guide> sorted = GuidesPage.sortGuidesForDisplay([v4, multi, v8], '8')
+
+        then: 'preferred major first; remaining guides keep newest-first date order'
+        sorted*.name == ['modern', 'multi', 'legacy']
+    }
+
+    def 'index mainContent features every Grails 8 guide and version page lists them all'() {
+        given:
+        List<Guide> guides = [
+                new SingleGuide(
+                        name: 'g8-a',
+                        title: 'G8 A',
+                        category: 'Web Layer',
+                        versionNumber: '8',
+                        publicationDate: Date.parse('yyyy-MM-dd', '2026-06-01'),
+                        tags: ['htmx'],
+                        authors: ['A'],
+                ),
+                new SingleGuide(
+                        name: 'g8-b',
+                        title: 'G8 B',
+                        category: 'GORM',
+                        versionNumber: '8',
+                        publicationDate: Date.parse('yyyy-MM-dd', '2026-05-15'),
+                        tags: ['gorm'],
+                        authors: ['A'],
+                ),
+                new SingleGuide(
+                        name: 'legacy',
+                        title: 'Legacy Guide',
+                        category: 'Web Layer',
+                        versionNumber: '4',
+                        publicationDate: Date.parse('yyyy-MM-dd', '2017-01-01'),
+                        tags: ['old'],
+                        authors: ['A'],
+                ),
+        ]
+        Set tags = [] as Set
+
+        when:
+        String index = GuidesPage.mainContent(guides, tags)
+        String versionPage = GuidesPage.mainContent(guides, tags, null, null, '8')
+
+        then: 'index leads with the full Grails 8 catalogue'
+        index.contains('Grails 8 Guides')
+        index.contains('/g8-a/8/guide/index.html')
+        index.contains('/g8-b/8/guide/index.html')
+        index.contains('Legacy Guide')
+
+        and: 'version page lists every G8 guide uncapped with a count'
+        versionPage.contains('2 guides for Grails 8')
+        versionPage.contains('/g8-a/8/guide/index.html')
+        versionPage.contains('/g8-b/8/guide/index.html')
+        !versionPage.contains('/legacy/4/guide/index.html')
+        versionPage.contains('G8 A')
+        versionPage.contains('G8 B')
+    }
+
+    def 'real conf/guides.yml exposes every version-8 entry on the version page'() {
+        given:
+        File yml = locateGuidesYml()
+
+        expect:
+        yml != null
+
+        when:
+        List<Guide> guides = GuidesFetcher.fetchGuides(yml, false)
+        List<String> v8Names = GuidesPage.guidesForVersionList('8', guides)*.name
+        String html = GuidesPage.guidesForVersion('8', guides)
+        String grid = GuidesPage.categoryGrid(guides, '8', true)
+
+        then:
+        v8Names.size() >= 13
+        v8Names.every { String name -> html.contains("/${name}/8/guide/index.html") }
+        html.contains("${v8Names.size()} guides for Grails 8")
+        // Categorized companion must not silently drop a modern guide whose
+        // category was missing from the hardcoded grid (regression: Grails REST APIs).
+        v8Names.every { String name -> grid.contains("/${name}/8/guide/index.html") }
+        grid.contains('Grails REST APIs')
+    }
+
+    private static File locateGuidesYml() {
+        [
+                new File('conf/guides.yml'),
+                new File('../conf/guides.yml'),
+                new File('../../conf/guides.yml'),
+        ].find { it.exists() }
+    }
+}