Static Site Generators (SSGs) — Pre-rendering the Web

Technical Deep Dive & Specifications

Web Architecture Comparison Matrix

The Universal SSG Build Pipeline

+-----------------------------------------------------------------------------------+
|                            THE UNIVERSAL SSG PIPELINE                             |
+-----------------------------------------------------------------------------------+

 1. CONTENT SOURCES:
    [Markdown Files (.md)]   [YAML / JSON Data]   [Headless CMS API (REST / GraphQL)]
             |                       |                            |
             +-----------------------+----------------------------+
                                     |
                                     v
 2. BUILD ENGINE (11ty / Hugo / Astro):
    +-------------------------------------------------------------------------------+
    | a. Parse YAML Frontmatter Metadata (title, date, author, tags)                |
    | b. Transform Markdown AST -> Semantic HTML via unified/remark/goldmark        |
    | c. Inject HTML + Metadata into Layout Templates (Nunjucks, Liquid, Go, Astro)  |
    | d. Compute Taxonomies (Tag pages, Pagination, RSS Feeds, Sitemaps)            |
    +-------------------------------------------------------------------------------+
                                     |
                                     v
 3. OUTPUT ARTIFACTS (dist/):
    ├── index.html                   (Pre-rendered homepage)
    ├── blog/
    │   ├── mastering-build-tools/index.html  (Full static HTML article)
    │   └── static-vs-dynamic/index.html
    ├── sitemap.xml
    └── feed.xml

Anatomy of a Content Document: Markdown + Frontmatter

Static site generators separate content data (metadata) from body prose using YAML Frontmatter delimited by triple dashes ---:

---
title: "The Architecture of Static Site Generators"
description: "How modern SSGs pre-render millions of pages at build time."
date: 2026-08-21
author: "Engineering Team"
tags:
  - webdev
  - performance
  - tooling
featured_image: "/assets/images/ssg-diagram.webp"
draft: false
---

Introduction to Pre-rendering

Static site generation shifts computation from request time to build time...

The SSG engine uses a library like `gray-matter` to split this document into two properties:
- `data`: A JavaScript object containing all key-value pairs defined in the YAML block.
- `content`: The raw Markdown body text, ready to be passed to a Markdown compiler.

---

💻 Interactive Code Playground

Starter Code: Eleventy (11ty) Static Build Pipeline

1. Content File (posts/speed-matters.md)

2. Master Template Layout (_includes/article-layout.njk)

3. Configuration (.eleventy.js)

Line-by-Line Code Breakdown

• posts/speed-matters.md Lines 1–8: YAML frontmatter providing metadata. The layout: "article-layout.njk" property tells 11ty which template wrapper to use.
• article-layout.njk Lines 5–10: Dynamic variables {{ title }} and {{ description }} are evaluated at build time. The resulting HTML file contains hardcoded, fully formed strings.
• article-layout.njk Lines 13–24 (<script type="application/ld+json">): Automatically generates valid Schema.org structured data for Google Search crawling without running client-side scripts.
• article-layout.njk Line 37 ({{ content | safe }}): Injects the compiled HTML generated from the Markdown body. The | safe filter prevents double-escaping of HTML tags.

Expected Generated Static HTML (_site/posts/speed-matters/index.html)

---
title: "Why Static HTML Outperforms Single Page Apps"
description: "A deep dive into Time to First Byte and Core Web Vitals."
date: 2026-08-21
author: "Ada Lovelace"
layout: "article-layout.njk"
tags: ["performance", "html"]
---

Speed is not merely a feature; it is the fundamental user experience. 

When a user agent receives pre-rendered static HTML, it can begin **DOM tokenization** immediately without waiting for megabytes of JavaScript execution.

module.exports = function(eleventyConfig) {
  // Pass static assets directly to output folder
  eleventyConfig.addPassthroughCopy("assets");

  // Custom filter for ISO Date formatting in JSON-LD
  eleventyConfig.addFilter("dateToISO", function(dateObj) {
    return new Date(dateObj).toISOString();
  });

  return {
    dir: {
      input: ".",
      includes: "_includes",
      output: "_site"
    },
    markdownTemplateEngine: "njk",
    htmlTemplateEngine: "njk"
  };
};