dallasgroot/Documentation
1
0
Fork 0
mirror of https://codeberg.org/Codeberg/Documentation.git synced 2026-08-15 14:53:29 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'main' into Iridium13-main

Browse source
This commit is contained in:
Robert Wolff 2026-07-17 12:11:53 +02:00
commit cc83330bc5
No known key found for this signature in database
GPG key ID: 1614C70AD69A61A1
52 changed files with 1078 additions and 1290 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
.cspell.json
View file

@ -112,6 +112,7 @@
"mstruebing",
"davidanson",
"pipelinecomponents",
"passwordless",
"corepack",
"letsencrypt.org",
"accounturi",
@ -119,7 +120,12 @@
"getent",
"sealioning",
"DNSSEC",
"Arminiusstraße"
"Arminiusstraße",
"HELLOTUX",
"Merch",
"merch",
"freewear",
"gedankenstuecke"
],
"ignorePaths": [
"**/node_modules/**/*",

1
.woodpecker/build.yaml
View file

@ -1,5 +1,4 @@
when:
- event: [pull_request]
- event: push
branch:
- ${CI_REPO_DEFAULT_BRANCH}

27
.woodpecker/delete-preview.yaml Normal file
View file

@ -0,0 +1,27 @@
when:
- event: pull_request_closed
steps:
create-empty-dir:
image: alpine
commands:
- mkdir _empty
delete-preview:
image: codeberg.org/gedankenstuecke/git-pages-woodpecker-plugin@sha256:5257561a95054104f7499838817f3b447049a1edc14e87b99156b1302e0bce36
settings:
SITE_URL: https://codeberg.codeberg.page/documentation
PATH: pull_${CI_COMMIT_PULL_REQUEST}
TOKEN:
from_secret: surge_forge_token
UPLOAD_DIR: _empty
depends_on: create-empty-dir
comment:
image: mcs94/gitea-comment@sha256:f1a06366bfa34ff7594f369ebf81cbadd2d4410b7d51c9aa59c0c0264aa5fbd9
settings:
gitea_address: https://codeberg.org
gitea_token:
from_secret: surge_forge_token
comment: 'Preview deleted.'
depends_on: delete-preview

40
.woodpecker/deploy-preview.yaml
View file

@ -1,29 +1,37 @@
when:
- event: [pull_request, pull_request_closed]
- event: pull_request
steps:
change-path:
image: alpine
commands:
- |
sed -i.orig -e "s~pathPrefix: '/'~pathPrefix: '/documentation/pull_${CI_COMMIT_PULL_REQUEST}/'~" eleventy.config.mjs
build:
image: codeberg.org/woodpecker-plugins/node-pm
image: codeberg.org/woodpecker-plugins/node-pm@sha256:bff3ee2d7492e89a0dfbe6ee4c7d5ce636108cd973c0c355269f681e8dd8a196
settings:
run: build
with: pnpm
frozen_lockfile: true
ignore_node_modules: true
depends_on: change-path
deploy-preview:
image: docker.io/woodpeckerci/plugin-surge-preview:1.4.2
image: codeberg.org/gedankenstuecke/git-pages-woodpecker-plugin@sha256:5257561a95054104f7499838817f3b447049a1edc14e87b99156b1302e0bce36
settings:
path: '_site/'
forge_type: gitea
forge_url: https://codeberg.org
surge_token:
from_secret: surge_token
forge_repo_token:
SITE_URL: https://codeberg.codeberg.page/documentation
PATH: pull_${CI_COMMIT_PULL_REQUEST}
TOKEN:
from_secret: surge_forge_token
failure: ignore
when:
event: [pull_request, pull_request_closed]
path:
- content/**
- assets/**
- .eleventy.js
UPLOAD_DIR: _site
depends_on: build
comment:
image: mcs94/gitea-comment@sha256:f1a06366bfa34ff7594f369ebf81cbadd2d4410b7d51c9aa59c0c0264aa5fbd9
settings:
gitea_address: https://codeberg.org
gitea_token:
from_secret: surge_forge_token
comment: 'Preview ready: https://codeberg.codeberg.page/documentation/pull_${CI_COMMIT_PULL_REQUEST}'
depends_on: deploy-preview

6
.woodpecker/lint.yaml
View file

@ -14,7 +14,7 @@ steps:
include: ['.woodpecker/*.yaml', '*.{md,markdown}']
editor-config:
image: mstruebing/editorconfig-checker:v3.6.0
image: mstruebing/editorconfig-checker:v3.6.1
depends_on: []
prettier:
@ -22,7 +22,7 @@ steps:
depends_on: []
settings:
# renovate: datasource=npm depName=prettier
version: 3.8.1
version: 3.9.4
links:
image: lycheeverse/lychee:0.22.0
@ -31,7 +31,7 @@ steps:
- lychee -v -t 40 --root-dir $(pwd)/content --fallback-extensions md .
lint-yaml:
image: pipelinecomponents/yamllint:0.35.9
image: pipelinecomponents/yamllint:0.35.13
depends_on: []
commands:
- yamllint --strict .

4
Dockerfile
View file

@ -1,6 +1,6 @@
# The main purpose of this Dockerfile is to install the `pnpm` package manager in the official Node.js image
# and use an init script as the entrypoint of a custom image to build and run the documentation site.
FROM node:lts-slim@sha256:bf22df20270b654c4e9da59d8d4a3516cce6ba2852e159b27288d645b7a7eedc
FROM node:lts-slim@sha256:e8e2e91b1378f83c5b2dd15f0247f34110e2fe895f6ca7719dbb780f929368eb
EXPOSE 8080/tcp
SHELL [ "bash", "-c" ]
@ -9,7 +9,7 @@ ENTRYPOINT [ "./container-init.sh" ]
ENV CI="true"
# renovate: datasource=npm depName=pnpm
ENV PNPM_VERSION="10.28.2"
ENV PNPM_VERSION="11.5.3"
RUN apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get --assume-yes upgrade \

19
assets/css/codeberg-docs.css
View file

@ -20,6 +20,19 @@
--admonition-icon-dimension: 20px;
--pagefind-ui-text: var(--bs-link-color) !important;
--color-nav-bg: #2185d0;
}
.sidebar,
.navbar-brand {
--bs-sidebar-brand-color: var(--bs-white);
--bs-navbar-brand-color: var(--bs-white);
}
.btn-close {
filter: var(--bs-btn-close-white-filter);
--bs-btn-close-opacity: 1;
}
.content :not(img, pre) {
@ -218,6 +231,7 @@ a.show-on-focus:focus {
.docs-navbar {
min-height: 55px;
border-bottom: var(--bs-border-width) solid var(--bs-content-border-color);
background-color: var(--color-nav-bg);
}
.filter-docs {
@ -238,11 +252,6 @@ a.show-on-focus:focus {
color: hsla(var(--bs-emphasis-color-hsl), 0.9);
}
[data-bs-theme='light'] .sidebar-brand img,
[data-bs-theme='light'] .navbar-brand img {
content: url(https://design.codeberg.org/logo-kit/icon.svg);
}
.alert-heading {
margin-bottom: 0.5rem;
}

3
content/_includes/default_layout.njk
View file

@ -20,7 +20,8 @@
<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" />
<link rel="stylesheet" type="text/css" href="/halfmoon.css">
<link rel="stylesheet" type="text/css" href="/assets/css/halfmoon/halfmoon.min.css">
<link rel="stylesheet" type="text/css" href="/assets/css/halfmoon/cores/halfmoon.modern.css">
<link rel="stylesheet" type="text/css" href="/assets/css/codeberg-docs.css" />
<!-- Syntax highlighting -->

21
content/advanced/index.md
View file

@ -12,23 +12,4 @@ the more advanced features of Codeberg.
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></td>
</tr>
{%- endfor %}
</tbody>
</table>
{% endif %}
{% endif %}
{%- endfor %}
{% sectionNav collections %}

2
content/ci/actions.md
View file

@ -49,7 +49,7 @@ determine where your Runner will accept workflows from.
## Installing Forgejo Runner
For the installation of the runner, see the [Forgejo documentation](https://forgejo.org/docs/next/admin/actions/runner-installation/).
For the installation of the runner, see the [Forgejo documentation](https://forgejo.org/docs/latest/admin/actions/runner-installation/).
## References

4
content/ci/agents.md
View file

@ -70,14 +70,14 @@ Tokens are added as the `WOODPECKER_AGENT_SECRET` environment variable to avoid
```yaml
services:
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:v3
image: woodpeckerci/woodpecker-agent:v3.13.0
command: agent
restart: always
volumes:
- woodpecker-agent-config:/etc/woodpecker
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WOODPECKER_SERVER=grpc.ci.codeberg.org
- WOODPECKER_SERVER=grpc.ci.codeberg.org:443
- WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
- WOODPECKER_GRPC_SECURE=true

1
content/codeberg-pages/advanced-usage.md
View file

@ -5,6 +5,7 @@ eleventyNavigation:
parent: CodebergPages
order: 999
---
## Custom error page for 404s
You can replace the default 404 error page that Codeberg Pages will show for missing pages with your own version if you prefer.

52
content/codeberg-pages/forgejo-actions.md
View file

@ -5,38 +5,63 @@ eleventyNavigation:
parent: CodebergPages
order: 100
---
{% admonition "Warning" %}
The following instructions depend on the new git-pages server for Codeberg Pages and can currently only be used on sites which are hosted under our `codeberg.page` domain, and not with sites that should be served from custom domains.
Follow the [old instructions for legacy v2 sites](/codeberg-pages/) if you would like to deploy to a custom domain.
{% endadmonition %}
Git-pages has an [associated Forgejo Action](https://codeberg.org/git-pages/action) that can be used to automatically deploy your website from a static site generation tool.
You can use any such tool you like: git-pages does not privilege any particular publishing system over others.
If you already use a static site generator and/or already use Forgejo Actions, using the pre-made Forgejo Action is by far the simplest and most efficient way to publish your site to Codeberg Pages.
To use it, simply add it as a final step to your workflow:
**If you use a `*.codeberg.page` subdomain,**
add the following step at the end of your workflow after replacing `repository-name` in the `site` parameter with the name of your repository:
{% raw %}
```yaml
- uses: https://codeberg.org/git-pages/action@v2
with:
site: "https://${{ forge.repository_owner }}.codeberg.page/repository-name/"
site: https://${{ forge.repository_owner }}.codeberg.page/repository-name/
token: ${{ forge.token }}
source: _site/
```
{% endraw %}
Replace `repository-name` in the `site` parameter with the name of your repository.
If your repository is also called `pages`, you can also omit the repository name and deploy directly to the site `https://username.codeberg.page/`.
To publish a site to the root of your subdomain, `https://username.codeberg.page/`, ensure your repository is called `pages`, and add the following step instead:
{% raw %}
```yaml
- uses: https://codeberg.org/git-pages/action@v2
with:
site: https://${{ forge.repository_owner }}.codeberg.page/
token: ${{ forge.token }}
source: _site/
```
{% endraw %}
**If you use a custom domain,**
add the following step at the end of your workflow after replacing `yourdomain.com` with your custom domain:
{% raw %}
```yaml
- uses: https://codeberg.org/git-pages/action@v2
with:
site: https://yourdomain.com/
server: codeberg.page
token: ${{ forge.token }}
source: _site/
```
{% endraw %}
The `server` parameter directs the Action to upload your site to a specific git-pages server instead of resolving the A/AAAA records DNS records specified in the `site` parameter. It may be specified as `codeberg.page` anytime a site is published to Codeberg Pages, but is **required** for publishing a site on a custom domain for the first time.
This is caused by a circular dependency: git-pages will not issue a TLS certificate unless a site exists on that domain, but contacting it over HTTPS is not possible unless a TLS certificate is obtained. When the `site` parameter is specified, the HTTPS connection is established with the specified server (`codeberg.page` in this case), and the custom domain is passed in the `Host:` header instead, breaking this loop.
The `source` parameter should point to the directory (relative to the root, after all previous steps in your workflow) where your site generator has put the generated version of your site.
This directory can also contain the `404.html` and `_redirects` files to customize your site’s behaviour, as described in the [advanced documentation](/codeberg-pages/advanced-usage/).
This directory can also contain the `404.html` and `_redirects` files to customize your site’s behavior, as described in the [advanced documentation](/codeberg-pages/advanced-usage/).
The `token` will automatically be filled by Forgejo Actions with a secret token, which in turn will automatically be recognized by git-pages as authorizing this workflow to publish to this site.
@ -44,7 +69,7 @@ The `token` will automatically be filled by Forgejo Actions with a secret token,
If you use branches to test out new features, write draft blog posts, etc., you should either limit the whole workflow, or this step only, to pushes to a default branch (usually `main` or `master`) to ensure that only finalized content is published to your site.
To do this, either add a [`on.push.branches` list](https://forgejo.org/docs/next/user/actions/reference/#onpush) to the whole workflow, or add [an `if` condition to the step](https://forgejo.org/docs/next/user/actions/reference/#jobsjob_idstepsif-1) (or [to the whole job](https://forgejo.org/docs/next/user/actions/reference/#jobsjob_idif)) like this:
To do this, either add a [`on.push.branches` list](https://forgejo.org/docs/latest/user/actions/reference/#onpush) to the whole workflow, or add [an `if` condition to the step](https://forgejo.org/docs/latest/user/actions/reference/#jobsjob_idstepsif-1) (or [to the whole job](https://forgejo.org/docs/latest/user/actions/reference/#jobsjob_idif)) like this:
{% raw %}
@ -57,4 +82,3 @@ if: ${{ forge.ref == 'refs/heads/main'}}
This will limit deploys so they only happen when CI is triggered by a push to the `main` branch.
{% endadmonition %}

52
content/codeberg-pages/index.md
View file

@ -8,21 +8,19 @@ eleventyNavigation:
{% admonition "Warning" %}
Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase.
Codeberg Pages has recently migrated from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase.
Currently, websites that use custom domains can only be deployed using the old method, but we are working to fix this.
Such websites will keep working indefinitely.
You will be able to seamlessly migrate to the new version of Pages once it is supported.
Take note of some minor [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations).
Websites hosted under the `codeberg.page` domain can already use the new git-pages method.
If you have not yet [migrated your own site to the new server,](/codeberg-pages/migrating-from-pages-v2/) we encourage you to do so.
Pages Server v2 has already been disabled for new users due to abuse, however it is still working for users and organizations that already existed prior to the service being discontinued. We apologize for any inconvenience this has caused.
The new documentation is work in progress, and we appreciate your feedback. Please let us know in case you find yourself confused.
{% endadmonition %}
Codeberg Pages allows you to easily publish static websites with a human-friendly address (`{username}.codeberg.page`) or your custom domain on Codeberg.
You can publish an website for your user or organization, as well as websites for each repository.
You can publish a website for your user or organization, as well as websites for each repository.
Codeberg Pages are served using a deployment of [git-pages](https://git-pages.org/), which itself is [developed on Codeberg](https://codeberg.org/git-pages/git-pages).
It is free/libre open source software.
@ -34,26 +32,7 @@ See also:
- [codeberg.page](https://codeberg.page)
- [Troubleshooting (Codeberg Documentation)](troubleshooting)
{% 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></td>
</tr>
{%- endfor %}
</tbody>
</table>
{% endif %}
{% endif %}
{%- endfor %}
{% sectionNav collections %}
## Getting started with a `codeberg.page` URL
@ -68,7 +47,7 @@ This page documents the first method. See the [separate page on using Forgejo Ac
1. Create a repository called `pages` under your own username or under the organization you want to create a website for
The website will be published from a branch also called `pages`. You can also set this as the default branch, if you prefer.
The website will be published from a branch also called `pages`. You can also set this as the default branch, if you prefer.
2. Go to **Settings** at the top right of your repository page.
@ -76,7 +55,7 @@ This page documents the first method. See the [separate page on using Forgejo Ac
4. Click the **Add webhook** button in the top right corner of the webhook settings page.
Select **Forgejo** from the drop-down list of webhook types.
Select **Forgejo** from the drop-down list of webhook types.
5. Enter `https://username.codeberg.page/` as the **Target URL**, replacing the `username` with your Codeberg username or organization name. This is the URL your website will be available from.
@ -94,7 +73,7 @@ This page documents the first method. See the [separate page on using Forgejo Ac
3. Click the **Add webhook** button in the top right corner of the webhook settings page.
Select **Forgejo** from the drop-down list of webhook types.
Select **Forgejo** from the drop-down list of webhook types.
4. Enter `https://username.codeberg.page/repository-name/` as the **Target URL**, replacing the `username` with your Codeberg username or organization name, and `repository-name` with the name of your repository. This is the URL your website will be available from.
@ -106,20 +85,7 @@ This page documents the first method. See the [separate page on using Forgejo Ac
## Getting started with a custom domain
{% admonition "warning" %}
You can only use the ‘legacy’ v2 Pages deployment method at the moment if you want to serve your site with a custom domain.
Websites deployed this way will keep working indefinitely.
You will be able to seamlessly migrate to the new version of Pages once it is supported.
{% endadmonition %}
There are two steps to getting started with a custom domain: configuration on Codeberg’s side, and configuration on the side of your DNS.
To set up your website for publication on a custom domain on the Codeberg side, simply upload your content to a branch of a repository called `pages`. You then also need to create a plain text file called `.domains` listing the domains your website should be available at.
You then need to set up DNS records to point to Codeberg. Instructions on how to do this are available on the [documentation page about using custom domains](/codeberg-pages/using-custom-domain/).
You can now deploy custom domains using git-pages! Please see the [documentation page about using custom domains](/codeberg-pages/using-custom-domain/) for details.
## Having problems?

24
content/codeberg-pages/migrating-from-pages-v2.md
View file

@ -5,21 +5,23 @@ eleventyNavigation:
parent: CodebergPages
order: 120
---
{% admonition "Warning" %}
Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase.
Currently, websites that use custom domains can only be deployed using the old method, but we are working to fix this.
Such websites will keep working indefinitely.
You will be able to seamlessly migrate to the new version of Pages once it is supported.
Take note of some minor [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations).
Websites hosted under the `codeberg.page` domain can already use the new git-pages method.
The new documentation is work in progress, and we appreciate your feedback. Please let us know in case you find yourself confused.
{% endadmonition %}
{% admonition "info" "Notice" %}
Custom domains are now supported by the new git-pages server! Please refer to [the updated custom domain setup guide](/codeberg-pages/using-custom-domain/) for details on how to properly replace your old DNS records before proceeding.
{% endadmonition %}
Since December 2025, Codeberg offers a new Pages service based on [git-pages](https://codeberg.org/git-pages/git-pages).
It improves performance and stability, and fixes various design issues from the current [Pages Server v2](https://codeberg.org/Codeberg/pages-server). Unfortunately, these fixed design issues require some migration and deprecation of features.
@ -27,10 +29,10 @@ It improves performance and stability, and fixes various design issues from the
Please be aware of the following changes and deprecated features.
* The recommended way to deploy websites is by directly uploading them to git-pages.
* Content is no longer fetched automatically. You need to use a method that informs git-pages about changes.
* `raw.codeberg.page` is no longer available. CORS headers are now directly set on your page and this workaround is no longer necessary.
* Direct access to repos and branches is no longer possible. You can no longer use the `/repository/@branch` access. `git-pages` restricts you to the website you explicitly deployed. Serving arbitrary resources from Codeberg was a common abuse vector and is going to be deprecated.
- The recommended way to deploy websites is by directly uploading them to git-pages.
- Content is no longer fetched automatically. You need to use a method that informs git-pages about changes.
- `raw.codeberg.page` is no longer available. CORS headers are now directly set on your page and this workaround is no longer necessary.
- Direct access to repos and branches is no longer possible. You can no longer use the `/repository/@branch` access. `git-pages` restricts you to the website you explicitly deployed. Serving arbitrary resources from Codeberg was a common abuse vector and is going to be deprecated.
## The first push
@ -66,11 +68,11 @@ To do this:
3. Click the **Add webhook** button in the top right corner of the webhook settings page.
Select **Forgejo** from the drop-down list of webhook types.
Select **Forgejo** from the drop-down list of webhook types.
4. Enter `https://username.codeberg.page/repository-name/` as the **Target URL**, replacing the `username` with your Codeberg username or organization name, and `repository-name` with the name of your repository. This is the URL your website will be available from.
If your repository *and* your branch are both called `pages`, you can omit the `repository-name` and just push to `https://username.codeberg.page/` directly.
If your repository _and_ your branch are both called `pages`, you can omit the `repository-name` and just push to `https://username.codeberg.page/` directly.
5. Set the **Branch filter** to `pages`.

127
content/codeberg-pages/pushing-output.md
View file

@ -1,127 +0,0 @@
---
eleventyNavigation:
key: PushingOutput
title: Pushing output from SSGs into Codeberg Pages
parent: CodebergPages
author: Fayçal Alami Hassani - https://codeberg.org/ka2in
order: 110
---
{% admonition "Warning" %}
Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase.
Currently, websites that use custom domains can only be deployed using the old method, but we are working to fix this.
Such websites will keep working indefinitely.
You will be able to seamlessly migrate to the new version of Pages once it is supported.
Take note of some minor [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations).
Websites hosted under the `codeberg.page` domain can already use the new git-pages method.
**This page documents the method used for legacy v2 Pages sites.**
You should be able to adapt the directions for git-pages (assuming you are not using a custom domain) using, for example, the [instructions on using Forgejo Actions with git-pages](/codeberg-pages/forgejo-actions/).
The new documentation is work in progress.
We hope to update this page with information on how to use the new server directly with static side generators soon.
In the meanwhile, we appreciate your feedback.
Please let us know in case you find yourself confused.
{% endadmonition %}
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.
## Manual pushing
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:
```bash
├── 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.
## Using a CI
Both the [Woodpecker CI](/ci/#using-codeberg's-instance-of-woodpecker-ci) and the [hosted Forgejo Actions](/ci/actions/)
can be used to automate the build and deployment of your static website.
For the Woodpecker CI, you can see the [existing example workflows in the `Codeberg-CI/examples` repo](https://codeberg.org/Codeberg-CI/examples),
which provides examples for Jekyll, Hugo, Zola and many other popular SSG.
Currently, we do not have any examples for the Forgejo Actions yet, but individual SSG tools might
have details in their own documentation.
Note that if you use Forgejo Actions to publish the website, you should make sure that `.domains`
file will be preserved in the root directory of the **output** branch or repository.

384
content/codeberg-pages/using-custom-domain.md
View file

@ -5,16 +5,15 @@ eleventyNavigation:
parent: CodebergPages
order: 10
---
{% admonition "Warning" %}
Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase.
Codeberg Pages has recently migrated from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase.
Currently, websites that use custom domains can only be deployed using the old method, but we are working to fix this.
Such websites will keep working indefinitely.
You will be able to seamlessly migrate to the new version of Pages once it is supported.
Take note of some minor [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations).
Websites hosted under the `codeberg.page` domain can already use the new git-pages method.
If you have not yet [migrated your own site to the new server,](/codeberg-pages/migrating-from-pages-v2/) we encourage you to do so.
Pages Server v2 has already been disabled for new users due to abuse, however it is still working for users and organizations that already existed prior to the service being discontinued. We apologize for any inconvenience this has caused.
The new documentation is work in progress, and we appreciate your feedback. Please let us know in case you find yourself confused.
@ -26,108 +25,34 @@ 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/).
The value of the CAA record would look like `letsencrypt.org;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/292520050;validationmethods=tls-alpn-01,http-01`.
you must [explicitly allow Let's Encrypt (staging) in your CAA record](https://letsencrypt.org/docs/caa/).
This means you need to add two extra CAA records.
The first record has a value of `letsencrypt.org;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/292520050;validationmethods=tls-alpn-01,http-01`.
The second record has a value of `letsencrypt.org;accounturi=https://acme-staging-v02.api.letsencrypt.org/acme/acct/272029763;validationmethods=tls-alpn-01,http-01`.
{% endadmonition %}
For custom domains, two things are required:
{% admonition "info" "Notice" %}
- 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 external 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.
Throughout this document, the domain `example.org` is used as a placeholder for your own domain. Please ensure you replace any literal instances of `example.org` with the domain that you've purchased to ensure the proper setup procedure.
- 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.
We provide context-appropriate examples for both the apex domain, and the `www` subdomain commonly used for websites. If you wish to use a different subdomain, replace the `www` in the following examples with the hostname of your desired subdomain. If you wish to use the apex domain (that is, the bare domain without any `www.` in front), we recommend additionally setting up a redirect on the `www` subdomain (or vice versa) to ensure compatibility with all browsers and devices.
{% 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>
{% admonition "warning" "Repository names with dots are not supported" %}
Repository names containing dots (`.`) are **not supported** for custom domains.
The Pages server uses dots as delimiters to parse the repository name, branch, and owner from DNS records.
For example, if your repository is named `my.project`, the TXT record `my.project.username.codeberg.page`
will be incorrectly parsed as:
- Branch: `my`
- Repository: `project`
- Owner: `username`
**Solution:** If you need to use a custom domain, rename your repository to use hyphens (`-`) or
underscores (`_`) instead of dots. For example, rename `my.project` to `my-project`.
{% endadmonition %}
_We assume for the following description, that you want to serve your website with and without www in front.
If you are on a subdomain already (like myproject.yourdomain.com), you can skip the `www.yourdomain.com` CNAME entry._
{% admonition "Warning" %}
When setting up DNS records with many registrars, any domain added to the `Domain` or `Host` option is automatically
When setting up DNS records with many providers, 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`.
For example, if your domain is `example.org`, entering `www` will mean the record refers to `www.example.org`.
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`.
Therefore, in this guide, you may need to replace references to just your domain name (e.g. `example.org`) with `@` and
`anything.example.org` (i.e. any subdomain) with just `anything`, depending on your DNS provider.
{% endadmonition %}
### Option 1: CNAME record
### Step 1: CNAME, ALIAS, or A/AAAA 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:
@ -140,41 +65,29 @@ In the end, it should look like this:
</thead>
<tbody>
<tr>
<td>yourdomain.com</td>
<td>www.example.org</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>
<td>codeberg.page.</td>
</tr>
</tbody>
</table>
<br />
{% admonition "info" "Notice" %}
{% 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.
DNSSEC has now been enabled for `codeberg.page`, try using a CNAME record if your zone is signed! You can verify that your DNSSEC setup works properly using [this tool](https://dnssec-analyzer.verisignlabs.com).
{% endadmonition %}
### Option 2: ALIAS record
{% admonition "Warning" %}
If you cannot use a CNAME record to configure the target you can use this method, which needs two entries instead of one.
With a CNAME record, everything on this subdomain is delegated to `codeberg.page`, which means you cannot setup other types of DNS records for other services on the same subdomain.
- 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`.
If you need to setup other records for other services, such as MX records for email, on the same subdomain, you must use one of the remaining options.
In the end it should look like this:
{% endadmonition %}
If the domain you wish to use is the apex of the zone or has other existing DNS records, you will not be able to use a CNAME record.
In this case, some DNS providers support an ALIAS record, which will work instead. Some DNS providers (such as Cloudflare) only allow setting "flattened" CNAME records at the apex, which works the same way as an ALIAS record.
<table class="table">
<thead>
@ -184,29 +97,31 @@ In the end it should look like this:
</thead>
<tbody>
<tr>
<td>yourdomain.com</td><td>ALIAS</td><td>codeberg.page</td>
<td>example.org</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>reponame.username.codeberg.page</td>
<td>www.example.org</td>
<td>ALIAS</td>
<td>codeberg.page</td>
</tr>
</tbody>
</table>
### Option 3: A/AAAA record
{% admonition "Warning" %}
If your service provider does not support `ALIAS records` you can also use `A records` and `AAAA records` instead.
This type of record is not supported in conjunction with DNSSEC signed zones, which may cause unexpected behavior with your domain if your domain's zone is signed and a client is using a DNSSEC validating resolver.
- 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.84.141`
- `AAAA record` which contains the IPv6 value `2a0a:4580:103f:c0de::2`
- Second, you need to setup a `TXT record` which contains the information of your repository
location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
If you have DNSSEC enabled, you should use A/AAAA records for now. You can verify that your DNSSEC setup works properly using [this tool](https://dnssec-analyzer.verisignlabs.com).
In the end, it should look like this:
{% endadmonition %}
If you cannot use a CNAME nor an ALIAS record,
you will need to set up the A and AAAA records to point to Codeberg’s IP addresses directly.
It is possible these IP addresses will change in future,
so keep an eye on Codeberg updates to check.
<table class="table">
<thead>
@ -216,147 +131,110 @@ In the end, it should look like this:
</thead>
<tbody>
<tr>
<td>yourdomain.com</td>
<td>example.org</td>
<td>A</td>
<td>217.197.84.141</td>
</tr>
<tr>
<td>yourdomain.com</td>
<td>example.org</td>
<td>AAAA</td>
<td>2a0a:4580:103f:c0de::2</td>
</tr>
<tr>
<td>yourdomain.com</td>
<td>TXT</td>
<td>reponame.username.codeberg.page</td>
</tr>
</tbody>
</table>
## Examples
### Step 2: Configure git-pages authorization
The following sub-sections include a few examples of the different alternatives, assuming the following:
{% admonition "question" "Why do I need all these extra DNS records?" %}
- 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`).
When someone tries to deploy a website to your domain,
Codeberg Pages needs to know which repository is responsible for the content,
and that the content actually comes from that repository.
All considerations regarding a _Personal_ site also apply to an _Organization_ site, so these two cases will be
addressed together.
### Personal (or Organization) site, subdomain
In this case, we want our _Personal_ pages available at the URL `https://myself.example.com`.
The `.domains` file contains the following:
```text
myself.example.com
```
For the DNS configuration:
- if the domain is not the apex of the zone and does not have other services such as email,
you should always use a CNAME record:
- 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.84.141`
- name `myself.example.com`, type `AAAA`, data `2a0a:4580:103f:c0de::2`
- 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`.
We also want the URL `https://www.example.com` to redirect to the apex domain.
The `.domains` file contains the following:
```text
example.com
www.example.com
```
_You may also put the `www` subdomain on the first line if you wish to use it as the canonical URL_
_and redirect the apex domain instead._
For the DNS configuration, CNAME records CANNOT be used for the apex domain, so:
- if ALIAS can be used, three DNS records will be needed:
- name `example.com`, type `ALIAS`, data `codeberg.page`
- name `example.com`, type `TXT`, data `frida.codeberg.page`
- name `www.example.com`, type `CNAME`, data `frida.codeberg.page`
_Note that ALIAS records are not real DNS records and are typically incompatible with DNSSEC signed zones._
- otherwise, A/AAAA records must be used, together with a TXT record:
- name `example.com`, type `A`, data `217.197.84.141`
- name `example.com`, type `AAAA`, data `2a0a:4580:103f:c0de::2`
- name `example.com`, type `TXT`, data `frida.codeberg.page`
- name `www.example.com`, type `CNAME`, data `frida.codeberg.page`
### Project site, subdomain
In this case, we want our _Project_ pages available at the URL `https://colormix-app.example.com`.
The `.domains` file contains the following:
```text
colormix-app.example.com
```
For the DNS configuration:
- if the domain is not the apex of the zone and does not have other services such as email,
you should always use a CNAME record:
- 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.84.141`
- name `colormix-app.example.com`, type `AAAA`, data `2a0a:4580:103f:c0de::2`
- 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.
When the webhook or Forgejo Action are triggered,
the server receives a token letting it know that the repository’s policies allowed the deploy.
The DNS records in turn ensure that the domain owner authorizes that repository to be deployed to that domain.
{% endadmonition %}
The `.domains` file contains the following:
{% admonition "info" "Notice" %}
```text
example.com
www.example.com
Since the new git-pages server uses these DNS records as an authorization method, it is no longer necessary to have a `.domains` file in your repository. You may remove it if you are migrating your website from the old Pages Server v2.
If you were relying on the old server's multi-domain redirection implementation, it may still be used if you only deploy your site to one of your domains on git-pages. See [the last section of this document](/codeberg-pages/migrating-from-pages-v2/#deploying-to-versions-of-your-domain-both-with-and-without-www.) for detailed instructions on setting up similar redirects on git-pages.
{% endadmonition %}
**If you deploy from a webhook,**
set a TXT record on the `_git-pages-repository` subdomain of your domain with the HTTPS Git clone URL for your repository.
<table class="table">
<thead>
<th>Domain</th>
<th>Type</th>
<th>Data</th>
</thead>
<tbody>
<tr>
<td>_git-pages-repository.example.org</td>
<td>TXT</td>
<td>https://codeberg.org/username/repository.git</td>
</tr>
<tr>
<td>_git-pages-repository.www.example.org</td>
<td>TXT</td>
<td>https://codeberg.org/username/repository.git</td>
</tr>
</tbody>
</table>
**If you deploy from Forgejo Actions,**
set a TXT record on the `_git-pages-forge-allowlist` subdomain of your domain with the HTTPS Git clone URL for your repository.
<table class="table">
<thead>
<th>Domain</th>
<th>Type</th>
<th>Data</th>
</thead>
<tbody>
<tr>
<td>_git-pages-forge-allowlist.example.org</td>
<td>TXT</td>
<td>https://codeberg.org/username/repository.git</td>
</tr>
<tr>
<td>_git-pages-forge-allowlist.www.example.org</td>
<td>TXT</td>
<td>https://codeberg.org/username/repository.git</td>
</tr>
</tbody>
</table>
### Step 3: Set your webhook or Forgejo Actions deploy target
**If you deploy from a webhook,**
the webhook **Target URL** should be set to the domain you want to deploy your website to.
For technical reasons, the first deployment needs to go over HTTP and you need to specify the `http://` scheme.
After the first successful deployment you can change it to the `https://` scheme.
**If you deploy from Forgejo Actions,**
the `site` parameter to the git-pages action should be set to the URL of your custom domain, and the `server` parameter should be set to `codeberg.page`. The [Forgejo Actions guide](/codeberg-pages/forgejo-actions/) includes example workflows and more information.
### Deploying to versions of your domain both with and without `www.`
If you would like to serve your website at versions with and without a `www.` prefix,
you should choose one of them to be the ‘canonical’ URL,
add a [`_redirects` file](/codeberg-pages/advanced-usage/) to your site redirecting from one version to the other,
and deploy your website to both domains. (I.e. set up two separate webhooks, or use two separate deploy actions.)
For example, to redirect people from www.example.org to example.org,
use this `_redirects` file:
```
//www.example.org/* https://example.org/:splat 302!
```
_You may also put the `www` subdomain on the first line if you wish to use it as the canonical URL_
_and redirect the apex domain instead._
For the DNS configuration, CNAME records CANNOT be used for the apex domain, so:
- if ALIAS can be used, three DNS records will be needed:
- name `example.com`, type `ALIAS`, data `codeberg.page`
- name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`
- name `www.example.com`, type `CNAME`, data `colormix.frida.codeberg.page`
_Note that ALIAS records are not real DNS records and are typically incompatible with DNSSEC signed zones._
- otherwise, A/AAAA records must be used, together with one TXT record:
- name `example.com`, type `A`, data `217.197.84.141`
- name `example.com`, type `AAAA`, data `2a0a:4580:103f:c0de::2`
- name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`
- name `www.example.com`, type `CNAME`, data `colormix.frida.codeberg.page`
For the redirect to work,
you should be sure that the code (here `302!`) includes an `!` at the end.
Otherwise, the redirect will only work on pages which are otherwise not found.

21
content/codeberg-translate/index.md
View file

@ -9,23 +9,4 @@ description: These articles shows you how to use Codeberg Translate
These documentation pages contain information on how you can use [Codeberg Translate](https://translate.codeberg.org)
{% 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></td>
</tr>
{%- endfor %}
</tbody>
</table>
{% endif %}
{% endif %}
{%- endfor %}
{% sectionNav collections %}

24
content/collaborating/create-organization.md
View file

@ -70,8 +70,7 @@ You can also delete your organization, and access more advanced settings like or
<img src="/images/collaborating/create-organization/orga-settings.png" alt="orga-settings">
The `Name` of the organization is the name that will define the URLs of the organization and of all its repositories;
it is recommended to keep it short. This name will also appear on the member's profiles (see [People](#people)).
The `Name` of the organization is the name that will define the URLs of the organization and of all its repositories.
On the other hand, the `Full Name` is the name that will appear on the organization's home page.
In the `Labels` tab, you can create labels that will be used across all repositories of this organization.
@ -117,27 +116,6 @@ It is also possible to invite people by email.
This also works for email addresses not associated with any Codeberg account, in which case they
will be prompted to create an account first.
## People
On the `People` tab, you can get an overview of all the people who belong to your organization:
<img src="/images/collaborating/create-organization/people.png" alt="people">
Somewhat counter-intuitively, this is not where you can add members;
this is done in the `Teams` tab (see [Teams](#teams) above).
However, you can remove members from the `People` tab.
The visibility of the members can also be edited here; `Hidden` means that the members' memberships will not be shown on
their profiles, while `Visible` makes the avatar of the organization appear in the info card on their profile,
as shown in the screenshot below. Note that your membership will always be visible to you on your profile;
this visibility setting is for other users only.
<img src="/images/collaborating/create-organization/profile.png" alt="profile">
Shown here is also whether or not each member has activated two-factor authentication (2FA, see [Setting up Two-factor Authentication](/security/2fa)).
Finally, from here you can choose to leave the organization.
## Access rights
An overview of the repository permissions is given in the article [Repository Permissions](/collaborating/repo-permissions).

21
content/collaborating/index.md
View file

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

16
content/collaborating/pull-requests-and-git-flow.md
View file

@ -80,6 +80,22 @@ git pull
That's it. You can now push your changes, and create the pull request as usual by clicking on the "New Pull Request" button.
#### Via the web interface
Another way of keeping up-to-date is to sync your fork via the web interface.
If your branch is behind in commits from the repository and branch it is tracking, you will automatically be shown how far
behind it is and given the option to `sync`. This will bring your Codeberg fork up-to-date with the upstream project branch.
![Syncing a fork](/images/collaborating/pull-requests-and-git-flow/sync-button.png)
If you now need to pull those changes to your local repository you can do so as before but now from `origin` e.g.
```shell
git pull --rebase origin main
git pull
```
## A friendly note on owner rights, and force push permissions
Please keep in mind that project owners can do _everything_, including editing and rewriting the history using `force-push`.

8
content/collaborating/repo-permissions.md
View file

@ -17,11 +17,13 @@ You can assign teams different levels of permission for each unit (e.g. issues,
The visibility of your repositories will depend on the visibility of your profile, as well as whether you have marked a
repository as private. Let's break down what this means:
- If your profile's visibility is set to "Limited", _all_ of your non-private repositories will only be visible to logged
- If your profile's visibility is set to "**Limited**", _all_ of your non-private repositories will only be visible to logged
in users.
- If your profile's visibility is set to "Public", _all_ of your non-private repositories will be shown to everyone.
- If your profile's visibility is set to "**Public**", _all_ of your non-private repositories will be shown to everyone.
- If you do not want anyone (apart from [your fellow collaborators](https://docs.codeberg.org/collaborating/invite-collaborators/))
to see your repositories, mark your repository as "Private".
to see your repositories, mark your repository as "**Private**".
However, Codeberg's Moderation Team and infrastructure administrators can access private profiles and repositories as per the
[Privacy Policy](https://codeberg.org/Codeberg/org/src/branch/main/PrivacyPolicy.md#4-data-handling-by-association-bodies-third-parties).
The visibility of your profile can be changed in the [Privacy settings](https://codeberg.org/user/settings).
Be careful when you set your profile's visibility to "Limited"; Even if a repository is public, users that are

7
content/getting-started/first-repository.md
View file

@ -234,8 +234,8 @@ Codeberg does not provide an interface to add license files, `.gitignore` or `RE
so you should add at least the license and `README.md` yourself.
- To choose a license, read [Codeberg's guidance](https://docs.codeberg.org/getting-started/licensing/).
- If you already know which license you need, Codeberg has [copies](https://codeberg.org/Codeberg-Infrastructure/forgejo/src/branch/codeberg-9/options/license).
- [gitignores](https://codeberg.org/Codeberg-Infrastructure/forgejo/src/branch/codeberg-9/options/gitignore)
- If you already know which license you need, Codeberg has [copies](https://codeberg.org/Codeberg-Infrastructure/forgejo/src/options/license).
- [gitignores](https://codeberg.org/Codeberg-Infrastructure/forgejo/src/options/gitignore)
## Making a commit
@ -364,7 +364,8 @@ The `-u` option sets the upstream remote, which we want to be Codeberg.org, as c
The `main` argument sets the name of the branch onto which shall be pushed upstream.
For this example, it should be the same branch name that you specified when creating the repository.
When connecting via HTTPS, Git will ask you for your username and password, which you can enter interactively.
When connecting via HTTPS, Git will ask you for your username and password.
If you have enabled Two-Factor Authentication, use your generated [access token](/advanced/access-token/) as the password instead.
After refreshing the repository page, you should now see something similar to this:

21
content/getting-started/index.md
View file

@ -24,23 +24,4 @@ You can start with [finding out more about Codeberg](/getting-started/what-is-co
Welcome to Codeberg! 😊
{% assign navPages = collections.all | eleventyNavigation %}
{%- for entry in navPages %}
{% if entry.url == page.url %}
{%- if entry.children.length -%}
<table class="table">
<thead>
<th>Find out more in this section:</th>
</thead>
<tbody>
{%- for child in entry.children %}
<tr>
<td><a href="{{ child.url }}">{{ child.title }}</a></td>
</tr>
{%- endfor %}
</tbody>
</table>
{% endif %}
{% endif %}
{%- endfor %}
{% sectionNav collections %}

37
content/getting-started/licensing.md
View file

@ -10,21 +10,21 @@ Adding a license to a project is essential for making it reusable: In the absenc
copyright law would otherwise forbid others from (re-)using and distributing your work.
Moreover, a license can further specify other important properties, such as the temporary- or forever-openness of the code,
the rights granted to the users (such as the [four fundamental software freedoms](https://www.gnu.org/philosophy/free-sw.html#four-freedoms)),
or the permission of using patents encoded in a program.
or the permission to use patents encoded in a program.
## Copyright: The mechanism behind most software licenses
The international validity of most common licenses is guaranteed by copyright law, and in particular by the [Copyright Treaty](https://en.wikipedia.org/wiki/WIPO_Copyright_Treaty)
of the United Nations' (UN) World Intellectual Property Organization (WIPO) adopted in 1996.
This treaty sets a common denominator for all adhering countries, but individual countries can still extend domestically
the reach of copyright. The article 4 of the Copyright Treaty clarified once for all that computer programs are
the reach of copyright. Article 4 of the Copyright Treaty clarified once and for all that computer programs are
protected by copyright just as literary works.
Unfortunately, however, copyright law does not protect hardware objects.
[Copyright law is extremely powerful](https://www.gnu.org/philosophy/enforcing-gpl.en.html).
In fact, it grants the author of a work exclusive rights to use or distribute their work.
An author can grant permission of using his/her work under arbitrary conditions; just for illustration, an author could
invent for example a "coffee license" and impose that whoever uses his work has to offer the author a coffee.
An author can grant permission to use their work under arbitrary conditions. Just for illustration, an author could
invent for example a "coffee license" and impose that whoever uses their work has to offer the author a coffee.
Similarly, forever-open licenses grant users the right to use the work provided that they will redistribute any
derivative work using the same license again (copyleft).
@ -47,7 +47,7 @@ project to remain small (e.g. less than 300 lines)?
- Yes --> we recommend using the **LGPL-3.0-or-later** license
- Yes --> Do you want to be able to sue users of your code for [patent infringement](#patent-usage) implemented in the code?
- No --> We recommend using the **Apache-2.0** license
- Yes --> We recommend using the **MIT** license
- Yes --> We recommend using the **BSD 3-Clause Clear** license
## Correctly applying a license
@ -74,7 +74,8 @@ One of the major distinctions between licenses is between:
the code include contractual law, but that is rarely used for software licenses.
2. Licenses which permit to close the source, i.e. temporarily-open licenses.
These licenses are usually known as permissive licenses. The MIT license or the Apache license belong to this category.
These licenses are usually known as permissive licenses. The MIT license, the BSD license, or the Apache license belong to
this category.
The term "permissive" often causes confusion, because it sounds fair and good to unexperienced people.
People who contribute to the development of a program released with a permissive license must be aware that the
program could become proprietary at any time. For example, when a company hires the original team of developers.
@ -89,10 +90,10 @@ copyleft licenses whenever possible.
Free software licenses are licenses which respect the [four fundamental software freedoms](https://www.gnu.org/philosophy/free-sw.en.html#four-freedoms)
defined by the Free Software Foundation.
Both copyleft and permissive license can, or cannot, be free licenses. For example, the [Modified BSD license](https://www.gnu.org/licenses/license-list.en.html#ModifiedBSD)
Both copyleft and permissive license may, or may not, be free licenses. For example, the [Modified BSD license](https://www.gnu.org/licenses/license-list.en.html#ModifiedBSD)
is a permissive non-copyleft free software license.
In the context of licenses, the term "free" means free as in "freedom", not of gratis, but this has often been confused.
In the context of licenses, the term "free" means free as in "freedom", not as in gratis, but this has often been confused.
Still, free software is often also gratis software.
Gratis non-free software usually includes gratis proprietary programs (shareware), demonstration or trial versions,
limited versions (crippleware), advertising-supported software (e.g. antivirus), and usually viruses and worms
@ -100,19 +101,13 @@ limited versions (crippleware), advertising-supported software (e.g. antivirus),
### Patent usage
Some permissive/temporarily-open licenses like the MIT license do not contain a patent provision granting the users the
right to use their patents.
For example, the code might be licensed under the MIT license, but implements an algorithm which is protected by a patent.
In this case, the license might allow to copy, modify and distribute the code but at the same time does not guarantee
the right to use the patented algorithm.
It is a common argument in favour of the MIT license to claim that no public lawsuit has ever been conducted yet.
Still, the threat to be sued remains, and it can be used to exert pressure. Some, if not most, license disputes moreover
are settled even [before reaching the court](https://www.gnu.org/philosophy/enforcing-gpl.en.html) and could therefore
leave no trace.
Even Google [avoided the use of the MIT license when developing Android](https://source.android.com/setup/start/licenses),
presumably because of the missing patent provision.
Some permissive/temporarily-open licenses like the Apache-2.0 license contain a patent provision explicitly granting the
users the right to use their patents. Some, like the BSD 3-Clause Clear license explicitly do not grant the right to use
their patents. And some, like the MIT license, do not mention patents, making it arguable that they [implicitly grant](https://opensource.com/article/18/3/patent-grant-mit-license)
patent rights, or that they [do not](https://web.archive.org/web/20190312190935/http://stlr.org/2018/10/15/the-truth-about-oss-frand-by-all-indications-compatible-models-in-standards-settings/).
We recommend that you use a license with a clear statement so your users know your specific intent.
For further information on "patents and free software", head over to [this wikipedia article](https://en.wikipedia.org/wiki/Software_patents_and_free_software).
For further information on "patents and free software", head over to [this Wikipedia article](https://en.wikipedia.org/wiki/Software_patents_and_free_software).
## Warnings
@ -141,7 +136,7 @@ The incompatibility between licenses is clearly a headache for every developer.
recommend, is to use only mainstream licenses (as recommended in this page) and hence avoid [license proliferation](#license-proliferation).
For more information on license compatibility, we recommend the commented [license list curated by the GNU project](https://www.gnu.org/licenses/license-list.html).
### Conflict-of-interests
### Conflicts-of-interest
The open-source community is represented by a variety of groups with different, and sometimes opposite, interests.
For example, the prominent websites [ChooseALicense.com](https://choosealicense.com) is curated by GitHub and can be

2
content/getting-started/what-is-codeberg.md
View file

@ -92,7 +92,7 @@ Here are a few options:
They do offer much more than Forgejo, so check them out in any case.
- [other public Forgejo instances](https://codeberg.org/forgejo-contrib/delightful-forgejo#user-content-public-instances)
- Self-Hosting [Forgejo](https://forgejo.org), the software that powers Codeberg.
- [SourceHut](https://sourcehut.org): A minimum-GUI Free Software based service, available as hosted version by a
- [SourceHut](https://sourcehut.org): A minimum-GUI, Free Software based service, available as hosted version by a
transparent for-profit. Self-Hostable.
---

22
content/git/clone-commit-via-cli.md
View file

@ -92,8 +92,9 @@ Here's an explanation of the command flags used here:
The last step is to synchronize (_push_) the commit from the local repository to the remote one on Codeberg.
If you are using HTTPS, you will be asked for your Codeberg username and password. If you want to avoid entering your
password every time, consider [using SSH](/security/ssh-key) instead.
If you are using HTTPS, you will be asked for your Codeberg username and password.
If you have enabled Two-Factor Authentication, use your generated [access token](/advanced/access-token/) as the password instead.
If you want to avoid entering your password every time, consider [using SSH](/security/ssh-key) instead.
```shell
~/examples$ git push
@ -116,7 +117,7 @@ It's even more important when you have collaborators on a project; they may chan
pull these modifications before you start working.
Because of this, it is recommended to pull before pushing.
## CLI clients `tea` and `berg` for other actions
## CLI clients `tea` and `fj` for other actions
### Gitea / Forgejo CLI `tea`
@ -125,15 +126,10 @@ and [Forgejo](https://forgejo.org). Since Codeberg runs on Forgejo, you can use
This project is maintained by [the Gitea project](https://gitea.com).
### Codeberg CLI `berg`
### Forgejo CLI `fj`
The [codeberg-cli project](https://codeberg.org/RobWalt/codeberg-cli), aka. `berg`, is a CLI client that is tailored
for Codeberg.
The main difference compared to `tea` are:
The [forgejo-cli project](https://codeberg.org/forgejo-contrib/forgejo-cli), or `fj`, is a CLI client that can be used
with instances of Forgejo, including Codeberg. It is a younger project than `tea`, but its scope includes features
specific to Forgejo, such as browsing a repo's integrated wiki.
- extra features: `berg` provides some features that `tea` doesn't implement, like editing issues or pull requests
- active development: the `berg` repository is actively developed and maintained by a few community members
- modern UI: `berg` offers an interactive and modern looking user experience
If you're interested, check out the [codeberg-cli wiki](https://codeberg.org/RobWalt/codeberg-cli/wiki), which contains
just about everything you need to know about it.
This project is maintained by contributors in the [Forgejo community](https://codeberg.org/forgejo-contrib).

14
content/git/configuring-git.md
View file

@ -8,9 +8,17 @@ eleventyNavigation:
Once you've managed to get Git up and running, the first thing you must do before you can use your fresh installation of
Git is to tell Git your name and email address. You only have to do this once; this is easily done with:
{% admonition "warning" %}
Starting from git version 2.46, multiple `git config` commands have changed and it's recommended to migrate to the new command syntax. The command examples below have been updated to the new command syntax.
A complete list of deprecated commands can be found on the official [Git documentation](https://git-scm.com/docs/git-config#_deprecated_modes).
{% endadmonition %}
```bash
git config --global user.name 'knut'
git config --global user.email 'knut@example.com'
git config set --global user.name 'knut'
git config set --global user.email 'knut@example.com'
```
The username can be anything, but it is important that the email is the same as the one you use on Codeberg.
@ -18,7 +26,7 @@ This is because the email address will later be used to assign your commits to y
To verify that you've set up everything properly, run:
```bash
git config --global --list
git config list --global
```
{% admonition "tip" %}

21
content/git/index.md
View file

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

2
content/git/reduce-size.md
View file

@ -128,7 +128,7 @@ to undo in case anything goes wrong.
1. Turn off the mirror flag and carry out force pushes to your remote
```shell
git config --unset remote.origin.mirror
git config unset remote.origin.mirror
git push origin --force 'refs/heads/*'
git push origin --force 'refs/tags/*'
git push origin --force 'refs/replace/*'

6
content/git/using-lfs.md
View file

@ -150,6 +150,12 @@ This disables LFS for all files ending with .rnd in your repository.
The man page of [git-lfs-migrate(1)][git-lfs-migrate] further explains how to export files in order to disable tracking
them by LFS.
## Troubleshooting
If you connect to Git through SSH, you may encounter errors using LFS (such as `Connection closed`).
This is because the latest versions of Git LFS are now also using SSH by default in that case, but not all servers allow it.
Configuring Git with `git config lfs.sshTransfer never` will switch back to using HTTPS and should solve your problem.
## Further reading
- [Git LFS Website][git-lfs]

5
content/halfmoon.njk
View file

@ -1,5 +0,0 @@
---
permalink: halfmoon.css
---
{% include "../node_modules/halfmoon/css/halfmoon.min.css" %}
{% include "../node_modules/halfmoon/css/cores/halfmoon.modern.css" %}

BIN
content/images/collaborating/create-organization/people.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 57 KiB

BIN
content/images/collaborating/create-organization/profile.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 99 KiB

BIN
content/images/collaborating/pull-requests-and-git-flow/pull-request-button.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.3 KiB

After

Width:  |  Height:  |  Size: 6.4 KiB

BIN
content/images/collaborating/pull-requests-and-git-flow/sync-button.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.8 KiB

8
content/improving-codeberg/index.md
View file

@ -51,6 +51,14 @@ If you have questions, always feel free to ask in the Issue Trackers or on the M
Even tiny patches or suggestions, even if you are not a skilled developer, will be considered and are part of the
community-maintenance mission of Codeberg.
## Translations
Translators are always needed for our fork of Forgejo. Our [translation docs](/codeberg-translate) are a good place to
start and you can also join our [Matrix](https://matrix.org/) room: [#codeberg-translate](https://matrix.to/#/#codeberg-translate:bubu1.eu)
The Codeberg [translation service](https://translate.codeberg.org) also hosts translation projects for [Forgejo](https://forgejo.org/)
upstream and many other OSS projects.
## Reporting issues
If you experience an issue on some of the projects provided by Codeberg, please report it on Codeberg first so people

45
content/improving-codeberg/merch.md Normal file
View file

@ -0,0 +1,45 @@
---
eleventyNavigation:
key: Merch
title: Codeberg Merch
parent: ImprovingCodeberg
order: 60
---
As Codeberg's profile is increasing, so does the demand for merchandise.
Codeberg e.V. neither produces nor sells merch.
Following the [Debian Project's approach](https://www.debian.org/events/merchandise), we aim to provide a list of providers selling merchandise containing Codeberg's logos as a favor to those requesting it.
The ordering is purely alphabetical and no ranking of endorsement of a specific vendor.
The logos, available on [Codeberg's Design repository](https://codeberg.org/codeberg/design), have a [public domain dedication](https://codeberg.org/Codeberg/Design/src/branch/main/LICENSE).
Codeberg does not receive any money (e.g. in the form of a commission) from sales done through these suppliers.
We have explicitly indicated vendors that have been reviewed by Codeberg contributors and/or community members for e.g. their adherence to the spirit of the [Design guidelines](https://codeberg.org/Codeberg/Design).
---
**FreeWear.org**
- **URL:** [freewear.org/Codeberg](https://freewear.org/Codeberg)
- **Products:** T-shirts, polo shirts, mugs, tote bags
- **Last Updated:** May 10th, 2026
- **Available languages:** English
- **Original country:** Spain
- **International delivery:** Yes
- **Reviewed by contributors/community:** Yes
---
**HELLOTUX**
- **URL:** [hellotux.com/Codeberg](https://hellotux.com/Codeberg)
- **Products:** T-shirts, polo shirts, sweatshirts, towels, bags, zip jackets
- **Last Updated:** May 10th, 2026
- **Available languages:** English
- **Original country:** Hungary
- **International delivery:** Yes
- **Reviewed by contributors/community:** Yes
---
If you would like to be listed on this page, send an email to [merch@codeberg.org](mailto:merch@codeberg.org). Please provide us with the information listed above.

21
content/improving-documentation/index.md
View file

@ -8,26 +8,7 @@ eleventyNavigation:
We're very happy you're considering to contribute to Codeberg Documentation!
{% assign navPages = collections.all | eleventyNavigation %}
{%- for entry in navPages %}
{% if entry.url == page.url %}
{%- if entry.children.length -%}
<table class="table">
<thead>
<th>Find out more in this section:</th>
</thead>
<tbody>
{%- for child in entry.children %}
<tr>
<td><a href="{{ child.url }}">{{ child.title }}</a></td>
</tr>
{%- endfor %}
</tbody>
</table>
{% endif %}
{% endif %}
{%- endfor %}
{% sectionNav collections %}
## How do I contribute to Codeberg Documentation?

21
content/integrations/index.md
View file

@ -13,23 +13,4 @@ ecosystem of Forgejo instances.
Can can also see [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/README.md), most of the Gitea-specific
solutions should work with our Forgejo instance, too.
{% 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></td>
</tr>
{%- endfor %}
</tbody>
</table>
{% endif %}
{% endif %}
{%- endfor %}
{% sectionNav collections %}

11
content/integrations/read-the-docs.md
View file

@ -5,9 +5,9 @@ eleventyNavigation:
parent: Integrations
---
This article will guide you through integrating Codeberg with [Read the Docs](https://readthedocs.org/) to allow
This article will guide you through integrating Codeberg with [Read the Docs](https://about.readthedocs.org/) to allow
automatic build of your documentation. It will show you how to connect Read the Docs to a Git repository hosted on Codeberg.
To learn how Read the Docs works, take a look at the [official Documentation](https://docs.readthedocs.io).
To learn how Read the Docs works, take a look at the [official Documentation](https://docs.readthedocs.com/platform/stable/).
{% admonition "warning" %}
@ -17,15 +17,14 @@ Forgejo is currently not official supported by Read the Docs, so this may break
## Registration
If you do not have an account yet, you must sign up with [readthedocs first](https://readthedocs.org/accounts/signup/).
After sign-up you need to login with your user to access your [dashboard](https://readthedocs.org/dashboard/).
If you do not have an account yet, you first must [sign up with Read the Docs](https://app.readthedocs.org/).
After sign-up you need to login with your user to access your [dashboard](https://app.readthedocs.org/dashboard/).
## Create new Project
This steps shows how to create a new project on Read the Docs
1. On the [Read the Docs dashboard](https://readthedocs.org/dashboard/) click "Import a Project"
1. On the [Read the Docs dashboard](https://app.readthedocs.org/dashboard/) click "Import a Project"
2. If you have connected Read the Docs with some provider e.g. GitHub, you see a list of your repos at that provider.
Ignore it and click "Import Manually". You should see this screen:

21
content/markdown/index.md
View file

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

20
content/markdown/introduction-to-markdown.md
View file

@ -95,6 +95,25 @@ is rendered as
This is ~~strikethrough text~~.
### Monospaced font (code)
_For preformatted code blocks, see "[Preformatted Text](/markdown/preformatted-text)."_
It is a common convention in technical writing to use a monospaced or
fixed-width font to indicate code, literal text to be typed at a command
prompt, or program output.
To create a span of inline text with a monospaced font, wrap the text in
backtick (\`) characters, like so:
```markdown
This text contains an `inline code` span.
```
which renders as
This text contains an `inline code` span.
### Footnotes
To add footnotes use the syntax `[^name]` inline, and define them with:<br>
@ -102,6 +121,7 @@ To add footnotes use the syntax `[^name]` inline, and define them with:<br>
```markdown
Text with a footnote.[^1]
[^1]: A footnote.
```

101
content/markdown/preformatted-text.md
View file

@ -6,29 +6,71 @@ eleventyNavigation:
order: 50
---
There are two ways to use monospace preformatted text within your Markdown document:
In technical writing, code blocks, commands to be typed verbatim, or program
output are commonly represented by monospaced or fixed-width fonts. These
blocks are considered _preformatted_, because internal whitespace is to be
preserved.
- Using indentation
- Using one or more backticks at the beginning and the end of a preformatted section
There are three ways to use preformatted text within your Markdown documents:
## Using indentation
- [Indenting](#indented-blocks) each line of a block of text by 4 or more spaces, or a tab character.
- Beginning and ending a block of text with a row of 3 or more backtick (\`) or
tilde (~) characters, referred to as a ["fenced" code block](#fenced-code-blocks).
- Wrapping HTML `<pre></pre>` tags around a block of text.
You can preformat a section of text or code by indenting the code with 4 or more spaces, or a tab.
Fenced code blocks can optionally
[specify a rendering hint](<#rendering-hints-(syntax-highlighting)>)
to apply syntax highlighting to the block.
Using indentation, it's not possible to add a rendering hint. It's also not possible to preformat text within a line
using this syntax.
<a id="using-indentation"></a> <!-- old section name, do not remove -->
## Indented blocks
You can preformat a block of text or code by indenting the code with **4 or more spaces, or a tab character**.
Example:
```
This block of text
will be preformatted
and internal whitespace will be preserved.
```
Result:
```
This block of text
will be preformatted
and internal whitespace will be preserved.
```
Using indentation, it's not possible to add a rendering hint, so the block will not be syntax-highlighted.
Indentation-based preformatting sometimes causes false positives where text is
preformatted that isn't supposed to. For this reason, it is disabled in some
unintentionally preformatted; for this reason, it is disabled in some
Markdown renderers, including in Codeberg Documentation.
## Using backticks
<a id="using-backticks"></a> <!-- old section name, no not remove -->
A better way of preformatting a section of text is by starting a section of text with one or more backtick characters.
## Fenced code blocks
Here, we use 3 backtick characters on its own line, then our text, then another line containing 3 more backticks.
As an alternative, you can create blocks of preformatted text by starting and ending the block with a row of 3 or more backtick (\`) or tilde (~) characters. There should be an equal number of these characters at both start and end.
```markdown
Here, we use 3 backtick characters (\`\`\`) on their own line, then our text, then another line containing another 3 backticks.
````
```
this
is
displayed
as
preformatted
```
````
The result:
```
this
is
displayed
@ -36,16 +78,23 @@ as
preformatted
```
You can also preformat a section of text within a line using backtick syntax.
The following text is for example `preformatted` by using the backtick syntax.
<a id="rendering-hints"></a> <!-- old section name, do not remove -->
### Rendering hints
### Rendering hints (syntax highlighting)
Sometime renderers use hints to syntax highlight the code in a preformatted section.
To provide a hint, simply add the language name at the end of the introductory backtick(s).
To provide a hint, simply add the language name at the end of the introductory backtick(s). For example, using `shell` as the hint will tell the renderer that the given code should be highlighted as a shell script:
For example, using `shell` as the hint will tell the renderer that the given code should be highlighted as a shell script:
````
```shell
#!/bin/bash
echo "Hello world"
```
````
The result:
```shell
#!/bin/bash
@ -53,10 +102,24 @@ For example, using `shell` as the hint will tell the renderer that the given cod
echo "Hello world"
```
The same thing would be rendered without syntax highlighting if the hint is not given:
If the hint is omitted, the section will be rendered without syntax highlighting:
```text
````
```
#!/bin/bash
echo "Hello world"
```
````
The result:
```
#!/bin/bash
echo "Hello world"
```
## See also
- [Introduction to Markdown § Monospaced font (code)](</markdown/introduction-to-markdown#monospaced-font-(code)>).

4
content/markdown/using-links.md
View file

@ -78,17 +78,21 @@ This is rendered as:
The link parser used in Forgejo can also work with the _double square brackets_ syntax in issues and
other places where markdown is rendered:
<!-- prettier-ignore-start -->
```markdown
[[https://codeberg.org/]]
```
<!-- prettier-ignore-end -->
will get rendered as <https://codeberg.org>.
You can also give a link description, as with the regular markdown syntax:
<!-- prettier-ignore-start -->
```markdown
[[This is a link to Codeberg|https://codeberg.org]]
```
<!-- prettier-ignore-end -->
will be rendered as [This is a link to Codeberg](https://codeberg.org).

4
content/security/2fa.md
View file

@ -27,7 +27,7 @@ You will need an authenticator app installed on your phone.
If you don't already have an authenticator app and you're not sure which app to use, have a look at
Aegis Authenticator ([F-Droid](https://f-droid.org/de/packages/com.beemdevelopment.aegis/) |
[Google Play Store](https://play.google.com/store/apps/details?id=com.beemdevelopment.aegis&hl=en_US)),
Authenticator ([App Store](https://itunes.apple.com/app/authenticator/id766157276))
Authenticator ([App Store](https://apps.apple.com/app/authenticator/id766157276))
or Ente Auth ([F-Droid](https://f-droid.org/packages/io.ente.auth/) |
[Google Play Store](https://play.google.com/store/apps/details?id=io.ente.auth) |
[App Store](https://apps.apple.com/app/ente-auth-2fa-authenticator/id6444121398)).
@ -142,7 +142,7 @@ If you want to permanently save your generated access token you can use the foll
your computer:
```bash
git config --global credential.helper cache
git config set --global credential.helper cache
```
## Troubleshooting

12
content/security/gpg-key.md
View file

@ -85,9 +85,17 @@ you can sign the provided message. If the signed message is valid, Codeberg can
You will need to tell Git about your key and have it sign new commits for you.
{% admonition "warning" %}
Starting from git version 2.46, multiple `git config` commands have changed and it's recommended to migrate to the new command syntax. The command examples below have been updated to the new command syntax.
A complete list of deprecated commands can be found on the official [Git documentation](https://git-scm.com/docs/git-config#_deprecated_modes).
{% endadmonition %}
1. Open your terminal
2. Type `git config --global user.signingkey <GPG KEY ID>`
3. Type `git config --global commit.gpgsign true`
2. Type `git config set --global user.signingkey <GPG KEY ID>`
3. Type `git config set --global commit.gpgsign true`
{% admonition "note" %}

21
content/security/index.md
View file

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

69
content/security/ssh-key.md
View file

@ -6,6 +6,7 @@ eleventyNavigation:
order: 20
---
In comparison to using HTTPS, SSH keys provide a safer and passwordless way to authenticate with Codeberg.
It is recommended to use one key per client. This means that if you access your Codeberg repository from your home PC,
your laptop and your office PC you should generate separate keys for each machine.
@ -22,6 +23,8 @@ your laptop and your office PC you should generate separate keys for each machin
This will generate a new SSH key.
You can also add a comment to help you identify the client with `-C "comment here"`.
The program may also ask for a name and email address to associate with the key. While it is recommended to fill in something identifiable here, if you don't wish to, it may safely be left blank. These fields are for organizational purposes.
```shell
> Generating public/private ed25519 key pair.
```
@ -36,13 +39,7 @@ your laptop and your office PC you should generate separate keys for each machin
If you see that `/home/knut/.ssh/id_ed25519 already exists`, follow these steps:
1. When prompted to overwrite the existing file, type <kbd>n</kbd> to choose not to overwrite.
2. Afterward, re-run the same command:
```shell
ssh-keygen -t ed25519 -a 100
```
3. This time, enter a new filepath when prompted (e.g., `/home/knut/.ssh/id_ed25519_codeberg`) to avoid overwriting the
2. Afterward, re-run the same command. This time, enter a new filepath when prompted (e.g., `/home/knut/.ssh/id_ed25519_codeberg`) to avoid overwriting the
existing key.
4. You will be asked for a passphrase; enter one if you'd like, or leave the prompt empty.
@ -76,8 +73,9 @@ be prompted to touch it to continue.
1. Copy the SSH key to your clipboard. You must only copy the public key not the private one.
You can identify it by the `.pub` suffix. By default, you can find the public key in `$HOME/.ssh/id_ed25519.pub`.
On Linux, assuming you are using Wayland, you can use `wl-copy` on the command line.
You may need to install `wl-clipboard` from your package manager.
The key can be opened with any text editor and copied from there. However, there are other ways to copy the key from the terminal.
On Linux with Wayland, use the `wl-copy` utility. (This may require an installation of the `wl-clipboard` package):
```shell
wl-copy -t text/plain < ~/.ssh/id_ed25519.pub
@ -89,10 +87,10 @@ be prompted to touch it to continue.
xclip -selection clipboard < ~/.ssh/id_ed25519.pub
```
On Windows you can use `clip`.
On Windows you can use `clip` (powershell)
```shell
clip < ~/.ssh/id_ed25519.pub
gc ~/.ssh/id_ed25519.pub | clip
```
On macOS you can use `pbcopy`.
@ -101,12 +99,9 @@ be prompted to touch it to continue.
pbcopy < ~/.ssh/id_ed25519.pub
```
These commands will copy the contents of id_ed25519.pub (your SSH public key) to your clipboard.
These commands will copy the contents of `id_ed25519.pub` (your SSH public key) to your clipboard.
> Alternatively you can locate the hidden .ssh folder, open the file in your favorite text editor, and copy it to
> your clipboard.
2. Navigate to your [user settings](https://codeberg.org/user/settings)
2. Navigate to your [user settings](https://codeberg.org/user/settings).
<img src="/images/security/user-settings.png" alt="User Settings">
@ -138,6 +133,14 @@ Do this simple test:
ssh -T git@codeberg.org
```
<br>
{% admonition "tip" %}
If this is your first time connecting to Codeberg, you may be warned by your SSH client that the authenticity of the host cannot be established.
In this case, you will need to [verify the host fingerprint](/security/ssh-fingerprint/).
{% endadmonition %}
The output should look like this:
```text
@ -160,7 +163,7 @@ added key is yours.
1. Go to the [SSH/GPG Keys tab](https://codeberg.org/user/settings/keys) in your Codeberg settings.
2. Click on the **Verify** button next to the SSH key you would like to verify.
3. Codeberg will show a token. Under its text box copy the command, and replace `/path_to_your_private_key` with the
correct path of your private key.
correct path of your private (or public) key. (Either key works, ssh-keygen will do the right thing.)
4. Copy the output, beginning with `-----BEGIN SSH SIGNATURE-----` and ending with `-----END SSH SIGNATURE-----`.
5. Paste it into the large textbox and click the **Verify** button.
@ -175,11 +178,33 @@ To update your version of Git,see the [Git](https://git-scm.com/downloads) websi
{% endadmonition %}
1. Open your terminal.
2. Type `git config --global gpg.format ssh`.
3. Type `git config --global user.signingKey <PATH TO PUBLIC SSH KEY>`, substituting `<PATH TO PUBLIC SSH KEY>` with the
path to the public key you'd like to use, for example _~/.ssh/id_ed25519.pub_.
4. Type `git config --global commit.gpgSign true`.
{% admonition "warning" %}
Starting from git version 2.46, multiple `git config` commands have changed and it's recommended to migrate to the new command syntax. The command examples below have been updated to the new command syntax.
A complete list of deprecated commands can be found on the official [Git documentation](https://git-scm.com/docs/git-config#_deprecated_modes).
{% endadmonition %}
In your terminal, run the following commands:
1. Make git use SSH to sign commits and tags:
```shell
git config set --global gpg.format ssh
```
2. Set the SSH signing key to your public key:
```shell
git config set --global user.signingKey '~/.ssh/<YOUR PUBLIC SSH KEY>'
```
3. Sign commits by default:
```shell
git config set --global commit.gpgSign true
```
## Avoid re-typing the passphrase

26
eleventy.config.mjs
View file

@ -1,5 +1,6 @@
import navigationPlugin from '@11ty/eleventy-navigation';
import syntaxHighlightingPlugin from '@11ty/eleventy-plugin-syntaxhighlight';
import { HtmlBasePlugin } from '@11ty/eleventy';
import { eleventyImageTransformPlugin } from '@11ty/eleventy-img';
import markdownIt from 'markdown-it';
import tableOfContentsPlugin from '@uncenter/eleventy-plugin-toc';
@ -10,6 +11,7 @@ import { fas } from '@fortawesome/free-solid-svg-icons';
import { execSync } from 'child_process';
export default function (eleventyConfig) {
eleventyConfig.addPlugin(HtmlBasePlugin);
eleventyConfig.addPlugin(navigationPlugin);
eleventyConfig.addPlugin(syntaxHighlightingPlugin);
eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
@ -23,6 +25,7 @@ export default function (eleventyConfig) {
});
eleventyConfig.addPassthroughCopy('assets');
eleventyConfig.addPassthroughCopy({ 'node_modules/halfmoon/css': '/assets/css/halfmoon' });
eleventyConfig.addPassthroughCopy('fonts');
// Font Awesome Icons
@ -82,6 +85,28 @@ export default function (eleventyConfig) {
},
});
// the article list navigation for section index pages
eleventyConfig.addShortcode('sectionNav', function (collections) {
const navFilter = eleventyConfig.getFilter('eleventyNavigation');
// from the nav tree, find the current page's entry
const entry = navFilter(collections.all).find((page) => page.url == this.page.url);
// if the current page has children, create a nav table with a link for each
if (entry.children.length) {
const rows = entry.children
.map((child) => `<tr><td><a href="${child.url}">${child.title}</a></td></tr>`)
.join('');
return `<table class="table">
<thead>
<th>Find out more in this section:</th>
</thead>
<tbody>${rows}</tbody>
</table>`;
}
});
eleventyConfig.on('eleventy.after', () => {
execSync(`npx pagefind`, { encoding: 'utf-8' });
});
@ -91,4 +116,5 @@ export const config = {
dir: {
input: 'content',
},
pathPrefix: '/',
};

16
package.json
View file

@ -12,20 +12,20 @@
"lint-spellcheck": "cspell lint --no-progress --gitignore '{**,.*}/{*,.*}'"
},
"devDependencies": {
"@11ty/eleventy": "3.1.2",
"@11ty/eleventy": "3.1.6",
"@11ty/eleventy-img": "6.0.4",
"@11ty/eleventy-navigation": "1.0.5",
"@11ty/eleventy-plugin-syntaxhighlight": "5.0.2",
"@fortawesome/fontawesome-svg-core": "7.1.0",
"@fortawesome/free-solid-svg-icons": "7.1.0",
"@fortawesome/fontawesome-svg-core": "7.3.0",
"@fortawesome/free-solid-svg-icons": "7.3.0",
"@toycode/markdown-it-class": "1.2.4",
"@uncenter/eleventy-plugin-toc": "1.0.3",
"cspell": "9.6.0",
"@uncenter/eleventy-plugin-toc": "2.1.2",
"cspell": "10.0.1",
"halfmoon": "2.0.2",
"markdown-it": "14.1.0",
"markdown-it": "14.2.0",
"markdown-it-anchor": "9.2.0",
"markdownlint-cli2": "0.20.0",
"pagefind": "1.4.0",
"prettier": "3.8.1"
"pagefind": "1.5.2",
"prettier": "3.9.4"
}
}

966
pnpm-lock.yaml
View file

File diff suppressed because it is too large Load diff