trigger pipeline on pull_request_closed event

- All acronyms should be defined in first use. This adds this for Continuous Integration (CI) and Role Based Access Control (RBAC).
- Changes language around acceptance to soften tone, and shift from guaranteed to conditional acceptance.
- Specifies that login to woodpecker-ci is via codeberg account, and that repositories are automatically available to link.
- Adds reference to codeberg-ci/examples repository.
- Removes reference to knut organization.

Co-authored-by: Patrick Schratz <pat-s@noreply.codeberg.org>
Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/435
Reviewed-by: Patrick Schratz <pat-s@noreply.codeberg.org>
Co-authored-by: Mark Pitblado <mark@pitblado.me>
Co-committed-by: Mark Pitblado <mark@pitblado.me>

.cspell.json

@@ -0,0 +1,142 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "dictionaries": [
+    // language
+    "en_us",
+    // code
+    "go",
+    "node",
+    // package names
+    "npm"
+  ],
+  "words": [
+    "codeberg",
+    "editview",
+    "forgejo",
+    "gitea",
+    "keycloak",
+    "knut",
+    "nord",
+    "orga",
+    "pageview",
+    "styleguide",
+    "tydata",
+    "webauthn",
+    "weblate",
+    "webp",
+    "xclip",
+    "endfor",
+    "pagefind",
+    "mray",
+    "keypair",
+    "gpgsign",
+    "signinkey",
+    "srcset",
+    "endadmonition",
+    "TOTP",
+    "Setext",
+    "Marlroy",
+    "preformatting",
+    "endfor",
+    "Goldmark",
+    "Homeserver",
+    "subpage",
+    "PKCE",
+    "block",
+    "keyid",
+    "pubring",
+    "signingkey",
+    "Browsersync",
+    "endraw",
+    "callouts",
+    "libwebp",
+    "cwebp",
+    "Kesi",
+    "IBAN",
+    "SEPA",
+    "fileorpathname",
+    "oneline",
+    "eins",
+    "zwei",
+    "Commitvia",
+    "knuts",
+    "Hostable",
+    "disroot",
+    "hostable",
+    "LICENCE",
+    "browsable",
+    "homebrewed",
+    "libera",
+    "jumpstart",
+    "Figshare",
+    "Zenodo",
+    "gettext",
+    "colormix",
+    "frida",
+    "reponame",
+    "yourdomain",
+    "myproject",
+    "branchname",
+    "venv",
+    "mydocs",
+    "Hassani",
+    "Alami",
+    "Fayçal",
+    "toctree",
+    "Malroy",
+    "Wrzx",
+    "pacman",
+    "xbps",
+    "GENODEF",
+    "netcup",
+    "YOURCODEBERGUSERNAME",
+    "respository",
+    "mynewfile",
+    "docstrings",
+    "autodoc",
+    "quickstart",
+    "virtualenv",
+    "dind",
+    "Packagist",
+    "Feishu",
+    "Gogs",
+    "noreferrer",
+    "tabindex",
+    "CERTDIR",
+    "nbsp",
+    "lycheeverse",
+    "mstruebing",
+    "davidanson",
+    "pipelinecomponents",
+    "corepack"
+  ],
+  "ignorePaths": [
+    "**/node_modules/**/*",
+    "*.webp",
+    "*.png",
+    ".git/**/*",
+    ".gitignore",
+    "pnpm-lock.yaml",
+    "package.json",
+    "*.svg",
+    "*.css",
+    "*.js",
+    "*.njk",
+    ".cspell.json"
+  ],
+  // Exclude imports, because they are also strings.
+  "ignoreRegExpList": [
+    // ignore mulltiline imports
+    "import\\s*\\((.|[\r\n])*?\\)",
+    // ignore single line imports
+    "import\\s*.*\".*?\"",
+    // ignore go generate directive
+    "//\\s*go:generate.*",
+    // ignore nolint directive
+    "//\\s*nolint:.*",
+    // ignore docker image names
+    "\\s*docker\\.io/.*"
+  ],
+  "enableFiletypes": ["dockercompose"]
+}

.ecrc

@@ -0,0 +1,3 @@
+{
+  "Exclude": ["LICENSE", ".git*"]
+}

.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+tab_width = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+indent_size = 1
+
+[Makefile]
+indent_style = tab

.eleventy.js

@@ -1,43 +1,85 @@
-const navigationPlugin = require("@11ty/eleventy-navigation")
-const syntaxHighlightingPlugin = require("@11ty/eleventy-plugin-syntaxhighlight")
+const navigationPlugin = require('@11ty/eleventy-navigation');
+const syntaxHighlightingPlugin = require('@11ty/eleventy-plugin-syntaxhighlight');
 const markdownIt = require('markdown-it');
+const tableOfContentsPlugin = require('@uncenter/eleventy-plugin-toc');
 const markdownItClass = require('@toycode/markdown-it-class');
-const markdownItAnchor = require('markdown-it-anchor')
-const searchFilter = require("./content/filters/searchFilter");
+const markdownItAnchor = require('markdown-it-anchor');
+const library = require('@fortawesome/fontawesome-svg-core').library;
+const icon = require('@fortawesome/fontawesome-svg-core').icon;
+const fas = require('@fortawesome/free-solid-svg-icons').fas;
+const { execSync } = require('child_process');
 
-module.exports = function(eleventyConfig) {
-  eleventyConfig.addPlugin(navigationPlugin)
-  eleventyConfig.addPlugin(syntaxHighlightingPlugin)
+module.exports = function (eleventyConfig) {
+  eleventyConfig.addPlugin(navigationPlugin);
+  eleventyConfig.addPlugin(syntaxHighlightingPlugin);
 
-  eleventyConfig.addPassthroughCopy("assets")
-  eleventyConfig.addPassthroughCopy("fonts")
+  eleventyConfig.addPassthroughCopy('assets');
+  eleventyConfig.addPassthroughCopy('fonts');
 
-  eleventyConfig.addFilter("search", searchFilter);
-
-  eleventyConfig.addShortcode("fas_icon", function(name) { return `<span class="fas fa-${name}"></span>` })
+  // Font Awesome Icons
+  library.add(fas);
+  eleventyConfig.addShortcode('fas_icon', function (args) {
+    var fas_svg = icon({ prefix: 'fas', iconName: args });
+    return `${fas_svg.html}`;
+  });
 
   const mapping = {
-    h2: 'content-title',h3: 'content-title',h4: 'content-title',h5: 'content-title',h6: 'content-title',
+    h2: 'content-title',
+    h3: 'content-title',
+    h4: 'content-title',
+    h5: 'content-title',
+    h6: 'content-title',
     table: 'table',
-    blockquote: 'alert'
+    blockquote: 'alert',
   };
-  
+
   const mdOptions = { linkify: false, html: true };
-  const mdAnchorOpts = { 
+  const mdAnchorOpts = {
     permalink: markdownItAnchor.permalink.headerLink(),
-    permalinkClass: 'ml-5', permalinkSymbol: '#', level: [1, 2, 3, 4] 
-  }
-  
+    permalinkClass: 'ml-5',
+    permalinkSymbol: '#',
+    level: [1, 2, 3, 4],
+  };
+
   eleventyConfig.setLibrary(
     'md',
-    markdownIt(mdOptions)
-      .use(markdownItClass, mapping)
-      .use(markdownItAnchor, mdAnchorOpts)
-  )
-  
+    markdownIt(mdOptions).use(markdownItClass, mapping).use(markdownItAnchor, mdAnchorOpts),
+  );
+
+  eleventyConfig.addPairedShortcode('admonition', function (content, type, title) {
+    let titleStr = '';
+    if (title) {
+      titleStr = title;
+    } else if (type) {
+      titleStr = type.substring(0, 1).toUpperCase() + type.substring(1).toLowerCase();
+    } else {
+      titleStr = 'Info';
+    }
+
+    return `<div class="admonition${type ? ` ${type.toLowerCase()}` : ''}">
+      <div class="admonition-title">
+        <span class="admonition-icon${type ? ` ${type.toLowerCase()}` : ''}"></span>
+        ${titleStr}
+      </div>
+      <div class="admonition-content">${content}</div>
+    </div>`;
+  });
+
+  eleventyConfig.addPlugin(tableOfContentsPlugin, {
+    tags: ['h2', 'h3'],
+    wrapper: function (toc) {
+      toc = toc.replaceAll('<a', "<a class='sidebar-link'");
+      return `${toc}`;
+    },
+  });
+
+  eleventyConfig.on('eleventy.after', () => {
+    execSync(`npx pagefind`, { encoding: 'utf-8' });
+  });
+
   return {
     dir: {
-      input: "content"
-    }
-  }
-}
+      input: 'content',
+    },
+  };
+};

.gitignore

@@ -1,3 +1,4 @@
 node_modules/
 _site/
 pages.git/
+.idea/

.lycheeignore

@@ -0,0 +1,8 @@
+http://127.0.0.1:**
+https://pages.codeberg.org/user.name/
+https://user.name.codeberg.page/
+https://repo.sitory.username.codeberg.page/
+file://** */
+https://codeberg.org/username/repo.git
+https://username.codeberg.page/**
+https://openclipart.org/**

.markdownlint.yaml

@@ -0,0 +1,141 @@
+# markdownlint YAML configuration
+# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
+
+# Default state for all rules
+default: true
+
+# Path to configuration file to extend
+extends: null
+
+# MD003/heading-style/header-style - Heading style
+MD003:
+  # Heading style
+  style: 'atx'
+
+# MD004/ul-style - Unordered list style
+MD004:
+  style: 'dash'
+
+# MD007/ul-indent - Unordered list indentation
+MD007:
+  # Spaces for indent
+  indent: 2
+  # Whether to indent the first level of the list
+  start_indented: false
+
+# MD009/no-trailing-spaces - Trailing spaces
+MD009:
+  # Spaces for line break
+  br_spaces: 2
+  # Allow spaces for empty lines in list items
+  list_item_empty_lines: false
+  # Include unnecessary breaks
+  strict: false
+
+# MD010/no-hard-tabs - Hard tabs
+MD010:
+  # Include code blocks
+  code_blocks: true
+
+# MD012/no-multiple-blanks - Multiple consecutive blank lines
+MD012:
+  # Consecutive blank lines
+  maximum: 1
+
+# MD013/line-length - Line length
+MD013:
+  # Number of characters
+  line_length: 500
+  # Number of characters for headings
+  heading_line_length: 100
+  # Number of characters for code blocks
+  code_block_line_length: 80
+  # Include code blocks
+  code_blocks: false
+  # Include tables
+  tables: false
+  # Include headings
+  headings: true
+  # Include headings
+  headers: true
+  # Strict length checking
+  strict: false
+  # Stern length checking
+  stern: false
+
+# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
+MD022:
+  # Blank lines above heading
+  lines_above: 1
+  # Blank lines below heading
+  lines_below: 1
+
+# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
+MD024:
+  # Only check sibling headings
+  allow_different_nesting: true
+
+# MD025/single-title/single-h1 - Multiple top-level headings in the same document
+MD025:
+  # Heading level
+  level: 1
+  # RegExp for matching title in front matter
+  front_matter_title: "^\\s*title\\s*[:=]"
+
+# MD026/no-trailing-punctuation - Trailing punctuation in heading
+MD026:
+  # Punctuation characters
+  punctuation: '.,;:!。，；：！'
+
+# MD029/ol-prefix - Ordered list item prefix
+MD029:
+  # List style
+  style: 'one_or_ordered'
+
+# MD030/list-marker-space - Spaces after list markers
+MD030:
+  # Spaces for single-line unordered list items
+  ul_single: 1
+  # Spaces for single-line ordered list items
+  ol_single: 1
+  # Spaces for multi-line unordered list items
+  ul_multi: 1
+  # Spaces for multi-line ordered list items
+  ol_multi: 1
+
+# MD033/no-inline-html - Inline HTML
+MD033: false
+
+# MD035/hr-style - Horizontal rule style
+MD035:
+  # Horizontal rule style
+  style: '---'
+
+# MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading
+MD036:
+  # Punctuation characters
+  punctuation: '.,;:!?。，；：！？'
+
+# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
+MD041:
+  # Heading level
+  level: 1
+  # RegExp for matching title in front matter
+  front_matter_title: "^\\s*title\\s*[:=]"
+
+# MD044/proper-names - Proper names should have the correct capitalization
+MD044:
+  # List of proper names
+  # names:
+  # Include code blocks
+  code_blocks: false
+
+# MD046/code-block-style - Code block style
+MD046:
+  # Block style
+  style: 'fenced'
+
+# MD048/code-fence-style - Code fence style
+MD048:
+  # Code fence style
+  style: 'backtick'

.prettierignore

@@ -0,0 +1 @@
+pnpm-lock.yaml

.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 120,
+  "tabWidth": 2,
+  "endOfLine": "lf"
+}

.woodpecker/build.yaml

@@ -0,0 +1,14 @@
+when:
+  - event: [pull_request]
+  - event: push
+    branch:
+      - ${CI_REPO_DEFAULT_BRANCH}
+
+steps:
+  build:
+    image: codeberg.org/woodpecker-plugins/node-pm:1.3.0
+    settings:
+      run: build
+      with: pnpm
+      frozen_lockfile: true
+      ignore_node_modules: true

.woodpecker/deploy-preview.yaml

@@ -0,0 +1,29 @@
+when:
+  - event: [pull_request, pull_request_closed]
+
+steps:
+  build:
+    image: codeberg.org/woodpecker-plugins/node-pm
+    settings:
+      run: build
+      with: pnpm
+      frozen_lockfile: true
+      ignore_node_modules: true
+
+  deploy-preview:
+    image: docker.io/woodpeckerci/plugin-surge-preview:1.3.1
+    settings:
+      path: '_site/'
+      forge_type: gitea
+      forge_url: https://codeberg.org
+      surge_token:
+        from_secret: surge_token
+      forge_repo_token:
+        from_secret: surge_forge_token
+    failure: ignore
+    when:
+      event: [pull_request, pull_request_closed]
+      path:
+        - content/**
+        - assets/**
+        - .eleventy.js

.woodpecker/lint.yaml

@@ -0,0 +1,44 @@
+when:
+  - event: [pull_request]
+  - event: push
+    branch:
+      - ${CI_REPO_DEFAULT_BRANCH}
+
+steps:
+  lint-markdown:
+    image: davidanson/markdownlint-cli2:v0.13.0
+    commands:
+      - 'markdownlint-cli2 *.{md,markdown}'
+    when:
+      path: '*.{md,markdown}'
+
+  editor-config:
+    image: mstruebing/editorconfig-checker:v3.0.1
+    depends_on: []
+
+  prettier:
+    image: docker.io/woodpeckerci/plugin-prettier:0.1.0
+    depends_on: []
+    settings:
+      version: 3.2.5
+
+  links:
+    image: lycheeverse/lychee:0.14.3
+    depends_on: []
+    commands:
+      - lychee -v -t 40 .
+
+  lint-yaml:
+    image: pipelinecomponents/yamllint:0.31.2
+    depends_on: []
+    commands:
+      - yamllint --strict .
+    when:
+      path: '*.{yml,yaml}'
+
+  spellcheck:
+    image: docker.io/node:22-alpine
+    depends_on: []
+    commands:
+      - corepack enable
+      - pnpx cspell lint --no-progress --gitignore '{**,.*}/{*,.*}'

.yamllint.yaml

@@ -0,0 +1,21 @@
+ignore: |
+  pnpm-lock.yaml
+  node_modules/
+
+rules:
+  comments:
+    require-starting-space: false
+    ignore-shebangs: true
+    min-spaces-from-content: 1
+  braces:
+    min-spaces-inside: 1
+    max-spaces-inside: 1
+  document-start:
+    present: false
+  indentation:
+    spaces: 2
+    indent-sequences: true
+  line-length:
+    max: 256
+  new-lines:
+    type: unix

CONTRIBUTORS.md

@@ -1,15 +0,0 @@
-# The Codeberg Documentation Contributors
-
-In alphabetic order (by last name / username):
-
-- Martijn de Boer (@sexybiggetje)
-- Christian Buhtz (@buhtz)
-- Ivan Calandra (@ivan-paleo)
-- Ben Cotterell (@benc)
-- Lucas Hinderberger (@lhinderberger)
-- Henning Jacobs (@hjacobs)
-- @mray (for the Codeberg Logo)
-- @n
-- Alex (@n0542344)
-- Holger Waechtler (@hw)
-- William Davis (@unbeatable-101)

Dockerfile

@@ -0,0 +1,16 @@
+FROM node:12.22.12-stretch-slim
+
+RUN apt-get update && apt-get -y upgrade
+
+RUN apt-get install -y git curl
+RUN curl -fsSL https://get.pnpm.io/install.sh | sh -
+
+RUN mkdir /opt/documentation && chown node: /opt/documentation
+
+USER node
+
+WORKDIR /opt/documentation
+
+RUN pnpm install
+
+CMD [ "pnpm", "run", "serve"]

LICENSE.md

@@ -1,13 +1,19 @@
-This website by [The Codeberg Documentation Contributors](CONTRIBUTORS.md)
-is licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/deed.en).
+<!-- markdownlint-disable MD041 -->
+
+This website is licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/deed.en).
 
 Due to the wiki-like nature of this website, pages usually have multiple authors and are changed
 frequently. Changes to the original versions of the works as well as their individual authors can be
-looked up in [the website's commit history](https://codeberg.org/Codeberg/Documentation/commits/branch/master).
+looked up in [the website's commit history](https://codeberg.org/Codeberg/Documentation/commits/branch/main).
 
 The Codeberg logos in this website are by @mray,
 licensed under [CC0 1.0](http://creativecommons.org/publicdomain/zero/1.0/).
 
+The fonts in this website are documented on the [Codeberg Design repo](https://codeberg.org/Codeberg/Design#font-inter).
+
+The icons in this website are by [Font Awesome](https://github.com/FortAwesome/Font-Awesome),
+licensed under [multiple licenses](https://fontawesome.com/license/free).
+
 Codeberg and the Codeberg Logo are trademarks of Codeberg e.V.
 
-"Knut the Polar Bear" has been derived from https://openclipart.org/detail/193243/polar-bear-remix, under CC0 1.0
+"Knut the Polar Bear" has been derived from [https://openclipart.org/detail/193243/polar-bear-remix](https://openclipart.org/detail/193243/polar-bear-remix), under CC0 1.0

README.md

@@ -1,28 +1,30 @@
 # Codeberg Documentation
-This repository contains the documentation for Codeberg, with some code to build it into
+
+This repository contains the [documentation for Codeberg](https://docs.codeberg.org/), with some code to build it into
 a static website.
 
 Please have a look into it and consider to help writing the Documentation. This is still very much work-in-progress, the more useful material we collect, the better we can later present it! All contributions are very welcome!
 
 For an introduction on contributing to Codeberg Documentation, please have a look
-at [the Contributor FAQ](https://docs.codeberg.org/improving-codeberg/docs-contributor-faq)
-
+at [the section on improving the documentation](https://docs.codeberg.org/improving-documentation/).
 
 ## Usage
+
 ### Local Development
+
 If you want to work on the documentation, for example by writing your own articles,
 the easiest way to do so is to fork the documentation repository and develop locally.
 
 First, run
 
-```npm install```
+`pnpm install`
 
 to install all dependencies (they will be installed only for this project, not globally).
 You only have to do this once.
 
 Then run
 
-```npm run serve```
+`pnpm run serve`
 
 to start a development web server that by default is listening at `http://localhost:8080`.
 
@@ -32,30 +34,72 @@ should automatically reload all changed pages using the amazing Browsersync.
 When you're done, commit your changes to your fork and write a pull request for
 Codeberg/Documentation. We're happy about every contribution!
 
+### Local development using the Dockerfile
+
+If you do not have nodejs installed or do not want to run the development web server directly on your host,
+you can also use a docker container.
+
+You must have a container-engine installed (docker, podman, etc.)
+
+First build the container image:
+
+```shell
+docker build -t Codeberg/Documentation-server .
+```
+
+You do not have to rebuild the image every time. Once you build the image you can always start the development
+webserver using the container engine:
+
+```shell
+docker run --rm -v $PWD:/opt/documentation Codeberg/Documentation-server:latest
+```
+
+Use the "External" URL the container outputs on startup to access your documentation.
+
+Changes to files in the documentation are reflected in the browser as the server regularly updates the generated files.
+
+Use `Ctrl-C` to exit / end the container.
+
+The parameters are:
+
+`--rm` removes the container after it's use
+`-v` mounts the current (documentation repository root) folder to `/opt/documentation` in the container.
+
+`Codeberg/Documentation-server:latest` refers to the container image built in the first step (using `docker build`).
+
 ### Build & Deployment
+
 Like for local development, before building and deploying you first have to install
 the dependencies (once):
 
-```npm install```
+`pnpm install`
 
 To build the entire website to the `_site` directory run
 
-```npm run build```
+`pnpm run build`
 
 Instead, to directly publish the page to Codeberg pages, you can also run
 
-```npm run deploy```
+`pnpm run deploy`
 
-which includes a call to `npm run build`.
+which includes a call to `pnpm run build`.
 
 ### Technical Information
+
 This website uses [Eleventy](https://www.11ty.dev/), a static site generator.
 
 It's supplied as a dev-dependency in `package.json` and its dependencies are locked
 with `package-lock.json` to try to ensure reproducible builds.
 
+It also uses [PageFind](https://pagefind.app/), a static search library.
+
+Deployment previews are generated for every PR using [Surge.sh](https://surge.sh/) through the corresponding [Woodpecker plugin](https://woodpecker-ci.org/plugins/Surge%20preview%20plugin).
+
+A spellchecker is used to check for spelling errors in the documentation.
+To add exceptions to the spellchecker, add them to the `.cspell.json` file.
 
 ## License and Contributors
+
 This website (excluding bundled fonts) is licensed under CC BY-SA 4.0. See the [LICENSE](LICENSE.md) file for details.
 
-The contributors are listed in `CONTRIBUTORS.md`.
+Please refer to the [commit log](https://codeberg.org/Codeberg/Documentation/commits/branch/main) for an exhaustive list of contributors to Codeberg Documentation.

assets/css/codeberg-docs.css

@@ -1,47 +1,269 @@
-.content img { border: 5px solid rgba(0, 0, 0, 0.2); max-width: 100%; }
-.content blockquote { margin: 0; }
-.content-title { margin-top: 20px !important; }
+:root {
+  --admonition-background-color--info: rgba(68, 138, 255, 0.2);
+  --admonition-background-color--note: rgba(0, 184, 212, 0.2);
+  --admonition-background-color--warning: rgba(255, 145, 0, 0.2);
+  --admonition-background-color--tip: rgba(0, 191, 165, 0.2);
+  --admonition-background-color--question: rgba(100, 221, 23, 0.2);
 
-.content pre { border-left: 5px solid #2185d0; }
-.dark-mode .content pre { border-left: 5px solid #355379; }
+  --admonition-border-color--info: rgb(68, 138, 255);
+  --admonition-border-color--note: rgb(0, 184, 212);
+  --admonition-border-color--warning: rgb(255, 145, 0);
+  --admonition-border-color--tip: rgb(0, 191, 165);
+  --admonition-border-color--question: rgb(100, 221, 23);
 
-.content ol { list-style: decimal outside; padding-left: 2em; }
-.content ul { list-style: outside; padding-left: 2em; }
+  --admonition-icon--info: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M13 7.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0Zm-3 3.75a.75.75 0 0 1 .75-.75h1.5a.75.75 0 0 1 .75.75v4.25h.75a.75.75 0 0 1 0 1.5h-3a.75.75 0 0 1 0-1.5h.75V12h-.75a.75.75 0 0 1-.75-.75Z"></path><path d="M12 1c6.075 0 11 4.925 11 11s-4.925 11-11 11S1 18.075 1 12 5.925 1 12 1ZM2.5 12a9.5 9.5 0 0 0 9.5 9.5 9.5 9.5 0 0 0 9.5-9.5A9.5 9.5 0 0 0 12 2.5 9.5 9.5 0 0 0 2.5 12Z"></path></svg>');
+  --admonition-icon--note: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M17.263 2.177a1.75 1.75 0 0 1 2.474 0l2.586 2.586a1.75 1.75 0 0 1 0 2.474L19.53 10.03l-.012.013L8.69 20.378a1.753 1.753 0 0 1-.699.409l-5.523 1.68a.748.748 0 0 1-.747-.188.748.748 0 0 1-.188-.747l1.673-5.5a1.75 1.75 0 0 1 .466-.756L14.476 4.963ZM4.708 16.361a.26.26 0 0 0-.067.108l-1.264 4.154 4.177-1.271a.253.253 0 0 0 .1-.059l10.273-9.806-2.94-2.939-10.279 9.813ZM19 8.44l2.263-2.262a.25.25 0 0 0 0-.354l-2.586-2.586a.25.25 0 0 0-.354 0L16.061 5.5Z"></path></svg>');
+  --admonition-icon--warning: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M13 17.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0Zm-.25-8.25a.75.75 0 0 0-1.5 0v4.5a.75.75 0 0 0 1.5 0v-4.5Z"></path><path d="M9.836 3.244c.963-1.665 3.365-1.665 4.328 0l8.967 15.504c.963 1.667-.24 3.752-2.165 3.752H3.034c-1.926 0-3.128-2.085-2.165-3.752Zm3.03.751a1.002 1.002 0 0 0-1.732 0L2.168 19.499A1.002 1.002 0 0 0 3.034 21h17.932a1.002 1.002 0 0 0 .866-1.5L12.866 3.994Z"></path></svg>');
+  --admonition-icon--tip: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M12.596 2.043c1.075.076 2.059.281 2.743.956.698.688.92 1.696.92 2.941 0 .432-.057.955-.117 1.438-.026.2-.051.392-.076.572l-.056.429h2.05c.752 0 1.446.108 2.036.404.612.306 1.062.787 1.355 1.431.551 1.214.542 3.008.223 5.394l-.051.39c-.134 1.01-.248 1.872-.396 2.58-.166.795-.394 1.496-.816 2.05-.89 1.168-2.395 1.372-4.583 1.372-2.331 0-4.08-.418-5.544-.824l-.602-.17c-1.023-.29-1.852-.526-2.69-.586A1.75 1.75 0 0 1 5.25 22h-1.5A1.75 1.75 0 0 1 2 20.25V9.75C2 8.784 2.784 8 3.75 8h1.5a1.75 1.75 0 0 1 1.746 1.633 1.85 1.85 0 0 0 .523-.131c.961-.415 2.774-1.534 2.774-4.2V4.249c0-1.22 1.002-2.298 2.303-2.206ZM7 18.918c1.059.064 2.079.355 3.118.652l.568.16c1.406.39 3.006.77 5.142.77 2.277 0 3.004-.274 3.39-.781.216-.283.388-.718.54-1.448.136-.65.242-1.45.379-2.477l.05-.384c.32-2.4.253-3.795-.102-4.575-.16-.352-.375-.568-.66-.711-.305-.153-.74-.245-1.365-.245h-2.37c-.681 0-1.293-.57-1.211-1.328.026-.243.065-.537.105-.834l.07-.527c.06-.482.105-.921.105-1.25 0-1.125-.213-1.617-.473-1.873-.275-.27-.774-.455-1.795-.528-.351-.024-.698.274-.698.71v1.053c0 3.55-2.488 5.063-3.68 5.577-.372.16-.754.232-1.113.26ZM3.75 20.5h1.5a.25.25 0 0 0 .25-.25V9.75a.25.25 0 0 0-.25-.25h-1.5a.25.25 0 0 0-.25.25v10.5c0 .138.112.25.25.25Z"></path></svg>');
+  --admonition-icon--question: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M10.97 8.265a1.45 1.45 0 0 0-.487.57.75.75 0 0 1-1.341-.67c.2-.402.513-.826.997-1.148C10.627 6.69 11.244 6.5 12 6.5c.658 0 1.369.195 1.934.619a2.45 2.45 0 0 1 1.004 2.006c0 1.033-.513 1.72-1.027 2.215-.19.183-.399.358-.579.508l-.147.123a4.329 4.329 0 0 0-.435.409v1.37a.75.75 0 1 1-1.5 0v-1.473c0-.237.067-.504.247-.736.22-.28.486-.517.718-.714l.183-.153.001-.001c.172-.143.324-.27.47-.412.368-.355.569-.676.569-1.136a.953.953 0 0 0-.404-.806C12.766 8.118 12.384 8 12 8c-.494 0-.814.121-1.03.265ZM13 17a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path><path d="M12 1c6.075 0 11 4.925 11 11s-4.925 11-11 11S1 18.075 1 12 5.925 1 12 1ZM2.5 12a9.5 9.5 0 0 0 9.5 9.5 9.5 9.5 0 0 0 9.5-9.5A9.5 9.5 0 0 0 12 2.5 9.5 9.5 0 0 0 2.5 12Z"></path></svg>');
 
-a.header-anchor, a.header-anchor:visited { color: var(--lm-base-text-color) !important; text-decoration: none; }
-.dark-mode a.header-anchor, .dark-mode a.header-anchor:visited { color: var(--dm-base-text-color) !important; text-decoration: none; }
-a.header-anchor:hover { text-decoration: underline; }
+  --admonition-icon-dimension: 20px;
+}
 
-code span .content { margin: 0 !important; }
+.content :not(img, pre) {
+  max-width: 80ch;
+}
+.content img {
+  border: 5px solid rgba(0, 0, 0, 0.2);
+  max-width: 100%;
+}
+.content blockquote {
+  margin: 0;
+}
+.content-title {
+  margin-top: 20px !important;
+}
+
+.content pre {
+  border-left: 5px solid #2185d0;
+}
+.dark-mode .content pre {
+  border-left: 5px solid #355379;
+}
+
+.content ol {
+  list-style: decimal outside;
+}
+.content ul {
+  list-style: outside;
+}
+.content ol,
+.content ul {
+  margin-top: 10px;
+  padding-left: 2em;
+}
+
+.codeberg-design .card,
+.codeberg-design hr {
+  margin-left: 0;
+}
+
+a.header-anchor,
+a.header-anchor:visited {
+  color: var(--lm-base-text-color) !important;
+  text-decoration: none;
+}
+.dark-mode a.header-anchor,
+.dark-mode a.header-anchor:visited {
+  color: var(--dm-base-text-color) !important;
+  text-decoration: none;
+}
+a.header-anchor:hover {
+  text-decoration: underline;
+}
+
+code span .content {
+  margin: 0 !important;
+}
 
 /* Apply code style to generic code */
