Externalize embedded HTML templates to templates/ folder

brunoborges · Copilot · brunoborges · commit dd9fcf261f7e · 2026-02-17T00:09:41.000-05:00
Extract why-card, related-card, and social-share HTML templates from
inline strings in Generate.java and generate.py into separate template
files under templates/. Both generators now use the same {{placeholder}}
token replacement pattern for all templates.

New files:
- templates/why-card.html
- templates/related-card.html
- templates/social-share.html

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/Generate.java b/Generate.java
@@ -28,6 +28,9 @@
 
 static final String BASE_URL = "https://javaevolved.github.io";
 static final String TEMPLATE_FILE = "templates/slug-template.html";
+static final String WHY_CARD_TEMPLATE = "templates/why-card.html";
+static final String RELATED_CARD_TEMPLATE = "templates/related-card.html";
+static final String SOCIAL_SHARE_TEMPLATE = "templates/social-share.html";
 static final String CONTENT_DIR = "content";
 static final String SITE_DIR = "site";
 static final Pattern TOKEN_PATTERN = Pattern.compile("\\{\\{(\\w+)}}");
@@ -105,12 +108,16 @@ record Empty()           implements NavArrow {}
 
 void main() throws IOException {
     var template = Files.readString(Path.of(TEMPLATE_FILE));
+    var whyCardTemplate = Files.readString(Path.of(WHY_CARD_TEMPLATE));
+    var relatedCardTemplate = Files.readString(Path.of(RELATED_CARD_TEMPLATE));
+    var socialShareTemplate = Files.readString(Path.of(SOCIAL_SHARE_TEMPLATE));
     var allSnippets = loadAllSnippets();
     IO.println("Loaded %d snippets".formatted(allSnippets.size()));
 
     // Generate HTML files
     for (var snippet : allSnippets.values()) {
-        var html = generateHtml(template, snippet, allSnippets).strip();
+        var html = generateHtml(template, whyCardTemplate, relatedCardTemplate, socialShareTemplate,
+                snippet, allSnippets).strip();
         Files.createDirectories(Path.of(SITE_DIR, snippet.category()));
         Files.writeString(Path.of(SITE_DIR, snippet.category(), snippet.slug() + ".html"), html);
     }
@@ -224,92 +231,56 @@ String renderArrow(NavArrow arrow, String label, String symbol) {
     };
 }
 
