Add more explanation for git-pages/action server: option. (#826)

Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/826
Reviewed-by: crystal <crystal@noreply.codeberg.org>
Reviewed-by: Bastian Greshake Tzovaras <gedankenstuecke@noreply.codeberg.org>

content/codeberg-pages/forgejo-actions.md

@@ -11,14 +11,44 @@ You can use any such tool you like: git-pages does not privilege any particular
 
 If you already use a static site generator and/or already use Forgejo Actions, using the pre-made Forgejo Action is by far the simplest and most efficient way to publish your site to Codeberg Pages.
 
-To use it, simply add it as a final step to your workflow:
+**If you use a `*.codeberg.page` subdomain,**
+add the following step at the end of your workflow after replacing `repository-name` in the `site` parameter with the name of your repository:
 
 {% raw %}
 
 ```yaml
 - uses: https://codeberg.org/git-pages/action@v2
   with:
-    site: 'https://${{ forge.repository_owner }}.codeberg.page/repository-name/'
+    site: https://${{ forge.repository_owner }}.codeberg.page/repository-name/
+    token: ${{ forge.token }}
+    source: _site/
+```
+
+{% endraw %}
+
+To publish a site to the root of your subdomain, `https://username.codeberg.page/`, ensure your repository is called `pages`, and add the following step instead:
+
+{% raw %}
+
+```yaml
+- uses: https://codeberg.org/git-pages/action@v2
+  with:
+    site: https://${{ forge.repository_owner }}.codeberg.page/
+    token: ${{ forge.token }}
+    source: _site/
+```
+
+{% endraw %}
+
+**If you use a custom domain,**
+add the following step at the end of your workflow after replacing `yourdomain.com` with your custom domain:
+
+{% raw %}
+
+```yaml
+- uses: https://codeberg.org/git-pages/action@v2
+  with:
+    site: https://yourdomain.com/
     server: codeberg.page
     token: ${{ forge.token }}
     source: _site/
@@ -26,8 +56,9 @@ To use it, simply add it as a final step to your workflow:
 
 {% endraw %}
 
-Replace `repository-name` in the `site` parameter with the name of your repository.
+The `server` parameter directs the Action to upload your site to a specific git-pages server instead of resolving the A/AAAA records DNS records specified in the `site` parameter. It may be specified as `codeberg.page` anytime a site is published to Codeberg Pages, but is **required** for publishing a site on a custom domain for the first time.
-If your repository is also called `pages`, you can also omit the repository name and deploy directly to the site `https://username.codeberg.page/`.
+
+This is caused by a circular dependency: git-pages will not issue a TLS certificate unless a site exists on that domain, but contacting it over HTTPS is not possible unless a TLS certificate is obtained. When the `site` parameter is specified, the HTTPS connection is established with the specified server (`codeberg.page` in this case), and the custom domain is passed in the `Host:` header instead, breaking this loop.
 
 The `source` parameter should point to the directory (relative to the root, after all previous steps in your workflow) where your site generator has put the generated version of your site.
 This directory can also contain the `404.html` and `_redirects` files to customize your site’s behavior, as described in the [advanced documentation](/codeberg-pages/advanced-usage/).

content/codeberg-pages/using-custom-domain.md

@@ -143,7 +143,7 @@ so keep an eye on Codeberg updates to check.
  </tbody>
 </table>
 
-### Step 2: Configure Git-pages authorization
+### Step 2: Configure git-pages authorization
 
 {% admonition "question" "Why do I need all these extra DNS records?" %}
 
@@ -219,7 +219,7 @@ For technical reasons, the first deployment needs to go over HTTP and you need t
 After the first successful deployment you can change it to the `https://` scheme.
 
 **If you deploy from Forgejo Actions,**
-the `site` parameter to the Git-pages action should be set to the URL of your custom domain.
+the `site` parameter to the git-pages action should be set to the URL of your custom domain, and the `server` parameter should be set to `codeberg.page`. The [Forgejo Actions guide](/codeberg-pages/forgejo-actions/) includes example workflows and more information.
 
 ### Deploying to versions of your domain both with and without `www.`