-pre:not([class*="language-"]) { 
-	background: #2E3440;
-	color: #f8f8f2; 
-    padding: 1em;
-	margin: .5em 0;
-	overflow: auto;
-	border-radius: 0.3em;
+pre:not([class*='language-']) {
+  background: #2e3440;
+  color: #f8f8f2;
+  padding: 1em;
+  margin: 0.5em 0;
+  overflow: auto;
+  border-radius: 0.3em;
 }
 
 /* Override sidebar link style */
-.codeberg-design .sidebar-title a { color: var(--sidebar-title-text-color); }
-.codeberg-design .sidebar-title .dark-mode a { color: var(--dm-sidebar-title-text-color); }
+.codeberg-design .sidebar-title a {
+  color: var(--sidebar-title-text-color);
+}
+.codeberg-design .sidebar-title .dark-mode a {
+  color: var(--dm-sidebar-title-text-color);
+}
 
 /* Apply halfmoon style to inline code */
-code:not(pre > code)  {
-    font-size: var(--code-font-size);
-    line-height: var(--code-line-height);
-    padding: var(--code-padding);
-    margin: var(--code-margin);
-    color: var(--lm-code-text-color);
-    background-color: var(--lm-code-bg-color);
-    border: var(--code-border-width)  var(--lm-code-border-color);
-    border-radius:  var(--code-border-radius);
+code:not(pre > code) {
+  font-size: var(--code-font-size);
+  line-height: var(--code-line-height);
+  padding: var(--code-padding);
+  margin: var(--code-margin);
+  color: var(--lm-code-text-color);
+  background-color: var(--lm-code-bg-color);
+  border: var(--code-border-width) var(--lm-code-border-color);
+  border-radius: var(--code-border-radius);
 }
 .dark-mode code:not(pre > code) {
-    color: var(--dm-code-text-color);
-    background-color: var(--dm-code-bg-color);
-    border-color: var(--dm-code-border-color);
+  color: var(--dm-code-text-color);
+  background-color: var(--dm-code-bg-color);
+  border-color: var(--dm-code-border-color);
 }
 
+/* Custom Admonition boxes */
+
+.admonition {
+  background-color: var(--admonition-background-color--info);
+  border: 0.2rem solid var(--admonition-border-color--info);
+  border-radius: 0.3rem;
+
+  border-left-width: 0.5rem;
+
+  padding: 1em 1.5em;
+}
+
+.admonition-title {
+  font-weight: bold;
+  font-size: 1.2em;
+}
+
+.admonition-icon::before {
+  content: '';
+
+  background-color: var(--admonition-border-color--info);
+
+  mask-position: center;
+  mask-repeat: no-repeat;
+  mask-size: contain;
+  mask-image: var(--admonition-icon--info);
+
+  -webkit-mask-position: center;
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-size: contain;
+  -webkit-mask-image: var(--admonition-icon--info);
+
+  display: inline-block;
+  margin-right: 0.4em;
+  vertical-align: bottom;
+
+  height: 1.5em;
+  width: 1.5em;
+}
+
+.admonition.note {
+  background-color: var(--admonition-background-color--note);
+  border-color: var(--admonition-border-color--note);
+}
+
+.admonition-icon.note::before {
+  background-color: var(--admonition-border-color--note);
+
+  mask-image: var(--admonition-icon--note);
+  -webkit-mask-image: var(--admonition-icon--note);
+}
+
+.admonition.warning {
+  background-color: var(--admonition-background-color--warning);
+  border-color: var(--admonition-border-color--warning);
+}
+
+.admonition-icon.warning::before {
+  background-color: var(--admonition-border-color--warning);
+
+  mask-image: var(--admonition-icon--warning);
+  -webkit-mask-image: var(--admonition-icon--warning);
+}
+
+.admonition.tip {
+  background-color: var(--admonition-background-color--tip);
+  border-color: var(--admonition-border-color--tip);
+}
+
+.admonition-icon.tip::before {
+  background-color: var(--admonition-border-color--tip);
+
+  mask-image: var(--admonition-icon--tip);
+  -webkit-mask-image: var(--admonition-icon--tip);
+}
+
+.admonition.question {
+  background-color: var(--admonition-background-color--question);
+  border-color: var(--admonition-border-color--question);
+}
+
+.admonition-icon.question::before {
+  background-color: var(--admonition-border-color--question);
+
+  mask-image: var(--admonition-icon--question);
+  -webkit-mask-image: var(--admonition-icon--question);
+}
+
+.admonition-content > *:last-child {
+  margin-bottom: 0;
+}
+
+#search-results {
+  overflow: hidden;
+  word-wrap: anywhere;
+  white-space: break-spaces;
+  --pagefind-ui-background: var(--dm-sidebar-bg-color);
+  --pagefind-ui-primary: var(--dm-sidebar-link-text-color);
+  --pagefind-ui-border: var(--dm-sidebar-divider-bg-color);
+}
+
+#search-results li {
+  margin-bottom: 0;
+  gap: 0;
+  padding: 10px 0px;
+}
+
+.pagefind-modular-list-thumb {
+  display: none;
+}
+
+#search-input::placeholder {
+  --lm-input-placeholder-text-color: rgba(0, 0, 0, 0.8);
+  --dm-input-placeholder-text-color: rgba(255, 255, 255, 0.8);
+}
+
+#toc {
+  padding: 5px;
+}
+
+#toc ol {
+  padding: 5px;
+  margin: 0;
+}
+
+#toc li {
+  list-style-type: none;
+  margin-bottom: 0;
+}
+
+#toc a {
+  display: block;
+  height: auto;
+}
+
+#toc-side {
+  margin-top: 50px;
+}
+
+#toc-side span {
+  font-weight: 500;
+  font-size: 1.5rem;
+  margin-bottom: 1rem;
+}
+
+#toc-side ol:first-child {
+  border-left: 1px solid rgba(0, 0, 0, 0.15);
+}
+
+.dark-mode #toc-side ol:first-child {
+  border-left: 1px solid rgba(255, 255, 255, 0.15);
+}
+
+#toc-side a {
+  padding-left: 10px;
+}

assets/css/prism-nord.css

@@ -1,24 +1,24 @@
 /**
  * Copied from https://github.com/PrismJS/prism-themes
- * 
- * 
- * 
+ *
+ *
+ *
  * prism-themes License:
- * 
+ *
  * The MIT License (MIT)
- * 
+ *
  * Copyright (c) 2015 PrismJS
- * 
+ *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
  * in the Software without restriction, including without limitation the rights
  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  * copies of the Software, and to permit persons to whom the Software is
  * furnished to do so, subject to the following conditions:
- * 
+ *
  * The above copyright notice and this permission notice shall be included in all
  * copies or substantial portions of the Software.
- * 
+ *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
@@ -26,27 +26,27 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
- * 
- * 
- * 
- * 
+ *
+ *
+ *
+ *
  * Nord Color Theme license:
- * 
+ *
  * MIT License (MIT)
- * 
- * Copyright (c) 2016-present Arctic Ice Studio <development@arcticicestudio.com> (https://www.arcticicestudio.com)  
+ *
+ * Copyright (c) 2016-present Arctic Ice Studio <development@arcticicestudio.com> (https://www.arcticicestudio.com)
  * Copyright (c) 2016-present Sven Greb <development@svengreb.de> (https://www.svengreb.de)
- * 
+ *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
  * in the Software without restriction, including without limitation the rights
  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  * copies of the Software, and to permit persons to whom the Software is
  * furnished to do so, subject to the following conditions:
- * 
+ *
  * The above copyright notice and this permission notice shall be included in all
  * copies or substantial portions of the Software.
- * 
+ *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
@@ -56,7 +56,6 @@
  * SOFTWARE.
  */
 
