pages: Mention git-pages manifest in Troubleshooting page

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://website.tld/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://website.tld/.git-pages/manifest.json
+# Or a dedicated tool from git-pages
+git-pages-cli --debug-manifest https://website.tld
+```
+
+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!