Document HTTP cache config

content/en/getting-started/configuration.md

@@ -850,6 +850,53 @@ If you want to know the current value of `cacheDir`, you can run `hugo config`,
 [static-files]: /content-management/static-files/
 
 
+## Configure HTTP cache
+
+{{< new-in 0.127.0 >}}
+
+Note that this configuration is currently only relevevant when using the [resources.GetRemote] function.
+
+The caching in Hugo is layered:
+
+```goat {.w-40}
+ .-----------.
+|  dynacache  |
+ '-----+-----'
+       |
+       v
+ .----------.
+| HTTP cache |
+ '-----+----'
+       |
+       v
+ .----------.
+| file cache |
+ '-----+----'
+```
+
+Dynacache
+: A in memory LRU cache that gets evicted on changes, [Cache Buster](#configure-cache-busters) matches and in low memory situations.
+
+HTTP Cache
+: Enables HTTP cache behaviour (RFC 9111) for remote resources. This works best for resources with properly set up HTTP cache headers. The HTTP cache uses the [file cache] to store and serve cached resources.
+
+File Cache
+: See [file cache].
+
+
+The default HTTP cache configuration is:
+
+{{< code-toggle config=HTTPCache />}}
+
+caching
+: Enabled RFC 9111 cache behaviour _for_ a configured set of resources. Stale resources will be refreshed from the [file cache] even if their configured TTL isn't reached.
+
+polling
+: Enables polling _for_ a set of resources. Note that you can enable polling for resources even if caching is disabled. This setting is only used when in watch mode (e.g. `hugo server`). When a change resource is detected, that change triggers a rebuild of pages using that resource.
+
+[resources.GetRemote]: /functions/resources/getremote/
+[file cache]: #configure-file-caches
+
 ## Configure segments
 
 {{< new-in 0.124.0 >}}
@@ -914,3 +961,4 @@ Some use cases for this feature:
 [kind]: /getting-started/glossary/#page-kind
 [output format]: /getting-started/glossary/#output-format
 [type]: /getting-started/glossary/#content-type
+

data/docs.yaml

@@ -926,6 +926,36 @@ chroma:
     - zig
     Name: Zig
 config:
+  HTTPCache:
+    caching:
+      for:
+        excludes:
+        - '**{.jpg,.jpeg,.png,.webp,.gif,.ttf}'
+        includes:
+        - '**'
+    polls:
+    - disable: true
+      for:
+        excludes: null
+        includes:
+        - '**{.jpg,.jpeg,.png,.webp,.gif,.ttf}'
+      high: 0s
+      low: 0s
+    - disable: false
+      for:
+        excludes: null
+        includes:
+        - https://*.git.luolix.top/**
+        - https://*.twitter.com/**
+      high: 30m0s
+      low: 10m0s
+    - disable: false
+      for:
+        excludes: null
+        includes:
+        - '**'
+      high: 30s
+      low: 1s
   archeTypeDir: archetypes
   assetDir: assets
   author: {}
@@ -939,6 +969,7 @@ config:
     cacheBusters:
     - source: (postcss|tailwind)\.config\.js
       target: (css|styles|scss|sass)
+    duplicateResourceFiles: false
     noJSConfigInAssets: false
     useResourceCacheWhen: fallback
   buildDrafts: false
@@ -1721,6 +1752,8 @@ config_helpers:
       _merge: none
     frontmatter:
       _merge: none
+    httpcache:
+      _merge: none
     imaging:
       _merge: none
     languages: