The rewrite `posts/title -> posts/title/index.html` vs. Statocles export to GitHub Pages

[wbazant]

I mean this rewrite:

https://github.com/preaction/Mojolicious-Command-export/blob/071bf97dd06a65b2090372d4e7633e949bc9c6fd/lib/Mojolicious/Plugin/Export.pm#L264

In Statocles v2, the links from the main page, tag pages, etc. are to posts/title and the statocles daemon knows that for posts/title it should serve the post which was written to posts/title.markdown.

When the blog gets exported, it needs to get served by a static server that knows that a path posts/title corresponds to a file under posts/title/index.html, which is common behaviour.

In particular GitHub Pages works like that, except is has a sane default way of rendering posts/title from posts/title.markdown which is enabled unless I add an empty file at the root of the repo under the path .nojekyll.

For a while I didn't even notice I wasn't rendering posts on deploy in the same way as in localhost, and after I did notice, I thought I had messed around with Statocles themes too much and I've let it be. Now that I've found what it actually is and added the aforementioned .nojekyll file, my now blog is cool again - GitHub Pages redirects posts/title to posts/title/, and knows that it should show the file under posts/title/index.html

I'm not sure whether I'm contributing anything by describing this :) because Mojolicious::Command::export does an arguably reasonable thing and it's up to me to set up a static file server that will work with the files it generates.

I also don't know what's the right thing to do, the posts/title -> posts/title/index.html rewrite is probably a good idea in general (although I don't really understand the tradeoffs involved ) and supplementing it with e.g. a corresponding rewrite of URLs don't seem all that good.

[preaction]

Ugh... I've come across this problem a lot. And, yeah, making the Statocles page posts/title into the static file posts/title.html isn't always the right behavior, as that'd then involve rewriting all the links (and then folks submitting new issue reports about how the .html is undesirable and having to explain how to configure content negotiation so the web server assumes .html in absence of it...)

That being said, we could do a couple things to improve this:

1. We can document this issue and explain how to configure common deployment destinations (Apache, nginx, Github, etc...)
2. We could make it a configuration. Default is current behavior, but one can add some config value to turn page/title into page/title.html. This could also improve performance of the static site (the user would not get redirected from /page/title to /page/title/).
3. Statocles v2 could refuse to support the development and deployment branches being the same. I'm not sure if I like that, but using the same branch for both causes a lot of issues... Otherwise, Statocles could warn about that situation (+ a github remote) and recommend a .nojekyll file (or just add one and add a message about it).

We should at least do (1) so that hopefully the next person doesn't have the same problem.

[preaction]

Actually, I missed the last bit: Rewriting the URLs for /posts/title to /posts/title/ is a good idea. It removes a redirect. That could be the best solution, since it would solve everything.

[wbazant]

I agree this solves this issue if Mojolicious::Command::export continues to make pages like /posts/title.html and Statocles starts to use URLs like /posts/title/.

I've tried to consider relative goodness of /posts/title and /posts/title/ but it hasn't been really productive: they are different, but we can choose either, etc.

[preaction]

The difference between /posts/title and /posts/title/ is two parts:

1. If /posts/title is a directory with a /posts/title/index.html, the web server must redirect /posts/title to /posts/title/ or else all relative links in /posts/title/index.html will be broken (this is the thing that I keep messing up, is why I know a bit about this issue :smile:)
2. To make/posts/title work to render the file /posts/title.html, one has to configure their web server to do content negotiation (if it supports that). That can be complicated. Then, the browser's Accept header would control what file they got. So, some URLs could end up not going to the right place (for example if you have a /logo.jpg and /logo.png and choose to do <img src="/logo">).

Since all web servers are (by default at least) configured to redirect a request for a directory (/posts/title) to add a trailing slash (/posts/title/), that's probably a better default (though the option remains open to configure other ways of building paths from files). If one wants the static site to exactly match the generated site URL for URL, they'll need to do more than just move some files into /var/www.

So I think this issue should be solved by rewriting links targeting a directory to have a trailing slash, and later if someone wants they (or me) can add a mirror_urls option or something to reduce the amount of rewriting.