pages: git-pages changes and troubleshooting (#854)

Hi! This updates Pages docs with more details on git-pages quirks and troubleshooting.

Adapted from https://aartaka.me/codeberg-pages.html#git-pages

Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/854
Reviewed-by: Catherine <whitequark@whitequark.org>

content/codeberg-pages/advanced-usage.md

@@ -63,4 +63,10 @@ Redirects every path under `/articles` to `/posts` while keeping the path.
 /articles/*  /posts/:splat  302
 ```
 
+{% admonition "Warning" %}
+
+`:splat` should always be the last element of the path, so something like `/*/ /:splat.html` is not a valid rule.
+
+{% endadmonition %}
+
 Example: `/articles/2022/10/12/post-1/` → `/posts/2022/10/12/post-1/`

content/codeberg-pages/migrating-from-pages-v2.md

@@ -33,6 +33,8 @@ Please be aware of the following changes and deprecated features.
 - Content is no longer fetched automatically. You need to use a method that informs git-pages about changes.
 - `raw.codeberg.page` is no longer available. CORS headers are now directly set on your page and this workaround is no longer necessary.
 - Direct access to repos and branches is no longer possible. You can no longer use the `/repository/@branch` access. `git-pages` restricts you to the website you explicitly deployed. Serving arbitrary resources from Codeberg was a common abuse vector and is going to be deprecated.
+- There no longer are automatic redirections from `path` to `path.html`, add a [redirect rule](/codeberg-pages/advanced-usage/#redirects) for each of the pages you need to redirect.
+- Splat redirects only work for simple `/old-path/* /new-path/:splat` patterns of moved posts, no way to e.g. replace file extension with `/* /:splat.html`.
 
 ## The first push
 

content/codeberg-pages/troubleshooting.md

@@ -26,3 +26,101 @@ It is important that when you use [Cloudflare](https://cloudflare.com) to manage
 that every DNS record used for Codeberg Pages needs to be set to **DNS only** (Have a gray cloud).
 This ensures that Codeberg pages can properly handle everything necessary for your site such as SSL-Certificate and
 redirects from other (sub-)domains.
+
+## Troubleshooting post-git-pages errors
+
+Given that Codeberg has moved to [git-pages](https://git-pages.org/) entirely, some behaviors changed.
+Some things broke.
+Including some undocumented behaviors website authors depended on.
+This needs troubleshooting.
+Luckily, git-pages allows troubleshooting.
+
+Say, we add this (broken) [redirect rule](/codeberg-pages/advanced-usage/#redirects) to simulate old pages server redirection to `.html` pages:
+
+```
+/*/ /:splat.html 301
+```
+
+After committing it and opening a page like `https://example.org/hello`, we are redirected to a 404 page.
+Something must be brokein in redirects.
+However, we don’t know that for sure.
+Need to check.
+
+There are two ways to find out what’s broken in the website:
+
+```
+# Plain web request
+curl https://example.org/.git-pages/manifest.json
+# Or a dedicated tool from git-pages
+git-pages-cli --debug-manifest https://example.org
+```
+
+In either case, you get huge JSONs with meta-information about the website.
+The structure is roughly:
+
+``` json
+{
+  "repoUrl": "https://codeberg.org/.../pages.git",
+  "branch": "pages",
+  "commit": "abcdef...",
+  "contents": {
+    "": {
+      "type": "Directory"
+    },
+    ".domains": {
+      // ...
+    },
+    ".gitignore": {
+      // ...
+    },
+    "assets": {
+      "type": "Directory"
+    },
+    "assets/...png": {
+      "type": "ExternalFile",
+      "originalSize": "...",
+      "compressedSize": "...",
+      "data": "...",
+      "transform": "Identity",
+      "contentType": "image/png",
+      "gitHash": "..."
+    },
+    "index.html": {
+      "type": "ExternalFile",
+      "originalSize": "...",
+      "compressedSize": "...",
+      "data": "...",
+      "transform": "Zstd",
+      "contentType": "text/html; charset=utf-8",
+      "gitHash": "..."
+    }
+    // ...
+  },
+  "originalSize": "...",
+  "compressedSize": "...",
+  "storedSize": "...",
+  "redirects": [
+    {
+      "from": "/foo",
+      "to": "/bar",
+      "status": 301,
+      "force": false
+    },
+    // ...
+  ],
+  "headers": [],
+  "basicAuth": [],
+  "problems": [
+    {
+      "path": "_redirects",
+      "cause": "rule #1 \"/*/ /:splat.html 301\": splat * must be its own final segment of the path"
+    }
+  ]
+}
+```
+
+And here’s the problem, under the `"problems"` key: the redirect is malformed!
+In the end, this is one of the [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations) that happened in migration.
+But lamenting that is a story for another time.
+Problem diagnosed through the useful git-pages manifest!
+Use it to diagnose errors from now on!