docs: added nginx deployment documentation

[florian-sattler]

Added nginx deployment documentation as discussed in #3756 with some links for further reading.

[brc-dd]

This doesn't handle the case of removing trailing slash. /foo/bar/ should also check for /foo/bar.html when cleanUrls is enabled.

[florian-sattler]

@brc-dd Yes indeed. Removing the trailing slash by redirecting also has downsides: https://blog.mehdi.cc/articles/vitepress-cleanurls-on-nginx-environment#the-trade-off-for-index-pages

Using the currently described setup:

• When accessing a folder which has an index.html file this will get delivered whether or not using a trailing "/"
• When trying to access a document (e.g. example.html) this will break if being accessed using a trailing "/" (the page gets shown however filled from the error page which results in a broken sidebar as discussed in Broken sidebar when loading page #3756)

I'm currently on vacation, so I couldn't test the behavior when there is a folder (example/) along a file with the same name (example.html). This might indeed break.

Did I miss a (easy) way to handle this?

[brc-dd]

I don't think that blog post is doing things correctly. They are doing 301 redirects while vitepress explicitly states you need rewrites for cleanUrls to work (rewrites here are different than nginx rewrite directive). Rewrite basically means serving the page without doing 301/302. I'll try and update the configuration to handle that case. Basically all these cases need to be handled - https://github.com/slorber/trailing-slash-guide (the "both" test case there is ambiguous and left out to implementation. One needs to do what Netlify is doing for cleanUrls to work properly)

[meduzen]

Hi! Author of the article here.

What I do

I don't think that blog post is doing things correctly. They are doing 301 redirects while vitepress explicitly states you need rewrites for cleanUrls to work (rewrites here are different than nginx rewrite directive)

Actually I do both. My goal is that the user is always on the canonical (no trailing / nor .html), so:

• I redirect to make sure the clean URL is actually clean.
• Once redirected, I do rewrite to make sure the right path/to/file.html gets served.

For example, to serve the file at https://blog.mehdi.cc/articles.html:

• https://blog.mehdi.cc/articles is the canonical (default behaviour of Vitepress cleanUrls)
• the following URLs get redirected to the canonical:
  • https://blog.mehdi.cc/articles.html
  • https://blog.mehdi.cc/articles/
  • https://blog.mehdi.cc/articles/index.html (2 redirects: goes first to https://blog.mehdi.cc/articles/)

(And I also want all URLs to work without JavaScript in the browser. But in a way or another, static site generators have their limits, and looking at what hosting service do, there are redirects and URL inconsistencies (user point of view) in most clean URLs scenarios. So choices have to be made and URL consistency is very important for me.)

Alternatively

Since I provide a <meta name="canonical"> I could just skip the redirects, but it seems not easy with Nginx to cover all use cases, like for example the one you describe:

This doesn't handle the case of removing trailing slash. /foo/bar/ should also check for /foo/bar.html when cleanUrls is enabled.

I can’t have this without first getting rid of the trailing slash with a redirect. And then it creates more issues if. More on this in next section.

Testing domain and branch

To help with testing purpose, I opened a branch and a new subdomain:

• the only change on the branch is to moves /notes.md to /notes/index.md (while /articles.md remains at the same place).
• the subdomain https://test.blog.mehdi.cc applies the nginx config described in Vitepress doc (so the one from this PR, not the one from my article).

When doing this:

• All variations of https://test.blog.mehdi.cc/notes works (/notes, /notes/, /notes.html, /notes/index.html) to serve the file is at https://test.blog.mehdi.cc/notes/index.html, but /notes.html and /notes/index.html only works if JavaScript is available client-side
• https://test.blog.mehdi.cc/articles works but https://test.blog.mehdi.cc/articles/ fails (the wanted file is at https://test.blog.mehdi.cc/articles.html)

I also tested with rewrite ^(.+)/+$ $1; (remove trailing slash) to enable the use case quoted in the previous section (/foo/bar/): it works fine in all scenarios, but:

• forward slash fails: for /notes and /notes/ both redirect endlessly to /notes/;
• https://test.blog.mehdi.cc/articles/index.html works (redirects to https://test.blog.mehdi.cc/articles client-side) but fails without JS

(This is not the config live on the test. subdomain but I can enable it if you want to have a look.)

Let me know if you would like to test specific things.