Add improvements to the Documentation according to open issues (#314)

Tried to close some open issues in the issue tracker by submitting the following changes as my first contribution to Codeberg:

 - added list on every section index page, should fix #63
 - added webhooks documentation, should fix #282
 - described behaviour of a limited user profile, should fix #279
 - added further explanation to 2fa section, according to Codeberg/Documentation#268, should fix #268
 - added codeberg badge generator to first-repository description, should fix #39
 - added dns record description to custom-domains, should fix #302
 - added description how to use 2fa with git, should fix #278
 - added and updated repo migration service description, should fix #312

Feedback highly appreciated.

Co-authored-by: f0sh <f0sh@mailbox.org>
Co-authored-by: Panagiotis "Ivory" Vasilopoulos <git@n0toose.net>
Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/314
Co-authored-by: f0sh <f0sh@noreply.codeberg.org>
Co-committed-by: f0sh <f0sh@noreply.codeberg.org>

content/advanced/index.md

@@ -11,3 +11,23 @@ the more advanced features of Codeberg.
 
 See also the [documentation of Gitea](https://docs.gitea.io), the software which
 Codeberg is based on.
+
+{% assign navPages = collections.all | eleventyNavigation %}
+{%- for entry in navPages %}
+{% if entry.url == page.url %}
+{%- if entry.children.length -%}
+<table class="table">
+  <thead>
+    <th> Find out more in this section: </th>
+  </thead>
+  <tbody>
+{%- for child in entry.children %}
+    <tr><td>
+        <a href="{{ child.url }}">{{ child.title }}</a>
+    </tr></td>
+{%- endfor %}
+  </tbody>
+</table>
+{% endif %}
+{% endif %}
+{%- endfor %}

content/advanced/migrating-repos.md

@@ -15,12 +15,22 @@ This works well for moving files, but when you want to migrate metadata like iss
   <img src="/assets/images/advanced/migrating-repos/new-migration.png">
 </picture>
 
-On Codeberg, you can click on the plus symbol on the top right, and then select [`New Migration`](https://codeberg.org/repo/migrate) on the dropdown to access the migration tool. 
+On Codeberg, you can click on the plus symbol on the top right, and then select [**New Migration**](https://codeberg.org/repo/migrate) on the dropdown to access the migration tool. 
 
 ## Selecting your host
-Once you're at the [`New Migration`](https://codeberg.org/repo/migrate) page, you can select the Git host you are migrating from. If it's not on the list, you will have to select the Git option. This will not migrate metadata.
+Once you're at the [**New Migration**](https://codeberg.org/repo/migrate) page, you can select the Git host you are migrating from. For the following services, the migration tool can not only migrate your repository data, but also metadata like issues, labels, wiki, releases, milestones, etc.
 
-Here we document instructions for migrating specific to each service. Once you've followed through, move on to [`Starting Migration`](#starting-migration).
+  - [Github](#migrating-from-services)
+  - [GitLab](#migrating-from-services)
+  - [Gitea / Forgejo](#migrating-from-services)
+  - [Gogs](#migrating-from-services)
+  - [OneDev](#migrating-from-services)
+  - [GitBucket](#migrating-from-services)
+  - [Codebase](#migrating-from-services)
+
+If you cannot find your service, you can select the [Git option](#migrating-from-git). This will not migrate mentioned metadata.
+
+Here we document instructions for migrating specific to each service. Once you've followed through, move on to [Starting Migration](#starting-migration).
 
 ### Migrating from Git
 <picture>
@@ -32,10 +42,9 @@ Here's an explanation of some fields on the [Git migration page](https://codeber
 - **Migrate / Clone From URL**: This is the URL to your repository. For example: `https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git`.
 - **Username and Password**: Optionally, if authentication is required to access the repo, you can enter a username and password here.
 
-### Migrating from Gitea
-To migrate a repo with its metadata from a Gitea instance, you will first need to [create an access token](/advanced/access-token/) on the Gitea instance with your repository. Don't forget to delete the access token when you are finished.
+### Migrating from Services
 
-> You can also use this method to migrate your repos away from Codeberg to another Gitea instance.
+To migrate a repo with its metadata from a different service, you will first need to [create an access token](/advanced/access-token/) on the service with your repository. *Please check your services documentation, on how to get the access token.* Examples can be found for [Gitlab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) and [Github](https://github.com/settings/tokens).  Don't forget to delete the access token once you are finished.
 
 <picture>
   <source srcset="/assets/images/advanced/migrating-repos/gitea-migration.webp" type="image/webp">
@@ -44,8 +53,15 @@ To migrate a repo with its metadata from a Gitea instance, you will first need t
 
 Here's an explanation of some fields on the [Gitea migration page](https://codeberg.org/repo/migrate?service_type=3):
 - **Migrate / Clone From URL**: This is the URL to your repository. For example: `https://gitea.com/gitea/tea`.
-- **Access Token**: You will paste the access token generated here. An access token is required to migrate metadata.
+- **Access Token**: You will paste the access token generated here. An access token is required to migrate metadata or non-public repositories.
 - **Migration Items**: Here you can select the metadata you want migrated.
+- **Owner**: The new owner of the migrated repository.
+- **Repository Name**: The name of the migrated repository.
+- **Visibility**: Select if the migrated repository should be private or public.
+- **Description**: Give your migrated repository a description.
+
+> **Hint** <br />
+> You can also use this method to migrate your repos away from Codeberg to another Gitea or Forgejo instance.
 
 ## Starting Migration
 

content/advanced/using-webhooks.md

@@ -0,0 +1,87 @@
+---
+eleventyNavigation:
+  key: UsingWebhooks
+  title: Using Webhooks
+  parent: AdvancedUsage
+---
+
+Webhooks can help you to automate working with your repository. For example it can trigger an defined action if someone pushes to your repository or opens a new issue by using a target web URL.
+
+Detailed documentation on how to use webhooks can be found in the [forgejo Documentation](https://forgejo.org/docs/latest/user/webhooks/).
+
+The following paragaphs will give concrete examples on how to use webhooks with some services.
+
+Currently, Codeberg offers implementation templates for the following services:
+
+  - Forgejo
+  - Slack
+  - Discord
+  - DingTalk
+  - Telegram
+  - Microsoft Teams
+  - Feishu
+  - Matrix
+  - WeCom
+  - Packagist
+
+Every service that offers webhook functionality can be added using the **Forgejo** template using the **webhook URL** provided by the service.
+
+## Using Read the Docs
+
+To better illustrate how webhooks can be used, we prepared a tutorial for you that works with *[Read the Docs](https://readthedocs.io). In this example, we will show you how to build your documentation every time that a new commit is pushed to your Codeberg repository.
+
+<picture>
+  <source srcset="/assets/images/advanced/using-webhooks/using-webhooks-readthedocs-2.webp" type="image/webp">
+  <img src="/assets/images/advanced/using-webhooks/using-webhooks-readthedocs-2.jpg" alt="Open the admin settings on ReadTheDocs">
+</picture>
+
+  1. Login into your *Read the Docs* account and **select the project** you want to add a webhook to.
+  2. Click on the **Admin** button.
+  3. In the left side menu, click on **Integrations**.
+
+<picture>
+  <source srcset="/assets/images/advanced/using-webhooks/using-webhooks-readthedocs-3.webp" type="image/webp">
+  <img src="/assets/images/advanced/using-webhooks/using-webhooks-readthedocs-3.jpg" alt="Open the admin settings on ReadTheDocs">
+</picture>
+
+  4. Click on the button **Add Integration**.
+  5. Select **GitHub incoming webhook**. (GitHub, GitLab or BitBucket incoming webhooks, all work equally well and generate the needed webhook URL)
+
+<picture>
+  <source srcset="/assets/images/advanced/using-webhooks/using-webhooks-readthedocs-4.webp" type="image/webp">
+  <img src="/assets/images/advanced/using-webhooks/using-webhooks-readthedocs-4.jpg" alt="Open the admin settings on ReadTheDocs">
+</picture>
+
+  6. A **webhook address** will be displayed to you. Write it down and keep it safe!
+
+Now go to your Codeberg repository.
+
+  1. Go to your repository and click on **Settings**.
+  2. In the top menu, click on **Webhooks**.
+
+<picture>
+  <source srcset="/assets/images/advanced/using-webhooks/using-webhooks-codeberg-1.webp" type="image/webp">
+  <img src="/assets/images/advanced/using-webhooks/using-webhooks-codeberg-1.jpg" alt="Open the admin settings on ReadTheDocs">
+</picture>
+
+  3. Click on **Add Webhook** and choose **Forgejo**.
+  4. Paste the **webhook address** provided by *Read the Docs* into the **Target URL** field.
+  5. You can select when the webhook should be triggered using the **Trigger On** setting. For illustrative purposes, we will select **Push Events**; this will trigger the webhook everytime that someone pushes to your repository.
+
+<picture>
+  <source srcset="/assets/images/advanced/using-webhooks/using-webhooks-codeberg.webp" type="image/webp">
+  <img src="/assets/images/advanced/using-webhooks/using-webhooks-codeberg.jpg" alt="Open the admin settings on ReadTheDocs">
+</picture>
+
+In this example, we do not need to use any other fields to make the webhook work. For your personal reference, here are some explanations as to what these other fields do:
+
+  - **HTTP Method**: Should be "POST" by default, so that the data is sent within the HTTP header
+  - **POST Content Type**: specifies how the data should be sent in the header. "application/json" and "application/x-www-form-urlencoded" both work with *Read the Docs*
+  - **Secret**: For authentication reasons, you can send a secret. For ReadTheDocs leave it empty.
+  - **Branch filter**: You can define, that the webhook is only triggered on certain branches in your repository
+  - **Authorization Header**: Some services need an authorization to call the webhook
+
+Once you're done, you can click on **Add Webhook** to add the webhook to your repository.
+Now, whenever something is pushed to your repository, the webhook will trigger and your *Read the Docs* documentation will be rebuilt.
+
+You can confirm that everything is working as it should by selecting the webhook that you just created and clicking on the button **Test Delivery**, which will manually trigger your webhook.

content/codeberg-pages/index.md

@@ -16,6 +16,26 @@ Follow these simple steps below to get started, or check out the advanced usage
 
 See also [https://codeberg.page/](https://codeberg.page) or the [Troubleshooting](troubleshooting) page.
 
+{% assign navPages = collections.all | eleventyNavigation %}
+{%- for entry in navPages %}
+{% if entry.url == page.url %}
+{%- if entry.children.length -%}
+<table class="table">
+  <thead>
+    <th> Find out more in this section: </th>
+  </thead>
+  <tbody>
+{%- for child in entry.children %}
+    <tr><td>
+        <a href="{{ child.url }}">{{ child.title }}</a>
+    </tr></td>
+{%- endfor %}
+  </tbody>
+</table>
+{% endif %}
+{% endif %}
+{%- endfor %}
+
 ## Advanced Usage: Canonical URLs
 
 The Codeberg Pages server responds to four different URLs:
@@ -27,134 +47,6 @@ The Codeberg Pages server responds to four different URLs:
 
 In all cases, you can append a branch using an `@` (e.g. `https://username.codeberg.page/@develop/README.md`). If the branch name contains a slash (`/`), they need to be replaced with a tilde (`~`) (e.g. the branch `docs/develop` can be accessed via `https://username.codeberg.page/@docs~develop/README.md`).
 
-## Custom Domains
-
-> **Currently known pitfalls for failed certificates:**  
-> - you must either not have a [CAA record](https://en.wikipedia.org/wiki/DNS_Certification_Authority_Authorization#Record), or explicitly allow [LetsEncrypt](https://letsencrypt.org) there
-
-For custom domains, two things are required:
-- a `.domains` file in the repository (in the branch in question), containing a list of *all* domains that shall be usable to access that repository, according to the following rules:
-  - One domain per line, you can leave lines empty and comment out lines with `#`.
-  - The first domain is the main one where all other domains in the file will be redirected to.
-  - The rest of the list includes also all relevant `*.codeberg.page` domains for the specific repository.
-- a CNAME record pointing to one of the following targets:
-  - `username.codeberg.page` → https://username.codeberg.page
-  - `reponame.username.codeberg.page` → https://username.codeberg.page/reponame/
-  - `branchname.reponame.username.codeberg.page` → https://username.codeberg.page/reponame/@branchname/
-  
-If you can't use a CNAME record to configure the target (e.g. for a zone root), you can use an A/AAAA/ALIAS record to `codeberg.page` with an additional TXT record for the target (`[[branch.]repo.]user.codeberg.page`, just as shown above for CNAME records).
-
-The following sub-sections include a few examples of the different alternatives, assuming the following:
-
-- we can add/modify DNS records in domain `example.com`.
-- Our Codeberg username is `frida`, and we want to publish pages for:
-    - `frida/pages`, with a *Personal* static site inside branch `pages`;
-    - `frida/colormix`, with a *Project* site (again, inside branch `pages`).
-
-All considerations regarding a *Personal* site also apply to an *Organization* site, so these two cases will be addressed together.
-
-### Personal (or Organization) site, third level domain
-
-In this case, we want our *Personal* pages available at the URL `https://myself.example.com`.
-
-The `.domains` file contains the following:
-
-```
-myself.example.com
-frida.codeberg.page
-pages.frida.codeberg.page
-pages.pages.frida.codeberg.page
-```
-
-For the DNS configuration:
-
-- if CNAME can be used, one single DNS record will suffice:
-    - name `myself.example.com`, type `CNAME`, data `frida.codeberg.page`
-
-- otherwise, if ALIAS can be used, two DNS records will be needed:
-    - name `myself.example.com`, type `ALIAS`, data `codeberg.page`
-    - name `myself.example.com`, type `TXT`, data `frida.codeberg.page`
-
-- otherwise, A/AAAA records must be used, together with one TXT record:
-    - name `myself.example.com`, type `A`, data `217.197.91.145`
-    - name `myself.example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
-    - name `myself.example.com`, type `TXT`, data `frida.codeberg.page`
-
-### Personal/Organization site, apex domain
-
-In this case, we want our *Personal*/*Organization* pages available at the URL `https://example.com`.
-
-The `.domains` file contains the following:
-
-```
-example.com
-frida.codeberg.page
-pages.frida.codeberg.page
-pages.pages.frida.codeberg.page
-```
-
-For the DNS configuration, the CNAME SHOULD NOT be used, so:
-
-- if ALIAS can be used, two DNS records will be needed:
-    - name `example.com`, type `ALIAS`, data `codeberg.page`
-    - name `example.com`, type `TXT`, data `frida.codeberg.page`
-
-- otherwise, A/AAAA records must be used, together with one TXT record:
-    - name `example.com`, type `A`, data `217.197.91.145`
-    - name `example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
-    - name `example.com`, type `TXT`, data `frida.codeberg.page`
-
-### Project site, third-level domain
-
-In this case, we want our *Project* pages available at the URL `https://colormix-app.example.com`.
-
-The `.domains` file contains the following:
-
-```
-colormix-app.example.com
-colormix.frida.codeberg.page
-pages.colormix.frida.codeberg.page
-```
-
-For the DNS configuration:
-
-- if CNAME can be used, one single DNS record will suffice:
-    - name `colormix-app.example.com`, type `CNAME`, data `colormix.frida.codeberg.page`
-
-- otherwise, if ALIAS can be used, two DNS records will be needed:
-    - name `colormix-app.example.com`, type `ALIAS`, data `codeberg.page`
-    - name `colormix-app.example.com`, type `TXT`, data `colormix.frida.codeberg.page`
-
-- otherwise, A/AAAA records must be used, together with one TXT record:
-    - name `colormix-app.example.com`, type `A`, data `217.197.91.145`
-    - name `colormix-app.example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
-    - name `colormix-app.example.com`, type `TXT`, data `colormix.frida.codeberg.page`
-
-### Project site, apex domain
-
-In this case, we want our *Project* pages available at the URL `https://example.com`.
-
-> Note: this would be incompatible with using the apex `example.com` for other purposes, e.g. for the *Personal*/*Organization* example discussed before.
-
-The `.domains` file contains the following:
-
-```
-example.com
-colormix.frida.codeberg.page
-pages.colormix.frida.codeberg.page
-```
-
-For the DNS configuration, CNAME SHOULD NOT be used:
-
-- if ALIAS can be used, two DNS records will be needed:
-    - name `example.com`, type `ALIAS`, data `codeberg.page`
-    - name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`
-
-- otherwise, A/AAAA records must be used, together with one TXT record:
-    - name `example.com`, type `A`, data `217.197.91.145`
-    - name `example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
-    - name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`
-
 
 
 ## Do you have questions, feedback or have you found a bug?

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

@@ -0,0 +1,250 @@
+---
+eleventyNavigation:
+  key: UsingCustomDomains
+  title: Using Custom Domains
+  parent: CodebergPages
+  order: 10
+---
+
+Instead of using the `codeberg.page` Domain, you can also purchase your own domain from your internet service provider of your choice and configure it to serve content from Codeberg Page.
+
+> **Currently known pitfalls for failed certificates:**  
+> - you must either not have a [CAA record](https://en.wikipedia.org/wiki/DNS_Certification_Authority_Authorization#Record), or explicitly allow [LetsEncrypt](https://letsencrypt.org) there
+
+For custom domains, two things are required:
+
+- a `.domains` file in the repository and branch where your files reside which you want to publish via Codeberg Pages. The file should contain a list of *all* domains that shall be usable to access that repository, according to the following rules:
+
+  - One domain per line, you can leave lines empty and comment out lines with `#`.
+  - The first domain is the main domain, all other domains in the file will be redirected to the first one.
+  - The rest of the list includes also all relevant `*.codeberg.page` domains for the specific repository.
+
+- a [DNS record](https://en.wikipedia.org/wiki/Domain_Name_System#Address_resolution_mechanism) pointing to one of the following targets, depending on where your static files reside: 
+
+<br />
+
+> **Why do I need all these DNS records?** <br />
+> To understand how the Pages Server serves content, you need to know that a user browsing your custom domain just sends "Hey, I want to see `yourdomain.com`" to the server. But the server might not know, that it is responsible for `yourdomain.com` and it cannot just server all domains in the world. So to find out if the server is responsible for `yourdomain.com` it will check the DNS entries of `yourdomain.com`. If it returns something with `codeberg.page` (according to the domain schemes mentioned below) then it knows, which respository to check for the `.domains` file and your content. 
+
+## Setting the DNS record
+
+There are several ways on how DNS records for your website can be setup in order to tell the Pages server your repository location. For all of the options it is important, that the Pages server knows where to look for the `.domains` file and your content. Depening on from where you want to serve your files, there is a naming scheme for the domain:
+
+<table class="table">
+<thead>
+<th>Domain Scheme</th>
+<th>Pages URL</th>
+</thead>
+<tbody>
+<tr>
+<td><code>username.codeberg.page</code></td>
+<td>https://username.codeberg.page <br /> which will serve <code>codeberg.org/username/pages</code></td>
+</tr>
+<tr>
+<td><code>reponame.username.codeberg.page</code></td>
+<td>https://username.codeberg.page/reponame <br /> which will serve <code>codeberg.org/username/reponame</code></td>
+</tr>
+<tr>
+<td><code>branchname.reponame.username.codeberg.page</code></td>
+<td>https://username.codeberg.page/reponame/@branchname/<br /> which will serve <code>codeberg.org/username/reponame/src/branch/branchname</code></td>
+</tr>
+</tbody>
+<table>
+
+*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.*
+
+**Option 1: CNAME record**
+
+The easiest and recommended way is to just setup a CNAME record for your domain, pointing to the mentioned above locations. In the end, it should look like this:
+ 
+<table class="table">
+<thead>
+<th>Domain</th>
+<th>Type</th>
+<th>Data</th>
+</thead>
+<tbody>
+<tr>
+<td>yourdomain.com</td><td>CNAME</td><td>reponame.username.codeberg.page</td>
+</tr>
+<tr>
+<td>www.yourdomain.com</td><td>CNAME</td><td>reponame.username.codeberg.page</td>
+</tr>
+</table>
+
+<br />
+
+> **⚠️ Caution** <br />
+> With a CNAME record everything on this domain is delegated to codeberg.page, which means you cannot setup your own e-mail adress with this method. If you need e-mail or others services, you have to use one of the remaining options.
+
+**Option 2: ALIAS record**
+
+If you cannot use a CNAME record to configure the target you can use this method, which needs two entries instead of one.
+
+ - First you need to specify, which server should be serving your website. Similar to CNAME you can use an `ALIAS record`. The [difference](https://www.ecosia.org/search?q=cname%20vs%20alias%20record) between an CNAME record is, that the DNS server directly responds with the ip address and not the `codeberg.page` domain. Therefore you need to add a second entry, so that the pages server knows, what to serve under this domain.
+ - Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
+
+In the end it should look like this:
+
+<table class="table">
+<thead>
+<th>Domain</th>
+<th>Type</th>
+<th>Data</th>
+</thead>
+<tbody>
+<tr>
+<td>yourdomain.com</td><td>ALIAS</td><td>codeberg.page</td>
+</tr>
+<tr>
+<td>yourdomain.com</td><td>TXT</td><td>reponame.username.codeberg.page</td>
+</tr>
+<tr>
+<td>www.yourdomain.com</td><td>CNAME</td><td>yourdomain.com</td>
+</tr>
+</table>
+
+**Option 3: A/AAAA record**
+
+If your service provider does not support `ALIAS records` you can also use `A records` and `AAAA records` instead.
+
+ - First you need to specify, which server should be serving your website. You can do this, by setting an `A record` for IPv4 and an `AAAA record` for IPv6 which contains the ip address of the Codeberg Page server. The servers ip addresses are:
+   - `A record` which contains the IPv4 value `217.197.91.145`
+   - `AAAA record` which contains the IPv6 value `2001:67c:1401:20f0::1`
+ - Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
+
+In the end, it should look like this:
+
+<table class="table">
+<thead>
+<th>Domain</th>
+<th>Type</th>
+<th>Data</th>
+</thead>
+<tbody>
+<tr>
+<td>yourdomain.com</td><td>A</td><td>217.197.91.145</td>
+</tr>
+<tr>
+<td>yourdomain.com</td><td>AAAA</td><td>2001:67c:1401:20f0::1</td>
+</tr>
+<tr>
+<td>yourdomain.com</td><td>TXT</td><td>reponame.username.codeberg.page</td>
+</tr>
+<tr>
+<td>www.yourdomain.com</td><td>CNAME</td><td>yourdomain.com</td>
+</tr>
+</table>
+
+## Examples
+
+The following sub-sections include a few examples of the different alternatives, assuming the following:
+
+- we can add/modify DNS records in domain `example.com`.
+- Our Codeberg username is `frida`, and we want to publish pages for:
+    - `frida/pages`, with a *Personal* static site inside branch `pages`;
+    - `frida/colormix`, with a *Project* site (again, inside branch `pages`).
+
+All considerations regarding a *Personal* site also apply to an *Organization* site, so these two cases will be addressed together.
+
+### Personal (or Organization) site, third level domain
+
+In this case, we want our *Personal* pages available at the URL `https://myself.example.com`.
+
+The `.domains` file contains the following:
+
+```
+myself.example.com
+frida.codeberg.page
+pages.frida.codeberg.page
+pages.pages.frida.codeberg.page
+```
+
+For the DNS configuration:
+
+- if CNAME can be used, one single DNS record will suffice:
+    - name `myself.example.com`, type `CNAME`, data `frida.codeberg.page`
+
+- otherwise, if ALIAS can be used, two DNS records will be needed:
+    - name `myself.example.com`, type `ALIAS`, data `codeberg.page`
+    - name `myself.example.com`, type `TXT`, data `frida.codeberg.page`
+
+- otherwise, A/AAAA records must be used, together with one TXT record:
+    - name `myself.example.com`, type `A`, data `217.197.91.145`
+    - name `myself.example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
+    - name `myself.example.com`, type `TXT`, data `frida.codeberg.page`
+
+### Personal/Organization site, apex domain
+
+In this case, we want our *Personal*/*Organization* pages available at the URL `https://example.com`.
+
+The `.domains` file contains the following:
+
+```
+example.com
+frida.codeberg.page
+pages.frida.codeberg.page
+pages.pages.frida.codeberg.page
+```
+
+For the DNS configuration, the CNAME SHOULD NOT be used, so:
+
+- if ALIAS can be used, two DNS records will be needed:
+    - name `example.com`, type `ALIAS`, data `codeberg.page`
+    - name `example.com`, type `TXT`, data `frida.codeberg.page`
+
+- otherwise, A/AAAA records must be used, together with one TXT record:
+    - name `example.com`, type `A`, data `217.197.91.145`
+    - name `example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
+    - name `example.com`, type `TXT`, data `frida.codeberg.page`
+
+### Project site, third-level domain
+
+In this case, we want our *Project* pages available at the URL `https://colormix-app.example.com`.
+
+The `.domains` file contains the following:
+
+```
+colormix-app.example.com
+colormix.frida.codeberg.page
+pages.colormix.frida.codeberg.page
+```
+
+For the DNS configuration:
+
+- if CNAME can be used, one single DNS record will suffice:
+    - name `colormix-app.example.com`, type `CNAME`, data `colormix.frida.codeberg.page`
+
+- otherwise, if ALIAS can be used, two DNS records will be needed:
+    - name `colormix-app.example.com`, type `ALIAS`, data `codeberg.page`
+    - name `colormix-app.example.com`, type `TXT`, data `colormix.frida.codeberg.page`
+
+- otherwise, A/AAAA records must be used, together with one TXT record:
+    - name `colormix-app.example.com`, type `A`, data `217.197.91.145`
+    - name `colormix-app.example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
+    - name `colormix-app.example.com`, type `TXT`, data `colormix.frida.codeberg.page`
+
+### Project site, apex domain
+
+In this case, we want our *Project* pages available at the URL `https://example.com`.
+
+> Note: this would be incompatible with using the apex `example.com` for other purposes, e.g. for the *Personal*/*Organization* example discussed before.
+
+The `.domains` file contains the following:
+
+```
+example.com
+colormix.frida.codeberg.page
+pages.colormix.frida.codeberg.page
+```
+
+For the DNS configuration, CNAME SHOULD NOT be used:
+
+- if ALIAS can be used, two DNS records will be needed:
+    - name `example.com`, type `ALIAS`, data `codeberg.page`
+    - name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`
+
+- otherwise, A/AAAA records must be used, together with one TXT record:
+    - name `example.com`, type `A`, data `217.197.91.145`
+    - name `example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
+    - name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`

content/codeberg-translate/index.md

@@ -7,4 +7,24 @@ eleventyNavigation:
 description: These articles shows you how to use Codeberg Translate
 ---
 
-These documentation pages contain information on how you can use [Codeberg Translate](https://translate.codeberg.org)
+These documentation pages contain information on how you can use [Codeberg Translate](https://translate.codeberg.org)
+
+{% assign navPages = collections.all | eleventyNavigation %}
+{%- for entry in navPages %}
+{% if entry.url == page.url %}
+{%- if entry.children.length -%}
+<table class="table">
+  <thead>
+    <th> Find out more in this section: </th>
+  </thead>
+  <tbody>
+{%- for child in entry.children %}
+    <tr><td>
+        <a href="{{ child.url }}">{{ child.title }}</a>
+    </tr></td>
+{%- endfor %}
+  </tbody>
+</table>
+{% endif %}
+{% endif %}
+{%- endfor %}

content/collaborating/index.md

@@ -12,3 +12,23 @@ on Codeberg, for example, [by making Pull Requests](/collaborating/pull-requests
 If you're new to Codeberg or software forges in general, please also have a look at
 our [Getting Started Guide](/getting-started) which will teach you the basics of
 issue tracking and wikis on Codeberg.
+
+{% assign navPages = collections.all | eleventyNavigation %}
+{%- for entry in navPages %}
+{% if entry.url == page.url %}
+{%- if entry.children.length -%}
+<table class="table">
+  <thead>
+    <th> Find out more in this section: </th>
+  </thead>
+  <tbody>
+{%- for child in entry.children %}
+    <tr><td>
+        <a href="{{ child.url }}">{{ child.title }}</a>
+    </tr></td>
+{%- endfor %}
+  </tbody>
+</table>
+{% endif %}
+{% endif %}
+{%- endfor %}

content/collaborating/repo-permissions.md

@@ -10,6 +10,18 @@ When you invite collaborators to join your repository (see [Invite Collaborators
 
 Since Gitea v1.16, you can assign teams different levels of permission for each unit (e.g. issues, PR's, wiki).
 
+## Profile and Visibility
+
+Visibility of your repositories is in general inherited from your profile. So other user can only see your repositories, if your profile is *public*.
+
+If you want to limit visibility access to your repositories you can set your **user visibility** in the [user privacy settings](https://codeberg.org/user/settings) to **Limited**. Even if your repository is public, non-contributors will get a 404-error if they try to access your repository.
+
+<picture>
+  <source srcset="/assets/images/collaborating/repo-permissions/user-settings-privacy-limited.webp" type="image/webp">
+  <img src="/assets/images/collaborating/repo-permissions/user-settings-privacy-limited.jpg" alt="Privacy Settings in Codeberg's User Settings" width="50%">
+</picture>
+
+
 ## Collaborators
 
 There are four permission levels: Read, Write, Administrator and Owner.  

content/getting-started/first-repository.md

@@ -141,6 +141,11 @@ knut@iceberg:~/my-project$ git remote add origin https://codeberg.org/knut/fooba
 
 If all is done correctly, this command should output nothing.
 
+> **Errors:**
+> If you added an already initalized remote repository and try to push, you will get an error, if your local commit history is different from the history of the remote. You have some choices to resolve the conflict:
+> - Merge your changes with the ones in the remote `git pull`
+> - If you are sure, that you want to overwrite all changes in the remote, you can force push with `git -f push`
+
 ## Making your first commit
 Now that you've connected your repository to your local development copy, it's time to make your first commit.
 
@@ -252,4 +257,44 @@ After refreshing the repository page, you should now see something similar to th
 
 Congratulations - you've just made your first source code contribution on Codeberg!
 
+### Promote your work
+
+If you want to promote your work you can use [Codeberg's Badge Generator](https://get-it-on.codeberg.org/) to easily generate a badge which links to you repository. 
+
+In the badge generator you can edit how the badge should appear. Mainly this is:
+
+  - **Claim**: What should be written on the badge above the Codeberg logo. Think of something catchy.
+  - **Type**: You can choose between three different themes.
+  - **Background**: Change the background color of your badge to fit to your site.
+  - **PNG width**: The width of your badge, the generate will automatically scale it with correct proportions.
+
+<picture>
+  <source srcset="/assets/images/getting-started/first-repository/badge-settings.webp" type="image/webp">
+  <img src="/assets/images/getting-started/first-repository/badge-settings.jpg" alt="Settings in Codeberg's badge generator">
+</picture>
+
+Just add the following line as markdown to the site you want to link from: 
+
+```markdown
+[![Get it on Codeberg](your-badge.png)](https://codeberg.org/your-username/your-repo)
+```
+
+or in HTML:
+
+```html
+<a href="https://codeberg.org/your-username/your-repo">
+<img src="your-badge.png" alt="Get It On Codeberg" width="250"/>
+<a/>
+```
+
+
+This will result in a badge like this:
+
+<a href="https://codeberg.org/Codeberg/Documentation">
+<picture>
+  <source srcset="/assets/images/getting-started/first-repository/badge.webp" type="image/webp">
+  <img src="https://codeberg.org/Codeberg/GetItOnCodeberg/raw/branch/main/get-it-on-blue-on-white.svg" alt="Get It On Codeberg" style="border:0px" width="250">
+</picture>
+</a>
+
 Now, you should [learn more about issue tracking](/getting-started/issue-tracking-basics).

content/getting-started/index.md

@@ -16,4 +16,24 @@ I'm Knut the Polar Bear, and I'm going to guide you through your first steps on
 
 You can start with [finding out more about Codeberg](/getting-started/what-is-codeberg) or by jumping right to [your first steps on Codeberg](/getting-started/first-steps).
 
-Welcome to Codeberg! 😊
+Welcome to Codeberg! 😊
+
+{% assign navPages = collections.all | eleventyNavigation %}
+{%- for entry in navPages %}
+{% if entry.url == page.url %}
+{%- if entry.children.length -%}
+<table class="table">
+  <thead>
+    <th> Find out more in this section: </th>
+  </thead>
+  <tbody>
+{%- for child in entry.children %}
+    <tr><td>
+        <a href="{{ child.url }}">{{ child.title }}</a>
+    </tr></td>
+{%- endfor %}
+  </tbody>
+</table>
+{% endif %}
+{% endif %}
+{%- endfor %}

content/git/index.md

@@ -16,3 +16,23 @@ Option 1 requires a Git client of your choice [installed on your local system](/
 
 We recommend the use of the [SSH protocol](https://en.wikipedia.org/wiki/Secure_Shell_Protocol).   
 It offers improved security through key-based access (stronger protection than a regular password) and better ease of use (no need to provide credentials on every push).
+
+{% assign navPages = collections.all | eleventyNavigation %}
+{%- for entry in navPages %}
+{% if entry.url == page.url %}
+{%- if entry.children.length -%}
+<table class="table">
+  <thead>
+    <th> Find out more in this section: </th>
+  </thead>
+  <tbody>
+{%- for child in entry.children %}
+    <tr><td>
+        <a href="{{ child.url }}">{{ child.title }}</a>
+    </tr></td>
+{%- endfor %}
+  </tbody>
+</table>
+{% endif %}
+{% endif %}
+{%- endfor %}

content/improving-documentation/index.md

@@ -8,6 +8,26 @@ eleventyNavigation:
 
 We're very happy you're considering to contribute to Codeberg Documentation!
 
+{% assign navPages = collections.all | eleventyNavigation %}
+{%- for entry in navPages %}
+{% if entry.url == page.url %}
+{%- if entry.children.length -%}
+<table class="table">
+  <thead>
+    <th> Find out more in this section: </th>
+  </thead>
+  <tbody>
+{%- for child in entry.children %}
+    <tr><td>
+        <a href="{{ child.url }}">{{ child.title }}</a>
+    </tr></td>
+{%- endfor %}
+  </tbody>
+</table>
+{% endif %}
+{% endif %}
+{%- endfor %}
+
 ### How do I contribute to Codeberg Documentation?
 
 To contribute to Codeberg Documentation, the first thing you should do (if you haven't already done it) is to create your own fork of the [Codeberg/Documentation repository](https://codeberg.org/Codeberg/Documentation).

content/integrations/index.md

@@ -9,3 +9,23 @@ eleventyNavigation:
 These documentation pages contain information on how you can use third-party software with Codeberg.
 
 See also [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/README.md) which lists projects that work with Gitea, the software which Codeberg is based on.
+
+{% assign navPages = collections.all | eleventyNavigation %}
+{%- for entry in navPages %}
+{% if entry.url == page.url %}
+{%- if entry.children.length -%}
+<table class="table">
+  <thead>
+    <th> Find out more in this section: </th>
+  </thead>
+  <tbody>
+{%- for child in entry.children %}
+    <tr><td>
+        <a href="{{ child.url }}">{{ child.title }}</a>
+    </tr></td>
+{%- endfor %}
+  </tbody>
+</table>
+{% endif %}
+{% endif %}
+{%- endfor %}

content/markdown/index.md

@@ -22,3 +22,22 @@ look them up and learn more about Markdown.
 - [English Wikipedia article on Markdown](https://en.wikipedia.org/wiki/Markdown)
 - [The Markdown Guide](https://www.markdownguide.org/)
 
+{% assign navPages = collections.all | eleventyNavigation %}
+{%- for entry in navPages %}
+{% if entry.url == page.url %}
+{%- if entry.children.length -%}
+<table class="table">
+  <thead>
+    <th> Find out more in this section: </th>
+  </thead>
+  <tbody>
+{%- for child in entry.children %}
+    <tr><td>
+        <a href="{{ child.url }}">{{ child.title }}</a>
+    </tr></td>
+{%- endfor %}
+  </tbody>
+</table>
+{% endif %}
+{% endif %}
+{%- endfor %}

content/security/2fa.md

@@ -87,3 +87,34 @@ Make sure you keep the generated token in a safe place, because it will not be s
 When asked for your password, just enter the token.
 
 You can create as many tokens as you'd like: one for each computer, one for each Git client, one for each session... you decide! You can also revoke tokens at any time by pressing `Delete` next to the token (see previous screenshot).
+
+## Configure Git with 2FA
+
+If you want to clone a repository using the Git CLI and 2FA enabled, you have two choices:
+
+  - use `SSH`: you do not have to do any special configuration, just use your ssh_key to login
+  - use `HTTPS`: for the login you use your username and your generated accesstoken as a password. First time you enter it, it will be saved for your repository.
+
+<pre>
+$ git clone https://codeberg.org/username/repo.git
+Username for 'https://codeberg.org': username
+Password for 'https://username@codeberg.org': access-token
+</pre>
+
+If you want to permanently save your generated access token you can use the following command to store it globally on your computer:
+
+    git config --global credential.helper cache
+
+## Troubleshooting
+
+Codeberg's instance of Forgejo is using an [OTP library](https://github.com/pquerna/otp/) to generate 2FA tokens and follows the [RFC 6238 standard](https://datatracker.ietf.org/doc/html/rfc6238) to generate TOTP which uses 30 seconds long timeframes to accept your 2FA code.
+
+```
+  00:00     00:30     01:00
+    v         v         v
+    | <-----> | <-----> | <----->
+         ^         ^         ^
+     Previous   Current     Next  
+```
+
+Codeberg's server is always at the **Current** period. If a token of the **Previous** period is submitted, which was generated between 00:00-00:30, it will be accepted, as long as that token was submitted between 00:30-01:00. So at a minimum you always got 30 seconds to submit the token, before it becomes "invalid" and Codeberg always accept two codes (**Previous**, **Current**)

content/security/index.md

@@ -6,4 +6,24 @@ eleventyNavigation:
   order: 50
 ---
 
-This section contains information on how to securely use Codeberg.
+This section contains information on how to securely use Codeberg.
+
+{% assign navPages = collections.all | eleventyNavigation %}
+{%- for entry in navPages %}
+{% if entry.url == page.url %}
+{%- if entry.children.length -%}
+<table class="table">
+  <thead>
+    <th> Find out more in this section: </th>
+  </thead>
+  <tbody>
+{%- for child in entry.children %}
+    <tr><td>
+        <a href="{{ child.url }}">{{ child.title }}</a>
+    </tr></td>
+{%- endfor %}
+  </tbody>
+</table>
+{% endif %}
+{% endif %}
+{%- endfor %}