Accessing Web Files with Stable URLs (Without <anti-cache> Value)

By default, when you generate a URL to a web file in a JSP or Freemarker template using the hst:webfile tag, the resulting URL includes an <anti-cache> value. For example, in Freemarker:

<@hst.webfile var="link" path="/js/script.js" />
<script src="${link}" />
copy

This generates a URL in the format:

/webfiles/<anti-cache>/js/script.js

The <anti-cache> segment changes whenever the web file is modified. This mechanism enables the server to send web files with a long-lived Expires header (for example, one year), allowing browsers to cache the files indefinitely until they change.

However, some use cases require a stable URL for web files. For example, if an external system (such as a Node.js server) needs to access a web file but cannot determine the current <anti-cache> value, you need a predictable URL path.

Providing Stable URLs for Web Files

To create a stable URL for a web file, configure a sitemap item under hst:default that replaces the <anti-cache> segment with a fixed value. For example, to make script.js available at:

/webfiles/latest/js/script.js

add a sitemap item named latest under hst:default/hst:configurations/hst:sitemap/webfiles. Use the following YAML configuration:

definitions:
  config:
    /hst:hst/hst:configurations/hst:default/hst:sitemap/webfiles/latest:
      jcr:primaryType: hst:sitemapitem
      /_any_:
        jcr:primaryType: hst:sitemapitem
        hst:relativecontentpath: ${1}
copy

After adding this configuration and restarting the application, the repository will include these sitemap items:

/hst:hst:
  /hst:configurations:
    /hst:default:
      /hst:sitemap:
        /webfiles:
          /_default_ :
            /_any_:
          /latest:
            /_any_:
copy

You can now access the script.js file using the stable URL:

/webfiles/latest/js/script.js

This approach allows external systems to reference web files with a consistent URL, regardless of the internal <anti-cache> value.