Templatize index.html — auto-generate preview cards from JSON

- Create templates/index.html with {{tipCards}} and {{snippetCount}} placeholders
- Create templates/index-card.html for preview card rendering
- Update Java and Python generators to render index.html from templates
- Remove site/index.html from git tracking (now fully generated)
- Update .gitignore, copilot-instructions, rebuild fat JAR
- Adding a new pattern no longer requires manual index.html edits

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: brunoborges

.github/copilot-instructions.md

@@ -24,17 +24,19 @@ content/streams/stream-tolist.json
 
 The following are **generated by `html-generators/generate.java`** and must not be edited directly:
 
+- `site/index.html` — homepage with preview cards (generated from `templates/index.html`)
 - `site/language/*.html`, `site/collections/*.html`, etc. — detail pages
 - `site/data/snippets.json` — aggregated search index
 
 Run `java -jar html-generators/generate.jar` to rebuild all generated files from the JSON sources.
 
 ### Manually Maintained Files
 
-- `site/index.html` — homepage with preview cards (must be updated manually when adding/removing patterns)
 - `site/app.js` — client-side search, filtering, code highlighting
 - `site/styles.css` — all styling
 - `templates/slug-template.html` — HTML template with `{{placeholder}}` tokens used by the generator
+- `templates/index.html` — homepage template with `{{tipCards}}` and `{{snippetCount}}` placeholders
+- `templates/index-card.html` — preview card template for the homepage grid
 
 ### Project Structure
 
@@ -112,8 +114,7 @@ Each `content/category/slug.json` file has this structure:
 
 1. Create `content/category/new-slug.json` with all required fields
 2. Update `prev`/`next` in the adjacent patterns' JSON files
-3. Add a preview card in `site/index.html`
-4. Run `java -jar html-generators/generate.jar`
+3. Run `java -jar html-generators/generate.jar`
 
 ## Local Development
 

.gitignore

@@ -13,6 +13,9 @@ site/tooling/*.html
 # Generated aggregate file (built from individual JSON sources by html-generators/)
 site/data/snippets.json
 
+# Generated index page (built from templates/index.html by html-generators/)
+site/index.html
+
 # Platform-specific CDS/AOT cache (generated by build-cds.sh)
 html-generators/generate.aot
 html-generators/generate.jsa

html-generators/generate.jar

@@ -61,13 +61,16 @@ List<String> related() {
     }
 }
 
-record Templates(String page, String whyCard, String relatedCard, String socialShare) {
+record Templates(String page, String whyCard, String relatedCard, String socialShare,
+                 String index, String indexCard) {
     static Templates load() throws IOException {
         return new Templates(
             Files.readString(Path.of("templates/slug-template.html")),
             Files.readString(Path.of("templates/why-card.html")),
             Files.readString(Path.of("templates/related-card.html")),
-            Files.readString(Path.of("templates/social-share.html")));
+            Files.readString(Path.of("templates/social-share.html")),
+            Files.readString(Path.of("templates/index.html")),
+            Files.readString(Path.of("templates/index-card.html")));
     }
 }
 
@@ -97,10 +100,15 @@ void main() throws IOException {
     Files.writeString(Path.of(SITE_DIR, "data", "snippets.json"), prettyMapper.writeValueAsString(snippetsList) + "\n");
     IO.println("Rebuilt data/snippets.json with %d entries".formatted(snippetsList.size()));
 
-    // Patch index.html with the current snippet count
-    var indexPath = Path.of(SITE_DIR, "index.html");
-    Files.writeString(indexPath, Files.readString(indexPath).replace("{{snippetCount}}", String.valueOf(allSnippets.size())));
-    IO.println("Patched index.html with snippet count: %d".formatted(allSnippets.size()));
+    // Generate index.html from template
+    var tipCards = allSnippets.values().stream()
+            .map(s -> renderIndexCard(templates.indexCard(), s))
+            .collect(Collectors.joining("\n"));
+    var indexHtml = replaceTokens(templates.index(), Map.of(
+            "tipCards", tipCards,
+            "snippetCount", String.valueOf(allSnippets.size())));
+    Files.writeString(Path.of(SITE_DIR, "index.html"), indexHtml);
+    IO.println("Generated index.html with %d cards".formatted(allSnippets.size()));
 }
 
 SequencedMap<String, Snippet> loadAllSnippets() throws IOException {
@@ -166,6 +174,14 @@ String renderNavArrows(Snippet snippet) {
     return prev + "\n          " + next;
 }
 
+String renderIndexCard(String tpl, Snippet s) {
+    return replaceTokens(tpl, Map.ofEntries(
+            Map.entry("category", s.category()), Map.entry("slug", s.slug()),
+            Map.entry("catDisplay", s.catDisplay()), Map.entry("title", escape(s.title())),
+            Map.entry("oldCode", escape(s.oldCode())), Map.entry("modernCode", escape(s.modernCode())),
+            Map.entry("jdkVersion", s.jdkVersion())));
+}
+
 String renderWhyCards(String tpl, JsonNode whyList) {
     var cards = new ArrayList<String>();
     for (var w : whyList)

html-generators/generate.java

@@ -13,6 +13,8 @@
 WHY_CARD_TEMPLATE = "templates/why-card.html"
 RELATED_CARD_TEMPLATE = "templates/related-card.html"
 SOCIAL_SHARE_TEMPLATE = "templates/social-share.html"
+INDEX_TEMPLATE = "templates/index.html"
+INDEX_CARD_TEMPLATE = "templates/index-card.html"
 CONTENT_DIR = "content"
 SITE_DIR = "site"
 
@@ -159,6 +161,20 @@ def _support_badge_class(state):
     return {"preview": "preview", "experimental": "experimental"}.get(state, "widely")
 
 
+def render_index_card(index_card_template, data):
+    """Render a single index page preview card."""
+    cat = data["category"]
+    return replace_tokens(index_card_template, {
+        "category": cat,
+        "slug": data["slug"],
+        "catDisplay": CATEGORY_DISPLAY[cat],
+        "title": escape(data["title"]),
+        "oldCode": escape(data["oldCode"]),
+        "modernCode": escape(data["modernCode"]),
+        "jdkVersion": data["jdkVersion"],
+    })
+
+
 def generate_html(template, why_card_template, related_card_template,
                   social_share_template, data, all_snippets):
     """Generate the full HTML page for a snippet by rendering the template."""
@@ -204,6 +220,8 @@ def main():
     why_card_template = open(WHY_CARD_TEMPLATE).read()
     related_card_template = open(RELATED_CARD_TEMPLATE).read()
     social_share_template = open(SOCIAL_SHARE_TEMPLATE).read()
+    index_template = open(INDEX_TEMPLATE).read()
+    index_card_template = open(INDEX_CARD_TEMPLATE).read()
     all_snippets = load_all_snippets()
     print(f"Loaded {len(all_snippets)} snippets")
 
@@ -234,16 +252,20 @@ def main():
 
     print(f"Rebuilt data/snippets.json with {len(snippets_list)} entries")
 
-    # Patch index.html with the current snippet count
+    # Generate index.html from template
+    tip_cards = "\n".join(
+        render_index_card(index_card_template, data)
+        for data in all_snippets.values()
+    )
     count = len(all_snippets)
-    index_path = os.path.join(SITE_DIR, "index.html")
-    with open(index_path) as f:
-        index_content = f.read()
-    index_content = index_content.replace("{{snippetCount}}", str(count))
-    with open(index_path, "w") as f:
-        f.write(index_content)
-
-    print(f"Patched index.html with snippet count: {count}")
+    index_html = replace_tokens(index_template, {
+        "tipCards": tip_cards,
+        "snippetCount": str(count),
+    })
+    with open(os.path.join(SITE_DIR, "index.html"), "w") as f:
+        f.write(index_html)
+
+    print(f"Generated index.html with {count} cards")
 
 
 if __name__ == "__main__":