Static site hosting basics: index files, clean URLs, trailing slashes and the deploy order for fingerprinted assets

What it is

A static site is a directory tree served as-is. Three mapping rules decide what a URL returns. First, the index rule: the nginx index directive defines the files used when a request ends in a slash, checked in order, and the documentation notes that using an index file causes an internal redirect, so the request may be handled by a different location. Second, the lookup order for clean URLs: nginx try_files checks the existence of files in the specified order and uses the first found, with $uri/ testing for a directory and a final =404 returning that status; try_files $uri $uri/index.html $uri.html =404; gives /about from about.html or about/index.html. Third, the slash rule: /docs and /docs/ are different URLs, and one of them should redirect permanently to the other so that only one is linked and indexed.

Why it matters

These rules define the site's URL space for years; changing them later means redirects. They also decide the difference between a page and an error: a misconfigured fallback that serves the home page for unknown paths turns every typo into a 200 (a soft 404).

How to apply

• Choose one URL form per page (/about/ with about/index.html, or /about with about.html) and make the generator, the server rules and internal links agree.
• Send correct Content-Type for every extension the site uses (.webmanifest, .svg, .wasm, .xml); an unknown extension falls back to the server's default type.
• Fingerprint assets (app.3f9c1b.css) and give them a long freshness lifetime; give HTML a short one or require revalidation, so a deploy is visible on the next page load. The Cache-Control article covers the directives.
• Deploy in the safe order: upload new assets first, then the HTML that references them, and keep old assets for at least as long as HTML may sit in caches; a page cached yesterday must still find yesterday's CSS.
• Make the deploy atomic where the host allows it (upload to a new directory, switch a symlink or release pointer) so no request sees a half-copied tree.
• Serve a real 404 file with status 404, and keep directory listings off.

Pitfalls

Two index candidates (index.html and index.htm) in one directory produce ambiguity nobody notices until a stale file wins. Generators that emit both about.html and about/index.html create duplicate URLs. Deleting old fingerprinted assets on deploy breaks pages still open in browsers.