-
 /**
  * Nord Theme Originally by Arctic Ice Studio
  * https://nordtheme.com
@@ -64,59 +63,59 @@
  * Ported for PrismJS by Zane Hitchcoxc (@zwhitchcox) and Gabriel Ramos (@gabrieluizramos)
  */
 
-code[class*="language-"],
-pre[class*="language-"] {
-	color: #f8f8f2;
-	background: none;
-	font-family: "Fira Code", Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace;
-	text-align: left;
-	white-space: pre;
-	word-spacing: normal;
-	word-break: normal;
-	word-wrap: normal;
-	line-height: 1.5;
-	-moz-tab-size: 4;
-	-o-tab-size: 4;
-	tab-size: 4;
-	-webkit-hyphens: none;
-	-moz-hyphens: none;
-	-ms-hyphens: none;
-	hyphens: none;
+code[class*='language-'],
+pre[class*='language-'] {
+  color: #f8f8f2;
+  background: none;
+  font-family: 'Fira Code', Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace;
+  text-align: left;
+  white-space: pre;
+  word-spacing: normal;
+  word-break: normal;
+  word-wrap: normal;
+  line-height: 1.5;
+  -moz-tab-size: 4;
+  -o-tab-size: 4;
+  tab-size: 4;
+  -webkit-hyphens: none;
+  -moz-hyphens: none;
+  -ms-hyphens: none;
+  hyphens: none;
 }
 
 /* Code blocks */
-pre[class*="language-"] {
-	padding: 1em;
-	margin: .5em 0;
-	overflow: auto;
-	border-radius: 0.3em;
+pre[class*='language-'] {
+  padding: 1em;
+  margin: 0.5em 0;
+  overflow: auto;
+  border-radius: 0.3em;
 }
 
-:not(pre) > code[class*="language-"],
-pre[class*="language-"] {
-	background: #2E3440;
+:not(pre) > code[class*='language-'],
+pre[class*='language-'] {
+  background: #2e3440;
 }
 
 /* Inline code */
-:not(pre) > code[class*="language-"] {
-	padding: .1em;
-	border-radius: .3em;
-	white-space: normal;
+:not(pre) > code[class*='language-'] {
+  padding: 0.1em;
+  border-radius: 0.3em;
+  white-space: normal;
 }
 
 .token.comment,
 .token.prolog,
 .token.doctype,
 .token.cdata {
-	color: #636f88;
+  color: #636f88;
 }
 
 .token.punctuation {
-	color: #81A1C1;
+  color: #81a1c1;
 }
 
 .namespace {
-	opacity: .7;
+  opacity: 0.7;
 }
 
 .token.property,
@@ -124,15 +123,15 @@ pre[class*="language-"] {
 .token.constant,
 .token.symbol,
 .token.deleted {
-	color: #81A1C1;
+  color: #81a1c1;
 }
 
 .token.number {
-	color: #B48EAD;
+  color: #b48ead;
 }
 
 .token.boolean {
-	color: #81A1C1;
+  color: #81a1c1;
 }
 
 .token.selector,
@@ -141,7 +140,7 @@ pre[class*="language-"] {
 .token.char,
 .token.builtin,
 .token.inserted {
-	color: #A3BE8C;
+  color: #a3be8c;
 }
 
 .token.operator,
@@ -150,34 +149,34 @@ pre[class*="language-"] {
 .language-css .token.string,
 .style .token.string,
 .token.variable {
-	color: #81A1C1;
+  color: #81a1c1;
 }
 
 .token.atrule,
 .token.attr-value,
 .token.function,
 .token.class-name {
-	color: #88C0D0;
+  color: #88c0d0;
 }
 
 .token.keyword {
-	color: #81A1C1;
+  color: #81a1c1;
 }
 
 .token.regex,
 .token.important {
-	color: #EBCB8B;
+  color: #ebcb8b;
 }
 
 .token.important,
 .token.bold {
-	font-weight: bold;
+  font-weight: bold;
 }
 
 .token.italic {
-	font-style: italic;
+  font-style: italic;
 }
 
 .token.entity {
-	cursor: help;
+  cursor: help;
 }

content/_data/env.js

@@ -1,3 +1,3 @@
 module.exports = {
-    environment: process.env.ELEVENTY_ENV
-};
+  environment: process.env.ELEVENTY_ENV,
+};

content/_data/urls.json

@@ -1,4 +1,4 @@
 {
-    "commitHistoryMaster": "https://codeberg.org/Codeberg/Documentation/commits/branch/master",
-    "docsSourcesMaster": "https://codeberg.org/codeberg/documentation/src/branch/master"
+  "commitHistoryMaster": "https://codeberg.org/Codeberg/Documentation/commits",
+  "docsSourcesMaster": "https://codeberg.org/Codeberg/Documentation/src"
 }

content/_includes/contribution_invitation.njk

@@ -1,12 +1,12 @@
-<div class="card">
+<div class="card" data-pagefind-ignore="all">
         <p>Hey there! 👋 Thank you for reading this article!</p>
         <p>
-            Is there something missing or do you have an idea on how to improve the documentation?
+            Is there something missing, or do you have an idea on how to improve the documentation?
             Do you want to write your own article?
         </p>
         <p>
             You're invited to contribute to the Codeberg Documentation at <a href="https://codeberg.org/Codeberg/Documentation">its source code repository</a>,
-            for example by <a href="/collaborating/pull-requests-and-git-flow">Adding a pull request</a>
+            for example, by <a href="/collaborating/pull-requests-and-git-flow">adding a pull request</a>
             or joining in on the discussion in <a href="https://codeberg.org/Codeberg/Documentation/issues">the issue tracker</a>.
         </p>
         <p>

content/_includes/default_layout.njk

@@ -1,159 +1,210 @@
 <!DOCTYPE html>
 <html lang="en" class="codeberg-design">
-    <head>
-        <title>{% if eleventyNavigation.title %}{{ eleventyNavigation.title }} | {% endif %}Codeberg Documentation</title>
+  <head>
+    <title>{% if eleventyNavigation.title %}{{ eleventyNavigation.title }} | {% endif %}Codeberg Documentation</title>
 
-        <meta charset="UTF-8">
-        {% if description %}<meta name="description" content="{{ description }}">{% endif %}
-        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
-        <meta name="viewport" content="width=device-width, initial-scale=1"/>
-        {% if env.environment == "testing" %}<meta name="robots" content="noindex">{% endif %}
+    <meta charset="UTF-8" />
+    {% if description %}
+    <meta name="description" content="{{ description }}" />
+    {% endif %}
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {% if env.environment == "testing" %}
+    <meta name="robots" content="noindex" />
+    {% endif %}
 
-        <link rel="icon" href="https://design.codeberg.org/logo-kit/favicon.ico" type="image/x-icon"/>
-        <link rel="icon" href="https://design.codeberg.org/logo-kit/favicon.svg" type="image/svg+xml"/>
-        <link rel="apple-touch-icon" href="https://design.codeberg.org/logo-kit/apple-touch-icon.png"/>
+    <link rel="icon" href="https://design.codeberg.org/logo-kit/favicon.ico" type="image/x-icon" />
+    <link rel="icon" href="https://design.codeberg.org/logo-kit/favicon.svg" type="image/svg+xml" />
+    <link rel="apple-touch-icon" href="https://design.codeberg.org/logo-kit/apple-touch-icon.png" />
 
-        <link rel="preload" type="text/css" href="/assets/css/codeberg-docs.css" as="style">
-        <link rel="preload" type="text/css" href="https://design.codeberg.org/design-kit/codeberg.css" as="style">
-        <link rel="preload" href="https://fonts.codeberg.org/dist/inter/Inter Web/inter.css" as="style">
-        <link rel="preload" href="https://fonts.codeberg.org/dist/fontawesome5/css/solid.min.css" as="style">
-        <link rel="preload" href="https://fonts.codeberg.org/dist/fontawesome5/css/fontawesome.min.css" as="style">
+    <link rel="preload" type="text/css" href="/assets/css/codeberg-docs.css" as="style" />
+    <link rel="preload" type="text/css" href="https://design.codeberg.org/design-kit/codeberg.css" as="style" />
+    <link rel="preload" href="https://fonts.codeberg.org/dist/inter/Inter%20Web/inter.css" as="style" />
+    <link rel="preload" href="https://fonts.codeberg.org/dist/fontawesome6/css/svg-with-js.css" as="style" />
 
-        <!-- Details and License: https://codeberg.org/Codeberg/Design/src/branch/master/design-kit -->
-        <link rel="stylesheet" href="https://design.codeberg.org/design-kit/codeberg.css"/>
-        <script defer src="https://design.codeberg.org/design-kit/codeberg.js"></script>
+    <!-- Details and License: https://codeberg.org/Codeberg/Design/src/design-kit -->
+    <link rel="stylesheet" href="https://design.codeberg.org/design-kit/codeberg.css" />
+    <script defer src="https://design.codeberg.org/design-kit/codeberg.js"></script>
 
-        <link rel="stylesheet" type="text/css" href="/assets/css/codeberg-docs.css" async>
-        <!-- Syntax highlighting -->
-        <link rel="stylesheet" type="text/css" href="/assets/css/prism-nord.css" async>
+    <link rel="stylesheet" type="text/css" href="/assets/css/codeberg-docs.css" />
+    <!-- Syntax highlighting -->
+    <link rel="stylesheet" type="text/css" href="/assets/css/prism-nord.css" />
 
-        <!-- Details and License: https://fonts.codeberg.org/fonts/inter -->
-        <link rel="stylesheet" type="text/css" href="https://fonts.codeberg.org/dist/inter/Inter Web/inter.css" async>
+    <!-- Details and License: https://fonts.codeberg.org/fonts/inter -->
+    <link rel="stylesheet" type="text/css" href="https://fonts.codeberg.org/dist/inter/Inter%20Web/inter.css" />
 
-        <!-- Details and License: https://fonts.codeberg.org/fonts/fontawesome5 -->
-        <link rel="stylesheet" type="text/css" href="https://fonts.codeberg.org/dist/fontawesome5/css/solid.min.css" async>
-        <link rel="stylesheet" type="text/css" href="https://fonts.codeberg.org/dist/fontawesome5/css/fontawesome.min.css" async>
+    <!-- Details and License: https://fonts.codeberg.org/fonts/fontawesome5 -->
+    <link rel="stylesheet" type="text/css" href="https://fonts.codeberg.org/dist/fontawesome6/css/svg-with-js.css" />
 
-        {% if page.url != '/' %}
-        <script>
-            // @license magnet:?xt=urn:btih:90dc5c0be029de84e523b9b3922520e79e0e6f08&dn=cc0.txt CC0
-            document.addEventListener("DOMContentLoaded", function() {
-                document.getElementsByClassName("active")[0].scrollIntoView({block: "center"})
-            });
-            // @license-end
-        </script>
-        {% endif %}
-    </head>
+    <link href="/pagefind/pagefind-modular-ui.css" rel="stylesheet" />
+    <script src="/pagefind/pagefind-modular-ui.js"></script>
+    <script>
+      window.addEventListener('DOMContentLoaded', (event) => {
+        const instance = new PagefindModularUI.Instance();
+        instance.add(
+          new PagefindModularUI.Input({
+            containerElement: '#search-input',
+          }),
+        );
+        instance.add(
+          new PagefindModularUI.ResultList({
+            containerElement: '#search-results',
+          }),
+        );
+        document.addEventListener(
+          'keydown',
+          (event) => {
+            if (event.key == '/') {
+              event.preventDefault();
+              document.getElementById('search-input').focus();
+            }
+          },
+          false,
+        );
+      });
+    </script>
 
-    <body data-set-preferred-mode-onload="true">
-        {% include 'license.njk' %}
-        <div class="page-wrapper with-sidebar with-navbar with-transitions" data-sidebar-type="overlayed-sm-and-down">
-            <div class="sidebar-overlay" onclick="halfmoon.toggleSidebar()"></div>
-            <nav class="navbar">
-                <div class="navbar-content">
-                    <button class="btn btn-primary" type="button" onclick="halfmoon.toggleSidebar()">
-                        <i class="fa fa-bars" aria-hidden="true"></i>
-                        <span class="sr-only">Toggle sidebar</span>
-                    </button>
-                </div>
-                <!-- Navbar brand -->
-                <a href="/" class="navbar-brand" title="Codeberg Docs">
-                    <img src="https://design.codeberg.org/logo-kit/icon_inverted.svg" height="22px" width="22px" alt="Codeberg"> Docs
-                </a>
-                <!-- Navbar nav -->
-                <ul class="navbar-nav ml-auto d-none d-md-flex">
-                    <li class="nav-item">
-                        <a href="{{ urls.commitHistoryMaster }}/{{ page.inputPath }}" class="nav-link" target="_blank" rel="noreferrer">
-                            {% fas_icon "history" %} &nbsp; View History
-                    </a>
-                    </li>
-                    <li class="nav-item">
-                        <a href="{{ urls.docsSourcesMaster }}/{{ page.inputPath }}" class="nav-link" target="_blank" rel="noreferrer">
-                            {% fas_icon "code" %} &nbsp; View Source
-                    </a>
-                    </li>
-                    {# <li class="nav-item">
-                        <a href="javascript:;" onclick="document.body.classList.toggle('dark-mode')" class="nav-link">
-                            {% fas_icon "moon" %} &nbsp; Toggle Dark Mode
-                    </a>
-                    </li> #}
-                </ul>
-                <!-- Navbar content (dropdown menu) -->
-                <div class="navbar-content d-md-none ml-auto">
-                    <div class="dropdown with-arrow">
-                        <button class="btn" data-toggle="dropdown" type="button" id="navbar-dropdown-toggle-btn-1">
-                            Menu <i class="fa fa-angle-down" aria-hidden="true"></i>
-                        </button>
-                        <div class="dropdown-menu dropdown-menu-right w-200" aria-labelledby="navbar-dropdown-toggle-btn-1">
-                            <a href="{{ urls.commitHistoryMaster }}/{{ page.inputPath }}" class="dropdown-item" target="_blank" rel="noreferrer">
-                                {% fas_icon "history" %} &nbsp; View History
-                            </a>
-                            <a href="{{ urls.docsSourcesMaster }}/{{ page.inputPath }}" class="dropdown-item" target="_blank" rel="noreferrer">
-                                {% fas_icon "code" %} &nbsp; View Source
-                            </a>
-                            {# <a href="javascript:;" onclick="document.body.classList.toggle('dark-mode')" class="dropdown-item">
-                                {% fas_icon "moon" %} &nbsp; Toggle Dark Mode
-                            </a> #}
-                            <div class="dropdown-divider mt-5"></div>
-                        </div>
-                    </div>
-                </div>
-            </nav>
+    {% if page.url != '/' %}
+    <script>
+      // @license magnet:?xt=urn:btih:90dc5c0be029de84e523b9b3922520e79e0e6f08&dn=cc0.txt CC0
+      document.addEventListener('DOMContentLoaded', function () {
+        document.getElementsByClassName('active')[0].scrollIntoView({ block: 'center' });
+      });
+      // @license-end
+    </script>
+    {% endif %}
+  </head>
 
-            <div class="sidebar">
-                <div class="sidebar-menu">
-                {# <!-- Sidebar content with the search box -->
-                <div class="sidebar-content">
-                <input type="text" class="form-control" placeholder="Filter Docs" id="search-input">
-                <div class="mt-10 font-size-12">
-                    Press <kbd>/</kbd> to focus
-                </div>
-                </div> #}
-
-                {% for entry in collections.all | eleventyNavigation %}
-                    {% set active = entry.url == page.url or entry.key == eleventyNavigation.parent %}
-                    {% if (not entry.draft) or active %}
-                        <h5 class="sidebar-title {% if active %} active{% endif %}">
-                            <a href="{{ entry.url }}" id="{{ entry.key }}">{% fas_icon entry.icon | default("caret-right") %} {{ entry.title }}</a>
-                        </h5>
-                        <div class="sidebar-divider"></div>
-                        {% if entry.children.length > 0 %}
-                            {% for child in entry.children %}
-                                {% set child_active = child.url == page.url %}
-                                {% if child_active or not child.draft %}
-                                    <a href="{{ child.url }}" class="sidebar-link{% if child_active %} active{% endif %}" id="{{ child.key }}">
-                                        <span class="name">{{ child.title }}</span>
-                                    </a>
-                                {% endif %}
-                            {% endfor %}
-                        {% endif %}
-                    {% endif %}
-                    <br>
-                {%- endfor %}
-
-                </div>
-            </div>
-
-            <div class="content-wrapper">
-                <div class="container-lg">
-                    <div class="content">
-                        {% if eleventyNavigation.title %}
-                            <h1 class="content-title font-size-24">{{ eleventyNavigation.title }}</h1>
-                        {% endif %}
-                        {% if eleventyNavigation.draft %}
-                            <strong>Please note that this article is still a draft and might not have any contents yet.</strong>
-                        {% endif %}
-                        {{ content | safe }}
-                        <hr class="mb-20">
-                        {% if page.url != '/' %}
-                            {% include 'contribution_invitation.njk' %}
-                        {% endif %}
-                        <div class="font-size-16 text-right">
-                            <p>&copy; Codeberg Docs Contributors. See <a href="#modal-1" role="button">LICENSE</a></p>
-                        </div>
-                    </div>
-                </div>
-            </div>
+  <body data-set-preferred-mode-onload="true">
+    {% include 'license.njk' %}
+    <div class="with-navbar with-sidebar with-transitions page-wrapper" data-sidebar-type="overlayed-sm-and-down">
+      <div class="sidebar-overlay" onclick="halfmoon.toggleSidebar()"></div>
+      <nav class="navbar">
+        <div class="navbar-content">
+          <button class="btn btn-primary" type="button" onclick="halfmoon.toggleSidebar()">
+            {% fas_icon "bars" %}
+            <span class="sr-only">Toggle sidebar</span>
+          </button>
         </div>
-    </body>
+        <!-- Navbar brand -->
+        <a href="/" class="navbar-brand" title="Codeberg Docs">
+          <img src="https://design.codeberg.org/logo-kit/icon_inverted.svg" height="22" width="22" alt="Codeberg" />
+          Docs
+        </a>
+        <!-- Navbar nav -->
+        <ul class="d-md-flex ml-auto d-none navbar-nav">
+          <li class="nav-item">
+            <a
+              href="{{ urls.commitHistoryMaster }}/{{ page.inputPath }}"
+              class="nav-link"
+              target="_blank"
+              rel="noreferrer"
+            >
+              {% fas_icon "history" %} &nbsp; View History
+            </a>
+          </li>
+          <li class="nav-item">
+            <a
+              href="{{ urls.docsSourcesMaster }}/{{ page.inputPath }}"
+              class="nav-link"
+              target="_blank"
+              rel="noreferrer"
+            >
+              {% fas_icon "code" %} &nbsp; View Source
+            </a>
+          </li>
+          {#
+          <li class="nav-item">
+            <a href="javascript:;" onclick="document.body.classList.toggle('dark-mode')" class="nav-link">
+              {% fas_icon "moon" %} &nbsp; Toggle Dark Mode
+            </a>
+          </li>
+          #}
+        </ul>
+        <!-- Navbar content (dropdown menu) -->
+        <div class="ml-auto d-md-none navbar-content">
+          <div class="with-arrow dropdown">
+            <button class="btn" data-toggle="dropdown" type="button" id="navbar-dropdown-toggle-btn-1">
+              Menu {% fas_icon "angle-down" %}
+            </button>
+            <div class="dropdown-menu-right w-200 dropdown-menu" aria-labelledby="navbar-dropdown-toggle-btn-1">
+              <a
+                href="{{ urls.commitHistoryMaster }}/{{ page.inputPath }}"
+                class="dropdown-item"
+                target="_blank"
+                rel="noreferrer"
+              >
+                {% fas_icon "history" %} &nbsp; View History
+              </a>
+              <a
+                href="{{ urls.docsSourcesMaster }}/{{ page.inputPath }}"
+                class="dropdown-item"
+                target="_blank"
+                rel="noreferrer"
+              >
+                {% fas_icon "code" %} &nbsp; View Source
+              </a>
+              {#
+              <a href="javascript:;" onclick="document.body.classList.toggle('dark-mode')" class="dropdown-item">
+                {% fas_icon "moon" %} &nbsp; Toggle Dark Mode
+              </a>
+              #}
+              <div class="mt-5 dropdown-divider"></div>
+            </div>
+          </div>
+        </div>
+      </nav>
+
+      <div class="sidebar">
+        <div class="sidebar-menu">
+          <!-- Sidebar content with the search box -->
+          <div class="sidebar-content">
+            <input type="text" class="form-control" placeholder="Filter Docs" id="search-input" />
+            <div class="mt-10 font-size-12">Press <kbd>/</kbd> to focus</div>
+            <div id="search-results"></div>
+          </div>
+
+          {% for entry in collections.all | eleventyNavigation %} {% set active = entry.url == page.url or entry.key ==
+          eleventyNavigation.parent %} {% if (not entry.draft) or active %}
+          <h5 class="sidebar-title {% if active %} active{% endif %}">
+            <a href="{{ entry.url }}" id="{{ entry.key }}"
+              >{% fas_icon entry.icon | default("caret-right") %} {{ entry.title }}</a
+            >
+          </h5>
+          <div class="sidebar-divider"></div>
+          {% if entry.children.length > 0 %} {% for child in entry.children %} {% set child_active = child.url ==
+          page.url %} {% if child_active or not child.draft %}
+          <a href="{{ child.url }}" class="sidebar-link{% if child_active %} active{% endif %}" id="{{ child.key }}">
+            <span class="name">{{ child.title }}</span>
+          </a>
+          {% endif %} {% endfor %} {% endif %} {% endif %}
+          <br />
+          {%- endfor %}
+        </div>
+      </div>
+
+      <div class="content-wrapper">
+        <div class="container-fluid">
+          <div class="row">
+            <div class="col-xl-8 content" data-pagefind-body>
+              {% if eleventyNavigation.title %}
+              <h1 class="content-title font-size-24">{{ eleventyNavigation.title }}</h1>
+              {% endif %} {% if eleventyNavigation.draft %}
+              <strong data-pagefind-ignore="all"
+                >Please note that this article is still a draft and might not have any contents yet.</strong
+              >
+              {% endif %} {% include 'toc-collapse.njk' %}
+              {{ content | safe }}
+              <hr class="mb-20" />
+              {% if page.url != '/' %} {% include 'contribution_invitation.njk' %} {% endif %}
+              <div class="text-right font-size-16" data-pagefind-ignore="all">
+                <p>&copy; Codeberg Docs Contributors. See <a href="#modal-1" role="button">LICENSE</a></p>
+              </div>
+            </div>
+            {% include 'toc-side.njk' %}
+          </div>
+        </div>
+      </div>
+    </div>
+  </body>
 </html>

content/_includes/license.njk

@@ -1,25 +1,36 @@
 <div class="modal" id="modal-1" tabindex="-1" role="dialog">
-    <div class="modal-dialog" role="document">
-        <div class="modal-content">
-            <h5 class="modal-title">LICENSE</h5>
-            <p>
-                This Website by <a href="{{ urls.docsSourcesMaster }}/CONTRIBUTORS.md">The Codeberg Documentation Contributors</a> 
-                is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/deed.en">CC-BY-SA 4.0</a>.
-            </p>
-            <p>
-                It bundles third-party font software licensed under a different license.
-                Please look at <a href="{{ urls.docsSourcesMaster }}/LICENSE.md">the LICENSE file</a> for details.
-            </p>
-            <p>
-                Changes to the original versions of the article as well as its individual authors can be looked up in 
-                <a href="{{ urls.commitHistoryMaster }}/{{ page.inputPath }}" target="_blank" rel="noreferrer">this article's commit history</a>
-            </p>
-            <p>
-                Codeberg and the Codeberg Logo are trademarks of Codeberg e.V.
-            </p>
-            <div class="text-right mt-20">
-                <a href="#" class="btn mr-5" role="button">Close</a>
-            </div>
-        </div>
+  <div class="modal-dialog" role="document">
+    <div class="modal-content">
+      <h5 class="modal-title">LICENSE</h5>
+      <p>
+        The
+        <span
+          xmlns:dct="http://purl.org/dc/terms/"
+          href="http://purl.org/dc/dcmitype/Text"
+          property="dct:title"
+          rel="dct:type"
+        >
+          Codeberg Documentation website</span
+        >
+        is licensed under a
+        <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"
+          >Creative Commons Attribution-ShareAlike 4.0 International License</a
+        >.
+      </p>
+      <p>
+        It bundles third-party font software licensed under a different license. Please look at
+        <a href="{{ urls.docsSourcesMaster }}/LICENSE.md">the LICENSE file</a> for details.
+      </p>
+      <p>
+        Changes to the original versions of the article as well as its individual authors can be looked up in
+        <a href="{{ urls.commitHistoryMaster }}/{{ page.inputPath }}" target="_blank" rel="noreferrer"
+          >this article's commit history</a
+        >
+      </p>
+      <p>Codeberg and the Codeberg Logo are trademarks of Codeberg e.V.</p>
+      <div class="text-right mt-20">
+        <a href="#" class="mr-5 btn" role="button">Close</a>
+      </div>
     </div>
-</div>
+  </div>
+</div>

content/_includes/redirect.njk

@@ -1,10 +1,10 @@
-<!doctype html>
+<!DOCTYPE html>
 <html lang="en">
-<head>
-	<meta charset="utf-8">
-	<meta http-equiv="refresh" content="0; url='{{ redirect.to }}'" />
-</head>
-<body>
-	Redirecting to <a href="{{ redirect.to }}">{{ redirect.to }}</a>
-</body>
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="refresh" content="0; url='{{ redirect.to }}'" />
+  </head>
+  <body>
+    Redirecting to <a href="{{ redirect.to }}">{{ redirect.to }}</a>
+  </body>
 </html>

content/_includes/toc-collapse.njk

@@ -0,0 +1,12 @@
+{% if content | toc %}
+<nav class="mb-3 d-xl-none" data-pagefind-ignore="all">
+  <details class="collapse-panel">
+    <summary class="d-block d-flex justify-content-between align-items-center py-2 w-full collapse-header">
+      <span class="antialiased">On this page</span>
+    </summary>
+    <div id="toc" class="collapse-content">
+      {{ content | toc | safe }}
+    </div>
+  </details>
+</nav>
+{% endif %}

content/_includes/toc-side.njk

@@ -0,0 +1,10 @@
+{% if content | toc %}
+<nav class="col-xl-3 position-relative d-none d-xl-block" id="toc-side" data-pagefind-ignore="all">
+  <div class="position-fixed  mr-20">
+    <span>On this page</span>
+    <div id="toc" class="overflow-y-auto" style="max-height: 43.75rem;">
+      {{ content | toc | safe }}
+    </div>
+  </div>
+</nav>
+{% endif %}

content/advanced/access-token.md

@@ -5,11 +5,16 @@ eleventyNavigation:
   parent: AdvancedUsage
 ---
 
-Access Tokens are special tokens that are used to authenticate to Codeberg through the [API](https://codeberg.org/api/swagger). They can be used to give applications access to your Codeberg account without sharing your password. 
+Access Tokens are special tokens that are used to authenticate to Codeberg through the [API](https://codeberg.org/api/swagger). They can be used to give applications access to your Codeberg account without sharing your password.
 
-> This guide explains how to generate an access token from the website. However, you can also generate access tokens from the API. Read more at [Gitea's documentation](https://docs.gitea.io/en-us/api-usage/#generating-and-listing-api-tokens).
+{% admonition "info" %}
+
+This guide explains how to generate an access token from the website. However, you can also generate access tokens from the API. Read more at [Forgejo's documentation](https://forgejo.org/docs/v1.19/user/api-usage/#generating-and-listing-api-tokens).
+
+{% endadmonition %}
 
 ## Generating an Access Token
+
 Access tokens grant full access to your account. You must handle them securely.
 
 <picture>
@@ -20,7 +25,7 @@ Access tokens grant full access to your account. You must handle them securely.
 1. In a web browser, go to Codeberg and click on the `Profiles and Settings` button on the top right. The button will be your profile picture.
 2. Click on [`Settings`](https://codeberg.org/user/settings) in the dropdown.
 3. Navigate to the [`Applications`](https://codeberg.org/user/settings/applications) settings tab.
-4. Under `Manage Access Tokens | Generate New Token`, enter a name to identify your token in the `Token Name` field. 
+4. Under `Manage Access Tokens | Generate New Token`, enter a name to identify your token in the `Token Name` field.
 5. Click the generate token button.
 
 <picture>
@@ -30,9 +35,14 @@ Access tokens grant full access to your account. You must handle them securely.
 
 Your access token has now been generated! Copy your token and store it securely.
 
-> Be sure to generate new access tokens for each app you use, and delete them once they are not in use.
+{% admonition "tip" %}
+
+Be sure to generate new access tokens for each app you use, and delete them once they are not in use.
+
+{% endadmonition %}
 
 ## Deleting an Access Token
+
 Once you are done using an access token, you should delete it. Deleting an access token revokes access to your account for apps using the token.
 
-To delete an access token, click the red `Delete` button next to the access token you want to delete, then click `Yes` in the popup. Your access token is now deleted.
+To delete an access token, click the red `Delete` button next to the access token you want to delete, then click `Yes` in the popup. Your access token is now deleted.

content/advanced/index.md

@@ -2,12 +2,33 @@
 eleventyNavigation:
   key: AdvancedUsage
   title: Advanced Usage
-  icon: terminal 
+  icon: terminal
   order: 65
 ---
 
 These documentation pages contain tips and tricks for diving more deeply into
 the more advanced features of Codeberg.
 
-See also the [documentation of Gitea](https://docs.gitea.io), the software which
+See also the [documentation of Forgejo](https://forgejo.org/docs/), 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,27 +15,39 @@ 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.
 
-Here we document instructions for migrating specific to each service. Once you've followed through, move on to [`Starting Migration`](#starting-migration).
+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.
+
+- [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>
   <source srcset="/assets/images/advanced/migrating-repos/git-migration.webp" type="image/webp">
   <img src="/assets/images/advanced/migrating-repos/git-migration.png">
 </picture>
 
 Here's an explanation of some fields on the [Git migration page](https://codeberg.org/repo/migrate?service_type=1):
+
 - **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">
@@ -43,9 +55,20 @@ To migrate a repo with its metadata from a Gitea instance, you will first need t
 </picture>
 
 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.
+
+- **Migrate / Clone From URL**: This is the URL to your repository. For example: `https://code.forgejo.org/forgejo/end-to-end`.
+- **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.
+
+{% admonition "tip" %}
+
+You can also use this method to migrate your repos away from Codeberg to another Gitea or Forgejo instance.
+
+{% endadmonition %}
 
 ## Starting Migration
 
@@ -54,4 +77,12 @@ Migration might take a while, depending on how large the repo is.
 
 When the repo code appears, migration is complete!
 
-> **Troubleshooting**: The migration process may time out after a while. If this happens, or if you have any other issues with migration, feel free to open an issue in the [Community Issue Tracker](https://codeberg.org/Codeberg/Community/issues).
+## Inaccessible repo after failed migration
+
+Sometimes a migration might fail for no obvious reasons like timeouts or invalid data in the source repo, leaving you with an inaccessible repo on Codeberg.
+When you try to navigate to your repo on Codeberg, e.g. `https://codeberg.org/knut/example/`, you are welcomed with a `500 Internal Server Error`.
+
+In this case it might be worthwhile to retry the migration.  
+First you need to remove the inaccessible repo. To do so, go to the settings page of your repo by appending `/settings` to the URI, e.g. `https://codeberg.org/knut/example/settings`. You can delete the repo from here and start over with a new migration.
+
+If this doesn't work out, feel free to open an issue in the [Community Issue Tracker](https://codeberg.org/Codeberg/Community/issues).

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 paragraphs 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 every time 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/ci/actions.md

@@ -0,0 +1,310 @@
+---
+eleventyNavigation:
+  key: UsingForgejoActions
+  title: Using Forgejo Actions (Self-hosted)
+  parent: CI
+---
+
+Actions is a continuous integration and continuous delivery (CI/CD) feature that allows you to automate your build, test and deployment pipelines in Forgejo, the software Codeberg uses. For more information, please read [Forgejo's Documentation](https://forgejo.org/docs/latest/user/actions/).
+
+Due to outstanding security issues and bus factor (we need more maintainers for our CI service to get it running),
+we are currently not yet providing hosted Actions.
+If you need Codeberg to host your CI, please use Woodpecker CI instead.
+
+But you can already connect your own Runner to Codeberg.
+CI jobs will run on your machine, and the result will be displayed in Codeberg.
+
+This guide will walk you through setting up your own [Forgejo Actions](https://forgejo.org/2023-02-27-forgejo-actions/) Runner to use for CI jobs.
+
+## Obtaining a registration token
+
+{% admonition "info" "Make sure to enable actions" %}
+
+Repository Actions are disabled by default and will require you to enable them in the "Advanced Settings" section of the settings page.
+
+{% endadmonition %}
+
+Before deploying the Runner, you need to obtain a registration token from Codeberg. Registration tokens are used by the Runner and Codeberg to share secrets and configurations.
+
+You can add Runners to your account, organization, or repository. Choosing where you obtain the registration token will determine where your Runner will accept workflows from.
+
+1. Go to the account/organization/repository settings page.
+
+2. Click on Actions.
+
+3. Click on Runners.
+
+4. Click on Create new Runner.
+
+5. Copy the registration token.
+
+<picture>
+    <source srcset="/assets/images/ci/actions/create-new-runner.webp" type="image/webp">
+    <img src="/assets/images/ci/actions/create-new-runner.png" alt="Create new Runner">
+</picture>
+
+## Installing Forgejo Runner
+
+Forgejo Runner is released in both binary and container image (OCI) forms:
+
+- Download the binary to run on your machine:
+
+  ```bash
+  $ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v3.3.0/forgejo-runner-3.3.0-linux-amd64
+  $ chmod +x forgejo-runner
+  ```
+
+  Make sure to replace `amd64` with `arm64` if your host machine is on ARM.
+
+- Or download the container image and run it using Docker:
+
+  ```bash
+  $ docker run --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner --version
+  forgejo-runner version v3.3.0
+  ```
+
+## Preparing configuration files
+
+Before you deploy the Runner, you need to generate its configuration files and modify as suited.
+
+You can generate them to your current directory by either running the binary on host or in a Docker container.
+
+Make sure to replace `{TOKEN}` with the registration token you copied, and `{NAME}` with any identifier to monitor it on Codeberg.
+
+### Binary
+
+```bash
+$ ./forgejo-runner register --no-interactive --token {TOKEN} --name {NAME} --instance https://codeberg.org
+INFO Registering runner, arch=amd64, os=linux, version=3.3.0.
+DEBUG Successfully pinged the Forgejo instance server
+INFO Runner registered successfully.
+$ ./forgejo-runner generate-config > config.yml
+```
+
+### Docker
+
+```bash
+$ docker run -v /var/run/docker.sock:/var/run/docker.sock  -v $PWD:/data --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner register --no-interactive --token {TOKEN} --name {NAME} --instance https://codeberg.org
+Status: Downloaded newer image for code.forgejo.org/forgejo/runner:3.3.0
+level=info msg="Registering runner, arch=arm64, os=linux, version=v3.3.0."
+level=warning msg="Runner in user-mode."
+level=debug msg="Successfully pinged the Forgejo instance server"
+level=info msg="Runner registered successfully."
+$ docker run -v /var/run/docker.sock:/var/run/docker.sock  -v $PWD:/data --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner generate-config > config.yml
+```
+
+---
+
+These commands will generate two files in your current directory:
+
+- `.runner` which is the configuration file produced when registering the runner.
+
+- `config.yml` which is the main configuration file with defaults in place you can modify to suit your needs and environment.
+
+## Deployment Methods
+
+Depending on your setup and your security needs, there is a wide variety of options for deploying the Runner.
+
+### Running on Docker
+
+This method uses the host Docker server by mounting the socket.
+
+{% admonition "info" "Podman compatibility" %}
+
+Podman can work by executing:
+
+```bash
+$ podman system service -t 0 &
+
+$ DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock ./forgejo-runner daemon
+```
+
+{% endadmonition %}
+
+Since this method requires access to the Docker socket, you will need to get the GID of the Docker group (usually `docker`) in your host machine by running:
+
+```bash
+$ id | grep -Po '\d+\(docker\)'
+$ 996(docker)
+```
+
+Make sure to replace `996` with the Docker group GID of the host in the following command:
+
+```bash
+$ docker run -d -v /var/run/docker.sock:/var/run/docker.sock --user 1000:996 -v $PWD:/data --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner --config config.yml daemon
+22eae46a021294a213e7f733203f7551250b67367c7507b53b5fd427f0f82d2e
+```
+
+Now your CI Runner should be running in a new container.
+
+#### Running on Docker in Docker
+
+Using Docker Compose, we can configure the Runner container to execute workflows inside another layer of containers (Docker-in-Docker).
+
+Here is an example snippet of how it can be configured:
+
+```yaml
+version: '3'
+
+services:
+  docker:
+    image: docker:dind
+    privileged: true
+    volumes:
+      - certs:/certs
+
+  runner:
+    image: code.forgejo.org/forgejo/runner:3.3.0
+    environment:
+      DOCKER_HOST: tcp://docker:2376
+      DOCKER_TLS_VERIFY: 1
+      DOCKER_CERT_PATH: /certs/client
+    volumes:
+      - /opt/forgejo-runner:/data
+      - certs:/certs
+    command: 'forgejo-runner --config config.yml daemon'
+volumes:
+  certs:
+```
+
+Make sure to replace `/opt/forgejo-runner` with the directory path of your configuration files.
+
+### Running on Kubernetes
+
+{% admonition "warning" "Warning" %}
+
+Docker in Docker (dind) requires elevated privileges on Kubernetes.
+
+The current way to achieve this is to set the pod `SecurityContext` to `privileged`.
+
+Keep in mind that this is a potential security issue that can allow a malicious application to break out of the container context.
+
+{% endadmonition %}
+
+Here is an example snippet of how it can be configured:
+
+```yaml
+apiVersion: v1
+stringData:
+  token: your_registration_token
+kind: Secret
+metadata:
+  name: runner-secret
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app: forgejo-runner
+  name: forgejo-runner
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: forgejo-runner
+  strategy: {}
+  template:
+    metadata:
+      creationTimestamp: null
+      labels:
+        app: forgejo-runner
+    spec:
+      restartPolicy: Always
+      volumes:
+        - name: docker-certs
+          emptyDir: {}
+        - name: runner-data
+          emptyDir: {}
+      initContainers:
+        - name: runner-config-generation
+          image: code.forgejo.org/forgejo/runner:3.3.0
+          command:
+            ['forgejo-runner create-runner-file --instance $FORGEJO_INSTANCE_URL --secret $RUNNER_SECRET --connect']
+          env:
+            - name: RUNNER_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: runner-secret
+                  key: token
+            - name: FORGEJO_INSTANCE_URL
+              value: https://codeberg.org
+          volumeMounts:
+            - name: runner-data
+              mountPath: /data
+      containers:
+        - name: runner
+          image: code.forgejo.org/forgejo/runner:3.3.0
+          command:
+            [
+              'sh',
+              '-c',
+              "while ! nc -z localhost 2376 </dev/null; do echo 'waiting for docker daemon...'; sleep 5; done; forgejo-runner daemon",
+            ]
+          env:
+            - name: DOCKER_HOST
+              value: tcp://localhost:2376
+            - name: DOCKER_CERT_PATH
+              value: /certs/client
+            - name: DOCKER_TLS_VERIFY
+              value: '1'
+          volumeMounts:
+            - name: docker-certs
+              mountPath: /certs
+            - name: runner-data
+              mountPath: /data
+        - name: daemon
+          image: docker:dind
+          env:
+            - name: DOCKER_TLS_CERTDIR
+              value: /certs
+          securityContext:
+            privileged: true
+          volumeMounts:
+            - name: docker-certs
+              mountPath: /certs
+```
+
+Make sure to replace the value of `token` with your registration token.
+
+### Running on host machine
+
+{% admonition "warning" "Warning" %}
+
+There is no isolation at all and a single job can permanently destroy the host.
+
+{% endadmonition %}
+
+```bash
+$ ./forgejo-runner --config config.yml daemon
+INFO[0000-00-00T00:00:00Z] Starting runner daemon
+```
+
+Now your CI Runner should running on your host machine.
+
+## Testing workflows
+
+To test your CI runner setup, you can use the following demo workflow:
+
+```yaml
+on: [push]
+jobs:
+  test:
+    runs-on: docker
+    steps:
+      - run: echo All Good
+```
+
+The runner seeks action recipes from `.forgejo/workflows`, so make sure your file is in the required path.
+
+<picture>
+    <source srcset="/assets/images/ci/actions/demo-workflow.webp" type="image/webp">
+    <img src="/assets/images/ci/actions/demo-workflow.png" alt="Demo workflow running successfully">
+</picture>
+
+## References
+
+- [Initial announcement blog post by Forgejo](https://forgejo.org/2023-02-27-forgejo-actions/)
+- [Admin docs for Forgejo](https://forgejo.org/docs/latest/admin/actions/)
+- [User docs for Forgejo](https://forgejo.org/docs/latest/user/actions/)
+- [Codeberg Issue tracking the Actions Progress](https://codeberg.org/Codeberg/Community/issues/843)
+- [Setting up a Self-Hosted Forgejo Actions Runner with Docker Compose](https://linus.dev/posts/setting-up-a-self-hosted-forgejo-actions-runner-with-docker-compose/)

content/ci/index.md

@@ -0,0 +1,55 @@
+---
+eleventyNavigation:
+  key: CI
+  title: Working with Codeberg's CI
+  icon: arrows-spin
+  order: 65
+---
+
+Every piece of code should be tested regularly. Ideally developers already implement unit-tests to test the functionality of code sections.
+Some projects even implement a suite of integration tests, testing whether the code in different parts of the software works as a whole and (still) provides the functionality the software promises to deliver.
+Running these tests regularly (or continuously) is the job of a Continuous Integration (CI) solution.
+The results of the tests are displayed to the project members and maintainers, enabling them to identify problems and react if errors occur.
+
+## Using Codeberg's instance of Woodpecker CI
+
+Codeberg provides a [Woodpecker CI](https://woodpecker-ci.org) instance at [ci.codeberg.org](https://ci.codeberg.org/).
+
+Onboarding requires a few manual steps, as to prevent the abuse of Codeberg's limited resources.
+You will need to request access [by filling out this form](https://codeberg.org/Codeberg-e.V./requests/issues/new?template=ISSUE_TEMPLATE%2fWoodpecker-CI.yaml).
+After submitting, a Codeberg volunteer will review your request and grant you access if your use case is appropriate.
+
+In order to ensure a fast approval,
+please take a minute to read about [the criteria that your project has to adhere to](https://codeberg.org/Codeberg-e.V./requests#woodpecker-ci).
+
+If your request gets approved, you will be able to login to [ci.codeberg.org](https://ci.codeberg.org) via your Codeberg account.
+To start builds for your repository, you must enable them in Woodpecker specifically using https://ci.codeberg.org/repos/add. Repositories owned by your codeberg account should automatically be available as options to select.
+
+### Caveats
+
+For the usage of our Woodpecker instance, keep the following in mind:
+
+- **CI access is provided as-is and might break at any time** and for an undefined period of time, due to server issues, for testing and maintenance purpose or human error.
+- **Resource usage must be reasonable** for the intended use-case. CI requires substantial computing resources (cloning the repo and pulling the image, installing required tools, building and throwing everything away). Please try to ensure a good balance between code quality/automation and resource usage. Therefore, please consider twice how to create a good balance between ensuring code quality for your project and resource usage therefore.
+- The CI service requires manual onboarding and Woodpecker has limited Role-Based Access Control (RBAC) capabilities, which will be a problem for projects with a team-based permission structure or many individual collaborators.
+  Issues and general feedback should be reported in our
+  [dedicated Codeberg CI feedback repository](https://codeberg.org/Codeberg-CI/feedback).
+
+### Usage
+
+If you are curious about Woodpecker or are already using a third-party Woodpecker instance,
+please consult [Woodpecker's documentation](https://woodpecker-ci.org/docs/intro). If you wish to see examples of integrating Woodpecker-CI with codeberg, please consult the [Codeberg-CI examples repository.](https://codeberg.org/Codeberg-CI/examples)
+
+### Custom Woodpecker Instances
+
+You can alternatively host your own Woodpecker instance and link it to Codeberg.
+This will give you a lot more freedom and capabilities with the downside of having to utilize your own hardware.
+Please consult Woodpecker's
+[Forgejo integration documentation](https://woodpecker-ci.org/docs/administration/forges/gitea)
+for more information.
+
+## Using Forgejo Actions
+
+Forgejo, the software Codeberg is built on, offers a CI/CD feature called Actions.
+
+Further information such as how to run it is available in [Using Forgejo Actions (Self-hosted) page](./actions).

content/codeberg-pages/examples/docs-as-code.md

@@ -0,0 +1,222 @@
+---
+eleventyNavigation:
+  key: DocsAsCode
+  title: 'Example: Docs as Code with Sphinx'
+  parent: CodebergPages
+  order: 100
+---
+
+Docs-as-code (also known as "Documentation as Code") refers to the concept of treating documentation as a codebase, i.e. integrating the documentation process in the toolchains and workflows used by software development teams.
+
+Docs-as-code involves using version control systems such as Git for your documentation projects and authoring your content with plain text markup languages such as Markdown or reStructuredText, among other things.
+
+To find out more about docs-as-code, head over to [its website](https://docs-as-co.de/).
+
+Whether you are a single technical communicator or a member of a larger documentation team, you can perfectly apply the docs-as-code approach to your documentation projects.
+
+This guide will show you how to implement docs-as-code on a Linux machine using [Sphinx](https://www.sphinx-doc.org/en/master/) as a documentation generator, [Git](https://ka2in.codeberg.page/gitinminutes.html) as a version control system and [Codeberg Pages](https://docs.codeberg.org/codeberg-pages/) as static site hosting.
+
+{% admonition "info" "Note" %}
+
+Despite the fact that we are using Sphinx in this particular case, you can easily apply these instructions to any static site generator (SSG) such as [Eleventy](https://www.11ty.dev/) or [Hugo](https://gohugo.io/).
+
+{% endadmonition %}
+
+## Building documentation with Sphinx
+
+Initially developed to generate Python documentation, Sphinx is now widely used by technical communicators and software developers to create technical and software documentation.
+
+Sphinx uses [reStructuredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html) as a markup language to generate documentation content. Among further advantages, Sphinx allows you to produce your documentation in different formats, including HTML, LaTeX and ePub. You can also use one of the multiple extensions developed by the community to extend its functionality.
+
+### Setting up the project
+
+To begin setting up your project, you will first need an account on Codeberg. If you don't already have one, follow the instructions provided under [Your First Steps on Codeberg](https://docs.codeberg.org/getting-started/first-steps/).
+
+This guide assumes that you already have Git installed on your machine. If you don't, you can install git as described in the article [Install Git](https://docs.codeberg.org/getting-started/install-git/).
+
+For the purpose of this guide, we will start a documentation project from scratch using an empty repository. To create a new empty repository and clone it to your local workspace, follow the steps described in the article [Your First Repository](https://docs.codeberg.org/getting-started/first-repository/) as well as the instructions provided under "Option A: Clone the newly created, empty repository" within the same article.
+
+### Creating a Python virtual environment
+
+A "virtual" isolated environment comes in very handy to eliminate the risk of any broken dependencies while working on your projects. In other words, setting up a virtual environment for your project allows you to run an instance of the Python interpreter with a particular package set and a specific configuration while ensuring compatibility between all these components inside that environment.
+
+Before starting, you should make sure that you have pip and Python 3 installed on your machine. To check, type the following commands in your terminal:
+
+```bash
+$ pip --version
+$ python3 --version
+```
+
+If pip and Python are not installed on your Linux machine, please follow the steps described in the articles [pip Installation](https://pip.pypa.io/en/latest/installation/) and [Installing Python 3 on Linux](https://docs.python-guide.org/starting/install3/linux/) respectively.
+
+Depending on your Python version, you will need to install a compatible virtual environment manager, i.e. either "venv" for Python >= 3.3, or "virtualenv" for older Python versions.
+
+{% admonition "warning" %}
+
+Please note that Python2 has reached its EOL (End of Life) on January 1st 2020, which means that it is no longer receiving any security updates.
+
+If you are using Python 3.3 or higher, you do not need to install the "venv" module, since it is already available in your Python standard library.
+
+{% endadmonition %}
+
+The next step is to create a virtual environment. To do so, navigate to the folder where you have cloned the repository described under the section [Setting up the project](#setting-up-the-project):
+
+```bash
+$ cd ~/repositories/foobar
+$ python3 -m venv env
+```
+
+You can replace the second argument "env" with any other name your like. This will be the folder hosting your virtual environment.
+
+{% admonition "warning" %}
+
+Use a **`.gitignore`** file to exclude your virtual environment directory from your version control system. To ignore the entire "env" folder, include the corresponding path and append a **`/`** at its end, e.g. **`env/`**.
+
+{% endadmonition %}
+
+### Activating the virtual environment
+
+Before you begin performing any tasks on your project, you must activate your virtual environment by running the following command:
+
+```bash
+$ . env/bin/activate
+```
+
+To make sure that you are working inside of your virtual environment, run the command:
+
+```bash
+$ which python
+```
+
+The output of the command above should be the **`env`** folder, e.g.:
+
+```bash
+./env/bin/python
+```
+
+When you are done working on your project, run the following command to leave the virtual environment:
+
+```bash
+$ deactivate
+```
+
+### Installing Sphinx in your virtual environment
+
+If you have followed the steps described up to this point, your local repository should now contain your virtual environment's folder **`env`** in addition to the hidden **`.git`** directory and the **`.gitignore`** file that we have already described at the end of the section [Creating a Python virtual environment](#creating-a-python-virtual-environment), e.g.:
+
+```
+├── myproject
+│   ├── env
+│   ├── .git
+│   └── .gitignore
+```
+
+<a name="mydocs"></a>
+You will now create an empty directory then navigate to it. For the purpose of this guide, we will call our directory `mydocs`. You can choose any name you'd like:
+
+```bash
+$ mkdir mydocs
+$ cd mydocs
+```
+
+Running the command `tree -a` should now output the following:
+
+```bash
+.
+├── mydocs
+├── env
+├── .git
+└── .gitignore
+```
+
+With your virtual environment activated as shown above, it is now time to install Sphinx with `pip`. To do so, run the following:
+
+```bash
+(.venv) $ pip install -U sphinx
+```
+
+{% admonition "tip" %}
+
+If you wish to learn about the different options of **`pip install`** are, run the command **`pip install -h`**.
+
+{% endadmonition %}
+
+Once Sphinx is installed on your virtual environment, type the following command in your terminal:
+
+```bash
+(.venv) $ sphinx-quickstart
+```
+
+You will then be asked to answer a series of questions regarding the configuration of your project.  
+Confirm that you want to **`Separate source and build directories`**. For the rest of the questions, keep pressing **Enter** to accept the default values and fill out the requested fields until you reach the question **`autodoc: automatically insert docstrings from modules`**, then choose **"y" (yes)**. Keep pressing **Enter** again until you reach the question **`Create Makefile?`** and select **"y" (yes)**.
+
+If you now run the `tree` command from your `mydocs` folder, you should get the following output:
+
+```bash
+.
+├── build
+├── make.bat
+├── Makefile
+└── source
+    ├── conf.py
+    ├── index.rst
+    ├── _static
+    └── _templates
+```
+
+Congratulations! 🎉 You have just finished installing Sphinx on your Linux machine.
+
+### Running a local HTTP server using Python
+
+To set up a local testing server for your documentation project, you can use the Python module **`http.server`**. To do so, you will first have to build the HTML resources for the initial test by running the command:
+
+<a name="build"></a>
+
+```bash
+(.venv) $ sphinx-build -b html docs/source/ docs/build/html
+```
+
+Then navigate to the directory hosting the HTML resources:
+
+```bash
+(.venv) $ cd docs/build/html
+```
+
+Once there, run the local python server with the command:
+
+```bash
+(.venv) $ python3 -m http.server 8080
+```
+
+{% admonition "info" %}
+
+"8080" is the TCP port on which the host server is listening for requests.
+
+{% endadmonition %}
+
+To access the default **`index.html`** file, type **`http://localhost:8080`** in your favorite browser. You should then see the default welcome page.
+
+### Creating files with reStructuredText and checking the output
+
+You can start creating your own content by making a new reStructuredText file (.rst) in the source directory:
+
+```bash
+(.venv) $ cd mydocs/source
+(.venv) $ touch mynewfile.rst
+```
+
+You have just created an empty ".rst" file with the **`touch`** command. An ".rst" file is simply a plain text file that is written with reStructuredText as a markup language. To learn about how to use reStructuredText, follow the instructions provided in the article [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
+
+You will be more productive in your writing if you use a text editor that supports syntax highlighting such as [Emacs](https://www.gnu.org/software/emacs/download.html) or [Atom](https://atom.io/). Linux offers plenty of powerful text editors that support syntax highlighting and other advanced features for coding and authoring tasks.
+
+{% admonition "info" %}
+
+Whenever you create a new .rst file, you must add it manually to the `toctree` of your root document, i.e. "index.rst".
+
+{% endadmonition %}
+
+The toctree directive (toc stands for Table of Contents) inserts a tree that connects the different ".rst" files located in your source directory with each other. Read the article [Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive) to learn more about the toctree directive.
+
+Once you have added an .rst file to the `toctree`, you can check the output at any time by running the [sphinx-build](#running-a-local-http-server-using-python) command illustrated above, then refreshing your local testing server.
+
+If you are satisfied with the result on your local development environment, you can publish the content on Codeberg Pages. To find out how to do this, read the article [Pushing output from SSGs into Codeberg Pages](https://docs.codeberg.org/codeberg-pages/pushing-output/).

content/codeberg-pages/index.md

@@ -6,12 +6,64 @@ eleventyNavigation:
   order: 60
 ---
 
-Codeberg allows you to publish static web content (HTML, images, etc) with a human-friendly address ({user-name}.codeberg.page).
+Codeberg Pages allows you to easily publish static websites with a human-friendly address (`{username}.codeberg.page`) via Git on Codeberg.
 
+Follow these simple steps below to get started, or check out the advanced usage below.
 
-1. Create a repository named 'pages' in your user account or organization.
-2. Create static content, HTML, style, fonts or images. Name the homepage file 'index.html'
-3. Push your content to the main branch of the new repository.
-4. You should now be able to access your content using the domain '{user-name}.codeberg.page'.
+1. Create a **public** repository named 'pages' in your user account or organization.
+2. Create static content, HTML, stylesheets, fonts or images. Name the homepage file `index.html`.
+3. Push your content to the default branch of the new repository.
+4. You should now be able to access your content by visiting `{username}.codeberg.page`.
 
-See also [https://codeberg.page/](https://codeberg.page)
+---
+
+This project is developed "in-house" by Codeberg. You can find the source code [here](https://codeberg.org/Codeberg/pages-server/).
+
+See also:
+
+- [codeberg.page](https://codeberg.page)
+- [Troubleshooting (Codeberg Documentation)](troubleshooting)
+- [Features (Codeberg Pages Repository)](https://codeberg.org/Codeberg/pages-server/src/branch/main/FEATURES.md)
+
+{% 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:
+
+- `https://raw.codeberg.page/username/reponame/`: raw content, uses correct MIME types (HTML is forbidden though) and is accessible with CORS.
+- `https://username.codeberg.page`: user page, points the default branch of a user's or organization's `pages` repository
+- `https://username.codeberg.page/reponame/`: repo page, points to the `pages` branch of the repository
+- `https://example.org`: custom domain, points to a repo of choice as outlined below
+
+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`).
+
+## Do you have questions, feedback or have you found a bug?
+
+The source code for Codeberg Pages is maintained over at the [Pages Server repository](https://codeberg.org/Codeberg/pages-server); feel free to head there to provide some feedback, suggestions, bug reports or even patches.
+If you need general community support or have questions, [Codeberg/Community](https://codeberg.org/Codeberg/Community) is a better place to ask, as more people will be watching there to help you out!
+We really appreciate your contribution.
+
+## Installing Pages for your own Forgejo instance
+
+Codeberg Pages works with any Forgejo host out there. So if you are running your own Forgejo, you can absolutely run it yourself and help with the development.
+Check out the [Pages Server repository](https://codeberg.org/Codeberg/pages-server) for more information.

content/codeberg-pages/pushing-output.md

@@ -0,0 +1,81 @@
+---
+eleventyNavigation:
+  key: PushingOutput
+  title: Pushing output from SSGs into Codeberg Pages
+  parent: CodebergPages
+  author: Fayçal Alami Hassani - https://codeberg.org/ka2in
+  date: January 2022
+  order: 101
+---
+
+If you are using a static site generator (SSG) and are satisfied with the result of your project on your local development environment, you can push the files to your Codeberg Pages repository.
+
+To begin with, we will have two separate repositories, both locally and on Codeberg:
+
+- A main repository for the source files, i.e. where the source files related to your main project will be located. We will refer to this repository as the `source` repository. This repository is the one associated with your [mydocs](/codeberg-pages/examples/docs-as-code/#mydocs) folder.
+
+- A second repository for Codeberg pages that we will call the `pages` repository. This repository will only contain the files available in the `html` folder located under docs/build/html.
+
+{% admonition "warning" %}
+
+The `pages` repository **must** be public, as Codeberg Pages will directly fetch the files from the repository, just like an ordinary user would.
+
+{% endadmonition %}
+
+{% admonition "info" %}
+
+For the purpose of this guide, we have chosen to use two separate folders/repositories. However, you may want to have a different setup that involves creating a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) instead of having folders and repositories in separate locations. With a submodule, your configuration may look like so:
+
+```
+├── sources --> This is a git repo
+│   ├── build
+│   │   └── html
+│   │       └── pages --> This is a separate git repo
+│   └── content
+```
+
+{% endadmonition %}
+
+To copy the content of the `html` folder to your new `pages` folder, run the command:
+
+```bash
+(.venv) $ cp -R docs/build/html/ pages
+```
+
+We will now initialize an empty repository inside the pages folder. To do this, type the command:
+
+```bash
+$ git init
+```
+
+To check the status of your project’s files, type the command:
+
+```bash
+$ git status
+```
+
+To add all the files that are available in your directory to Git, run the command:
+
+```bash
+$ git add -A
+```
+
+Now we will commit:
+
+```bash
+$ git commit -m "Example commit message"
+```
+
+Repeat these steps in your `source` folder, then push your local commits to the remote repository with the command:
+
+```bash
+$ git push origin HEAD:your-remote-branch-name
+```
+
+{% admonition "info" "Note" %}
+
+Replace `your-remote-branch-name` with the name of your remote branch. It is recommended to initially push your commits to a branch other than the default branch. Once you have made sure everything went smoothly, you can then make a pull request to merge it into the default branch. To learn more about pull requests, read the article [Pull requests and Git flow](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/).
+
+{% endadmonition %}
+
+You should now be able to access your content by visiting https://{username}.codeberg.page. You can find more information in the [Codeberg Pages](/codeberg-pages/) section.

content/codeberg-pages/redirects.md

@@ -0,0 +1,54 @@
+---
+eleventyNavigation:
+  key: Redirects
+  title: Redirects
+  parent: CodebergPages
+  order: 102
+---
+
+Redirects can be created with a `_redirects` file with the following format:
+
+```
+# Comment
+from  to  [status]
+```
+
+- Lines starting with `#` are ignored
+- `from` - the path to redirect from (Note: repository and branch names are removed from request URLs)
+- `to` - the path or URL to redirect to
+- `status` - status code to use when redirecting (default 301)
+
+## Status codes
+
+- `200` - returns content from specified path (no external URLs) without changing the URL (rewrite)
+- `301` - Moved Permanently (Permanent redirect)
+- `302` - Found (Temporary redirect)
+
+## Examples
+
+### Simple redirect
+
+Redirects a specific path.
+
+```
+/example  https://example.com/  301
+/path /other-path 301
+```
+
+### SPA (single-page application) rewrite
+
+Redirects all paths to `/index.html` for single-page apps.
+
+```
+/*  /index.html 200
+```
+
+### Splats
+
+Redirects every path under `/articles` to `/posts` while keeping the path.
+
+```
+/articles/*  /posts/:splat  302
+```
+
+Example: `/articles/2022/10/12/post-1/` -> `/posts/2022/10/12/post-1/`

content/codeberg-pages/troubleshooting.md

@@ -1,10 +1,21 @@
 ---
 eleventyNavigation:
-  key: CodebergPagesTroubleshooting
+  key: Troubleshooting
   title: Troubleshooting
   parent: CodebergPages
   order: 99
 ---
 
 ## My web browser displays a security warning when I try to access my Codeberg Pages.
-If your user name contains a dot (e.g. `user.name`) your Codeberg Pages URL (https://user.name.codeberg.page) contains a sub-sub-domain which does not work with Let's Encrypt wildcard certificates. Use the alternative URL https://pages.codeberg.org/user.name/ as a workaround.
+
+If your user name or repository name contains a dot, your Codeberg Pages URL (https://user.name.codeberg.page or https://repo.sitory.username.codeberg.page) contains a sub-sub-domain which does not work with Let's Encrypt wildcard certificates. Use the alternative URL https://pages.codeberg.org/user.name/ as a workaround or rename you repository (e.g. replace `.` by `_`).
+
+## My content is not updated
+
+The Codeberg Pages server caches files under a certain size (currently 1 MiB).
+Please wait a few minutes until the cache has been invalidated.
+This is done to improve performance, reduce cost and server load, and save energy.
+
+## Cloudflare and Codeberg Pages
+
+It is important that when you use [Cloudflare](https://cloudflare.com) to manage your Domain's DNS records, 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.

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

@@ -0,0 +1,281 @@
+---
+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 a domain registrar of your choice and configure it to serve content from Codeberg Pages.
+
+{% admonition "warning" "Known pitfalls for failed certificate errors" %}
+
+- If you have a [CAA record](https://en.wikipedia.org/wiki/DNS_Certification_Authority_Authorization#Record) configured, you must [explicitly allow Let's Encrypt in your CAA record](https://letsencrypt.org/docs/caa/).
+
+{% endadmonition %}
+
+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 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 />
+
+{% admonition "question" "Why do I need all of these DNS records?" %}
+
+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 serve 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.
+
+{% endadmonition %}
+
+## Setting the DNS record
+
+There are several ways 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. Depending 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._
+
+{% admonition "Warning" %}
+
+When setting up DNS records with many registrars, any domain added to the `Domain` or `Host` option is automatically appended onto the domain the records are being made for.
+
+For example, if your domain is `example.com`, entering `www` will mean the record refers to `www.example.com`.
+
+Therefore, in this guide, you may need to replace references to just your domain name (e.g. `example.com`) with `@` and `anything.example.com` (i.e. any subdomain) with just `anything`.
+
+{% endadmonition %}
+
+**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 />
+
+{% admonition "Warning" %}
+
+With a CNAME record everything on this domain is delegated to `codeberg.page`, which means you cannot setup your own email address with this method.
+
+If you need email or others services, you have to use one of the remaining options.
+
+{% endadmonition %}
+
+**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 Pages 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`.
+
+{% admonition "info" "Note" %}
+
+This would be incompatible with using the apex `example.com` for other purposes, e.g. for the _Personal_/_Organization_ example discussed before.
+
+{% endadmonition %}
+
+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`