Fix custom 404s

[robinmetral]

Any custom 404 page under /pages/404.html won't be rendered. Cloudflare Pages expect a 404.html, but brut transforms it into 404/index.html for pretty URLs.

Possible fixes:

• avoid transforming 404s in brut (opinionated fix)
• allow a frontmatter flag to disable pretty URLs for the page (config fix)

[robinmetral]

Other option: stop prettifying URLs in brut, leave this to users (someone could author a page under /some-page/index.html to have it show at example.com/some-page/).

I wouldn't actually mind having pages at example.com/some-page.html, and I think that Cloudflare Pages actually redirects this to example.com/soma-page (no trailing slash)[^1].

Related: https://www.zachleat.com/web/trailing-slash/

Once brut comes with a dev server (for now sites using it typically install serve separately), the config for serve (or similar tool) should match brut's behavior, and perhaps the host? (I'm using Cloudflare pages). This will ensure a consistent behavior between the dev server and production

[^1]: which might actually make things complicated if brut thinks the permalink should have the .html included, for example for webmentions and the like. With that in mind, keeping "pretty urls" might have the best compatibility/most expected behavior

[robinmetral]

One of the reasons I've set up "pretty URLs" was to make Tim BL happy. You've probably already seen/been sent this: https://www.w3.org/Provider/Style/URI

But increasingly, it seems to me like this should not be the concern of a static site generator. URLs should be closer to what the raw files are authored as, so posts/first.md should be transformed into posts/first.html and not posts/first/index.html. This is easier to reason about, and more aligned with brut's philosophy.

Pretty URLs could still be achieved by authors, as mentioned above:

someone could author a page under /some-page/index.html to have it show at example.com/some-page/).

Alternatively, someone could decide to follow Tim BL's advice and remove file extensions from the URL using their web server software:

If you are using, for example, Apache, you can set it up to do content negotiation. You keep the file extension (such as .png) on the file (e.g. mydog.png), but refer to the web resource without it. Apache then checks the directory for all files with that name and any extension, and it can also pick the best one out of a set (e.g. GIF and PNG). (You do not have to put different types of file in different directories, in fact the content negotiation won't work if you do.)

[robinmetral]

Ironically, this change will not make Tim BL happy, because it will end up changing the URLs for sites that are already using brut. Since there are a grand total of 2, I think I can live with it. (I'll even be a good citizen and set up redirects.)

[robinmetral]

Re: pretty URLs or not

I looked at https://www.zachleat.com/web/trailing-slash/ again and I'm not sure that I want to remove pretty URLs anymore. Maybe they should stay for the sake of portability:

Using the (possibly outdated) research from the article, say you want to move a static site from Cloudflare Pages to Vercel. If a document was under /posts/first.html, any URLs would have to be rewritten (and redirects handled) from /posts/first (Cloudflare URL) to /posts/first.html (Vercel URL).

This behavior might be outdated (the latest available research is in this repo), but the point is that the URL is more likely to break than if the document were under /posts/first/index.html, which every host seems to agree should live at /posts/first/.

tl;dr: keeping trailing slashes for now.

---

But, and going back to the purpose of this issue, there's still the fact that Cloudlfare Pages doesn't accept a pretty 404: the 404 page needs to be named /404.html and can't be named /404/index.html.

As a temporary solution, I've implemented this suggestion from the original issue in #30:

• avoid transforming 404s in brut (opinionated fix)

Obviously, this is not great and only solves the issue for Cloudflare Pages itself. As a follow-up, I'll also start looking into the other suggestion:

• allow a frontmatter flag to disable pretty URLs for the page (config fix)

More accurately, I'm thinking of a frontmatter permalink key that would override the brut default (pretty URLs) and ensure that the file gets created at a given path. This is a common feature in generators and would allow handling edge cases like this one in a vendor-agnostic way (by moving the concern to users, who are the ones picking their host).

Closing this issue as resolved for now.