-String renderWhyCards(JsonNode whyList) {
+String renderWhyCards(String whyCardTemplate, JsonNode whyList) {
     var cards = new ArrayList<String>();
     for (var w : whyList) {
-        cards.add("""
-                <div class="why-card">
-                  <div class="why-icon">%s</div>
-                  <h3>%s</h3>
-                  <p>%s</p>
-                </div>\
-        """.formatted(
-                w.get("icon").asText(),
-                escape(w.get("title").asText()),
-                escape(w.get("desc").asText())).stripTrailing());
+        var replacements = Map.of(
+                "icon",  w.get("icon").asText(),
+                "title", escape(w.get("title").asText()),
+                "desc",  escape(w.get("desc").asText()));
+        cards.add(replaceTokens(whyCardTemplate, replacements));
     }
     return String.join("\n", cards);
 }
 
-String renderRelatedCard(Snippet rel) {
-    return """
-                <a href="/%s/%s.html" class="tip-card">
-                  <div class="tip-card-body">
-                    <div class="tip-card-header">
-                      <div class="tip-badges">
-                        <span class="badge %s">%s</span>
-                        <span class="badge %s">%s</span>
-                      </div>
-                    </div>
-                    <h3>%s</h3>
-                  </div>
-                  <div class="card-code">
-                    <div class="card-code-layer old-layer">
-                      <div class="mini-label">%s</div>
-                      <pre class="code-text">%s</pre>
-                    </div>
-                    <div class="card-code-layer modern-layer">
-                      <div class="mini-label">%s</div>
-                      <pre class="code-text">%s</pre>
-                    </div>
-                    <span class="hover-hint">Hover to see modern ➜</span>
-                  </div>
-                  <div class="tip-card-footer">
-                    <span class="browser-support"><span class="dot"></span>JDK %s+</span>
-                    <span class="arrow-link">→</span>
-                  </div>
-                </a>\
-        """.formatted(
-            rel.category(), rel.slug(),
-            rel.category(), rel.catDisplay(),
-            rel.difficulty(), rel.difficulty(),
-            escape(rel.title()),
-            escape(rel.oldLabel()), escape(rel.oldCode()),
-            escape(rel.modernLabel()), escape(rel.modernCode()),
-            rel.jdkVersion()).stripTrailing();
+String renderRelatedCard(String relatedCardTemplate, Snippet rel) {
+    var replacements = Map.ofEntries(
+            Map.entry("category",    rel.category()),
+            Map.entry("slug",        rel.slug()),
+            Map.entry("catDisplay",  rel.catDisplay()),
+            Map.entry("difficulty",  rel.difficulty()),
+            Map.entry("title",       escape(rel.title())),
+            Map.entry("oldLabel",    escape(rel.oldLabel())),
+            Map.entry("oldCode",     escape(rel.oldCode())),
+            Map.entry("modernLabel", escape(rel.modernLabel())),
+            Map.entry("modernCode",  escape(rel.modernCode())),
+            Map.entry("jdkVersion",  rel.jdkVersion()));
+    return replaceTokens(relatedCardTemplate, replacements);
 }
 
-String renderRelatedSection(Snippet snippet, Map<String, Snippet> allSnippets) {
+String renderRelatedSection(String relatedCardTemplate, Snippet snippet, Map<String, Snippet> allSnippets) {
     return snippet.related().stream()
             .filter(allSnippets::containsKey)
-            .map(path -> renderRelatedCard(allSnippets.get(path)))
+            .map(path -> renderRelatedCard(relatedCardTemplate, allSnippets.get(path)))
             .collect(Collectors.joining("\n"));
 }
 
-String renderSocialShare(String slug, String title) {
+String renderSocialShare(String socialShareTemplate, String slug, String title) {
     var pageUrl = "%s/%s.html".formatted(BASE_URL, slug);
     var shareText = "%s \u2013 java.evolved".formatted(title);
     var encodedUrl = urlEncode(pageUrl);
     var encodedText = urlEncode(shareText);
 
-    return """
-              <div class="social-share">
-                <span class="share-label">Share</span>
-                <a href="https://x.com/intent/tweet?url=%s&text=%s" target="_blank" rel="noopener" class="share-btn share-x" aria-label="Share on X">𝕏</a>
-                <a href="https://bsky.app/intent/compose?text=%s%%20%s" target="_blank" rel="noopener" class="share-btn share-bsky" aria-label="Share on Bluesky">🦋</a>
-                <a href="https://www.linkedin.com/sharing/share-offsite/?url=%s" target="_blank" rel="noopener" class="share-btn share-li" aria-label="Share on LinkedIn">in</a>
-                <a href="https://www.reddit.com/submit?url=%s&title=%s" target="_blank" rel="noopener" class="share-btn share-reddit" aria-label="Share on Reddit">⬡</a>
-              </div>\
-            """.formatted(
-            encodedUrl, encodedText,
-            encodedText, encodedUrl,
-            encodedUrl,
-            encodedUrl, encodedText).stripTrailing();
+    var replacements = Map.of(
+            "encodedUrl",  encodedUrl,
+            "encodedText", encodedText);
+    return replaceTokens(socialShareTemplate, replacements);
 }
 
 // -- Main generation logic -----------------------------------------------
 
-String generateHtml(String template, Snippet snippet, Map<String, Snippet> allSnippets) {
+String generateHtml(String template, String whyCardTemplate, String relatedCardTemplate,
+        String socialShareTemplate, Snippet snippet, Map<String, Snippet> allSnippets) {
     var replacements = Map.ofEntries(
             Map.entry("title",              escape(snippet.title())),
             Map.entry("summary",            escape(snippet.summary())),
@@ -332,11 +303,15 @@ String generateHtml(String template, Snippet snippet, Map<String, Snippet> allSn
             Map.entry("summaryJson",        jsonEscape(snippet.summary())),
             Map.entry("categoryDisplayJson", jsonEscape(snippet.catDisplay())),
             Map.entry("navArrows",          renderNavArrows(snippet)),
-            Map.entry("whyCards",           renderWhyCards(snippet.whyModernWins())),
-            Map.entry("relatedCards",       renderRelatedSection(snippet, allSnippets)),
-            Map.entry("socialShare",        renderSocialShare(snippet.slug(), snippet.title()))
+            Map.entry("whyCards",           renderWhyCards(whyCardTemplate, snippet.whyModernWins())),
+            Map.entry("relatedCards",       renderRelatedSection(relatedCardTemplate, snippet, allSnippets)),
+            Map.entry("socialShare",        renderSocialShare(socialShareTemplate, snippet.slug(), snippet.title()))
     );
 
+    return replaceTokens(template, replacements);
+}
+
+String replaceTokens(String template, Map<String, String> replacements) {
     var m = TOKEN_PATTERN.matcher(template);
     var sb = new StringBuilder();
     while (m.find()) {
diff --git a/generate.py b/generate.py
@@ -10,6 +10,9 @@
 
 BASE_URL = "https://javaevolved.github.io"
 TEMPLATE_FILE = "templates/slug-template.html"
+WHY_CARD_TEMPLATE = "templates/why-card.html"
+RELATED_CARD_TEMPLATE = "templates/related-card.html"
+SOCIAL_SHARE_TEMPLATE = "templates/social-share.html"
 CONTENT_DIR = "content"
 SITE_DIR = "site"
 
@@ -32,6 +35,14 @@ def escape(text):
     return html.escape(text, quote=True)
 
 
+def replace_tokens(template, replacements):
+    """Replace {{token}} placeholders in a template string."""
+    def replacer(m):
+        key = m.group(1)
+        return replacements.get(key, m.group(0))
+    return re.sub(r"\{\{(\w+)\}\}", replacer, template)
+
+
 def json_escape(text):
     """Escape text for embedding in JSON strings inside ld+json blocks.
 
@@ -84,89 +95,64 @@ def render_nav_arrows(data):
     return "\n          ".join(parts)
 
 
-def render_why_cards(why_list):
+def render_why_cards(why_card_template, why_list):
     """Render the 3 why-modern-wins cards."""
     cards = []
     for w in why_list:
         cards.append(
-            f"""        <div class="why-card">
-          <div class="why-icon">{w['icon']}</div>
-          <h3>{escape(w['title'])}</h3>
-          <p>{escape(w['desc'])}</p>
-        </div>"""
+            replace_tokens(why_card_template, {
+                "icon": w["icon"],
+                "title": escape(w["title"]),
+                "desc": escape(w["desc"]),
+            })
         )
     return "\n".join(cards)
 
 
-def render_related_card(related_data):
+def render_related_card(related_card_template, related_data):
     """Render a single related pattern tip-card."""
     cat = related_data["category"]
-    slug = related_data["slug"]
     cat_display = CATEGORY_DISPLAY[cat]
-    path = f"{cat}/{slug}"
-
-    return f"""        <a href="/{path}.html" class="tip-card">
-          <div class="tip-card-body">
-            <div class="tip-card-header">
-              <div class="tip-badges">
-                <span class="badge {cat}">{cat_display}</span>
-                <span class="badge {related_data['difficulty']}">{related_data['difficulty']}</span>
-              </div>
-            </div>
-            <h3>{escape(related_data['title'])}</h3>
-          </div>
-          <div class="card-code">
-            <div class="card-code-layer old-layer">
-              <div class="mini-label">{escape(related_data['oldLabel'])}</div>
-              <pre class="code-text">{escape(related_data['oldCode'])}</pre>
-            </div>
-            <div class="card-code-layer modern-layer">
-              <div class="mini-label">{escape(related_data['modernLabel'])}</div>
-              <pre class="code-text">{escape(related_data['modernCode'])}</pre>
-            </div>
-            <span class="hover-hint">Hover to see modern ➜</span>
-          </div>
-          <div class="tip-card-footer">
-            <span class="browser-support"><span class="dot"></span>JDK {related_data['jdkVersion']}+</span>
-            <span class="arrow-link">→</span>
-          </div>
-        </a>"""
-
-
-def render_related_section(related_paths, all_snippets):
+
+    return replace_tokens(related_card_template, {
+        "category": cat,
+        "slug": related_data["slug"],
+        "catDisplay": cat_display,
+        "difficulty": related_data["difficulty"],
+        "title": escape(related_data["title"]),
+        "oldLabel": escape(related_data["oldLabel"]),
+        "oldCode": escape(related_data["oldCode"]),
+        "modernLabel": escape(related_data["modernLabel"]),
+        "modernCode": escape(related_data["modernCode"]),
+        "jdkVersion": related_data["jdkVersion"],
+    })
+
+
+def render_related_section(related_card_template, related_paths, all_snippets):
     """Render all related pattern cards."""
     cards = []
     for path in related_paths:
         if path in all_snippets:
-            cards.append(render_related_card(all_snippets[path]))
+            cards.append(render_related_card(related_card_template, all_snippets[path]))
     return "\n".join(cards)
 
 
-def render_social_share(slug, title):
+def render_social_share(social_share_template, slug, title):
     """Render social share URLs using the old flat URL format."""
     page_url = f"{BASE_URL}/{slug}.html"
     share_text = f"{title} \u2013 java.evolved"
 
     encoded_url = quote(page_url, safe="")
     encoded_text = quote(share_text, safe="")
 
-    x_url = f"https://x.com/intent/tweet?url={encoded_url}&text={encoded_text}"
-    bsky_url = f"https://bsky.app/intent/compose?text={encoded_text}%20{encoded_url}"
-    li_url = f"https://www.linkedin.com/sharing/share-offsite/?url={encoded_url}"
-    reddit_url = (
-        f"https://www.reddit.com/submit?url={encoded_url}&title={encoded_text}"
-    )
-
-    return f"""  <div class="social-share">
-    <span class="share-label">Share</span>
-    <a href="{x_url}" target="_blank" rel="noopener" class="share-btn share-x" aria-label="Share on X">𝕏</a>
-    <a href="{bsky_url}" target="_blank" rel="noopener" class="share-btn share-bsky" aria-label="Share on Bluesky">🦋</a>
-    <a href="{li_url}" target="_blank" rel="noopener" class="share-btn share-li" aria-label="Share on LinkedIn">in</a>
-    <a href="{reddit_url}" target="_blank" rel="noopener" class="share-btn share-reddit" aria-label="Share on Reddit">⬡</a>
-  </div>"""
+    return replace_tokens(social_share_template, {
+        "encodedUrl": encoded_url,
+        "encodedText": encoded_text,
+    })
 
 
-def generate_html(template, data, all_snippets):
+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."""
     cat = data["category"]
     slug = data["slug"]
@@ -195,28 +181,27 @@ def generate_html(template, data, all_snippets):
         "summaryJson": json_escape(data["summary"]),
         "categoryDisplayJson": json_escape(cat_display),
         "navArrows": render_nav_arrows(data),
-        "whyCards": render_why_cards(data["whyModernWins"]),
-        "relatedCards": render_related_section(data.get("related", []), all_snippets),
-        "socialShare": render_social_share(slug, data["title"]),
+        "whyCards": render_why_cards(why_card_template, data["whyModernWins"]),
+        "relatedCards": render_related_section(related_card_template, data.get("related", []), all_snippets),
+        "socialShare": render_social_share(social_share_template, slug, data["title"]),
     }
 
-    # Replace all {{placeholder}} tokens
-    def replace_token(match):
-        key = match.group(1)
-        if key in replacements:
-            return str(replacements[key])
-        return match.group(0)
-
-    return re.sub(r"\{\{(\w+)\}\}", replace_token, template)
+    return replace_tokens(template, replacements)
 
 
 def main():
     template = load_template()
+    why_card_template = open(WHY_CARD_TEMPLATE).read()
+    related_card_template = open(RELATED_CARD_TEMPLATE).read()
+    social_share_template = open(SOCIAL_SHARE_TEMPLATE).read()
     all_snippets = load_all_snippets()
     print(f"Loaded {len(all_snippets)} snippets")
 
     for key, data in all_snippets.items():
-        html_content = generate_html(template, data, all_snippets).strip()
+        html_content = generate_html(
+            template, why_card_template, related_card_template,
+            social_share_template, data, all_snippets
+        ).strip()
         out_dir = os.path.join(SITE_DIR, data['category'])
         os.makedirs(out_dir, exist_ok=True)
         out_path = os.path.join(out_dir, f"{data['slug']}.html")
diff --git a/templates/related-card.html b/templates/related-card.html
@@ -0,0 +1,26 @@
+        <a href="/{{category}}/{{slug}}.html" class="tip-card">
+          <div class="tip-card-body">
+            <div class="tip-card-header">
+              <div class="tip-badges">
+                <span class="badge {{category}}">{{catDisplay}}</span>
+                <span class="badge {{difficulty}}">{{difficulty}}</span>
+              </div>
+            </div>
+            <h3>{{title}}</h3>
+          </div>
+          <div class="card-code">
+            <div class="card-code-layer old-layer">
+              <div class="mini-label">{{oldLabel}}</div>
+              <pre class="code-text">{{oldCode}}</pre>
+            </div>
+            <div class="card-code-layer modern-layer">
+              <div class="mini-label">{{modernLabel}}</div>
+              <pre class="code-text">{{modernCode}}</pre>
+            </div>
+            <span class="hover-hint">Hover to see modern ➜</span>
+          </div>
+          <div class="tip-card-footer">
+            <span class="browser-support"><span class="dot"></span>JDK {{jdkVersion}}+</span>
+            <span class="arrow-link">→</span>
+          </div>
+        </a>
diff --git a/templates/social-share.html b/templates/social-share.html
@@ -0,0 +1,7 @@
+  <div class="social-share">
+    <span class="share-label">Share</span>
+    <a href="https://x.com/intent/tweet?url={{encodedUrl}}&text={{encodedText}}" target="_blank" rel="noopener" class="share-btn share-x" aria-label="Share on X">𝕏</a>
+    <a href="https://bsky.app/intent/compose?text={{encodedText}}%20{{encodedUrl}}" target="_blank" rel="noopener" class="share-btn share-bsky" aria-label="Share on Bluesky">🦋</a>
+    <a href="https://www.linkedin.com/sharing/share-offsite/?url={{encodedUrl}}" target="_blank" rel="noopener" class="share-btn share-li" aria-label="Share on LinkedIn">in</a>
+    <a href="https://www.reddit.com/submit?url={{encodedUrl}}&title={{encodedText}}" target="_blank" rel="noopener" class="share-btn share-reddit" aria-label="Share on Reddit">⬡</a>
+  </div>
diff --git a/templates/why-card.html b/templates/why-card.html
@@ -0,0 +1,5 @@
+        <div class="why-card">
+          <div class="why-icon">{{icon}}</div>
+          <h3>{{title}}</h3>
+          <p>{{desc}}</p>
+        </div>
