Jekyll Asset Caching Strategy for AWS S3 + CloudFront Deployment

1. Why Caching Matters

• Over-caching -> Users see old content.
• Under-caching -> Site loads slowly and burns bandwidth.

• Immutable assets get a cache buster and can be stored for a year.
• Dynamic content is always fetched fresh.

2. Cache Busting in Jekyll

// language: html
<link rel="stylesheet" href="/styles.css?v=1723366892">
<script src="/main.js?v=1723366892"></script>
<img src="/logo.png?v=1723366892">

// language: ruby
require "uri"
require "nokogiri"

module Jekyll
  # Appends ?v=<build_time> to local asset URLs (img/src, script/src, link/href).
  # - Stable per build (uses site.time if available).
  # - Preserves existing query params and fragments.
  class CacheBuster
    CACHE_BUST_KEY   = "v"
    ASSET_EXTENSIONS = %w[.png .jpg .jpeg .gif .svg .css .js .json].freeze

    @build_bust_value = nil

    Jekyll::Hooks.register [:pages, :posts, :documents], :post_render do |item|
      next unless item.output

      # One stable value for the whole build
      @build_bust_value ||= (item.site.respond_to?(:time) ? item.site.time.to_i.to_s : Time.now.to_i.to_s)
      item.output = bust_assets(item.output)
    end

    class << self
      private

      def bust_assets(html)
        doc = Nokogiri::HTML::DocumentFragment.parse(html)
        asset_tags = [["img", "src"], ["script", "src"], ["link", "href"]]

        asset_tags.each do |tag, attr|
          doc.css("#{tag}[#{attr}]").each do |node|
            url = node[attr].to_s.strip
            next if url.empty? || skip_url?(url)

            uri = safe_parse_uri(url)
            next unless uri

            path = uri.path.to_s
            is_supported_asset = !path.empty? && path.end_with?(*ASSET_EXTENSIONS)
            next unless is_supported_asset

            params = URI.decode_www_form(uri.query.to_s)
            params.reject! { |k, _| k == CACHE_BUST_KEY }
            params << [CACHE_BUST_KEY, @build_bust_value]
            uri.query = URI.encode_www_form(params)

            node[attr] = uri.to_s
          end
        end

        doc.to_html
      end

      def skip_url?(raw)
        inline_data = raw.start_with?("data:")
        external_url = raw.start_with?("http://", "https://", "//")
        inline_data || external_url
      end

      def safe_parse_uri(raw)
        URI.parse(raw)
      rescue URI::InvalidURIError
        nil
      end
    end
  end
end

3. AWS + CloudFront Deployment

// language: bash
aws s3 sync _site/ "s3://$S3_BUCKET" \
  --exclude "*" \
  --include "*.js" \
  --include "*.css" \
  --include "*.json" \
  --include "*.png" \
  --include "*.jpg" \
  --include "*.jpeg" \
  --include "*.gif" \
  --include "*.svg" \
  --cache-control "public, max-age=31536000, immutable" \
  --delete

// language: bash
aws s3 sync _site/ "s3://$S3_BUCKET" \
  --exclude "*.js" \
  --exclude "*.css" \
  --exclude "*.json" \
  --exclude "*.png" \
  --exclude "*.jpg" \
  --exclude "*.jpeg" \
  --exclude "*.gif" \
  --exclude "*.svg" \
  --cache-control "no-cache, no-store, must-revalidate" \
  --delete

// language: bash
aws cloudfront create-invalidation \
  --distribution-id "$CLOUDFRONT_DISTRIBUTION_ID" \
  --paths "/*"

4. Conclusion

• Fast: Long-term caching for static assets.
• Fresh: No-cache headers for dynamic files.
• CDN-friendly: Automatic invalidation keep content consistent worldwide.