From 83ac61e9a8fb62f8ca56353cb6ac8e92b9739f3a Mon Sep 17 00:00:00 2001 From: Kilian Koeltzsch Date: Fri, 12 Sep 2025 15:32:49 +0200 Subject: [PATCH] add warning about pages for repositories with a dot in the name (#670) Hi, coming from https://codeberg.org/Codeberg/pages-server/issues/512, this adds a warning that repos with dots in the name can cause issues when trying to set up a custom domain. I'm not sure if the wording here fits the existing docs, or if hints like this fit in the docs at all, but I wanted to open this as a suggestion nonetheless :) Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/670 Reviewed-by: Bastian Greshake Tzovaras Co-authored-by: Kilian Koeltzsch Co-committed-by: Kilian Koeltzsch --- content/codeberg-pages/using-custom-domain.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/content/codeberg-pages/using-custom-domain.md b/content/codeberg-pages/using-custom-domain.md index fd87e10..caa8281 100644 --- a/content/codeberg-pages/using-custom-domain.md +++ b/content/codeberg-pages/using-custom-domain.md @@ -83,6 +83,20 @@ Depending on from where you want to serve your files, there is a naming scheme f +{% admonition "warning" "Repository names with dots are not supported" %} + +Repository names containing dots (`.`) are **not supported** for custom domains. The Pages server uses dots as delimiters to parse the repository name, branch, and owner from DNS records. + +For example, if your repository is named `my.project`, the TXT record `my.project.username.codeberg.page` will be incorrectly parsed as: + +- Branch: `my` +- Repository: `project` +- Owner: `username` + +**Solution:** If you need to use a custom domain, rename your repository to use hyphens (`-`) or underscores (`_`) instead of dots. For example, rename `my.project` to `my-project`. + +{% endadmonition %} + _We assume for the following description, that you want to serve your website with and without www in front. If you are on a subdomain already (like myproject.yourdomain.com), you can skip the `www.yourdomain.com` CNAME entry._