Improve integration with cloud static website hosting

[depp]

Proposal: Add an option to remap files named <dir>/index.html to <dir>/ during deployment.

Background

Traditional web servers (e.g. Apache, nginx) are typically configured to serve index.html files when users visit a directory. However, blob storage systems (e.g. S3, GCS) let you create files with names ending in /, and this is sometimes preferred.

For example, let’s say you deploy your site to an S3 bucket and CloudFront distribution. The simplest way to do this is to just use an S3 origin for your CloudFront distribution. However, this simple setup doesn’t work with Hugo out of the box—your website root / will correctly map to the root index.html file, but subdirectories will not work. You will get a 404 error for dir/, because CloudFront will look for an S3 object named dir/ instead of dir/index.html.

There are some workarounds for this:

• You can enable “static website hosting” for your S3 bucket, set the index document to index.html, and configure CloudFront to use an HTTP origin that points to the S3 bucket. However, this prevents you from using the normal authentication & authorization systems that you would otherwise get, so this option only works for sites that are public.

• You can use a CloudFront function to remap requests to dir/ to request dir/index.html, but this adds complexity and code to what would otherwise be a no-code configuration. See: https://stackoverflow.com/a/76581267

Solution

Add a new option to the deployment.targets section of the configuration called stripIndexHTML. This option maps any local file named <dir>/index.html to a remote file named <dir>/. The root page, index.html, is untouched.

This is “elegant” because this just means that the remote file path matches the canonical URLs that Hugo uses anyways. Your link to dir/ maps to a remote file named dir/.

Impact

From a web search, I can see that other people using Hugo have experienced this problem:

• discourse.gohugo.io: “Index.html pages in S3 bucket aren’t loading through CloudFront distribution”
• Stack Overflow: “Hugo on S3 with CloudFront doesn't redirect to index.html.”
• Stack Overflow: “Hugo multilingual site deploy to aws s3 error ‘AccessDenied’”
• Stack Overflow: “AWS static links fail without ‘index.html’”

[bep]

@vangent ... does the above match your world view?

[vangent]

I do not have any expertise in web site hosting, but the explanation sounds plausible and the proposed solution doesn't sound too hard.