Hedgerules handles four types of redirects, all stored in a CloudFront Key Value Store and processed by a viewer-request CloudFront Function.

Directory index redirects#

When your Hugo site has a directory like docs/, the S3 object is stored at docs/index.html. A request for /docs (no trailing slash) needs to redirect to /docs/.

Hedgerules generates these automatically by scanning your build output for directories. For every directory, it creates a KVS entry:

/docs -> /docs/

The CloudFront viewer-request function looks up the request URI in the KVS. If it finds a match, it returns a 301 redirect. If the URI ends with /, the function rewrites it to append index.html before forwarding to S3.

Hugo alias redirects#

Hugo’s aliases frontmatter lets you define old URLs that should redirect to the current page:

---
title: "Redirects"
aliases:
  - /docs/redirect-guide/
---

Hedgerules reads the _hedge_redirects.txt file (generated by the Hugo template) and creates KVS entries:

/docs/redirect-guide/ -> /docs/redirects/

Custom redirects#

You can define arbitrary site-wide redirects in your hugo.toml:

[params.HedgerulesRedirects]
  "/old-page" = "/new-page/"
  "/legacy/path" = "/modern/path/"

These are written to _hedge_redirects.txt by the Hugo template and read by Hedgerules. They appear first in the redirects file, before Hugo aliases and per-page path redirects.

Per-page path redirects#

The HedgerulesPathRedirects frontmatter parameter lets a page define redirects close to the content, rather than in the site-wide config. This is useful for creating redirects to files that don’t have frontmatter of their own (images, zip files, etc.).

Each entry has a from (the source path) and a to (the destination). If to starts with /, it is used as an absolute path. Otherwise, it is treated as relative and prefixed with the page’s RelPermalink.

---
title: "Formulae"
HedgerulesPathRedirects:
  - from: /formulae
    to: interesting-formula.pdf
  - from: /other-page
    to: /docs/somewhere-else/
---

If the page lives at /docs/formulae/, this generates:

/formulae -> /docs/formulae/interesting-formula.pdf
/other-page -> /docs/somewhere-else/

KVS constraints#

CloudFront KVS has size limits:

• Maximum key size: 512 bytes
• Maximum key + value size: 1 KB (1024 bytes)
• Maximum total data size: 5 MB

Hedgerules validates these constraints before uploading and reports errors if any entry exceeds them.