h759bkyo4/Documentation
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Add woodpecker ci & many linters (and their required fixes) (#377)

Browse source 
closes #238

Co-authored-by: pat-s <patrick.schratz@gmail.com>
Co-authored-by: Patrick Schratz <pat-s@noreply.codeberg.org>
Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/377
Co-authored-by: crapStone <crapstone01@gmail.com>
Co-committed-by: crapStone <crapstone01@gmail.com>
This commit is contained in:
crapStone 2024-06-11 07:51:22 +00:00 committed by Patrick Schratz
parent 8f5231283e
commit da1b77aa6a
89 changed files with 4089 additions and 1438 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.cspell/codeberg.txt Normal file
View file

@ -0,0 +1,2 @@
Codeberg
Forgejo

3
.ecrc Normal file
View file

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

17
.editorconfig Normal file
View file

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

92
.eleventy.js
View file

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

7
.lycheeignore Normal file
View file

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

141
.markdownlint.yaml Normal file
View file

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

8
.prettierrc.json Normal file
View file

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

14
.woodpecker/build.yaml Normal file
View file

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

37
.woodpecker/lint.yaml Normal file
View file

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

21
.yamllint.yaml Normal file
View file

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

2
Dockerfile
View file

@ -12,4 +12,4 @@ WORKDIR /opt/documentation
RUN npm install
CMD [ "npm", "run", "serve"]
CMD [ "npm", "run", "serve"]

9
LICENSE.md
View file

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

23
README.md
View file

@ -1,4 +1,5 @@
# Codeberg Documentation
This repository contains the [documentation for Codeberg](https://docs.codeberg.org/), with some code to build it into
a static website.
@ -7,22 +8,23 @@ Please have a look into it and consider to help writing the Documentation. This
For an introduction on contributing to Codeberg Documentation, please have a look
at [the section on improving the documentation](https://docs.codeberg.org/improving-documentation/).
## Usage
### Local Development
If you want to work on the documentation, for example by writing your own articles,
the easiest way to do so is to fork the documentation repository and develop locally.
First, run
```npm install```
`npm install`
to install all dependencies (they will be installed only for this project, not globally).
You only have to do this once.
Then run
```npm run serve```
`npm run serve`
to start a development web server that by default is listening at `http://localhost:8080`.
@ -42,14 +44,14 @@ You must have a container-engine installed (docker, podman, etc.)
First build the container image:
```shell
docker build -t codeberg/documentation-server .
docker build -t Codeberg/Documentation-server .
```
You do not have to rebuild the image every time. Once you build the image you can always start the development
webserver using the container engine:
```shell
docker run --rm -v $PWD:/opt/documentation codeberg/documentation-server:latest
docker run --rm -v $PWD:/opt/documentation Codeberg/Documentation-server:latest
```
Use the "External" URL the container outputs on startup to access your documentation.
@ -63,25 +65,27 @@ The parameters are:
`--rm` removes the container after it's use
`-v` mounts the current (documentation repository root) folder to `/opt/documentation` in the container.
`codeberg/documentation-server:latest` refers to the container image built in the first step (using `docker build`).
`Codeberg/Documentation-server:latest` refers to the container image built in the first step (using `docker build`).
### Build & Deployment
Like for local development, before building and deploying you first have to install
the dependencies (once):
```npm install```
`npm install`
To build the entire website to the `_site` directory run
```npm run build```
`npm run build`
Instead, to directly publish the page to Codeberg pages, you can also run
```npm run deploy```
`npm run deploy`
which includes a call to `npm run build`.
### Technical Information
This website uses [Eleventy](https://www.11ty.dev/), a static site generator.
It's supplied as a dev-dependency in `package.json` and its dependencies are locked
@ -90,6 +94,7 @@ with `package-lock.json` to try to ensure reproducible builds.
It also uses [PageFind](https://pagefind.app/), a static search library.
## License and Contributors
This website (excluding bundled fonts) is licensed under CC BY-SA 4.0. See the [LICENSE](LICENSE.md) file for details.
Please refer to the [commit log](https://codeberg.org/Codeberg/Documentation/commits/branch/main) for an exhaustive list of contributors to Codeberg Documentation.

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

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

125
assets/css/prism-nord.css
View file

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

4
content/_data/env.js
View file

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

4
content/_data/urls.json
View file

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

364
content/_includes/default_layout.njk
View file

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

58
content/_includes/license.njk
View file

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

16
content/_includes/redirect.njk
View file

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

6
content/_includes/toc-collapse.njk
View file

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

6
content/advanced/access-token.md
View file

@ -5,7 +5,7 @@ eleventyNavigation:
parent: AdvancedUsage
---
Access Tokens are special tokens that are used to authenticate to Codeberg through the [API](https://codeberg.org/api/swagger). They can be used to give applications access to your Codeberg account without sharing your password.
Access Tokens are special tokens that are used to authenticate to Codeberg through the [API](https://codeberg.org/api/swagger). They can be used to give applications access to your Codeberg account without sharing your password.
{% admonition "info" %}
@ -14,6 +14,7 @@ This guide explains how to generate an access token from the website. However, y
{% endadmonition %}
## Generating an Access Token
Access tokens grant full access to your account. You must handle them securely.
<picture>
@ -24,7 +25,7 @@ Access tokens grant full access to your account. You must handle them securely.
1. In a web browser, go to Codeberg and click on the `Profiles and Settings` button on the top right. The button will be your profile picture.
2. Click on [`Settings`](https://codeberg.org/user/settings) in the dropdown.
3. Navigate to the [`Applications`](https://codeberg.org/user/settings/applications) settings tab.
4. Under `Manage Access Tokens | Generate New Token`, enter a name to identify your token in the `Token Name` field.
4. Under `Manage Access Tokens | Generate New Token`, enter a name to identify your token in the `Token Name` field.
5. Click the generate token button.
<picture>
@ -41,6 +42,7 @@ Be sure to generate new access tokens for each app you use, and delete them once
{% endadmonition %}
## Deleting an Access Token
Once you are done using an access token, you should delete it. Deleting an access token revokes access to your account for apps using the token.
To delete an access token, click the red `Delete` button next to the access token you want to delete, then click `Yes` in the popup. Your access token is now deleted.

5
content/advanced/index.md
View file

@ -2,7 +2,7 @@
eleventyNavigation:
key: AdvancedUsage
title: Advanced Usage
icon: terminal
icon: terminal
order: 65
---
@ -16,6 +16,7 @@ Codeberg is based on.
{%- 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>
@ -30,4 +31,4 @@ Codeberg is based on.
</table>
{% endif %}
{% endif %}
{%- endfor %}
{%- endfor %}

28
content/advanced/migrating-repos.md
View file

@ -15,36 +15,39 @@ This works well for moving files, but when you want to migrate metadata like iss
<img src="/assets/images/advanced/migrating-repos/new-migration.png">
</picture>
On Codeberg, you can click on the plus symbol on the top right, and then select [**New Migration**](https://codeberg.org/repo/migrate) on the dropdown to access the migration tool.
On Codeberg, you can click on the plus symbol on the top right, and then select [**New Migration**](https://codeberg.org/repo/migrate) on the dropdown to access the migration tool.
## Selecting your host
Once you're at the [**New Migration**](https://codeberg.org/repo/migrate) page, you can select the Git host you are migrating from. For the following services, the migration tool can not only migrate your repository data, but also metadata like issues, labels, wiki, releases, milestones, etc.
- [GitHub](#migrating-from-services)
- [GitLab](#migrating-from-services)
- [Gitea / Forgejo](#migrating-from-services)
- [Gogs](#migrating-from-services)
- [OneDev](#migrating-from-services)
- [GitBucket](#migrating-from-services)
- [Codebase](#migrating-from-services)
- [GitHub](#migrating-from-services)
- [GitLab](#migrating-from-services)
- [Gitea / Forgejo](#migrating-from-services)
- [Gogs](#migrating-from-services)
- [OneDev](#migrating-from-services)
- [GitBucket](#migrating-from-services)
- [Codebase](#migrating-from-services)
If you cannot find your service, you can select the [Git option](#migrating-from-git). This will not migrate mentioned metadata.
Here we document instructions for migrating specific to each service. Once you've followed through, move on to [Starting Migration](#starting-migration).
### Migrating from Git
<picture>
<source srcset="/assets/images/advanced/migrating-repos/git-migration.webp" type="image/webp">
<img src="/assets/images/advanced/migrating-repos/git-migration.png">
</picture>
Here's an explanation of some fields on the [Git migration page](https://codeberg.org/repo/migrate?service_type=1):
- **Migrate / Clone From URL**: This is the URL to your repository. For example: `https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git`.
- **Username and Password**: Optionally, if authentication is required to access the repo, you can enter a username and password here.
### Migrating from Services
To migrate a repo with its metadata from a different service, you will first need to [create an access token](/advanced/access-token/) on the service with your repository. *Please check your services documentation, on how to get the access token.* Examples can be found for [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) and [GitHub](https://github.com/settings/tokens). Don't forget to delete the access token once you are finished.
To migrate a repo with its metadata from a different service, you will first need to [create an access token](/advanced/access-token/) on the service with your repository. _Please check your services documentation, on how to get the access token._ Examples can be found for [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) and [GitHub](https://github.com/settings/tokens). Don't forget to delete the access token once you are finished.
<picture>
<source srcset="/assets/images/advanced/migrating-repos/gitea-migration.webp" type="image/webp">
@ -52,6 +55,7 @@ To migrate a repo with its metadata from a different service, you will first nee
</picture>
Here's an explanation of some fields on the [Gitea migration page](https://codeberg.org/repo/migrate?service_type=3):
- **Migrate / Clone From URL**: This is the URL to your repository. For example: `https://code.forgejo.org/forgejo/end-to-end`.
- **Access Token**: You will paste the access token generated here. An access token is required to migrate metadata or non-public repositories.
- **Migration Items**: Here you can select the metadata you want migrated.
@ -75,10 +79,10 @@ When the repo code appears, migration is complete!
## Inaccessible repo after failed migration
Sometimes a migration might fail for no obvious reasons like timeouts or invalid data in the source repo, leaving you with an inaccessible repo on Codeberg.
When you try to navigate to your repo on Codeberg, e.g. `https://codeberg.org/knut/example/`, you are welcomed with a `500 Internal Server Error`.
Sometimes a migration might fail for no obvious reasons like timeouts or invalid data in the source repo, leaving you with an inaccessible repo on Codeberg.
When you try to navigate to your repo on Codeberg, e.g. `https://codeberg.org/knut/example/`, you are welcomed with a `500 Internal Server Error`.
In this case it might be worthwhile to retry the migration.
In this case it might be worthwhile to retry the migration.
First you need to remove the inaccessible repo. To do so, go to the settings page of your repo by appending `/settings` to the URI, e.g. `https://codeberg.org/knut/example/settings`. You can delete the repo from here and start over with a new migration.
If this doesn't work out, feel free to open an issue in the [Community Issue Tracker](https://codeberg.org/Codeberg/Community/issues).

56
content/advanced/using-webhooks.md
View file

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

126
content/ci/actions.md
View file

@ -43,26 +43,25 @@ You can add Runners to your account, organization, or repository. Choosing where
<img src="/assets/images/ci/actions/create-new-runner.png" alt="Create new Runner">
</picture>
## Installing Forgejo Runner
## Installing Forgejo Runner
Forgejo Runner is released in both binary and container image (OCI) forms:
- Download the binary to run on your machine:
```bash
$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v3.3.0/forgejo-runner-3.3.0-linux-amd64
$ chmod +x forgejo-runner
```
```bash
$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v3.3.0/forgejo-runner-3.3.0-linux-amd64
$ chmod +x forgejo-runner
```
Make sure to replace `amd64` with `arm64` if your host machine is on ARM.
Make sure to replace `amd64` with `arm64` if your host machine is on ARM.
- Or download the container image and run it using Docker:
```bash
$ docker run --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner --version
forgejo-runner version v3.3.0
```
```bash
$ docker run --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner --version
forgejo-runner version v3.3.0
```
## Preparing configuration files
@ -85,7 +84,7 @@ $ ./forgejo-runner generate-config > config.yml
### Docker
```bash
$ docker run -v /var/run/docker.sock:/var/run/docker.sock -v $PWD:/data --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner register --no-interactive --token {TOKEN} --name {NAME} --instance https://codeberg.org
$ docker run -v /var/run/docker.sock:/var/run/docker.sock -v $PWD:/data --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner register --no-interactive --token {TOKEN} --name {NAME} --instance https://codeberg.org
Status: Downloaded newer image for code.forgejo.org/forgejo/runner:3.3.0
level=info msg="Registering runner, arch=arm64, os=linux, version=v3.3.0."
level=warning msg="Runner in user-mode."
@ -104,7 +103,7 @@ These commands will generate two files in your current directory:
## Deployment Methods
Depending on your setup and your security needs, there is a wide variety of options for deploying the Runner.
Depending on your setup and your security needs, there is a wide variety of options for deploying the Runner.
### Running on Docker
@ -145,10 +144,9 @@ Using Docker Compose, we can configure the Runner container to execute workflows
Here is an example snippet of how it can be configured:
```yaml
version: "3"
version: '3'
services:
docker:
image: docker:dind
privileged: true
@ -164,9 +162,9 @@ services:
volumes:
- /opt/forgejo-runner:/data
- certs:/certs
command: "forgejo-runner --config config.yml daemon"
command: 'forgejo-runner --config config.yml daemon'
volumes:
certs:
certs:
```
Make sure to replace `/opt/forgejo-runner` with the directory path of your configuration files.
@ -175,7 +173,7 @@ Make sure to replace `/opt/forgejo-runner` with the directory path of your confi
{% admonition "warning" "Warning" %}
Docker in Docker (dind) requires elevated privileges on Kubernetes.
Docker in Docker (dind) requires elevated privileges on Kubernetes.
The current way to achieve this is to set the pod `SecurityContext` to `privileged`.
@ -213,51 +211,57 @@ spec:
spec:
restartPolicy: Always
volumes:
- name: docker-certs
emptyDir: {}
- name: runner-data
emptyDir: {}
- name: docker-certs
emptyDir: {}
- name: runner-data
emptyDir: {}
initContainers:
- name: runner-config-generation
image: code.forgejo.org/forgejo/runner:3.3.0
command: [ "forgejo-runner create-runner-file --instance $FORGEJO_INSTANCE_URL --secret $RUNNER_SECRET --connect" ]
env:
- name: RUNNER_SECRET
valueFrom:
secretKeyRef:
name: runner-secret
key: token
- name: FORGEJO_INSTANCE_URL
value: https://codeberg.org
volumeMounts:
- name: runner-data
mountPath: /data
- name: runner-config-generation
image: code.forgejo.org/forgejo/runner:3.3.0
command:
['forgejo-runner create-runner-file --instance $FORGEJO_INSTANCE_URL --secret $RUNNER_SECRET --connect']
env:
- name: RUNNER_SECRET
valueFrom:
secretKeyRef:
name: runner-secret
key: token
- name: FORGEJO_INSTANCE_URL
value: https://codeberg.org
volumeMounts:
- name: runner-data
mountPath: /data
containers:
- name: runner
image: code.forgejo.org/forgejo/runner:3.3.0
command: ["sh", "-c", "while ! nc -z localhost 2376 </dev/null; do echo 'waiting for docker daemon...'; sleep 5; done; forgejo-runner daemon"]
env:
- name: DOCKER_HOST
value: tcp://localhost:2376
- name: DOCKER_CERT_PATH
value: /certs/client
- name: DOCKER_TLS_VERIFY
value: "1"
volumeMounts:
- name: docker-certs
mountPath: /certs
- name: runner-data
mountPath: /data
- name: daemon
image: docker:dind
env:
- name: DOCKER_TLS_CERTDIR
value: /certs
securityContext:
privileged: true
volumeMounts:
- name: docker-certs
mountPath: /certs
- name: runner
image: code.forgejo.org/forgejo/runner:3.3.0
command:
[
'sh',
'-c',
"while ! nc -z localhost 2376 </dev/null; do echo 'waiting for docker daemon...'; sleep 5; done; forgejo-runner daemon",
]
env:
- name: DOCKER_HOST
value: tcp://localhost:2376
- name: DOCKER_CERT_PATH
value: /certs/client
- name: DOCKER_TLS_VERIFY
value: '1'
volumeMounts:
- name: docker-certs
mountPath: /certs
- name: runner-data
mountPath: /data
- name: daemon
image: docker:dind
env:
- name: DOCKER_TLS_CERTDIR
value: /certs
securityContext:
privileged: true
volumeMounts:
- name: docker-certs
mountPath: /certs
```
Make sure to replace the value of `token` with your registration token.

1
content/ci/index.md
View file

@ -6,7 +6,6 @@ eleventyNavigation:
order: 65
---
Every piece of code should be tested regularly. Ideally developers already implement unit-tests to test the functionality of code sections.
Some projects even implement a suite of integration tests, testing whether the code in different parts of the software works as a whole and (still) provides the functionality the software promises to deliver.
Running these tests regularly (or continuously) is the job of a Continuous Integration solution.

30
content/codeberg-pages/examples/docs-as-code.md
View file

@ -1,16 +1,16 @@
---
eleventyNavigation:
key: DocsAsCode
title: "Example: Docs as Code with Sphinx"
title: 'Example: Docs as Code with Sphinx'
parent: CodebergPages
order: 100
---
Docs-as-code (also known as "Documentation as Code") refers to the concept of treating documentation as a codebase, i.e. integrating the documentation process in the toolchains and workflows used by software development teams.
Docs-as-code (also known as "Documentation as Code") refers to the concept of treating documentation as a codebase, i.e. integrating the documentation process in the toolchains and workflows used by software development teams.
Docs-as-code involves using version control systems such as Git for your documentation projects and authoring your content with plain text markup languages such as Markdown or reStructuredText, among other things.
Docs-as-code involves using version control systems such as Git for your documentation projects and authoring your content with plain text markup languages such as Markdown or reStructuredText, among other things.
To find out more about docs-as-code, head over to [its website](https://docs-as-co.de/).
To find out more about docs-as-code, head over to [its website](https://docs-as-co.de/).
Whether you are a single technical communicator or a member of a larger documentation team, you can perfectly apply the docs-as-code approach to your documentation projects.
@ -24,13 +24,13 @@ Despite the fact that we are using Sphinx in this particular case, you can easil
## Building documentation with Sphinx
Initially developed to generate Python documentation, Sphinx is now widely used by technical communicators and software developers to create technical and software documentation.
Initially developed to generate Python documentation, Sphinx is now widely used by technical communicators and software developers to create technical and software documentation.
Sphinx uses [reStructuredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html) as a markup language to generate documentation content. Among further advantages, Sphinx allows you to produce your documentation in different formats, including HTML, LaTeX and ePub. You can also use one of the multiple extensions developed by the community to extend its functionality.
Sphinx uses [reStructuredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html) as a markup language to generate documentation content. Among further advantages, Sphinx allows you to produce your documentation in different formats, including HTML, LaTeX and ePub. You can also use one of the multiple extensions developed by the community to extend its functionality.
### Setting up the project
To begin setting up your project, you will first need an account on Codeberg. If you don't already have one, follow the instructions provided under [Your First Steps on Codeberg](https://docs.codeberg.org/getting-started/first-steps/).
To begin setting up your project, you will first need an account on Codeberg. If you don't already have one, follow the instructions provided under [Your First Steps on Codeberg](https://docs.codeberg.org/getting-started/first-steps/).
This guide assumes that you already have Git installed on your machine. If you don't, you can install git as described in the article [Install Git](https://docs.codeberg.org/getting-started/install-git/).
@ -38,7 +38,7 @@ For the purpose of this guide, we will start a documentation project from scratc
### Creating a Python virtual environment
A "virtual" isolated environment comes in very handy to eliminate the risk of any broken dependencies while working on your projects. In other words, setting up a virtual environment for your project allows you to run an instance of the Python interpreter with a particular package set and a specific configuration while ensuring compatibility between all these components inside that environment.
A "virtual" isolated environment comes in very handy to eliminate the risk of any broken dependencies while working on your projects. In other words, setting up a virtual environment for your project allows you to run an instance of the Python interpreter with a particular package set and a specific configuration while ensuring compatibility between all these components inside that environment.
Before starting, you should make sure that you have pip and Python 3 installed on your machine. To check, type the following commands in your terminal:
@ -70,7 +70,7 @@ You can replace the second argument "env" with any other name your like. This wi
{% admonition "warning" %}
Use a **``.gitignore``** file to exclude your virtual environment directory from your version control system. To ignore the entire "env" folder, include the corresponding path and append a **``/``** at its end, e.g. **``env/``**.
Use a **`.gitignore`** file to exclude your virtual environment directory from your version control system. To ignore the entire "env" folder, include the corresponding path and append a **`/`** at its end, e.g. **`env/`**.
{% endadmonition %}
@ -80,7 +80,7 @@ Before you begin performing any tasks on your project, you must activate your vi
```bash
$ . env/bin/activate
```
```
To make sure that you are working inside of your virtual environment, run the command:
@ -119,7 +119,7 @@ $ mkdir mydocs
$ cd mydocs
```
Running the command `tree -a` should now output the following:
Running the command `tree -a` should now output the following:
```bash
.
@ -174,7 +174,7 @@ To set up a local testing server for your documentation project, you can use the
```bash
(.venv) $ sphinx-build -b html docs/source/ docs/build/html
```
```
Then navigate to the directory hosting the HTML resources:
@ -184,7 +184,7 @@ Then navigate to the directory hosting the HTML resources:
Once there, run the local python server with the command:
```bash
```bash
(.venv) $ python3 -m http.server 8080
```
@ -205,7 +205,7 @@ You can start creating your own content by making a new reStructuredText file (.
(.venv) $ touch mynewfile.rst
```
You have just created an empty ".rst" file with the **`touch`** command. An ".rst" file is simply a plain text file that is written with reStructuredText as a markup language. To learn about how to use reStructuredText, follow the instructions provided in the article [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
You have just created an empty ".rst" file with the **`touch`** command. An ".rst" file is simply a plain text file that is written with reStructuredText as a markup language. To learn about how to use reStructuredText, follow the instructions provided in the article [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
You will be more productive in your writing if you use a text editor that supports syntax highlighting such as [Emacs](https://www.gnu.org/software/emacs/download.html) or [Atom](https://atom.io/). Linux offers plenty of powerful text editors that support syntax highlighting and other advanced features for coding and authoring tasks.
@ -217,6 +217,6 @@ Whenever you create a new .rst file, you must add it manually to the `toctree` o
The toctree directive (toc stands for Table of Contents) inserts a tree that connects the different ".rst" files located in your source directory with each other. Read the article [Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive) to learn more about the toctree directive.
Once you have added an .rst file to the `toctree`, you can check the output at any time by running the [sphinx-build](#running-a-local-http-server-using-python) command illustrated above, then refreshing your local testing server.
Once you have added an .rst file to the `toctree`, you can check the output at any time by running the [sphinx-build](#running-a-local-http-server-using-python) command illustrated above, then refreshing your local testing server.
If you are satisfied with the result on your local development environment, you can publish the content on Codeberg Pages. To find out how to do this, read the article [Pushing output from SSGs into Codeberg Pages](https://docs.codeberg.org/codeberg-pages/pushing-output/).

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

@ -20,6 +20,7 @@ Follow these simple steps below to get started, or check out the advanced usage
This project is developed "in-house" by Codeberg. You can find the source code [here](https://codeberg.org/Codeberg/pages-server/).
See also:
- [codeberg.page](https://codeberg.page)
- [Troubleshooting (Codeberg Documentation)](troubleshooting)
- [Features (Codeberg Pages Repository)](https://codeberg.org/Codeberg/pages-server/src/branch/main/FEATURES.md)
@ -28,6 +29,7 @@ See also:
{%- 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>
@ -55,8 +57,6 @@ The Codeberg Pages server responds to four different URLs:
In all cases, you can append a branch using an `@` (e.g. `https://username.codeberg.page/@develop/README.md`). If the branch name contains a slash (`/`), they need to be replaced with a tilde (`~`) (e.g. the branch `docs/develop` can be accessed via `https://username.codeberg.page/@docs~develop/README.md`).
## Do you have questions, feedback or have you found a bug?
The source code for Codeberg Pages is maintained over at the [Pages Server repository](https://codeberg.org/Codeberg/pages-server); feel free to head there to provide some feedback, suggestions, bug reports or even patches.

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

@ -8,11 +8,11 @@ eleventyNavigation:
order: 101
---
If you are using a static site generator (SSG) and are satisfied with the result of your project on your local development environment, you can push the files to your Codeberg Pages repository.
If you are using a static site generator (SSG) and are satisfied with the result of your project on your local development environment, you can push the files to your Codeberg Pages repository.
To begin with, we will have two separate repositories, both locally and on Codeberg:
- A main repository for the source files, i.e. where the source files related to your main project will be located. We will refer to this repository as the `source` repository. This repository is the one associated with your [mydocs](/codeberg-pages/examples/docs-as-code/#mydocs) folder.
- A 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.
@ -39,7 +39,7 @@ For the purpose of this guide, we have chosen to use two separate folders/reposi
To copy the content of the `html` folder to your new `pages` folder, run the command:
```bash
(.venv) $ cp -R docs/build/html/ pages
(.venv) $ cp -R docs/build/html/ pages
```
We will now initialize an empty repository inside the pages folder. To do this, type the command:
@ -48,7 +48,7 @@ We will now initialize an empty repository inside the pages folder. To do this,
$ git init
```
To check the status of your project’s files, type the command:
To check the status of your project’s files, type the command:
```bash
$ git status
@ -70,7 +70,7 @@ Repeat these steps in your `source` folder, then push your local commits to the
```bash
$ git push origin HEAD:your-remote-branch-name
```
```
{% admonition "info" "Note" %}

14
content/codeberg-pages/redirects.md
View file

@ -13,16 +13,16 @@ Redirects can be created with a `_redirects` file with the following format:
from to [status]
```
* Lines starting with `#` are ignored
* `from` - the path to redirect from (Note: repository and branch names are removed from request URLs)
* `to` - the path or URL to redirect to
* `status` - status code to use when redirecting (default 301)
- Lines starting with `#` are ignored
- `from` - the path to redirect from (Note: repository and branch names are removed from request URLs)
- `to` - the path or URL to redirect to
- `status` - status code to use when redirecting (default 301)
## Status codes
* `200` - returns content from specified path (no external URLs) without changing the URL (rewrite)
* `301` - Moved Permanently (Permanent redirect)
* `302` - Found (Temporary redirect)
- `200` - returns content from specified path (no external URLs) without changing the URL (rewrite)
- `301` - Moved Permanently (Permanent redirect)
- `302` - Found (Temporary redirect)
## Examples

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

@ -16,13 +16,13 @@ Instead of using the `codeberg.page` domain, you can also purchase your own doma
For custom domains, two things are required:
- a `.domains` file in the repository and branch where your files reside which you want to publish via Codeberg Pages. The file should contain a list of *all* domains that shall be usable to access that repository, according to the following rules:
- a `.domains` file in the repository and branch where your files reside which you want to publish via Codeberg Pages. The file should contain a list of _all_ domains that shall be usable to access that repository, according to the following rules:
- One domain per line, you can leave lines empty and comment out lines with `#`.
- The first domain is the main domain, all other domains in the file will be redirected to the first one.
- The rest of the list includes all relevant `*.codeberg.page` domains for the specific repository.
- a [DNS record](https://en.wikipedia.org/wiki/Domain_Name_System#Address_resolution_mechanism) pointing to one of the following targets, depending on where your static files reside:
- 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 />
@ -57,7 +57,7 @@ There are several ways DNS records for your website can be setup in order to tel
</tbody>
<table>
*We assume for the following description, that you want to serve your website with and without www in front. If you are on a subdomain already (like myproject.yourdomain.com), you can skip the `www.yourdomain.com` CNAME entry.*
_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" %}
@ -72,7 +72,7 @@ Therefore, in this guide, you may need to replace references to just your domain
**Option 1: CNAME record**
The easiest and recommended way is to just setup a CNAME record for your domain, pointing to the mentioned above locations. In the end, it should look like this:
<table class="table">
<thead>
<th>Domain</th>
@ -102,8 +102,8 @@ If you need email or others services, you have to use one of the remaining optio
If you cannot use a CNAME record to configure the target you can use this method, which needs two entries instead of one.
- First you need to specify which server should be serving your website. Similar to CNAME you can use an `ALIAS record`. The [difference](https://www.ecosia.org/search?q=cname%20vs%20alias%20record) between an CNAME record is, that the DNS server directly responds with the ip address and not the `codeberg.page` domain. Therefore you need to add a second entry, so that the pages server knows what to serve under this domain.
- Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
- First you need to specify which server should be serving your website. Similar to CNAME you can use an `ALIAS record`. The [difference](https://www.ecosia.org/search?q=cname%20vs%20alias%20record) between an CNAME record is, that the DNS server directly responds with the ip address and not the `codeberg.page` domain. Therefore you need to add a second entry, so that the pages server knows what to serve under this domain.
- Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
In the end it should look like this:
@ -129,10 +129,10 @@ In the end it should look like this:
If your service provider does not support `ALIAS records` you can also use `A records` and `AAAA records` instead.
- First you need to specify which server should be serving your website. You can do this by setting an `A record` for IPv4 and an `AAAA record` for IPv6 which contains the ip address of the Codeberg Pages server. The servers' ip addresses are:
- `A record` which contains the IPv4 value `217.197.91.145`
- `AAAA record` which contains the IPv6 value `2001:67c:1401:20f0::1`
- Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
- First you need to specify which server should be serving your website. You can do this by setting an `A record` for IPv4 and an `AAAA record` for IPv6 which contains the ip address of the Codeberg Pages server. The servers' ip addresses are:
- `A record` which contains the IPv4 value `217.197.91.145`
- `AAAA record` which contains the IPv6 value `2001:67c:1401:20f0::1`
- Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
In the end, it should look like this:
@ -163,14 +163,14 @@ The following sub-sections include a few examples of the different alternatives,
- 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`).
- `frida/pages`, with a _Personal_ static site inside branch `pages`;
- `frida/colormix`, with a _Project_ site (again, inside branch `pages`).
All considerations regarding a *Personal* site also apply to an *Organization* site, so these two cases will be addressed together.
All considerations regarding a _Personal_ site also apply to an _Organization_ site, so these two cases will be addressed together.
### Personal (or Organization) site, third level domain
In this case, we want our *Personal* pages available at the URL `https://myself.example.com`.
In this case, we want our _Personal_ pages available at the URL `https://myself.example.com`.
The `.domains` file contains the following:
@ -184,20 +184,22 @@ pages.pages.frida.codeberg.page
For the DNS configuration:
- if CNAME can be used, one single DNS record will suffice:
- name `myself.example.com`, type `CNAME`, data `frida.codeberg.page`
- 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`
- name `myself.example.com`, type `ALIAS`, data `codeberg.page`
- name `myself.example.com`, type `TXT`, data `frida.codeberg.page`
- otherwise, A/AAAA records must be used, together with one TXT record:
- name `myself.example.com`, type `A`, data `217.197.91.145`
- name `myself.example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
- name `myself.example.com`, type `TXT`, data `frida.codeberg.page`
- name `myself.example.com`, type `A`, data `217.197.91.145`
- name `myself.example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
- name `myself.example.com`, type `TXT`, data `frida.codeberg.page`
### Personal/Organization site, apex domain
In this case, we want our *Personal*/*Organization* pages available at the URL `https://example.com`.
In this case, we want our _Personal_/_Organization_ pages available at the URL `https://example.com`.
The `.domains` file contains the following:
@ -211,17 +213,18 @@ pages.pages.frida.codeberg.page
For the DNS configuration, the CNAME SHOULD NOT be used, so:
- if ALIAS can be used, two DNS records will be needed:
- name `example.com`, type `ALIAS`, data `codeberg.page`
- name `example.com`, type `TXT`, data `frida.codeberg.page`
- name `example.com`, type `ALIAS`, data `codeberg.page`
- name `example.com`, type `TXT`, data `frida.codeberg.page`
- otherwise, A/AAAA records must be used, together with one TXT record:
- name `example.com`, type `A`, data `217.197.91.145`
- name `example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
- name `example.com`, type `TXT`, data `frida.codeberg.page`
- name `example.com`, type `A`, data `217.197.91.145`
- name `example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
- name `example.com`, type `TXT`, data `frida.codeberg.page`
### Project site, third-level domain
In this case, we want our *Project* pages available at the URL `https://colormix-app.example.com`.
In this case, we want our _Project_ pages available at the URL `https://colormix-app.example.com`.
The `.domains` file contains the following:
@ -234,24 +237,26 @@ pages.colormix.frida.codeberg.page
For the DNS configuration:
- if CNAME can be used, one single DNS record will suffice:
- name `colormix-app.example.com`, type `CNAME`, data `colormix.frida.codeberg.page`
- 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`
- name `colormix-app.example.com`, type `ALIAS`, data `codeberg.page`
- name `colormix-app.example.com`, type `TXT`, data `colormix.frida.codeberg.page`
- otherwise, A/AAAA records must be used, together with one TXT record:
- name `colormix-app.example.com`, type `A`, data `217.197.91.145`
- name `colormix-app.example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
- name `colormix-app.example.com`, type `TXT`, data `colormix.frida.codeberg.page`
- name `colormix-app.example.com`, type `A`, data `217.197.91.145`
- name `colormix-app.example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
- name `colormix-app.example.com`, type `TXT`, data `colormix.frida.codeberg.page`
### Project site, apex domain
In this case, we want our *Project* pages available at the URL `https://example.com`.
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.
This would be incompatible with using the apex `example.com` for other purposes, e.g. for the _Personal_/_Organization_ example discussed before.
{% endadmonition %}
@ -266,10 +271,11 @@ pages.colormix.frida.codeberg.page
For the DNS configuration, CNAME SHOULD NOT be used:
- if ALIAS can be used, two DNS records will be needed:
- name `example.com`, type `ALIAS`, data `codeberg.page`
- name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`
- name `example.com`, type `ALIAS`, data `codeberg.page`
- name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`
- otherwise, A/AAAA records must be used, together with one TXT record:
- name `example.com`, type `A`, data `217.197.91.145`
- name `example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
- name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`
- name `example.com`, type `A`, data `217.197.91.145`
- name `example.com`, type `AAAA`, data `2001:67c:1401:20f0::1`
- name `example.com`, type `TXT`, data `colormix.frida.codeberg.page`

115
content/codeberg-translate/getting-started.md
View file

@ -1,56 +1,59 @@
---
eleventyNavigation:
key: CodebergTranslateGettingStarted
title: Getting started
parent: CodebergTranslate
---
This article will guide you, how to integrate Weblate with Codeberg.
## Projects and Components
The first thing you might notice, is that Weblate has Projects and Components. A Component is something that can be translated e.g. a Software or a Documentation. A Project is a Collection of Components that belong to the same thing.
e.g. You have a Software and the corresponding Documentation. Both use different translation systems. So you add a Project for your Software and one Component for the Software itself and another one for the Documentation.
In simple cases you only need one Component in a Project.
## Create a new Project
On [Codeberg Translate](https://translate.codeberg.org/) log in with your Codeberg Account. Now click on "+" and select "Add new translation project".
Now just enter some Metadata such as the Name, the URL slug (This is just the URL you find your projects. You project will live under the URL `https://translate.codeberg.org/projects/<your slug>`), the Link to the Website (if you
don't have one, just use the URL of your Codeberg Repo) and some instructions, how this Project should be translated (can be empty). This are just Metadata. They have no meaning, when you connect to your Codeberg Repo later.
Click on "Save" and you are done.
## Add a Component
You now see your new project with no components at all. Now let's add a Component.
1. First click on the "Add new translation component" Button. You should see this Page.
<picture>
<source srcset="/assets/images/codeberg-translate/getting-started/add-component.webp" type="image/webp">
<img src="/assets/images/codeberg-translate/getting-started/add-component.png" alt="Image the add component page">
</picture>
2. Now enter the following:
- Name: The Name of your Component. You can choose freely.
- URL slug: The URL, you can find your Component (`https://translate.codeberg.org/projects/<your project>/<your component slug>`)
- Source language: If the source language of your Project is not English, select it here.
- Source code repository: The URL to your Codeberg Repo e.g. `https://codeberg.org/Codeberg/Documentation`. If you already have a component, that uses this Repo, use `weblate://<project>/<component>` to link it with the existing component instead.
Leave the rest as it is and click "Continue". Weblate will now scan your Repo and you should see something like this:
<picture>
<source srcset="/assets/images/codeberg-translate/getting-started/add-component-choose.webp" type="image/webp">
<img src="/assets/images/codeberg-translate/getting-started/add-component.choose.png" alt="Image the add component page">
</picture>
Weblate have searched your Repo for common translation structures and presents you what was found. If you select one, Weblate will set some settings automatically. You can change them later or fully configure
the component manually. Please note, that one Component only works with one translation system in one directory. If you have multiple, you need to add multiple components.
1. On the following page, you should select "Gitea pull request" under "Version control system", so Weblate will create a new PR to submit changes to your Repo.
If you haven't selected a Configuration from Weblate, visit [Manual Component configuration](/codeberg-translate/manual-component-configuration).
Now you should just select a Translation License and click "Save". Now you are done on the Weblate side.
2. On the Codeberg side, open your Repo settings and go the Webhooks. Now click "Add Webhook" and select "Gitea" from the drop down. Under "Target URL" enter `https://translate.codeberg.org/hooks/gitea` and click
"Add Webhook". Now Codeberg will notify Weblate about changes in your Repo, so it will be automatically updated.
Now you can share to the Link to Weblate to your translators.
## Commit translations to Codeberg
To commit the translations from your Component to Codeberg, go to your Component>Manage>Repository Maintance and click on "Push"
---
eleventyNavigation:
key: CodebergTranslateGettingStarted
title: Getting started
parent: CodebergTranslate
---
This article will guide you, how to integrate Weblate with Codeberg.
## Projects and Components
The first thing you might notice, is that Weblate has Projects and Components. A Component is something that can be translated e.g. a Software or a Documentation. A Project is a Collection of Components that belong to the same thing.
e.g. You have a Software and the corresponding Documentation. Both use different translation systems. So you add a Project for your Software and one Component for the Software itself and another one for the Documentation.
In simple cases you only need one Component in a Project.
## Create a new Project
On [Codeberg Translate](https://translate.codeberg.org/) log in with your Codeberg Account. Now click on "+" and select "Add new translation project".
Now just enter some Metadata such as the Name, the URL slug (This is just the URL you find your projects. You project will live under the URL `https://translate.codeberg.org/projects/<your slug>`), the Link to the Website (if you
don't have one, just use the URL of your Codeberg Repo) and some instructions, how this Project should be translated (can be empty). This are just Metadata. They have no meaning, when you connect to your Codeberg Repo later.
Click on "Save" and you are done.
## Add a Component
You now see your new project with no components at all. Now let's add a Component.
1. First click on the "Add new translation component" Button. You should see this Page.
<picture>
<source srcset="/assets/images/codeberg-translate/getting-started/add-component.webp" type="image/webp">
<img src="/assets/images/codeberg-translate/getting-started/add-component.png" alt="Image the add component page">
</picture>
2. Now enter the following:
- Name: The Name of your Component. You can choose freely.
- URL slug: The URL, you can find your Component (`https://translate.codeberg.org/projects/<your project>/<your component slug>`)
- Source language: If the source language of your Project is not English, select it here.
- Source code repository: The URL to your Codeberg Repo e.g. `https://codeberg.org/Codeberg/Documentation`. If you already have a component, that uses this Repo, use `weblate://<project>/<component>` to link it with the existing component instead.
Leave the rest as it is and click "Continue". Weblate will now scan your Repo and you should see something like this:
<picture>
<source srcset="/assets/images/codeberg-translate/getting-started/add-component-choose.webp" type="image/webp">
<img src="/assets/images/codeberg-translate/getting-started/add-component.choose.png" alt="Image the add component page">
</picture>
Weblate have searched your Repo for common translation structures and presents you what was found. If you select one, Weblate will set some settings automatically. You can change them later or fully configure
the component manually. Please note, that one Component only works with one translation system in one directory. If you have multiple, you need to add multiple components.
1. On the following page, you should select "Gitea pull request" under "Version control system", so Weblate will create a new PR to submit changes to your Repo. If you haven't selected a Configuration from Weblate, visit [Manual Component configuration](/codeberg-translate/manual-component-configuration). Now you should just select a Translation License and click "Save". Now you are done on the Weblate side.
2. On the Codeberg side, open your Repo settings and go the Webhooks. Now click "Add Webhook" and select "Gitea" from the drop down. Under "Target URL" enter `https://translate.codeberg.org/hooks/gitea` and click "Add Webhook". Now Codeberg will notify Weblate about changes in your Repo, so it will be automatically updated.
Now you can share to the Link to Weblate to your translators.
## Commit translations to Codeberg
To commit the translations from your Component to Codeberg, go to your Component>Manage>Repository Maintenance and click on "Push"

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

@ -13,6 +13,7 @@ These documentation pages contain information on how you can use [Codeberg Trans
{%- 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>
@ -27,4 +28,4 @@ These documentation pages contain information on how you can use [Codeberg Trans
</table>
{% endif %}
{% endif %}
{%- endfor %}
{%- endfor %}

4
content/codeberg-translate/introduction-to-weblate.md
View file

@ -8,12 +8,14 @@ eleventyNavigation:
Codeberg hosts it's own [Weblate](https://weblate.org) Instance to help Codeberg users localize their software. This service is called [Codeberg Translate](https://translate.codeberg.org/)
## What is Weblate?
When you write software, a website, documentation or something else, you may want to translate it, so it can be used by others, who do not speak English. But you are facing a problem: You don't speak all languages in the world.
Thankfully, there are a lot of native speakers who want to translate things in their language. But not all of those translators are coders, so you can't expect them to go to your your repository, fork it, edit the code to add the language
Thankfully, there are a lot of native speakers who want to translate things in their language. But not all of those translators are coders, so you can't expect them to go to your your repository, fork it, edit the code to add the language
and create a pull request. To solve this problem, software like Weblate exists. It provides a easy to use GUI for translators. They just see the English (or the other language you use as a base) texts and can write the translation. They don't need
to take a look at the code at all, so everyone, not only coders, can translate your software.
## Do I need to change my code?
You can't give Weblate your code and it magically makes it translatable. You need to use an existing translation system such as gettext or Qt Linguist. Which one you should use depends on your used language and toolkit. Take a look at their
documentation to learn more. You should end up with a directory which contains the different translations. Each language should have its own file. e.g. `de.po` for gettext. After that you give Weblate a link to your repository and basically
just say, my translations are in this directory and I'm using this format. Weblate does the rest.

73
content/codeberg-translate/manual-component-configuration.md
View file

@ -1,33 +1,40 @@
---
eleventyNavigation:
key: CodebergTranslateManualComponentConfiguration
title: Manual Component configuration
parent: CodebergTranslate
---
This article will teach how, how to manually configure a Weblate component, in case, it's not working automatically. You will not need this in most cases.
## What is monolingual and bilingual?
Weblate differs into 2 translation formats: monolingual and bilingual.
#### Bilingual
Bilingual means, that the source text live inside the code. See for example the following example from gettext:
```c
printf(_("This is some text"))
```
That means you have language file for the source text. Rather, the source text is in all translation files itself as reference.
#### Monolingual
With Monolingual, you have a extra translation file for your source language.
## Where can I find these Options:
When creating a new Component, you will land on a Page where you can enter them. For existing Components, go to the Component Manage>Settings>Files.
## Configuration options
You have the following options to configure the component:
File format: Choose one of the available formats
File mask: This is the path, in which your translations will be placed `*` is the placeholder for the language. e.g. if you enter `translations/*.ts`, a German translation would be placed as `translations/de.ts`.
Monolingual base language file: If you have a Monolingual format, enter the path to your source file here. If not, leave empty.
Edit base file: If you enable this, the source file can be edited in Weblate. If not ticked, it is read only in Weblate. Only available for monolingual formats.
Adding new translation: You can choose, what happens, if a User wan's to add a new language. The Options should be self-explanatory.
Template for new translations: If you choose "Create new language file" in the Box above, this file will be used as a template.
---
eleventyNavigation:
key: CodebergTranslateManualComponentConfiguration
title: Manual Component configuration
parent: CodebergTranslate
---
This article will teach how, how to manually configure a Weblate component, in case, it's not working automatically. You will not need this in most cases.
## What is monolingual and bilingual?
Weblate differs into 2 translation formats: monolingual and bilingual.
#### Bilingual
Bilingual means, that the source text live inside the code. See for example the following example from gettext:
```c
printf(_("This is some text"))
```
That means you have language file for the source text. Rather, the source text is in all translation files itself as reference.
#### Monolingual
With Monolingual, you have a extra translation file for your source language.
## Where can I find these Options:
When creating a new Component, you will land on a Page where you can enter them. For existing Components, go to the Component Manage>Settings>Files.
## Configuration options
You have the following options to configure the component:
File format: Choose one of the available formats
File mask: This is the path, in which your translations will be placed `*` is the placeholder for the language. e.g. if you enter `translations/*.ts`, a German translation would be placed as `translations/de.ts`.
Monolingual base language file: If you have a Monolingual format, enter the path to your source file here. If not, leave empty.
Edit base file: If you enable this, the source file can be edited in Weblate. If not ticked, it is read only in Weblate. Only available for monolingual formats.
Adding new translation: You can choose, what happens, if a User wan's to add a new language. The Options should be self-explanatory.
Template for new translations: If you choose "Create new language file" in the Box above, this file will be used as a template.

19
content/collaborating/citable-code.md
View file

@ -7,24 +7,27 @@ eleventyNavigation:
The easiest way to refer to your code is to send/post the URL of your repository. However, if you need to reliably refer to a specific version of your code in the long run, for example for scientific writing, this is not really viable, because URLs can change.
Another possibility is to download your repository as a ZIP or TAR.GZ archive (see section Clone in [Clone & Commit via Web](/git/clone-commit-via-web)) and share this file.
The third option, which actually complements the second, is to assign a [Digital Object Identifier](https://www.doi.org/) (DOI) to your code. Having a DOI for your code means that everybody can cite your code using this *standard* and *permanent identifier*. Assigning a DOI for citation is routine in the academic world.
The third option, which actually complements the second, is to assign a [Digital Object Identifier](https://www.doi.org/) (DOI) to your code. Having a DOI for your code means that everybody can cite your code using this _standard_ and _permanent identifier_. Assigning a DOI for citation is routine in the academic world.
This page will show you how to do just that. The process can be decomposed in four steps.
## Create a release of your repository
Creating a release is optional, but recommended. A release will make it clear what version of your code you want to share/cite. Any further edits to your code will not be included in the release. In other words, it's good practice to share/cite a release with fixed code rather than the always changing code of your repository.
You can find instructions on the [Tags and Releases article](/git/using-tags/#creating-tags-and-releases).
## Download the ZIP archive
If you created a release, download the ZIP archive of the source code on the `Releases` tab of your repository, as shown in the previous screenshot.
If not, you can simply download the ZIP archive of the repository (see section Clone in [Clone & Commit via Web](/git/clone-commit-via-web)).
## Upload the ZIP archive to an online repository
There are many online repositories made specifically for research, e.g. [Zenodo](https://zenodo.org/), [Figshare](https://figshare.com/), [Dryad](https://datadryad.org/), and [OSF](https://osf.io/). Others might be more appropriate for other uses.
Upload the ZIP archive to one of them, and follow the steps there to assign a DOI. Be sure that you add the URL of your Codeberg repository in the information of the record on the online repository, so that everyone accessing the record can easily find your Codeberg repository (and you!). In general, add as much information as applicable.
There are many online repositories made specifically for research, e.g. [Zenodo](https://zenodo.org/), [Figshare](https://figshare.com/), [Dryad](https://datadryad.org/), and [OSF](https://osf.io/). Others might be more appropriate for other uses.
Upload the ZIP archive to one of them, and follow the steps there to assign a DOI. Be sure that you add the URL of your Codeberg repository in the information of the record on the online repository, so that everyone accessing the record can easily find your Codeberg repository (and you!). In general, add as much information as applicable.
{% admonition "info" %}
@ -33,9 +36,11 @@ It should be possible to write an integration between Codeberg and one of the DO
{% endadmonition %}
## Share the DOI
Finally, get the DOI from the online repository. This is the permanent URL you can share and use for citation in scientific writing.
A DOI has the form `https://doi.org/repoID/recordID`. It has three parts:
* `https://doi.org`, the *proxy* is always there as is. It is sometimes omitted for compactness.
* `repoID`, the *prefix* is specific to the online repository. Its format is usually `10.XXXX`.
* `recordID`, the *suffix* identifies your record. Its format is specific to the online repository.
- `https://doi.org`, the _proxy_ is always there as is. It is sometimes omitted for compactness.
- `repoID`, the _prefix_ is specific to the online repository. Its format is usually `10.XXXX`.
- `recordID`, the _suffix_ identifies your record. Its format is specific to the online repository.

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

@ -7,6 +7,7 @@ eleventyNavigation:
---
## What is an organization?
An organization is a group of users that have access to a shared account. As such, they can all access the different repositories of the organization. An organization can be composed of several teams, each having a defined role in the project's development and also different access rights. This makes organizations an easy and powerful tool to collaborate on a project.
Everyone can create organizations on Codeberg for free. The following sections will show you how to create and manage an organization.
@ -18,6 +19,7 @@ Details about the roles involved (owner, admin, member, etc) are given in the se
{% endadmonition %}
## Create an Organization
On your Dashboard, click on the `+` next to your avatar and select `New Organization`:
<picture>
@ -27,7 +29,7 @@ On your Dashboard, click on the `+` next to your avatar and select `New Organiza
In the new page, choose a name for your organization (here we choose `PolarClub`) and select its visibility. Finally, choose what the administrators of repositories can do; if the box is ticked, repository administrators will be able to grant any team access to the repository (see [Access rights](#access-rights) below for details on repository administrators).
Confirm by clicking `Create Organization`:
Confirm by clicking `Create Organization`:
<picture>
<source srcset="/assets/images/collaborating/create-organization/create-orga.webp" type="image/webp">
@ -37,6 +39,7 @@ Confirm by clicking `Create Organization`:
You're now directed to the organization's dashboard.
## Switch between your personal account and the organization
On the dashboard, click on the avatar on the left and select the context (personal account or organization) you want to work with. Alternatively, switch between your repositories or your organizations tabs on the right side.
<picture>
@ -45,6 +48,7 @@ On the dashboard, click on the avatar on the left and select the context (person
</picture>
## View organization
The organization's dashboard gives you an overview of the organization:
<picture>
@ -62,6 +66,7 @@ If you click on the `View [organization]` (here `PolarClub`, you'll be directed
From here, you can access all repositories (there's currently none here) and create new ones. There's a list of all the members (`People`) and teams; in this example, there is only one member (Knut the polar bear), and one team (`Owners`) with one member (yourself) and no repositories.
## Edit organization
The cog next to the organization's name will lead you to its settings:
<picture>
@ -83,7 +88,8 @@ In the `Labels` tab, you can create labels that will be used across all reposito
In the top right corner, you have access to the members and teams of your organization. These can also be accessed from the organization's page.
## Teams
The `Teams` tab gives you an overview of all the teams, their members and their number of repositories. You can also join a team from here if you have the permission to do so:
The `Teams` tab gives you an overview of all the teams, their members and their number of repositories. You can also join a team from here if you have the permission to do so:
<picture>
<source srcset="/assets/images/collaborating/create-organization/teams.webp" type="image/webp">
@ -100,7 +106,7 @@ Click the `+ New Team` button to create a new team. Now, in the new page, you ca
</picture>
You can choose whether members of the team can only access some repositories explicitly added to the team, or whether they can access all repositories of the organization.
You can also allow members to be able to create new repositories on behalf of the organization.
You can also allow members to be able to create new repositories on behalf of the organization.
If you have allowed repository administrators to grant or remove access for teams (see [Create an Organization](#create-an-organization) above), they can do so in the `Settings → Collaborators` tab of the repository.
If you allow either `Read` or `Write` access, you can additionally set which sections of the repositories (code, issues, pull requests, releases and wiki) the members will have (read or write) access to. On the other hand, `Administrator Access` automatically grants read and write access to all sections; this part of the page is hidden in this case.
See the section [Access rights](#access-rights) below for details.
@ -116,6 +122,7 @@ Click on `Settings` to edit the team as shown above for the creation of a team.
This is also where you can add or remove members to/from a team, and assign repositories to them.
## People
On the `People` tab, you can get an overview of all the people who belong to your organization:
<picture>
@ -123,7 +130,7 @@ On the `People` tab, you can get an overview of all the people who belong to you
<img src="/assets/images/collaborating/create-organization/people.png" alt="people">
</picture>
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.
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.
@ -132,18 +139,19 @@ The visibility of the members can also be edited here; `Hidden` means that the m
<img src="/assets/images/collaborating/create-organization/profile.png" alt="profile">
</picture>
Shown here is also whether or not each member has activated two-factor authentication (2FA, see [Setting up Two-factor Authentication](/security/2fa)).
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).
Members of the "Owners" team can do everything that admins can do. However, only owners of the organization can manage the organization, which includes:
- edit/delete the organization,
- add/remove members and teams,
- define access rights of teams,
- edit organization repository settings in the danger zone (i.e. transfer ownership, delete wiki data and repository, and archive repository).
When owners allow members of a team to be able to create new repositories for the organization (see box "Create repositories" in [Teams](#teams) settings), the member who creates the repository will be added as a collaborator with administrator rights to this repository (see [Invite Collaborators](/collaborating/invite-collaborators) for details).
When owners allow members of a team to be able to create new repositories for the organization (see box "Create repositories" in [Teams](#teams) settings), the member who creates the repository will be added as a collaborator with administrator rights to this repository (see [Invite Collaborators](/collaborating/invite-collaborators) for details).

5
content/collaborating/index.md
View file

@ -6,7 +6,7 @@ eleventyNavigation:
order: 20
---
These documentation pages contain detailed information on how you can collaborate
These documentation pages contain detailed information on how you can collaborate
on Codeberg, for example, [by making Pull Requests](/collaborating/pull-requests-and-git-flow).
If you're new to Codeberg or software forges in general, please also have a look at
@ -17,6 +17,7 @@ issue tracking and wikis on Codeberg.
{%- 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>
@ -31,4 +32,4 @@ issue tracking and wikis on Codeberg.
</table>
{% endif %}
{% endif %}
{%- endfor %}
{%- endfor %}

6
content/collaborating/invite-collaborators.md
View file

@ -7,12 +7,14 @@ eleventyNavigation:
---
## Why invite collaborators?
If your project repository is public (see [Your First Repository](/getting-started/first-repository) on how to set up the visibility of a repository), everyone can see your repository, and every Codeberg user can contribute through issues and pull requests. This is contributing, but not collaborating, since you're still the only one who can *directly* commit changes to your repository.
On the other hand, if your repository is private, only you, your collaborators and the members of your organization (depending on their permissions, see [Create and Manage an Organization](/collaborating/create-organization)) can access your repository. In other words, if you want Codeberg users outside of your organization to be able to work with you on your project, you have to grant them access to your repository by adding them as *collaborators*.
If your project repository is public (see [Your First Repository](/getting-started/first-repository) on how to set up the visibility of a repository), everyone can see your repository, and every Codeberg user can contribute through issues and pull requests. This is contributing, but not collaborating, since you're still the only one who can _directly_ commit changes to your repository.
On the other hand, if your repository is private, only you, your collaborators and the members of your organization (depending on their permissions, see [Create and Manage an Organization](/collaborating/create-organization)) can access your repository. In other words, if you want Codeberg users outside of your organization to be able to work with you on your project, you have to grant them access to your repository by adding them as _collaborators_.
It is important to understand that only registered Codeberg users can contribute. If you want a colleague or friend to work with you, you first have to make sure they have a Codeberg account (see [Your First Steps on Codeberg](/getting-started/first-steps)).
## Add a collaborator
To add a user to a repository as a collaborator, first go to the settings of your repository.
<picture>

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

@ -1,84 +1,84 @@
---
eleventyNavigation:
key: PullRequestsGitFlow
title: Pull requests and Git flow
parent: Collaborating
order: 20
---
## Benefits of a pull-request based workflow
> ***TLDR:*** *Keep an eye on your repository and organization permissions. Don't take sweets from strangers. Use pull requests. Easy to review, easy to manage, and only the project maintainers/owners have permission to merge them.*
Although it is perfectly possible to use a Git project on Codeberg just as single shared central repository for individuals and teams, a collaborative workflow based on pull requests provides many benefits:
- The "hot" project repository requires only very few maintainers with full rights to sign off pull requests. Contributors can easily work on forked repositories.
- Each pull request collects the full edit history for a fix or feature branch. Contributors can squash this, or keep it, just as they prefer.
### Cheat sheet
Let's say, you would like to contribute to our "examples" project [knut/examples](https://codeberg.org/knut/examples).
First, fork the project you would like to work on, by clicking the `Fork` button in the top-right corner of the project page:
![Fork a project](/assets/images/collaborating/pull-requests-and-git-flow/fork-button.png)
Then, clone it onto your local machine. We assume that [you have set up your SSH keys](/security/ssh-key). This has to be done only once:
```shell
git clone git@codeberg.org:<YOURCODEBERGUSERNAME>/examples.git
```
Now, let's create a feature branch, do some changes, commit, push, edit, commit, push, ..., edit, commit, push:
```shell
git checkout -b my_cool_feature_branch
# do some changes
git commit -m "first feature"
git push # here you get asked to set your upstream URL, just confirm
# do more work, edit...
git add new_file.png
git commit -m "second feature introducing a new file"
git push
# ...
git commit -m "more work, tidy-up"
git push
```
Now you can create a pull request by selecting your feature branch, and clicking on the pull request button:
![Create a pull request](/assets/images/collaborating/pull-requests-and-git-flow/pull-request-button.png)
### Keep it up-to-date: rebase pull requests to upstream
Sometimes the upstream project repository is evolving while we are working on a feature branch, and we need to rebase and resolve merge conflicts for upstream changes into our feature branch. This is not hard:
In order to track the `upstream` repository, we'll add a second remote that is pointing to the original project. This has to be done only once:
```shell
git remote add upstream git@codeberg.org:knut/examples.git
```
You can also use the SSH variant here for public projects, if you want to be
able to pull without specifying your credentials.
Now, let's pull from `upstream`, and rebase our local branch against the latest `HEAD` of the upstream project repository (e.g. the `main` branch):
```shell
git pull --rebase upstream main
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.
## 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`. In some cases, this is a useful feature
(for example to undo accidental commits or clean up PRs),
but in most cases a transparent history based on a pull-request based workflow is surely preferable,
especially for the default branches of your project where other people rely on intact history.
**Warning** If you accidentally leaked sensitive data, say, leaked credentials,
keep in mind that commits stay directly accessible, e.g. from the user
activity tab or a Pull Request feed, for a while.
Please contact us if you really need to remove such data from the public.
---
eleventyNavigation:
key: PullRequestsGitFlow
title: Pull requests and Git flow
parent: Collaborating
order: 20
---
## Benefits of a pull-request based workflow
> **_TLDR:_** _Keep an eye on your repository and organization permissions. Don't take sweets from strangers. Use pull requests. Easy to review, easy to manage, and only the project maintainers/owners have permission to merge them._
Although it is perfectly possible to use a Git project on Codeberg just as single shared central repository for individuals and teams, a collaborative workflow based on pull requests provides many benefits:
- The "hot" project repository requires only very few maintainers with full rights to sign off pull requests. Contributors can easily work on forked repositories.
- Each pull request collects the full edit history for a fix or feature branch. Contributors can squash this, or keep it, just as they prefer.
### Cheat sheet
Let's say, you would like to contribute to our "examples" project [knut/examples](https://codeberg.org/knut/examples).
First, fork the project you would like to work on, by clicking the `Fork` button in the top-right corner of the project page:
![Fork a project](/assets/images/collaborating/pull-requests-and-git-flow/fork-button.png)
Then, clone it onto your local machine. We assume that [you have set up your SSH keys](/security/ssh-key). This has to be done only once:
```shell
git clone git@codeberg.org:<YOURCODEBERGUSERNAME>/examples.git
```
Now, let's create a feature branch, do some changes, commit, push, edit, commit, push, ..., edit, commit, push:
```shell
git checkout -b my_cool_feature_branch
# do some changes
git commit -m "first feature"
git push # here you get asked to set your upstream URL, just confirm
# do more work, edit...
git add new_file.png
git commit -m "second feature introducing a new file"
git push
# ...
git commit -m "more work, tidy-up"
git push
```
Now you can create a pull request by selecting your feature branch, and clicking on the pull request button:
![Create a pull request](/assets/images/collaborating/pull-requests-and-git-flow/pull-request-button.png)
### Keep it up-to-date: rebase pull requests to upstream
Sometimes the upstream project repository is evolving while we are working on a feature branch, and we need to rebase and resolve merge conflicts for upstream changes into our feature branch. This is not hard:
In order to track the `upstream` repository, we'll add a second remote that is pointing to the original project. This has to be done only once:
```shell
git remote add upstream git@codeberg.org:knut/examples.git
```
You can also use the SSH variant here for public projects, if you want to be
able to pull without specifying your credentials.
Now, let's pull from `upstream`, and rebase our local branch against the latest `HEAD` of the upstream project repository (e.g. the `main` branch):
```shell
git pull --rebase upstream main
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.
## 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`. In some cases, this is a useful feature
(for example to undo accidental commits or clean up PRs),
but in most cases a transparent history based on a pull-request based workflow is surely preferable,
especially for the default branches of your project where other people rely on intact history.
**Warning** If you accidentally leaked sensitive data, say, leaked credentials,
keep in mind that commits stay directly accessible, e.g. from the user
activity tab or a Pull Request feed, for a while.
Please contact us if you really need to remove such data from the public.

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

@ -13,11 +13,12 @@ You can assign teams different levels of permission for each unit (e.g. issues,
## Profile and Visibility
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 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 "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 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".
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 *not logged in* will get a [404 error](https://en.wikipedia.org/wiki/HTTP_404) if they try to access your repository — it will seem as if it does not exist at all!
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 _not logged in_ will get a [404 error](https://en.wikipedia.org/wiki/HTTP_404) if they try to access your repository — it will seem as if it does not exist at all!
<picture>
<source srcset="/assets/images/collaborating/repo-permissions/user-settings-privacy-limited.webp" type="image/webp">
@ -28,101 +29,100 @@ The visibility of your profile can be changed in the [Privacy settings](https://
There are four permission levels: **Read**, **Write**, **Administrator** and **Owner**.
By default, the person who creates a repository is an ***Owner***.
By default, the person who creates a repository is an **_Owner_**.
The table below gives an overview of what collaborators are allowed to do when granted each of these permission levels:
<table class="table">
<thead>
<tr>
<th> Task </th>
<th> Read </th>
<th> Write</th>
<th> Admin </th>
<th> Owner </th>
</thead>
<tbody>
<tr>
<td> View, clone and pull repository </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Contribute pull requests </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Push to/update contributed pull requests </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Push directly to repository </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Merge pull requests </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Moderate/delete issues and comments </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Force-push/rewrite history (if enabled) </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Add/remove collaborators to repository </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Configure branch settings (protect/unprotect, enable force-push) </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<tr>
<td> Configure repository settings (enable wiki, issues, PRs, update profile) </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Configure repository settings in the danger zone (transfer ownership, delete wiki data / repository, archive repository) </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
</tr>
</tbody>
<thead>
<tr>
<th> Task </th>
<th> Read </th>
<th> Write</th>
<th> Admin </th>
<th> Owner </th>
</tr>
</thead>
<tbody>
<tr>
<td> View, clone and pull repository </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Contribute pull requests </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Push to/update contributed pull requests </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Push directly to repository </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Merge pull requests </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Moderate/delete issues and comments </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Force-push/rewrite history (if enabled) </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Add/remove collaborators to repository </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Configure branch settings (protect/unprotect, enable force-push) </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<tr>
<td> Configure repository settings (enable wiki, issues, PRs, update profile) </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Configure repository settings in the danger zone (transfer ownership, delete wiki data / repository, archive repository) </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
</tbody>
</table>
## Teams
The permissions for teams are quite configurable. You can specify which repositories a team has access to; therefore, you can specify for each unit (Code Access, Issues, Releases) a different permission level.

25
content/collaborating/resolve-conflicts.md
View file

@ -21,7 +21,7 @@ An issue in the Gitea upstream repository of Forgejo, [#9014](https://github.com
If you want to skip the setup of the examples, you can skip to the sections explaining the resolutions:
- [Resolving the conflict (in files)](#resolving-the-conflict)
- [Resolving the conflict (in files)](#resolving-the-conflict)
- [Resolving the conflict (of deleted files)](#conflict-and-resolution)
## Example of a conflict, and its resolution
@ -53,7 +53,7 @@ In the `README.md` file, we change the line
An example repository for Codeberg Docs.
```
to
to
```
An example repository for [Codeberg Docs](https://docs.codeberg.org).
@ -63,7 +63,7 @@ Now, we'll add the change to our branch:
```shell
git add README.md
git commit -m "Added link to Codeberg docs in README"
git commit -m "Added link to Codeberg docs in README"
```
We will leave the branch. We won't merge it into `main` just yet.
@ -124,6 +124,7 @@ git merge update-last-sentence-in-readme
```
As expected there is a conflict:
```
$ git merge update-last-sentence-in-readme
Auto-merging README.md
@ -142,7 +143,7 @@ You have unmerged paths.
Unmerged paths:
(use "git add <file>..." to mark resolution)
both modified: README.md
both modified: README.md
no changes added to commit (use "git add" and/or "git commit -a")
```
@ -156,9 +157,9 @@ index 616dc84,088249f..0000000
+++ b/README.md
@@@ -1,3 -1,3 +1,7 @@@
![](https://docs.codeberg.org/assets/images/getting-started/knut.svg)
++<<<<<<< HEAD
+An example repository for [Codeberg Docs](https://docs.codeberg.org).
+An example repository for [Codeberg Docs](https://docs.codeberg.org).
++=======
+ An example repository to use with the Codeberg Documentation.
++>>>>>>> update-last-sentence-in-readme
@ -214,9 +215,9 @@ index 616dc84,088249f..0000000
+++ b/README.md
@@@ -1,3 -1,3 +1,3 @@@
![](https://docs.codeberg.org/assets/images/getting-started/knut.svg)
- An example repository for [Codeberg Docs](https://docs.codeberg.org).
-An example repository to use with the Codeberg Documentation.
- An example repository to use with the Codeberg Documentation.
++An example repository to use with the [Codeberg Documentation](https://docs.codeberg.org).
```
@ -252,7 +253,7 @@ Author: Knut <knut@...>
Date: Sat May 21 18:29:15 2022 +0200
Added link to Codeberg docs to README
```
Note the line starting with `Merge`; it includes the commit IDs of the two merged commits.
@ -290,6 +291,7 @@ We won't merge this branch yet.
### Editing the file
First switch back to the main branch.
```shell
git switch main
```
@ -306,6 +308,7 @@ git commit -m "added repository url to README.md"
### Merging the first branch
Again, switch back to the main branch.
```shell
git switch main
```
@ -337,7 +340,7 @@ You have unmerged paths.
Unmerged paths:
(use "git add/rm <file>..." as appropriate to mark resolution)
deleted by us: README.md
deleted by us: README.md
no changes added to commit (use "git add" and/or "git commit -a")
```
@ -367,4 +370,4 @@ As with before, issuing `git commit` without any comment will open your default
- Try to avoid using `git push -f` on the target branch.
- Ensure that all branches are pushed to a remote repository before trying to resolve a conflict, as it makes it easier to start over in case you run into a problem.
- Search for `<<<<<<<`, `=======` and `>>>>>>>` in the resolved files, in order to not leave a conflict description in your files.
- Search for `<<<<<<<`, `=======` and `>>>>>>>` in the resolved files, in order to not leave a conflict description in your files.

9
content/contact.md
View file

@ -12,7 +12,6 @@ We recommend to follow us on [Mastodon](https://social.anoxinon.de/@Codeberg).
You can also [check out our blog](https://blog.codeberg.org).
Also check out the Matrix Channels mentioned below!
## Questions and Issues
Codeberg relies on community members helping each other via public spaces.
@ -36,7 +35,6 @@ There's a large and active community of users on Matrix. Codeberg's [Matrix chat
You can also join an unofficial (community-maintained) `#codeberg` IRC channel on [libera.chat](https://libera.chat). There's much less activity than on Matrix.
## Contacting Codeberg e.V.
### Email
@ -57,7 +55,6 @@ If you still need to contact us, please email
double-check if your question can be found in the [FAQ](/getting-started/faq)
or asked via the public channels above.
### Abuse
The preferred way to report content on Codeberg is an email to [abuse@codeberg.org](mailto:abuse@codeberg.org).
@ -67,12 +64,13 @@ should be removed. Providing context helps us act faster.
Another faster method is tagging [@moderation](https://codeberg.org/moderation) in an issue comment,
which we highly recommend for automated spam bots.
When reporting *people*, we recommend making a private report, so as to protect
When reporting _people_, we recommend making a private report, so as to protect
yourself and others from retaliation in extreme cases.
Please keep in mind that we are only responsible for content hosted under the following domains:
- `codeberg.org`
- `codeberg.page` (including custom domains using *Codeberg Pages*)
- `codeberg.page` (including custom domains using _Codeberg Pages_)
- `codeberg-test.org`
- `codeberg.eu`
@ -81,7 +79,6 @@ reports will be investigated and acted upon accordingly,
but due to constrained human resources and the possibility of duplicated reports,
we do not typically find the time to keep you updated about the status of your reports.
### Legal inquiries
For legal inquiries, please refer to the [Imprint](https://codeberg.org/codeberg/org/src/Imprint.md).

2
content/content.11tydata.json
View file

@ -1 +1 @@
{ "layout": "default_layout" }
{ "layout": "default_layout" }

14
content/getting-started/email-settings.md
View file

@ -23,11 +23,11 @@ You can access it by clicking on the menu button “Profile and Settings...” i
In the section “Manage Email Addresses”, you can select one of the following options from the drop-down menu for each email address that you have registered with Codeberg:
| Option | Effect |
|:----------------------------|:---------------------------------------------------------------------------------------------------------------|
| Enable Email Notifications | Enables all notifications (default setting) |
| Only Email on Mention | Codeberg will only send an email to this address if your username is mentioned in an issue or a comment |
| Disable Email Notifications | Codeberg will not send any emails to this address |
| Option | Effect |
| :-------------------------- | :------------------------------------------------------------------------------------------------------ |
| Enable Email Notifications | Enables all notifications (default setting) |
| Only Email on Mention | Codeberg will only send an email to this address if your username is mentioned in an issue or a comment |
| Disable Email Notifications | Codeberg will not send any emails to this address |
When you're finished, press the button “Set Email Preference” to confirm your selection.
@ -39,13 +39,13 @@ Disabling email notifications doesn't mean that you'll stop receiving important
## Issue notifications
As soon as you make a comment on an issue, you automatically subscribe to it. Unless you disabled email notifications for all your email addresses, you will get an email for every change and comment on that issue.
As soon as you make a comment on an issue, you automatically subscribe to it. Unless you disabled email notifications for all your email addresses, you will get an email for every change and comment on that issue.
You can check and modify your issue subscription status under the “Notifications” section on the menu on the right side of the issue screen.
## Watching repositories
When you watch a repository (by clicking on the “Watch” button in a repository), you will receive emails for every change (creation of issues, pull requests, comments, etc.) done in this repository.
When you watch a repository (by clicking on the “Watch” button in a repository), you will receive emails for every change (creation of issues, pull requests, comments, etc.) done in this repository.
To stop watching a repository, simply click on “Unwatch” in a repository.

13
content/getting-started/faq.md
View file

@ -19,7 +19,6 @@ We still invite you to become part of our mission by joining it.
Your membership fee helps to improve the project,
and the distributed voting rights maintain a healthy governance of the project.
### Is Codeberg well funded?
Don't worry, the danger of having Codeberg disappear are low!
@ -44,14 +43,16 @@ Certain tasks are offloaded to other locations and providers,
e.g. [netcup GmbH](https://www.netcup.de/) and [Hetzner Online GmbH](https://www.hetzner.com/).
This is for backups, redundancy, disaster recovery, DDoS protection,
efficiency (using spare resources provided to us) and various other reasons.
We make sure that your data is sufficiently protected and avoid large cloud providers where possible.
We make sure that your data is sufficiently protected and avoid large cloud providers where possible.
### Is Codeberg based on free/libre (and open-source) software?
In short, **yes** — And proudly so! Codeberg uses [Forgejo](https://forgejo.org)
which explicitly uses free software for development.
And you can easily host it yourself!
Some other examples of free software works that we use are:
- [Woodpecker CI](https://woodpecker-ci.org). It powers [Codeberg CI](/ci).
- [Weblate](https://weblate.org). It is what we use for [Codeberg Translate](https://translate.codeberg.org).
- [Codeberg Pages](https://codeberg.page). This is a "homebrewed" piece of
@ -69,6 +70,7 @@ More often than not, we also send patches to upstream projects; that way, we all
## Before I start using Codeberg...
### Can I host software and resources without a free and open-source software license?
Our mission is to support the creation and development of Free Software; therefore we only allow repos licensed under an OSI/FSF-approved license.
For more details see [Licensing article](/getting-started/licensing).
However, we sometimes tolerate repositories that aren't perfectly licensed and focus on spreading awareness on the topic of improper FLOSS licensing and its issues.
@ -86,7 +88,6 @@ Further exceptions are spelled out in our [Terms of Service](https://codeberg.or
If you are still not sure if your usage is allowed or if you require a lot of private space for a Free Software project,
[please send us a formal request](https://codeberg.org/Codeberg-e.V./requests) and we'll have a look.
### What is the size limit for my repositories? Are there quotas for packages, LFS, ...?
Codeberg strives to provide **everyone with the necessary resources** to develop high quality Free/Libre software.
@ -104,12 +105,13 @@ If you intend to use more than:
You should [request these resources first](https://codeberg.org/Codeberg-e.V./requests)!
## I need to request more resources from an administrator. How do I do that?
We have a public repository, [Codeberg-e.V./requests](https://codeberg.org/Codeberg-e.V./requests),
which allows users to issue such requests.
We have some predefined templates that allow you to easily issue requests for the following situations:
- Requesting access to Codeberg's self-hosted CI solution, Woodpecker CI.
- Requesting more storage for a private repository.
- Requesting the increase of the repository limit (100) for a user account or an organization.
@ -118,6 +120,7 @@ If you need anything from us that goes beyond these examples, you may still use
that repository to do so. We will try our best to help!
### Why can't I mirror repositories from other code-hosting websites?
Mirrors that pull content from other code hosting services were problematic for Codeberg.
They ended up consuming a vast amount of resources (traffic, disk space) over time, as
users that were experimenting with Codeberg would not delete those mirrors when leaving.
@ -133,6 +136,7 @@ internal references.
## Using Codeberg
### I removed an object from my repo, why doesn't the reported size shrink?
By default, removing tracked files from Git keeps them in the history.
You'd need to rewrite history and force-push the branch,
or remove all branches your object is included in.
@ -143,4 +147,5 @@ we keep those objects around for approximately 30 days.
Afterwards, they will be removed by the regular Git garbage collector on our servers.
### What is the size limit for my avatar?
You can upload avatar pictures of up to 1 MB and a resolution of 1024x1024.

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

@ -38,7 +38,7 @@ Here's an explanation of the form's fields:
- **Owner** Here, you can specify whether you want this to be your own personal project or whether you want it to be part of an organization that you're a part of
- **Repository name** A name for your repository (which will also be part of its path, in this case `https://codeberg.org/knut/foobar`)
- **Visibility** Repositories are either *public* or *private*, where public means that everyone will be able to access your repository, while your private repositories can only be accessed by you and your collaborators (see [Invite Collaborators](/collaborating/invite-collaborators))
- **Visibility** Repositories are either _public_ or _private_, where public means that everyone will be able to access your repository, while your private repositories can only be accessed by you and your collaborators (see [Invite Collaborators](/collaborating/invite-collaborators))
- **Description** A short description that appears next to your repository's name where appropriate
- **Template** Occasionally you may want to generate your repository from an existing template. In that case, you can specify that template here. Otherwise, simply leave this field empty.
- **Issue Labels** If you want to initialize your project's issue tracker with a set of labels that you can use to categorize issues, you can choose one here. You don't have to choose this right away though, as you can choose and modify issue labels at a later time as well.
@ -65,15 +65,15 @@ Here's what the most important buttons here do:
- **The Repository Tabs (3)** contain links to every important feature within your repository:
- **Code** lets you browse through all versions of your code
- **Issues** is a very important communication tool between you, your users and your contributors. Think of it as part bug-tracker, part forum.
For more information on this, have a look at [The Basics of Issue Tracking](/getting-started/issue-tracking-basics)
For more information on this, have a look at [The Basics of Issue Tracking](/getting-started/issue-tracking-basics)
- **Pull Requests** is where other users can ask you to "pull" in code, from a fork into your program
- **Releases** is a space where you can upload finished versions of your program, e.g. binaries
- **Wiki** is a basic wiki feature built into Forgejo, the software Codeberg is based on
- **Activity** calculates statistics about your repository
- **Your repository's Git URLs (4)** - use these to let Git know where to find your repository. Don't worry if you don't understand this now - we will look at this in the following section.
## Connect a local repository to Codeberg
After creating a new repository, as laid out in the previous section, you can now move on to connect the repository with your local development copy.
In this guide, we'll focus on connecting to Codeberg via HTTP using Git on the command line, but note that there are multiple other ways to connect to Codeberg, as laid out in more detail in the articles:
@ -88,9 +88,11 @@ Although we use HTTP in this Getting Started guide, it is a good idea to [setup
{% endadmonition %}
### Option A: Clone the newly created, empty repository
If you want to start a fresh project (so if you don't already have source code that you want to upload to Codeberg), the quickest way to get started is to clone your newly created repository like this:
#### 1. Navigate to your local workspace (optional)
If you're just getting started, it's a good idea to keep your projects neatly sorted in a dedicated directory, like in this example:
```bash
@ -100,6 +102,7 @@ knut@iceberg:~/repositories$
```
#### 2. Clone the repository
To clone your newly created repository, execute `git clone` with the URL that is shown in your repository:
<picture>
@ -118,6 +121,7 @@ Unpacking objects: 100% (4/4), 11.94 KiB | 764.00 KiB/s, done.
```
#### 3. Navigate to the cloned repository
After cloning, the repository should now be in a new directory with the same name as your repository. In this case, it's called `foobar`.
```bash
@ -126,11 +130,12 @@ knut@iceberg:~/repositories/foobar$ ls
LICENSE README.md
```
### Option B: Connect an existing local source tree
If you already have written source code that you now would like to upload to Codeberg, follow these steps:
#### 1. Initialize a Git Repository
Unless you already have a Git Repository initialized in your local source tree,
run `git init` in your project's directory:
@ -140,6 +145,7 @@ Initialized empty Git repository in /home/knut/my-project/.git/
```
#### 2. Add Codeberg as the repository's origin
Now, you need to tell Git where to push your changes. You would do that by specifying Codeberg as a remote.
{% admonition "tip" %}
@ -159,11 +165,13 @@ When you clone a repository from the Internet, the URL that you got your copy of
{% endadmonition %}
## Making your first commit
Now that you've connected your repository to your local development copy, it's time to make your first commit.
> If you didn't generate the `LICENSE` and `README.md` files when creating the repository, it's a good idea to add them now. Just put them in your local development copy's directory and add them to your commit, as shown below.
#### 1. Create or edit a file
Let's modify the `README.md` file.
> If you didn't generate `README.md`, these commands will still work fine. However, instead of "Hello World!" being at the end of the file, it'll be the only line in the file.
@ -186,7 +194,7 @@ Your branch is up to date with 'origin/main'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: README.md
modified: README.md
no changes added to commit (use "git add" and/or "git commit -a")
```
@ -194,6 +202,7 @@ no changes added to commit (use "git add" and/or "git commit -a")
You can create or modify more files, if you'd like.
#### 2. Add changes to your commit
Next, you should add each modified file that you'd like to add to your commit with `git add`:
```bash
@ -205,6 +214,7 @@ This command should output nothing.
> If you want to add all modified files in your source tree, you can run `git add .` but **be careful** as this might add unwanted files as well, so it's a good idea to double-check by running `git status` before committing.
#### 3. Commit your changes
By committing your changes, you create a new step in the version history of your program. They act like snapshots of your program's state at a given point of time, and you will later be able to jump back and forth between them.
> It is recommended to keep commits small and focused, so that, if necessary, they can be reverted or easily adapted into another context without too many side-effects.
@ -214,7 +224,7 @@ To commit your changes, run `git commit` and specify a commit message; this will
```bash
knut@iceberg:~/repositories/foobar$ git commit -m "My first commit on Codeberg"
[main 1e12979] My first commit on Codeberg
1 file changed, 1 insertion(+)
1 file changed, 1 insertion(+)
```
If you look at the version history of your program using `git log`, you may now see something similar to this:
@ -235,6 +245,7 @@ Date: Sat Sep 26 12:29:57 2020 +0200
```
#### 4. Push your changes to Codeberg
If you're happy with the changes you made, the next step is to present them to the world by pushing them to Codeberg:
```bash
@ -250,20 +261,20 @@ Total 3 (delta 0), reused 0 (delta 0)
remote: . Processing 1 references
remote: Processed 1 references in total
To https://codeberg.org/knut/foobar
c75b509..1e12979 main -> main
c75b509..1e12979 main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.
```
{% admonition "warning" %}
If your local copy of the repository is missing some commits that exist in the remote repository, pushing will result in an error. There are two ways to fix this:
- Run `git pull` to combine your local changes with the changes that exist in the remote repository. If this does not work, please follow the instructions in your terminal.
- If you know what you are doing, you can also overwrite the remote repository using `git -f push`.
This action will **permanently** alter your remote repository and is not suitable if you are working on a project together with other people.
{% endadmonition %}
The `-u` option sets the upstream remote, which we want to be Codeberg.org, as configured previously.
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.
@ -281,21 +292,21 @@ Congratulations - you've just made your first source code contribution on Codebe
### Promote your work
If you want to promote your work you can use [Codeberg's Badge Generator](https://get-it-on.codeberg.org/) to easily generate a badge which links to you repository.
If you want to promote your work you can use [Codeberg's Badge Generator](https://get-it-on.codeberg.org/) to easily generate a badge which links to you repository.
In the badge generator you can edit how the badge should appear. Mainly this is:
- **Claim**: What should be written on the badge above the Codeberg logo. Think of something catchy.
- **Type**: You can choose between three different themes.
- **Background**: Change the background color of your badge to fit to your site.
- **PNG width**: The width of your badge, the generate will automatically scale it with correct proportions.
- **Claim**: What should be written on the badge above the Codeberg logo. Think of something catchy.
- **Type**: You can choose between three different themes.
- **Background**: Change the background color of your badge to fit to your site.
- **PNG width**: The width of your badge, the generate will automatically scale it with correct proportions.
<picture>
<source srcset="/assets/images/getting-started/first-repository/badge-settings.webp" type="image/webp">
<img src="/assets/images/getting-started/first-repository/badge-settings.jpg" alt="Settings in Codeberg's badge generator">
</picture>
Just add the following line as markdown to the site you want to link from:
Just add the following line as markdown to the site you want to link from:
```markdown
[![Get it on Codeberg](your-badge.png)](https://codeberg.org/your-username/your-repo)
@ -305,11 +316,11 @@ or in HTML:
```html
<a href="https://codeberg.org/your-username/your-repo">
<img src="your-badge.png" alt="Get It On Codeberg" width="250"/>
<a/>
<img src="your-badge.png" alt="Get It On Codeberg" width="250" />
<a
/></a>
```
This will result in a badge like this:
<a href="https://codeberg.org/Codeberg/Documentation">

8
content/getting-started/first-steps.md
View file

@ -7,6 +7,7 @@ eleventyNavigation:
---
## Registering at Codeberg.org
To create your account at Codeberg.org, visit [https://codeberg.org](https://codeberg.org)
and click on "Register" to bring up the registration form.
@ -15,8 +16,8 @@ Then, simply fill in your username and email address and then choose a good pass
After confirming your email address by clicking the link in the email we sent you,
you're done and good to go!
## Community
Codeberg is a non-profit volunteer effort. It relies on its friendly and dedicated community. We're happy that you're now a part of our community, too, and we hope you're feeling welcome!
We kindly ask you to be polite and civil when on Codeberg and to not excessively use the resources provided. Please see our [Terms of Use](https://codeberg.org/codeberg/org/src/TermsOfUse.md) for details.
@ -25,8 +26,8 @@ Please remember that everyone here is contributing on their free time, as volunt
If you like a project on Codeberg, consider **giving it a star** and/or **following its author**. This helps with building and growing a network of free software projects and people, and can serve as guidance for users exploring Codeberg, looking for interesting projects to try out or contribute to.
## Orienting yourself on Codeberg
After successfully registering on Codeberg, you should see something similar to this screen:
<picture>
@ -44,8 +45,8 @@ An explanation of the highlighted elements above:
- **Your Avatar (6)** will lead you to a menu, where you can look at your profile, edit your settings, read the documentation of Forgejo (the software Codeberg is based on) or log out.
- **The Dashboard Context Switcher (7)** If you're part of one or more organizations, you can use this context switcher to let the dashboard display information relevant to the organization, rather than your account.
## A word about Security
While it is important to choose a strong password, it is also
important to use Two-Factor Authentication in case your password or device
ever gets compromised, so that should be one of the first things to
@ -61,6 +62,7 @@ Please visit the [guide in the security section](/security/2fa) to learn how to
{% endadmonition %}
## Moving on from here
Now that you have an account on Codeberg, you can choose from a number of possible ways to explore:
- [Create your first repository](/getting-started/first-repository)

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

@ -6,6 +6,7 @@ eleventyNavigation:
order: 10
description: This article shows you how to get started with Codeberg
---
<img src="/assets/images/getting-started/knut.svg" style="float: right; width: 150px; border: none; margin-left: 25px; margin-bottom: 25px;" alt="Knut the Polar Bear">
Hello there!
@ -22,6 +23,7 @@ Welcome to Codeberg! 😊
{%- 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>
@ -36,4 +38,4 @@ Welcome to Codeberg! 😊
</table>
{% endif %}
{% endif %}
{%- endfor %}
{%- endfor %}

28
content/getting-started/install-git.md
View file

@ -15,36 +15,47 @@ Here we provide step-by-step instructions to install it.
**Disclaimer**: we try to keep these instructions up-to-date, but you might need to adjust them for your machine/OS.
## Linux
On Linux, you can install Git directly from your package manager. Check out [Git's official documentation](https://git-scm.com/download/linux) to get the right command for your distro.
Please see also the article [Configuring Git](/git/configuring-git), which describes how to set up your name and email address for Git.
## macOS
There are [several ways](https://git-scm.com/download/mac) to install Git on macOS. This guide will show you how to install Git using the Homebrew package manager. You will need to be on macOS High Sierra (10.13) or higher.
### Install
You will first need to install Homebrew. You can do this following the instructions on their [website](https://brew.sh/).
Once you've installed Homebrew, you can install Git from your terminal using the following command.
```bash
% brew install git
```
### Update
To update Git, run the following command.
```bash
% brew upgrade git
```
### Configure
Git is now up and running. Please proceed as described in the article [Configuring Git](/git/configuring-git) to set up your name and email address for Git.
## Windows 10
There are several ways to install Git on Windows. An easy one is to use Git’s install wizard, shown here.
### Permissions
For some Git clients (see [below](#git-clients)), e.g. [RStudio](https://rstudio.com/), it is recommended to install Git as administrator. It is also possible to install Git as a standard user, but you may have to manually specify the path to the Git executable in the settings of your Git client.
### Install
If you want to install Git as a standard user, just log in with your user account and run the installer.
To install with administrator permissions, run the installer as administrator. Right-click on the installer, select `Run as administrator` and enter your credentials:
@ -53,12 +64,11 @@ To install with administrator permissions, run the installer as administrator. R
<img src="/assets/images/getting-started/install-git/win-run-as-admin.png" alt="win-run-admin">
</picture>
From here, follow the steps in the setup wizard. It is okay to just accept the defaults, when in doubt.
Here are some important steps:
1. Choose your editor:<br>
By default, [Vim](https://www.vim.org/) will be used for Git. If you prefer to use another editor, select it here.
By default, [Vim](https://www.vim.org/) will be used for Git. If you prefer to use another editor, select it here.
<picture>
<source srcset="/assets/images/getting-started/install-git/win-editor.webp" type="image/webp">
@ -66,7 +76,7 @@ By default, [Vim](https://www.vim.org/) will be used for Git. If you prefer to u
</picture>
2. PATH environment:
This ensures that Git can be used by 3rd party software ([Git clients](#git-clients)). PATH adjustment is recommended (and the default).
This ensures that Git can be used by 3rd party software ([Git clients](#git-clients)). PATH adjustment is recommended (and the default).
<picture>
<source srcset="/assets/images/getting-started/install-git/win-path.webp" type="image/webp">
@ -74,8 +84,8 @@ This ensures that Git can be used by 3rd party software ([Git clients](#git-clie
</picture>
3. Choose credential helper:
From Git 2.29.0 onwards, the `Git Credential Manager Core` will be used by default. The `Git Credential Manager` can still be installed and used, but is now deprecated. When using either of these, your Git/Codeberg credentials will be stored in Windows' [Credential Manager](https://support.microsoft.com/en-us/help/4026814/windows-accessing-credential-manager) when you enter them for your first pull/push (see [Clone & Commit via HTTP](/git/clone-commit-via-http)). Windows' Credential Manager is also where you'd go to change them. Follow the links on the setup wizard for more details.
If you'd prefer not to store your credentials in Windows but e.g. in a password manager, select the third option (`None`). You'll have to enter your credentials at every push/pull.
From Git 2.29.0 onwards, the `Git Credential Manager Core` will be used by default. The `Git Credential Manager` can still be installed and used, but is now deprecated. When using either of these, your Git/Codeberg credentials will be stored in Windows' [Credential Manager](https://support.microsoft.com/en-us/help/4026814/windows-accessing-credential-manager) when you enter them for your first pull/push (see [Clone & Commit via HTTP](/git/clone-commit-via-http)). Windows' Credential Manager is also where you'd go to change them. Follow the links on the setup wizard for more details.
If you'd prefer not to store your credentials in Windows but e.g. in a password manager, select the third option (`None`). You'll have to enter your credentials at every push/pull.
<picture>
<source srcset="/assets/images/getting-started/install-git/win-cred-helper.webp" type="image/webp">
@ -90,19 +100,24 @@ If you'd prefer not to store your credentials in Windows but e.g. in a password
> </picture>
### Run
Git can be used through `Command Prompt` (the traditional Windows command line interpreter), `PowerShell` (the "replacement" of Command Prompt), your [Git client](#git-clients), or `Git Bash`. The latter two options are recommended.
`Git Bash` is what comes with Git. You can access it from the Start Menu: `Git → Git Bash`.
### Configure
You have now managed to get Git up and running. Please proceed as described in the article [Configuring Git](/git/configuring-git) to set up your name and email address for Git.
### Update
If you ticked the box to check for updates during installation, Git will inform you that a new version is available.
To check for updates, at the command line, type:
```bash
git update-git-for-windows
```
After that, just follow the instructions in the terminal to update to the latest version.
Alternatively, you can download the installer from the Git website as explained above.
@ -112,5 +127,6 @@ Alternatively, you can download the installer from the Git website as explained
If you want to keep all your previous settings, simply tick the box `Only show new options` in the setup wizard (see screenshots above).
## Git clients
Git can be used from the command line as shown above, but it can also be used through graphical user interfaces called *Git clients*.
Git can be used from the command line as shown above, but it can also be used through graphical user interfaces called _Git clients_.
You can find a list of various Git clients on the [Git website](https://git-scm.com/downloads/guis).

9
content/getting-started/issue-tracking-basics.md
View file

@ -12,6 +12,7 @@ they can be used to suggest enhancements, ask for new features, discuss a projec
direction, ask questions and much more.
### The Issue Tracker
<picture>
<source srcset="/assets/images/getting-started/issue-tracking-basics/issues-list.webp" type="image/webp">
<img src="/assets/images/getting-started/issue-tracking-basics/issues-list.png" alt="Issues List">
@ -38,6 +39,7 @@ the issue. Their profile picture, with a link to their profile, can be seen in t
list.
### Life of an Issue
Once an issue in the Issue Tracker has been created, it will usually pass through a
process of review, discussion and closure, which can be more or less strictly defined,
based on the project you're contributing to.
@ -65,7 +67,9 @@ consider forking it, if you want to assume responsibility for it (or, rather, yo
{% endadmonition %}
### Things to consider
#### Security bugs
If the bug you have found has security implications, **do not create
an issue right away!** Instead try contacting the project's maintainers privately.
Many projects have a dedicated e-mail address for reporting security bugs. If the
@ -75,12 +79,13 @@ maintainer or ask for the address in the issue tracker.
{% admonition "warning" %}
What's important is that you **don't publicly expose security bugs before they are
fixed *and* the fixes are deployed**, because **otherwise, you might put the users of that
fixed _and_ the fixes are deployed**, because **otherwise, you might put the users of that
project at severe risk**.
{% endadmonition %}
#### Existing issues
Before creating a new issue, please make sure that there isn't already an existing
issue about, i.e., the bug you want to report or the feature you want to request.
@ -91,6 +96,7 @@ You should also make sure that the issue has not already been solved by having a
at the closed issues **(3)** as well.
#### Try to be precise and helpful
Project maintainers love precise information about why, i.e., a bug is happening.
Some projects may even have templates that specifically ask for information like
@ -101,6 +107,7 @@ to quickly resolve your issue. And if you want it resolved even quicker,
consider writing a Pull Request solving the issue (if possible).
#### Be (reasonably) patient
Please remember that many project maintainers work on their free software projects
in their free time. Some maintainers may answer you within minutes, others within days.
Don't be discouraged if there isn't an immediate answer.

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

@ -6,7 +6,7 @@ eleventyNavigation:
order: 70
---
Adding a license to a project is essential for making it reusable: In the absence of other agreements, in fact, copyright law would otherwise forbid others from (re-)using and distributing your work.
Adding a license to a project is essential for making it reusable: In the absence of other agreements, in fact, 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.
## Copyright: The mechanism behind most software licenses
@ -24,23 +24,23 @@ If you need a license for a [non-software project](#hardware-projects), you can
Do you either want to allow people to create proprietary (closed-source) projects with your code, or do you expect your project to remain small (e.g. less than 300 lines)?
* No --> Do you want to allow people to create a closed-source service, for example by using your code on a web server without releasing the source code?
* No --> We recommend using the **AGPL-3.0-or-later** license
* Yes --> Do you want to allow people to use your code as a library and not disclose the source-code of their main program?
* No --> we recommend using the **GPL-3.0-or-later** license
* 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
- No --> Do you want to allow people to create a closed-source service, for example by using your code on a web server without releasing the source code?
- No --> We recommend using the **AGPL-3.0-or-later** license
- Yes --> Do you want to allow people to use your code as a library and not disclose the source-code of their main program?
- No --> we recommend using the **GPL-3.0-or-later** license
- 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
## Correctly applying a license
In order to correctly license your work, you have to explicitly tell which files of your work are under which license, and how to find the full license text.
We recommend to follow these steps to avoid ambiguities:
* Important: Make a clear statement about the license of the project. It is considered sufficient to add the full license text in a dedicated file in the root directory. Often this file is called 'LICENCE', 'LICENSE' or 'COPYING'. [REUSE](https://reuse.software) suggests to create a 'LICENSES' folder which holds all license texts. This is also well suited when multiple licenses are involved.
* Highly recommended: Add copyright and license information to each source file.
* Recommended but not necessary: Follow the [tutorial for becoming "REUSE-compliant"](https://reuse.software/tutorial/).
- Important: Make a clear statement about the license of the project. It is considered sufficient to add the full license text in a dedicated file in the root directory. Often this file is called 'LICENCE', 'LICENSE' or 'COPYING'. [REUSE](https://reuse.software) suggests to create a 'LICENSES' folder which holds all license texts. This is also well suited when multiple licenses are involved.
- Highly recommended: Add copyright and license information to each source file.
- Recommended but not necessary: Follow the [tutorial for becoming "REUSE-compliant"](https://reuse.software/tutorial/).
## Major open-source license categories
@ -48,21 +48,21 @@ We recommend to follow these steps to avoid ambiguities:
One of the major distinctions between licenses is between:
1. Licenses which guarantee the perpetual openness of the code, i.e. forever-open licenses. This is commonly obtained by a mechanism called "copyleft" which requires redistributing any derivative work using the same license again. The GPL licenses belong to this category. Other mechanisms to achieve the perpetual openness of the code include contractual law, but that is rarely used for software licenses.
1. Licenses which guarantee the perpetual openness of the code, i.e. forever-open licenses. This is commonly obtained by a mechanism called "copyleft" which requires redistributing any derivative work using the same license again. The GPL licenses belong to this category. Other mechanisms to achieve the perpetual openness of 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. 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.
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.
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.
If all copyright holders agree, a project can always be forked into a project with a different license. Therefore, the larger the number of developers, the more difficult it is to make such a change.
If all copyright holders agree, a project can always be forked into a project with a different license. Therefore, the larger the number of developers, the more difficult it is to make such a change.
There is no general rule for choosing one type of license or the other in every situation, but we encourage using copyleft licenses whenever possible.
### Free vs. non-free licenses
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.
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) 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. Still, free software is often also gratis software.
In the context of licenses, the term "free" means free as in "freedom", not of 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. antiviruses), and usually viruses and worms (the victim doesn't pay to get them).
### Patent usage
@ -80,14 +80,14 @@ Over the years, hundreds of different software/artwork licenses have been writte
### License incompatibilities
It can occur that different projects, licensed with different open-source licenses, cannot be used together in a single, often larger, project because the licenses require incompatible conditions.
Some licenses, in fact, impose on developers (thanks to the power granted by copyright law) some restrictions/obligations on any [derivative work](https://en.wikipedia.org/wiki/Derivative_work). The term "derivative work" has a precise meaning in copyright law: For example, when developers modify the source code written by somebody else, they have created a derivative work.
Some licenses, in fact, impose on developers (thanks to the power granted by copyright law) some restrictions/obligations on any [derivative work](https://en.wikipedia.org/wiki/Derivative_work). The term "derivative work" has a precise meaning in copyright law: For example, when developers modify the source code written by somebody else, they have created a derivative work.
As an example, if program A is licensed under GPL version 3 and program B is licensed under the Microsoft Public License ([MS-PL](https://directory.fsf.org/wiki/License:MS-PL)), the GPL requires to re-license any derivative work based on both programs A and B again under GPL, while the MS-PL requires to re-license the derivative work under MS-PL: the two conditions are incompatible with each other.
The incompatibility between licenses is clearly a headache for every developer. A possible way out, and the one we 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
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 assumed to reflect at least partially the interests of Microsoft; this website presents, for example GPL last on the front page and it is silent about the missing patent clause in the MIT license both in the front page and in the [dedicated page](https://choosealicense.com/licenses/mit/ ). Moreover, the wording "I want it simple and permissive" can induce people to favour the MIT license; laypeople will want to have legal matters simple, and "permissive" sounds like fair and good.
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 assumed to reflect at least partially the interests of Microsoft; this website presents, for example GPL last on the front page and it is silent about the missing patent clause in the MIT license both in the front page and in the [dedicated page](https://choosealicense.com/licenses/mit/). Moreover, the wording "I want it simple and permissive" can induce people to favour the MIT license; laypeople will want to have legal matters simple, and "permissive" sounds like fair and good.
When reading articles on licenses (including this one), we recommend exercising discretion by inspecting the governance of the source and the risk of conflicting interests.
### Contributor license agreement (CLA)
@ -95,15 +95,15 @@ When reading articles on licenses (including this one), we recommend exercising
A [contributor license agreement](https://en.wikipedia.org/wiki/Contributor_License_Agreement) may be forced upon a developer (e.g. by an employer), and may contain clauses which effectively void the spirit of certain open-source licenses. For example, a single company may advertise a project (for example for marketing reasons) under a GPL license, but on the other hand could require all its contributors to assign their copyright to the company. In this way the company could at any time (by being the only copyright holder) change the license from GPL to a proprietary license.
## Recommendations for software, hardware and other projects
### Software projects
For software projects, we recommend whenever possible to utilize a copyleft license. The only well-established licenses of this type are those of the GNU General Public License (GPL) family. The GPL licenses have evolved over time and come with different versions. Unfortunately, some versions are not compatible with older ones. To avoid [license proliferation](#license-proliferation) and to ease compatibility with future versions, we recommend using the "GNU Affero General Public License v3.0 or later" with SPDX license identifier ["AGPL-3.0-or-later"](https://spdx.org/licenses/AGPL-3.0-or-later.html). The AGPL provides the maximum openness of the code: Even when the software runs on a server, users who interact with that software (e.g. over a network connection) are entitled to receive a copy of the source code.
The [Affero GPL v3.0](https://www.gnu.org/licenses/agpl-3.0.en.html) is compatible with the [GPL v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) and vice-versa thanks to article 13 in each license.
For software projects, we recommend whenever possible to utilize a copyleft license. The only well-established licenses of this type are those of the GNU General Public License (GPL) family. The GPL licenses have evolved over time and come with different versions. Unfortunately, some versions are not compatible with older ones. To avoid [license proliferation](#license-proliferation) and to ease compatibility with future versions, we recommend using the "GNU Affero General Public License v3.0 or later" with SPDX license identifier ["AGPL-3.0-or-later"](https://spdx.org/licenses/AGPL-3.0-or-later.html). The AGPL provides the maximum openness of the code: Even when the software runs on a server, users who interact with that software (e.g. over a network connection) are entitled to receive a copy of the source code.
The [Affero GPL v3.0](https://www.gnu.org/licenses/agpl-3.0.en.html) is compatible with the [GPL v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) and vice-versa thanks to article 13 in each license.
If using AGPL-3.0-or-later is not an option, we recommend using another license of the GNU family, such as the General Public License (GPL), or the Lesser General Public License (LGPL), always indicating the version "**v3.0 or later**".
If using AGPL-3.0-or-later is not an option, we recommend using another license of the GNU family, such as the General Public License (GPL), or the Lesser General Public License (LGPL), always indicating the version "**v3.0 or later**".
In some cases, such as when writing certain libraries, using the Lesser General Public License (LGPL) may lead to a broader usage. In such cases, the [LGPL is preferred over the (A)GPL](https://www.gnu.org/licenses/gpl-faq.en.html#WhySomeGPLAndNotLGPL).
For software which is not very long (e.g. less than 300 lines of code) or unimportant, rather than using a copyleft license you may consider using a [lax permissive license instead](https://www.gnu.org/licenses/gpl-faq.en.html#WhatIfWorkIsShort).
For software which is not very long (e.g. less than 300 lines of code) or unimportant, rather than using a copyleft license you may consider using a [lax permissive license instead](https://www.gnu.org/licenses/gpl-faq.en.html#WhatIfWorkIsShort).
If you are not allowed to, or if you do not want to use a forever-open license (for example because the company you work for does not allow you to do so) we recommend using a temporarily-open or permissive (in the sense that it permits users to close source the code) license which contains a patent provision. To avoid [proliferation of licenses](#license-proliferation), we recommend therefore to use the Apache license version 2.0 (SPDX license identifier Apache-2.0).
@ -111,12 +111,12 @@ We recommend following the guidelines defined by the [GNU project](https://www.g
### Hardware projects
We distinguish primarily between two families of hardware projects:
We distinguish primarily between two families of hardware projects:
1. Hardware projects with little or no software dependencies (e.g. projects containing CAD drawings)
2. Hardware projects containing important software dependencies (e.g. the design of an integrated circuit) where compatibility issues with other licenses may arise
In the first case, we recommend the use of the CERN Open Hardware License Version 2 - Strongly Reciprocal (SPDX license identifier: CERN-OHL-S-2.0). This license guarantees the forever-openness of the project as well as the actual hardware objects, but is incompatible with other mainstream licenses like those of the GNU-GPL family.
In the first case, we recommend the use of the CERN Open Hardware License Version 2 - Strongly Reciprocal (SPDX license identifier: CERN-OHL-S-2.0). This license guarantees the forever-openness of the project as well as the actual hardware objects, but is incompatible with other mainstream licenses like those of the GNU-GPL family.
In the second case, there is currently no copyleft/forever-open license with wide license compatibility which is able to protect a hardware device. This is primarily due to the fact that hardware objects are not protected by copyright law. While awaiting for the appearance of a suited license, we recommend the use the "GNU Affero General Public License v3.0 or later" whenever the use of a CERN Open Hardware License is not permitted.
@ -126,9 +126,9 @@ For hardware projects which should allow creating proprietary forks and/or propr
For documentation, writing, and other non-code assets, a [Creative Commons (CC)](https://creativecommons.org/about/cclicenses/) license can be used, but note that only the following CC licenses are considered free (sorted from protective to unconditional):
* [CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0/)
* [CC-BY](https://creativecommons.org/licenses/by/4.0/)
* [CC0](https://creativecommons.org/publicdomain/zero/1.0/)
- [CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0/)
- [CC-BY](https://creativecommons.org/licenses/by/4.0/)
- [CC0](https://creativecommons.org/publicdomain/zero/1.0/)
Like CC themselves, Codeberg **recommends against** using a [CC license on code](https://creativecommons.org/faq/#can-i-apply-a-creative-commons-license-to-software).
@ -136,8 +136,8 @@ Like CC themselves, Codeberg **recommends against** using a [CC license on code]
We do not curate our own FAQ. Instead we redirect to other major collections:
* [Frequently Asked Questions about the GNU Licenses](https://www.gnu.org/licenses/gpl-faq.en.html)
* [Contributor's Frequently Asked Questions (FAQ) guide](https://www.fsf.org/licensing/contributor-faq)
* [Licensing and Compliance Lab: The most frequently asked Frequently Asked Questions](https://www.fsf.org/blogs/licensing/licensing-and-compliance-lab-the-most-frequently-asked-frequently-asked-questions)
- [Frequently Asked Questions about the GNU Licenses](https://www.gnu.org/licenses/gpl-faq.en.html)
- [Contributor's Frequently Asked Questions (FAQ) guide](https://www.fsf.org/licensing/contributor-faq)
- [Licensing and Compliance Lab: The most frequently asked Frequently Asked Questions](https://www.fsf.org/blogs/licensing/licensing-and-compliance-lab-the-most-frequently-asked-frequently-asked-questions)
If you have further questions on licensing, feel free to reach out to our community Matrix channels. Access links are provided at the [contact page](/contact/).

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

@ -42,6 +42,7 @@ The codebase history of Forgejo and its predecessors predates Codeberg.
However, since 2022, [Codeberg is backing the development of Forgejo](https://blog.codeberg.org/codeberg-launches-forgejo.html) as an umbrella organization.
People are often asking why they should use Codeberg over other Forgejo instances. The most important reasons are:
- a vivid, vibrant community to collaborate with and ask for help
- active maintenance through the community and shared effort to provide an awesome experience
- you are able to take part in operation and decisions, and ideally donate
@ -59,7 +60,6 @@ contribute to the association.
Codeberg members can also take part in the decisions of the platform as explained in the [bylaws](https://codeberg.org/Codeberg/org/src/en/bylaws.md), and they elect the presidium and board of the platform, thus Codeberg can be considered as community-owned.
## Alternatives to Codeberg
Codeberg is not the only libre option for hosting Free Software project.

32
content/getting-started/wiki.md
View file

@ -6,40 +6,45 @@ eleventyNavigation:
order: 60
---
A [wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web. It is a common practice to use wikis to collect knowledge and share information.
A [wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web. It is a common practice to use wikis to collect knowledge and share information.
Codeberg allows you to add a wiki to a repo for additional documentation.
The user in these examples is `knut`, the polar bear and its repository is `foobar`.
## Activation and Permissions
To enable the wiki for a repository, visit the `Settings` page and activate `Enable Repository Wiki` in the `Advanced Section`. It will default to the built-in wiki which is described here, but you can add an URI to an external site the "Wiki" tab should link to.
{% admonition "warning" %}
Be aware that the wiki, once enabled, is accessible for *everyone* who has `read` access to your repository - on public repositories even unauthenticated guests can access the wiki.
The wiki is *not* a suitable place for storing private information or secrets (like passwords).
Be aware that the wiki, once enabled, is accessible for _everyone_ who has `read` access to your repository - on public repositories even unauthenticated guests can access the wiki.
The wiki is _not_ a suitable place for storing private information or secrets (like passwords).
{% endadmonition %}
To edit the wiki `write` permission to the repository is required.
## Wiki structure
The wiki is essentially a separate Git repo in your repository with a predefined name in the form of `<your-repository-name>.wiki.git`.
It consists of [Markdown](https://en.wikipedia.org/wiki/Markdown) files (file extension `.md`) and additional assets like images.
It consists of [Markdown](https://en.wikipedia.org/wiki/Markdown) files (file extension `.md`) and additional assets like images.
No further stylesheets are needed. The Markdown files are automatically rendered according to the selected Codeberg theme.
## Adding content via web
## Adding content via web
After you have enabled the wiki you are prompted to create the initial page `Home.md`.
The web UI in your browser is currently limited to adding, updating, and deleting pages; you can't manage assets like images this way.
<picture>
<source srcset="/assets/images/getting-started/wiki/wiki_pageview.png" type="image/png">
<img src="/assets/images/getting-started/wiki/wiki_pageview.png" alt="Wiki home page with edit buttons">
</picture>
### Adding external images via web
If you cannot [use a local Git client](#adding-external-images-via-web), linking to *external* assets like images is still possible.
If you cannot [use a local Git client](#adding-external-images-via-web), linking to _external_ assets like images is still possible.
<picture>
<source srcset="/assets/images/getting-started/wiki/wiki_editview.png" type="image/png">
@ -51,6 +56,7 @@ Clicking on the "Insert Image" button will make the following text appear in you
You can read up more on how it works [in a later section](#describing-images-in-markdown).
## Adding content using a local Git client
You can work with the wiki repo as you would with any other Git repo on Codeberg; see our docs about managing a Git repo [via CLI](https://docs.codeberg.org/git/clone-commit-via-cli).
```shell
@ -63,6 +69,7 @@ git commit -am "create Home page"
Editing locally allows you to use your favorite editor (preferably with Markdown syntax check and highlighting) and manage additional assets like images.
### Adding images using a local Git client
You can add images to the root directory or a specific subfolder (like `assets` or `images`) using your local Git client.
A feasible workflow might look like this:
@ -82,16 +89,18 @@ git push
Now, you can reference the image in Markdown, like this:
**File in repository**:
```markdown
![image alt text](images/image.png "image title")
![image alt text](images/image.png 'image title')
```
**External image**:
```markdown
![image alt text](https://example.com/image.jpg "image title")
![image alt text](https://example.com/image.jpg 'image title')
```
When including images from Codeberg repositories, keep in mind that *you should use the raw version of the image.*
When including images from Codeberg repositories, keep in mind that _you should use the raw version of the image._
After saving your changes, the image should be visible.
@ -102,16 +111,19 @@ In contrast to embedding external images, images in Git are only rendered after
{% endadmonition %}
## Adding a sidebar and a footer
To enhance the usability of your wiki you can add a custom sidebar and a footer that are shown on every page. The sidebar will be displayed to the right of the main content and the footer below.
To enable the sidebar, just add a file named `_Sidebar.md` to your wiki. For a footer the file must be named `_Footer.md`.
Both file types allow common Markdown syntax to adjust the presentation to your needs.
Very basic example for a sidebar:
```markdown
- [[Home]]
### Content
- [Page 1](Page-1)
> knuts wiki
@ -119,7 +131,7 @@ Very basic example for a sidebar:
{% admonition "tip" %}
These files starting with `_` are hidden, so in the web UI you need to manually browse for the files. E.g. for our user *knut* and his *foobar* repo:
These files starting with `_` are hidden, so in the web UI you need to manually browse for the files. E.g. for our user _knut_ and his _foobar_ repo:
`https://codeberg.org/knut/foobar/wiki/_Sidebar`
{% endadmonition %}

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

@ -1,124 +1,125 @@
---
eleventyNavigation:
key: CloneCommitviaCLI
title: Clone & Commit via CLI
parent: Git
order: 20
---
# Git workflow
Cloning, editing, committing, pushing and pulling can be performed using Git directly from the command line, by using a Git client, or via the web interface. The former option is shown below. The latter option is detailed in the section [Clone & Commit via Web](/git/clone-commit-via-web).
The user in these examples is `knut` the polar bear, and its repository is `examples`. The repository was created via the Codeberg website, including a `README.md` file.
## Clone
*Cloning* refers to the process of creating an identical copy of an online repository to your local machine.
Clone with the Git command `clone` followed by the repo URL.
### HTTP
```shell
~$ git clone https://codeberg.org/knut/examples.git
Cloning into 'examples'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), 214 bytes | 1024 bytes/s, done.
```
### SSH
Before you are able to access Git repositories via SSH, you need to [add an SSH key to your account](/security/ssh-key).
{% admonition "warning" %}
Before connecting to Codeberg via SSH, please make sure that
you have [verified Codeberg's SSH fingerprint](/security/ssh-fingerprint)!
{% endadmonition %}
If you have set up a passphrase, you will be asked for it.
```shell
~$ git clone git@codeberg.org:knut/examples.git
Enter passphrase for key '/home/knut/.ssh/id_rsa': ****
Cloning into 'examples'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
```
## Edit
Modify an existing file:
```shell
~$ cd examples
~/examples$ nano README.md
```
For illustrative purposes, we will use the [`nano` text editor](https://www.nano-editor.org/) in this tutorial. You can still use your own text editor if you wish to.
## Commit
A *commit* is a record of the changes to the repository. This is like a snapshot of your edits.
A commit requires a commit message. For the example below, the message is "test". Keep in mind that "test" is not a very informative message, though. In the real world, make sure your commit message is informative, for you, your collaborators and anyone who might be interested in your work. Advice on how to write a good commit message can be found on countless websites and blogs.
Add a commit:
```shell
~/examples$ git commit -am 'test'
[main 10074d7] test
1 file changed, 2 insertions(+), 1 deletion(-)
```
Here's an explanation of the command flags used here:
- `-a`: automatically stages modified and deleted files for commits.
- `-m`: commit message
## Push
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.
```shell
~/examples$ git push
Username for 'https://codeberg.org': knut
Password for 'https://knut@codeberg.org':
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 266 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To https://codeberg.org/knut/examples.git
662e04e..10074d7 main -> main
```
## Pull
*Pulling* synchronizes the modifications (commit) from the remote repository on Codeberg to the local one.
Pulling is important when you're working on different computers, to make sure that all computers are on the same page. It's even more important when you have collaborators on a project; they may change the files as well, so you need to 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
## Gitea / Forgejo CLI `tea`
[`tea`](https://gitea.com/gitea/tea) is a general CLI client that can be used with instances of [Gitea](https://gitea.com) and [Forgejo](https://forgejo.org). Since Codeberg runs on Forgejo, you can use `tea` with it.
This project is maintained by [the Gitea project](https://gitea.com).
## Codeberg CLI `berg`
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:
- 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.
---
eleventyNavigation:
key: CloneCommitviaCLI
title: Clone & Commit via CLI
parent: Git
order: 20
---
# Git workflow
Cloning, editing, committing, pushing and pulling can be performed using Git directly from the command line, by using a Git client, or via the web interface. The former option is shown below. The latter option is detailed in the section [Clone & Commit via Web](/git/clone-commit-via-web).
The user in these examples is `knut` the polar bear, and its repository is `examples`. The repository was created via the Codeberg website, including a `README.md` file.
## Clone
_Cloning_ refers to the process of creating an identical copy of an online repository to your local machine.
Clone with the Git command `clone` followed by the repo URL.
### HTTP
```shell
~$ git clone https://codeberg.org/knut/examples.git
Cloning into 'examples'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), 214 bytes | 1024 bytes/s, done.
```
### SSH
Before you are able to access Git repositories via SSH, you need to [add an SSH key to your account](/security/ssh-key).
{% admonition "warning" %}
Before connecting to Codeberg via SSH, please make sure that
you have [verified Codeberg's SSH fingerprint](/security/ssh-fingerprint)!
{% endadmonition %}
If you have set up a passphrase, you will be asked for it.
```shell
~$ git clone git@codeberg.org:knut/examples.git
Enter passphrase for key '/home/knut/.ssh/id_rsa': ****
Cloning into 'examples'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
```
## Edit
Modify an existing file:
```shell
~$ cd examples
~/examples$ nano README.md
```
For illustrative purposes, we will use the [`nano` text editor](https://www.nano-editor.org/) in this tutorial. You can still use your own text editor if you wish to.
## Commit
A _commit_ is a record of the changes to the repository. This is like a snapshot of your edits.
A commit requires a commit message. For the example below, the message is "test". Keep in mind that "test" is not a very informative message, though. In the real world, make sure your commit message is informative, for you, your collaborators and anyone who might be interested in your work. Advice on how to write a good commit message can be found on countless websites and blogs.
Add a commit:
```shell
~/examples$ git commit -am 'test'
[main 10074d7] test
1 file changed, 2 insertions(+), 1 deletion(-)
```
Here's an explanation of the command flags used here:
- `-a`: automatically stages modified and deleted files for commits.
- `-m`: commit message
## Push
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.
```shell
~/examples$ git push
Username for 'https://codeberg.org': knut
Password for 'https://knut@codeberg.org':
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 266 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To https://codeberg.org/knut/examples.git
662e04e..10074d7 main -> main
```
## Pull
_Pulling_ synchronizes the modifications (commit) from the remote repository on Codeberg to the local one.
Pulling is important when you're working on different computers, to make sure that all computers are on the same page. It's even more important when you have collaborators on a project; they may change the files as well, so you need to 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
## Gitea / Forgejo CLI `tea`
[`tea`](https://gitea.com/gitea/tea) is a general CLI client that can be used with instances of [Gitea](https://gitea.com) and [Forgejo](https://forgejo.org). Since Codeberg runs on Forgejo, you can use `tea` with it.
This project is maintained by [the Gitea project](https://gitea.com).
## Codeberg CLI `berg`
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:
- 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.

12
content/git/clone-commit-via-web.md
View file

@ -11,7 +11,8 @@ As shown before, cloning, editing, committing, pushing and pulling can be perfor
The user in these examples is `knut` the polar bear and its repository is `foobar`. The repository was created via the Codeberg website including a `README.md` file.
## Clone
*Cloning* refers to the process of creating an identical copy of an online repository to the local machine.
_Cloning_ refers to the process of creating an identical copy of an online repository to the local machine.
Copy the repo URL from the Codeberg website to your Git client using the `Copy` icon.
@ -27,6 +28,7 @@ If you want to download a copy of a specific state of the repository without its
</picture>
## Edit
Click on the file you want to edit from the list of files in the repo. Let's try it here with the `README.md` file.
The pencil tool (`Edit File`) will open a new window.
@ -44,7 +46,8 @@ The `Preview` tab shows you how the file will look like when rendered, and `Prev
</picture>
## Commit
A *commit* is a record of your changes to the repository. This is like a snapshot of your edits.
A _commit_ is a record of your changes to the repository. This is like a snapshot of your edits.
The commit section is at the bottom of the edit window:
@ -60,9 +63,10 @@ If you intend to start a pull request with this commit, you should choose the op
Submit your changes by clicking on `Commit Changes`.
## Push and pull
Synchronizing the modifications (commit) from the local repository to the remote one on Codeberg is called *pushing*.
*Pulling* synchronizes the modifications (commit) from the remote repository on Codeberg to the local one.
Synchronizing the modifications (commit) from the local repository to the remote one on Codeberg is called _pushing_.
_Pulling_ synchronizes the modifications (commit) from the remote repository on Codeberg to the local one.
Pulling is important when you're working on different computers, to make sure that all computers are on the same page. It's even more important when you have collaborators on a project; they may change the files as well, so you need to pull these modifications before you start working.
Because of this, it's recommended to pull before pushing.

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

@ -11,6 +11,7 @@ Once you've managed to get Git up and running, the first thing you must do befor
git config --global user.name 'knut'
git config --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. This is because the email address will later be used to assign your commits to your account. To verify that you've set up everything properly, run:
```bash

6
content/git/index.md
View file

@ -9,18 +9,20 @@ eleventyNavigation:
On these pages, you will learn how to use the Git version control system with Codeberg.
There are 2 ways to interact with a Git repository hosted on Codeberg:
1. [via the command-line](/git/clone-commit-via-cli), either through SSH or HTTP.
2. [using the web UI](/git/clone-commit-via-web/)
Option 1 requires a Git client of your choice [installed on your local system](/getting-started/install-git/).
We recommend the use of the [SSH protocol](https://en.wikipedia.org/wiki/Secure_Shell_Protocol).
We recommend the use of the [SSH protocol](https://en.wikipedia.org/wiki/Secure_Shell_Protocol).
It offers improved security through key-based access (stronger protection than a regular password) and better ease of use (no need to provide credentials on every push).
{% assign navPages = collections.all | eleventyNavigation %}
{%- for entry in navPages %}
{% if entry.url == page.url %}
{%- if entry.children.length -%}
<table class="table">
<thead>
<th> Find out more in this section: </th>
@ -35,4 +37,4 @@ It offers improved security through key-based access (stronger protection than a
</table>
{% endif %}
{% endif %}
{%- endfor %}
{%- endfor %}

112
content/git/squash-commits.md
View file

@ -1,56 +1,56 @@
---
eleventyNavigation:
key: SquashCommits
title: Merge multiple commits into one
parent: Git
order: 50
---
Sometimes you'll want to merge multiple commits into one. Maybe the commits are "dirty", full of non-working code or embarrassing commit messages. The solution shown here is only one of many possible solutions. See this [StackOverflow question](https://stackoverflow.com/q/2563632/4865723) for more details.
Here is an example.
```bash
$ git log --graph --decorate --oneline
* cf634bb (HEAD -> main) english
* 722a9c7 zwei
* e59e6d0 eins
* c6990ba a
* 6dfc50b (origin/main, origin/HEAD) ix
* 10074d7 (tag: test) test
* 662e04e Initial commit
$ git status
On branch main
Your branch is ahead of 'origin/main' by 4 commits.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
```
Here, we want to merge the last 4 commits, from `a` to `english`.
```bash
$ git reset --soft "HEAD~4"
$ git status
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
new file: a
$ git commit --amend
[main 24e0e06] English
Date: Wed May 27 13:56:28 2020 +0200
2 files changed, 3 insertions(+), 1 deletion(-)
create mode 100644 a
$ git log --graph --decorate --oneline
* 24e0e06 (HEAD -> main) English
* 10074d7 (tag: test) test
* 662e04e Initial commit
```
After that, you can push it to the remote repository via `git push`.
---
eleventyNavigation:
key: SquashCommits
title: Merge multiple commits into one
parent: Git
order: 50
---
Sometimes you'll want to merge multiple commits into one. Maybe the commits are "dirty", full of non-working code or embarrassing commit messages. The solution shown here is only one of many possible solutions. See this [StackOverflow question](https://stackoverflow.com/q/2563632/4865723) for more details.
Here is an example.
```bash
$ git log --graph --decorate --oneline
* cf634bb (HEAD -> main) english
* 722a9c7 zwei
* e59e6d0 eins
* c6990ba a
* 6dfc50b (origin/main, origin/HEAD) ix
* 10074d7 (tag: test) test
* 662e04e Initial commit
$ git status
On branch main
Your branch is ahead of 'origin/main' by 4 commits.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
```
Here, we want to merge the last 4 commits, from `a` to `english`.
```bash
$ git reset --soft "HEAD~4"
$ git status
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
new file: a
$ git commit --amend
[main 24e0e06] English
Date: Wed May 27 13:56:28 2020 +0200
2 files changed, 3 insertions(+), 1 deletion(-)
create mode 100644 a
$ git log --graph --decorate --oneline
* 24e0e06 (HEAD -> main) English
* 10074d7 (tag: test) test
* 662e04e Initial commit
```
After that, you can push it to the remote repository via `git push`.

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

@ -27,7 +27,7 @@ This is achieved by calling:
```shell
git lfs install
```
```
You need to do this only once for every user you want to use Git LFS with.
@ -68,7 +68,7 @@ git lfs ls-files
## What is locking?
When you push your changes to Codeberg, Git LFS may tell you to enable locking:
When you push your changes to Codeberg, Git LFS may tell you to enable locking:
```
Locking support detected on remote "origin". Consider enabling it with:
@ -124,7 +124,7 @@ Then you can run `git lfs migrate import` to import some or all files into using
Afterwards you need to call `git push` to push your changes to your repository.
As the man page of [git-lfs-migrate(1)][git-lfs-migrate] already contains a much more detailed description on how to
import files, you are encouraged to read it to learn more about importing before starting the migration.
import files, you are encouraged to read it to learn more about importing before starting the migration.
### Disabling LFS
@ -151,4 +151,4 @@ The man page of [git-lfs-migrate(1)][git-lfs-migrate] further explains how to ex
[git-lfs]: https://git-lfs.github.com/
[git-lfs-locking]: https://github.com/git-lfs/git-lfs/wiki/File-Locking
[git-lfs-migrate]: https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-migrate.1.ronn
[git-lfs-migrate]: https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-migrate.adoc

12
content/git/using-tags.md
View file

@ -7,15 +7,19 @@ eleventyNavigation:
---
## What are tags?
Tags are a feature in Git that can be used to make a snapshot of a repository from a point in time. It is generally used to mark releases (e.g. v1.2.4), and it functions as a shortcut to see what the repo looked like at the time.
## What are releases?
Releases are a feature in Forgejo, independent of Git that allows you to attach files and release notes along with the source code at the time, and share it on Codeberg, linking to a Git tag.
### Wait, what is the difference between tags and releases?
They are very similar, the difference being that tags are just the repository frozen in time and are part of Git (you can make a tag inside of Git), but releases are tags accompanied with a binary file and are not part of Git (you need to go to your Codeberg repository page to create a release).
## Creating tags and releases
If you want to create tags, using Git is recommended. You can also create a new tag when creating a new release on Codeberg. Releases can be created using the Codeberg frontend or Codeberg's [API](https://codeberg.org/api/swagger#/repository/repoCreateRelease) — using Git to create new releases is not possible.
{% admonition "tip" %}
@ -25,7 +29,9 @@ Tags are generally labelled by version numbers. It is good practice to prefix a
{% endadmonition %}
### On Git
To create a tag using Git, use the following command in your local repository.
```bash
git tag -a <tag name> -m "<my tag message>"
```
@ -33,16 +39,19 @@ git tag -a <tag name> -m "<my tag message>"
You can omit `"<my tag message>"` to write a longer tag message in an editor window.
Tags are not automatically pushed when you run `git push` (compared to commits or branches). They have to be pushed manually to the remote target, like so:
```bash
git push --tags <remote target, probably "origin">
```
The argument `--tags` pushes all local tags to the remote target. If you want to push only a specific tag, use:
```bash
git push <remote target, probably "origin"> <tag name, e.g., "v1.2.3">
```
### On Codeberg
To create a release on Codeberg, first go to the `Releases` tab of your repository, and click on `New Release`:
<picture>
@ -69,10 +78,11 @@ You are then re-directed to the `Releases` tab of your repository. The newly cre
Here, you can edit the release if needed, and you can also download the source code in .zip or .tar.gz format.
## Finding and viewing releases in a repository
<picture>
<source srcset="/assets/images/git/using-tags/tags.webp" type="image/webp">
<img src="/assets/images/git/using-tags/tags.png" alt="tags">
</picture>
To view the release, go to the releases tab (1) in the repository. Then locate the release you want to view. As an example, we will be looking at the `Added Knut!` release (2). If you just want to access the files attached to the release, you can download it from the `Downloads` dropdown (3).
To view the release, go to the releases tab (1) in the repository. Then locate the release you want to view. As an example, we will be looking at the `Added Knut!` release (2). If you just want to access the files attached to the release, you can download it from the `Downloads` dropdown (3).
If you want to see a snapshot of the source code at the time of the release, select a source code archive download (4) from the `Downloads` dropdown or click on the tag on the left side (5).

3
content/home.md
View file

@ -3,6 +3,7 @@ eleventyNavigation:
title: Codeberg Documentation
permalink: /
---
Welcome! We're here to help you when you're having issues or questions with Codeberg.
Please choose a section from the sidebar on the left, which you can toggle by clicking the three stripes at the top left corner of your browser window.
@ -11,7 +12,7 @@ If you're new to Codeberg, consider reading the [Getting Started Guide](/getting
## Getting Help
Codeberg's Documentation mostly includes tutorials specific to using the platforms provided by *Codeberg*; they focus on the maintenance of open-source projects with the platforms provided by Codeberg (Forgejo, Woodpecker, Weblate, Pages, etc.).
Codeberg's Documentation mostly includes tutorials specific to using the platforms provided by _Codeberg_; they focus on the maintenance of open-source projects with the platforms provided by Codeberg (Forgejo, Woodpecker, Weblate, Pages, etc.).
If what you are trying to do is not covered by our Documentation, the following resources can be helpful:

7
content/improving-codeberg/contributing-code.md
View file

@ -19,7 +19,6 @@ The following projects always need a helping hand:
Also check out the [Codeberg](https://codeberg.org/Codeberg) and [Codeberg-Infrastructure](https://codeberg.org/Codeberg-Infrastructure) organizations, they contain numerous other software and setup projects that will appreciate your contributions.
## Getting Started
Having a lot of options to choose from is hard.
@ -27,7 +26,6 @@ We maintain a place for [all contributions to Codeberg](https://codeberg.org/Cod
If you don't know where to start, go ahead and introduce yourself there.
We'll try to match you with relevant and interesting tasks.
## Finding issues to work on
The following issue trackers may contain a few ideas for things that could be worked on:
@ -35,12 +33,11 @@ The following issue trackers may contain a few ideas for things that could be wo
- [Codeberg Community Tracker](https://codeberg.org/Codeberg/Community/issues?&state=open&labels=338)
- [Forgejo Issue Tracker](https://codeberg.org/forgejo/forgejo/issues)
We also recommend working on changes that *personally* bother you first. Something in the direction of simple UI changes changes would probably make the most sense, as they are the easiest to get started with and will help you get more acquainted with the codebase (which could help you solve more complicated problems later) in the process.
We also recommend working on changes that _personally_ bother you first. Something in the direction of simple UI changes changes would probably make the most sense, as they are the easiest to get started with and will help you get more acquainted with the codebase (which could help you solve more complicated problems later) in the process.
Solving easy problems helps a lot too! It makes Codeberg's underlying software look much more polished; it also lets other contributors use more of their limited time to solve very sophisticated or unexpected problems.
In the *Codeberg Community Tracker*, there are some issues that are marked using the [`contribution welcome`](https://codeberg.org/Codeberg/Community/issues?&state=open&labels=105) tag. This tag is meant to show that we would really appreciate your help here. They also act as a good starting point if you are looking for something to work on.
In the _Codeberg Community Tracker_, there are some issues that are marked using the [`contribution welcome`](https://codeberg.org/Codeberg/Community/issues?&state=open&labels=105) tag. This tag is meant to show that we would really appreciate your help here. They also act as a good starting point if you are looking for something to work on.
## More questions?

67
content/improving-codeberg/donate.md
View file

@ -12,46 +12,45 @@ develop new features and sustain the Free Software ecosystem around.
## How to Donate
<div class="card">
<div class="card-body">
<h5 class="card-title">Liberapay</h5>
<p class="card-text">
Set up your recurring donation to Codeberg via Liberapay.
Allows payment via Stripe (Credit or Debit Card, Direct Debit and more) and PayPal.
Liberapay itself is Free Software, but the payment processors are not.
<br>
<a href="https://liberapay.com/codeberg/donate" class="btn btn-primary">Donate using Liberapay</a>
</p>
</div>
<div class="card-body">
<h5 class="card-title">Liberapay</h5>
<p class="card-text">
Set up your recurring donation to Codeberg via Liberapay.
Allows payment via Stripe (Credit or Debit Card, Direct Debit and more) and PayPal.
Liberapay itself is Free Software, but the payment processors are not.
<br>
<a href="https://liberapay.com/codeberg/donate" class="btn btn-primary">Donate using Liberapay</a>
</p>
</div>
</div>
<div class="card">
<div class="card-body">
<h5 class="card-title">SEPA wire transfer</h5>
<p class="card-text">
Send us your donation directly to our bank account.
An easy option for people with compatible bank accounts,
and we have heard of others successfully using providers like Wise to transfer the money.
<pre>
Codeberg e.V.
IBAN: DE90 8306 5408 0004 1042 42
BIC: GENODEF1SLR
</pre>
</p>
</div>
<div class="card-body">
<h5 class="card-title">SEPA wire transfer</h5>
<p class="card-text">
Send us your donation directly to our bank account.
An easy option for people with compatible bank accounts,
and we have heard of others successfully using providers like Wise to transfer the money.
<pre>
Codeberg e.V.
IBAN: DE90 8306 5408 0004 1042 42
BIC: GENODEF1SLR
</pre>
</p>
</div>
</div>
<div class="card">
<div class="card-body">
<h5 class="card-title">Becoming a member of Codeberg e.V.</h5>
<p class="card-text">
If you join our non-profit association,
your membership fee also helps keep Codeberg up and running.
You can also receive voting rights and even join with your organization.
<br>
<a href="https://join.codeberg.org" class="btn btn-primary">Become a member!</a>
</p>
</div>
<div class="card-body">
<h5 class="card-title">Becoming a member of Codeberg e.V.</h5>
<p class="card-text">
If you join our non-profit association,
your membership fee also helps keep Codeberg up and running.
You can also receive voting rights and even join with your organization.
<br>
<a href="https://join.codeberg.org" class="btn btn-primary">Become a member!</a>
</p>
</div>
</div>
### Receipts for donations / membership fees
Codeberg is based in Berlin, Germany and

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

@ -28,7 +28,6 @@ And as always: Spread the word, tell your friends and invite them to collaborate
This section has moved to a dedicated page. <a href="./donate" class="btn btn-primary">Check out your options!</a>
## Join Codeberg e.V.
If you're interested in committing even more to Codeberg, consider [joining Codeberg e.V.](https://join.codeberg.org), the non-profit association behind Codeberg.org.

5
content/improving-documentation/docs-contributor-faq.md
View file

@ -13,20 +13,23 @@ The intent of this document is to give answers to a number of questions that mig
Please adhere to [kebab-Case](https://en.wikipedia.org/wiki/Kebab_case) naming rules for any files in Codeberg Documentation.
### When is my contribution being approved?
A Pull Request to Codeberg/Documentation will be reviewed by at least one other Codeberg Documentation collaborators and if your Pull Request is approved, they will merge it into the main branch.
There are a number of exceptions to the rule above:
- For bugfixes and other small and non-controversial changes, the process is much simplified - here it is enough for one collaborator to green-light and merge the changes. If you're already a collaborator yourself, feel free to merge right away (after sufficient testing, that is).
- For major changes, at least two people will need to approve the contribution.
- For changes that are critical, e.g. ones that might legally affect Codeberg e.V., the chairperson of Codeberg e.V. will need to approve of the changes as well.
### Where to create example repositories?
Please create example repositories for the Documentation in the `knut` organization on `codeberg.org`.
If you do not have permissions for that, feel free to ask [in the issue tracker](https://codeberg.org/Codeberg/Documentation/issues).
### How to link to non-existing articles? / Draft Articles
While it is not directly possible to link to non-existing articles, it is possible to create Draft Articles, which are articles that cannot be localized for example via the menu, but which do exist under their URL and do show a message stating that the article is unpublished.
Creating such a draft article can be done by creating a new article with the

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

@ -12,6 +12,7 @@ We're very happy you're considering to contribute to Codeberg Documentation!
{%- 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>
@ -35,4 +36,3 @@ To contribute to Codeberg Documentation, the first thing you should do (if you h
Then, for each major contribution that you want to make (e.g. for each new article), create a new branch, make your contributions and finally make a Pull Request to the Codeberg/Documentation repository. You can find the source code to all articles in the `content` directory of Codeberg Documentation's source tree.
The Codeberg Documentation collaborators will then review your pull request, they may request some changes and eventually, once all is good, they may merge your contribution into the official repository and deploy it to the live site.

3
content/improving-documentation/preview.md
View file

@ -6,7 +6,6 @@ eleventyNavigation:
order: 15
---
Yes, but currently only if you're working with a local clone of the repository. In that case, simply follow the instructions in the [`README.md`](https://codeberg.org/codeberg/documentation/src/README.md) file to set up and run a local preview.
Yes, but currently only if you're working with a local clone of the repository. In that case, simply follow the instructions in the [`README.md`](https://codeberg.org/Codeberg/Documentation/src/README.md) file to set up and run a local preview.
It is recommended to set this up, because it can help you a lot in spotting errors that would otherwise go unnoticed, especially aesthetic errors and broken links.

13
content/improving-documentation/screenshots.md
View file

@ -5,6 +5,7 @@ eleventyNavigation:
parent: ImprovingTheDocumentation
order: 15
---
Screenshots for Codeberg Documentation should follow the guidelines explained in
[Kesi Parker's excellent article](https://medium.com/technical-writing-is-easy/screenshots-in-documentation-27b45342aad8).
@ -32,14 +33,12 @@ cwebp -lossless screenshot.png -o screenshot.webp
As `cwebp` cli-tool is part of `libwebp` the package name might be different between different repositories, here's some tips how to install this tool:
- On Debian/Ubuntu in `apt` repository by `sudo apt install webp`
- On VoidLinux `xbps` repository by `sudo xbps-install libwebp`
- On ArchLinux `aur` repository by `sudo pacman -S libwebp`
- On Debian/Ubuntu in `apt` repository by `sudo apt install webp`
- On VoidLinux `xbps` repository by `sudo xbps-install libwebp`
- On ArchLinux `aur` repository by `sudo pacman -S libwebp`
{% endadmonition %}
If you prefer a GUI, there are [a number of options](https://en.wikipedia.org/wiki/WebP#Graphics_software) available, but please be sure that your GUI doesn't add thumbnails into the WebP file, which would inflate its size, rendering its key advantage meaningless.
> At the time of writing, there is no support for webP images in Safari browsers.
@ -47,7 +46,7 @@ If you prefer a GUI, there are [a number of options](https://en.wikipedia.org/wi
>
> ```html
> <picture>
> <source srcset="/assets/images/getting-started/issue-tracking-basics/issues-list.webp" type="image/webp">
> <img src="/assets/images/getting-started/issue-tracking-basics/issues-list.png" alt="Issues List">
> <source srcset="/assets/images/getting-started/issue-tracking-basics/issues-list.webp" type="image/webp" />
> <img src="/assets/images/getting-started/issue-tracking-basics/issues-list.png" alt="Issues List" />
> </picture>
> ```

141
content/improving-documentation/style-guide.md
View file

@ -2,7 +2,7 @@
eleventyNavigation:
key: StyleGuide
title: Style Guide
parent: ImprovingTheDocumentation
parent: ImprovingTheDocumentation
---
The present style guide aims at streamlining the authoring process. We would like to maintain a consistent style to guarantee a pleasant reading experience. If you haven't done it already, please read the [Documentation Contributor FAQ](https://docs.codeberg.org/improving-codeberg/docs-contributor-faq/) before using this guide.
@ -21,11 +21,11 @@ This style guide is a starting point. Feel free to create an issue, open a Pull
We intend to reach people from different knowledge backgrounds and life experiences. Therefore, we kindly ask you to follow these rules:
| Rule | What we recommend |
|:---------------------------|:---------------------------------------------------------------------------------------------------------------|
| Be as neutral as possible | Avoid using slang and colloquial expressions |
| Be as clear as possible | Avoid wordy sentences. Don't expect your readers to “guess” the intended meaning from context |
| Be as concise as possible | Keep your sentences short and prefer active over passive voice |
| Rule | What we recommend |
| :------------------------ | :-------------------------------------------------------------------------------------------- |
| Be as neutral as possible | Avoid using slang and colloquial expressions |
| Be as clear as possible | Avoid wordy sentences. Don't expect your readers to “guess” the intended meaning from context |
| Be as concise as possible | Keep your sentences short and prefer active over passive voice |
## Organization of the style guide
@ -55,7 +55,7 @@ Follow these guidelines to organize the structure of your document:
Screenshots and other images can heavily improve the quality of an article without much effort.
In our situation, screenshots generally help users find what they are looking for. They also use them to compare what *they* are seeing with what the *article's author* expects them to be seeing.
In our situation, screenshots generally help users find what they are looking for. They also use them to compare what _they_ are seeing with what the _article's author_ expects them to be seeing.
However, readers that cannot see images (e.g. users depending on screen reader software) should not be prevented from reading your article.
@ -81,21 +81,21 @@ Wikipedia's Manual of Style contains [several good examples of alt text](https:/
{% endadmonition %}
### Headings
### Headings
- Keep your headings short.
- Do not use periods (.) and colons (:) at the end of your headings.
- Avoid using consecutive headings without any content in between.
- Avoid using abbreviations in the headings. This particularly applies to lesser known abbreviations.
- Use sentence-style capitalization, i.e. capitalize only the first letter of the first word in the heading as well as words where capitalization is compulsory, such as proper nouns.
- Your headings must reflect the content of the text that follows.
- Use sentence-style capitalization, i.e. capitalize only the first letter of the first word in the heading as well as words where capitalization is compulsory, such as proper nouns.
- Your headings must reflect the content of the text that follows.
- Begin your headings with the following parts of speech according to the typology of your content:
| Content type | What we recommend | Explanation |
|:-------------|:--------------------|:--------------------------------------------------------------------------------------------------------|
| Conceptual | Noun or noun phrase | A conceptual text explains a concept, e.g. “Advantages of version control” |
| Procedural | Gerund | A procedural text describes a procedure or task, e.g. “Installing Git on you local machine” |
| Reference | Noun or noun phrase | A reference text provides information about different elements of a set, e.g. “Keyboard shortcuts” and “File formats”|
| Content type | What we recommend | Explanation |
| :----------- | :------------------ | :-------------------------------------------------------------------------------------------------------------------- |
| Conceptual | Noun or noun phrase | A conceptual text explains a concept, e.g. “Advantages of version control” |
| Procedural | Gerund | A procedural text describes a procedure or task, e.g. “Installing Git on you local machine” |
| Reference | Noun or noun phrase | A reference text provides information about different elements of a set, e.g. “Keyboard shortcuts” and “File formats” |
### Unordered and ordered lists
@ -117,52 +117,51 @@ Maintain a consistent punctuation style in lists. Decide whether you will use
Use curly quotes instead of straight quotes, e.g.:
| Do not write | Write |
|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| "That's an 'interesting' task" | “That's an ‘interesting’ task” |
| "We're 'happy' that you're here" | “We're ‘happy’ that you're here” |
| Do not write | Write |
| :------------------------------- | :------------------------------- |
| "That's an 'interesting' task" | “That's an ‘interesting’ task” |
| "We're 'happy' that you're here" | “We're ‘happy’ that you're here” |
### Dates, times, and numbers
Please follow the conventions below to ensure a consistent format of dates, times, and numbers.
#### Dates and times
Use the following format for dates in running text: **dd MMMM yyyy**, e.g. 9 March 2022.
Use the following “short” format for dates outside the running text: **dd.mm.yyyy**, e.g. 9.3.2022.
Use the following “short” format for dates outside the running text: **dd.mm.yyyy**, e.g. 9.3.2022.
Do not use leading zeros in dates, e.g.:
| Do not write | Write |
|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| 09 March 2022 | 9 March 2022 |
| 09.03.2022 | 9.3.2022 |
| Do not write | Write |
| :------------ | :----------- |
| 09 March 2022 | 9 March 2022 |
| 09.03.2022 | 9.3.2022 |
Use the 24-hour system. Do not use the 12-hour system with a.m. and p.m.
Do not use leading zeros to indicate time. Write full hours with zero minutes.
| Do not write | Write |
|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| 6.20 p.m | 18.20 |
| 12 | 12.00 |
| 09.03.2022 | 9.3.2022 |
| Do not write | Write |
| :----------- | :------- |
| 6.20 p.m | 18.20 |
| 12 | 12.00 |
| 09.03.2022 | 9.3.2022 |
#### Numbers
Write out the numbers zero to nine in letters.
Write out the numbers zero to nine in letters.
Use digits for all numbers above 9.
Use digits for all numbers above 9.
Use a combination of digits and letters when you have numbers that involve millions, billions, etc.
| Do not write | Write |
|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| 0 to 9 | zero to nine |
| Twenty five pages | 25 pages |
| Twenty billion | 20 billion |
| Do not write | Write |
| :---------------- | :----------- |
| 0 to 9 | zero to nine |
| Twenty five pages | 25 pages |
| Twenty billion | 20 billion |
### Hyphenation
@ -170,27 +169,27 @@ Write “**email**” in lowercase characters without a hyphen. Do not use any o
Use hyphens with compound adjectives and adverbs before nouns to eliminate any possible ambiguities, e.g.:
| Do not write | Write |
|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| Self evaluating object | Self-evaluating object |
| Well formed XML documents | Well-formed XML documents |
| Low level programming language | Low-level programming language |
| High performance databases | High-performance databases |
| Impossible to type characters | Impossible-to-type characters |
| Do not write | Write |
| :----------------------------- | :----------------------------- |
| Self evaluating object | Self-evaluating object |
| Well formed XML documents | Well-formed XML documents |
| Low level programming language | Low-level programming language |
| High performance databases | High-performance databases |
| Impossible to type characters | Impossible-to-type characters |
Do not use hyphens for adjectives and adverbs ending in **-ly**, e.g.
| Do not write | Write |
|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| Fully-qualified domain name | Fully qualified domain name |
| Highly-scalable application | Highly scalable application |
| Dynamically-typed languages | Dynamically typed languages |
| Do not write | Write |
| :-------------------------- | :-------------------------- |
| Fully-qualified domain name | Fully qualified domain name |
| Highly-scalable application | Highly scalable application |
| Dynamically-typed languages | Dynamically typed languages |
## Document structure
If you write an excessively long article, your readers might get lost on the way. Break your article down in smaller articles for a better reading experience.
Avoid the excessive use of hyperlinks and cross-references within your document to prevent readers from being distracted.
Avoid the excessive use of hyperlinks and cross-references within your document to prevent readers from being distracted.
### Sentences and paragraphs
@ -203,6 +202,7 @@ Favor “self-contained information units” over interconnected information uni
Keep notes and warnings outside the body of your running text. Use admonition boxes, also known as callouts, to show said information.
The syntax is as follows:
```
{% raw %}
{% admonition "type" "title [optional]" %}
@ -212,6 +212,7 @@ Content
{% endadmonition %}
{% endraw %}
```
If no title is provided will the admonition box default to the type being used as title.<br>
Note the gaps between the content and the start and end tag. These are required to allow markdown to be rendered.
@ -251,34 +252,34 @@ Use to show and answer a question the user may ask in this situation.
Adopt one of the following approaches according to the typology of your content (cf. the difference between “conceptual”, “procedural”, and “reference” content under the section [Headings](#headings)):
| Content type | Recommended structure |
|:-------------|:------------------------------------------------------------------------------------------------------------------------------|
| Conceptual | Use Definitions to introduce the reader to the subject matter before adding your explanations. Use paragraphs and unordered lists to explain the concepts.|
| Procedural | Provide a brief introduction to the procedure. Point out any prerequisites before you start describing the steps to follow. Use ordered lists for the different tasks|
| Reference | Provide a brief introduction in each section to help your readers decide whether they need this particular topic. Use subsections, tables and bullet-style lists to ensure easy access to information.|
| Content type | Recommended structure |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Conceptual | Use Definitions to introduce the reader to the subject matter before adding your explanations. Use paragraphs and unordered lists to explain the concepts. |
| Procedural | Provide a brief introduction to the procedure. Point out any prerequisites before you start describing the steps to follow. Use ordered lists for the different tasks |
| Reference | Provide a brief introduction in each section to help your readers decide whether they need this particular topic. Use subsections, tables and bullet-style lists to ensure easy access to information. |
## Wording and terminology
- Use simple and easy-to-understand terms in your writing
- Avoid references to culture-specific examples that people from other countries or continents may not understand
- Do not coin terms, i.e. create new ones, if a term denoting the same concept already exists
- Explain terms if you think that some readers may either not understand them or misinterpret them
- Explain terms if you think that some readers may either not understand them or misinterpret them
- Do not use double negatives, e.g.:
| Do not write | Write |
|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| You're not going nowhere | You're going nowhere |
| He didn't see nothing | He didn't see anything |
| Do not write | Write |
| :----------------------- | :--------------------- |
| You're not going nowhere | You're going nowhere |
| He didn't see nothing | He didn't see anything |
We use the standard American spelling conventions, i.e.:
| Do not write | Write |
|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| flavour; colour; labour | flavor; color; labor |
| analyse; organise; standardise | analyze; organize; standardize |
| catalogue; analogue, dialogue | catalog, analog, dialog |
| defence, licence | defense, license |
| whitelist, blacklist | allowlist, blockist |
| | |
| Do not write | Write |
| :----------------------------- | :----------------------------- |
| flavour; colour; labour | flavor; color; labor |
| analyse; organise; standardise | analyze; organize; standardize |
| catalogue; analogue, dialogue | catalog, analog, dialog |
| defence, licence | defense, license |
| whitelist, blacklist | allowlist, blockist |
| | |
- Start names with an upper case letter (e.g. Git instead of git, Markdown instead of markdown)
- Start names with an upper case letter (e.g. Git instead of git, Markdown instead of markdown)

1
content/integrations/index.md
View file

@ -15,6 +15,7 @@ Can can also see [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/READM
{%- 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>

22
content/integrations/keycloak.md
View file

@ -13,7 +13,7 @@ Using Codeberg with Keycloak means that you explicitly trust Codeberg and its op
{% endadmonition %}
> To test configurations on your `localhost`, the `--hostname-url` flag can be used to change the *Redirect URI* and other relevant fields' prefixes. The following example is not persistent between executions:
> To test configurations on your `localhost`, the `--hostname-url` flag can be used to change the _Redirect URI_ and other relevant fields' prefixes. The following example is not persistent between executions:
>
> ```shell data-line 2
> docker run -p 8080:8080 \
@ -22,7 +22,7 @@ Using Codeberg with Keycloak means that you explicitly trust Codeberg and its op
> --hostname-url=http://127.0.0.1:8080
> ```
>
> This instance will be accessible at <http://127.0.0.1:8080/admin> with the *Username* and *Password*, `admin`.
> This instance will be accessible at <http://127.0.0.1:8080/admin> with the _Username_ and _Password_, `admin`.
## Creating a new identity provider
@ -33,7 +33,7 @@ From the Keycloak Administration UI, click on "Identity providers" and select "O
<img src="/assets/images/integrations/keycloak/identity-providers.png" alt="Screenshot of the Identity Providers menu. The OpenID Connect v1.0 button is marked with a red box.">
</picture>
You should see a field called *Redirect URI* that has already been filled out for you. Copy the link to your clipboard and leave the page open.
You should see a field called _Redirect URI_ that has already been filled out for you. Copy the link to your clipboard and leave the page open.
<picture>
<source srcset="/assets/images/integrations/keycloak/redirect-uri.webp" type="image/webp">
@ -42,7 +42,7 @@ You should see a field called *Redirect URI* that has already been filled out fo
## Set up an OAuth2 application on Codeberg
On Codeberg, [go to "**Settings**", then "**Applications**"](https://codeberg.org/user/settings/applications). You should be able to find a section called *Manage OAuth2 Applications*.
On Codeberg, [go to "**Settings**", then "**Applications**"](https://codeberg.org/user/settings/applications). You should be able to find a section called _Manage OAuth2 Applications_.
{% admonition "tip" %}
@ -51,16 +51,16 @@ On Codeberg, [go to "**Settings**", then "**Applications**"](https://codeberg.or
{% endadmonition %}
The *Application Name* can be arbitrary; we will use "My Keycloak Instance" for illustrative purposes. Make sure to paste the *Redirect URI* that was shown in Keycloak earlier.
The _Application Name_ can be arbitrary; we will use "My Keycloak Instance" for illustrative purposes. Make sure to paste the _Redirect URI_ that was shown in Keycloak earlier.
<picture>
<source srcset="/assets/images/integrations/keycloak/manage-oauth2-applications.webp" type="image/webp">
<img src="/assets/images/integrations/keycloak/manage-oauth2-applications.png" alt="Screenshot of Manage OAuth2 Applications section in Application settings on Codeberg.">
</picture>
When you are done, click on the green *Create Application* button.
When you are done, click on the green _Create Application_ button.
You should now see two new fields: *Client ID* and *Client Secret*.
You should now see two new fields: _Client ID_ and _Client Secret_.
<picture>
<source srcset="/assets/images/integrations/keycloak/new-oauth2-application.webp" type="image/webp">
@ -73,14 +73,14 @@ Let's finish configuring the OpenID Connect provider on Keycloak.
- **Alias:** Arbitrary. For illustrative purposes, we will use `oidc`. `codeberg` could be used as well.
- **Display Name:** Also arbitrary. Here, we will just use `Codeberg`.
- Set *Use discovery endpoint* to **On**.
- Set _Use discovery endpoint_ to **On**.
- **Discovery endpoint:** `https://codeberg.org/.well-known/openid-configuration`
- **Client ID:** Use the Client ID provided by Codeberg.
- **Client Secret:** Use the Client Secret provided by Codeberg.
All other options can be left untouched. The [*discovery endpoint*](https://codeberg.org/.well-known/openid-configuration) will be used to fetch all metadata required for your Keycloak instance to work together with Codeberg.
All other options can be left untouched. The [_discovery endpoint_](https://codeberg.org/.well-known/openid-configuration) will be used to fetch all metadata required for your Keycloak instance to work together with Codeberg.
You can also optionally enable the [*Proof Key for Code Exchange (PKCE)*](https://docs.gitea.com/next/development/oauth2-provider#supported-oauth2-grants) extension in the *Show metadata* dropdown menu.
You can also optionally enable the [_Proof Key for Code Exchange (PKCE)_](https://docs.gitea.com/next/development/oauth2-provider#supported-oauth2-grants) extension in the _Show metadata_ dropdown menu.
In summary, this is what your configuration should look like:
@ -89,4 +89,4 @@ In summary, this is what your configuration should look like:
<img src="/assets/images/integrations/keycloak/finish-keycloak-configuration.png" alt="Screenshot of the Identity provider configuration page; it contains all aforementioned configuration options.">
</picture>
Click on the *Add*/*Save* button. You will be redirected to the settings of your brand new identity provider. Now, you will be able to use Codeberg to authenticate with the services that you use Keycloak with. Enjoy!
Click on the _Add_/_Save_ button. You will be redirected to the settings of your brand new identity provider. Now, you will be able to use Codeberg to authenticate with the services that you use Keycloak with. Enjoy!

11
content/integrations/matrix.md
View file

@ -8,9 +8,11 @@ eleventyNavigation:
This article will guide you through integrating Codeberg with Matrix, allowing repo updates to be automatically broadcast to your project's Matrix room.
## Create a new Matrix account
To set up the Matrix integration, it is recommended that you [create a new account](https://app.element.io/#/register) dedicated to broadcasting your repo updates. This will act as a bot account. You can create an account on your preferred Matrix server.
## Getting an access token
You will need an access token to give Codeberg access to send updates from your dedicated Matrix account. Here's how to do it on the Element web client.
1. Log in to the [Element web client](https://app.element.io/) in a private/incognito browser window, with the Matrix account you created earlier.
@ -28,6 +30,7 @@ Alternatively, you can get an access token directly from the Matrix API. Read mo
{% endadmonition %}
## Connecting your repo to your Matrix using webhooks
Now we will connect the Matrix bot to your Codeberg repository. You will need admin permissions for the repo.
<picture>
@ -40,9 +43,9 @@ Now we will connect the Matrix bot to your Codeberg repository. You will need ad
3. Click on the `Add Webhook` button and select `Matrix`.
4. Here are explanations for some key fields:
- Homeserver URL: for example `https://matrix.org`
- Room ID: for example `!VTjWrzxSWgLJnHgDUd:matrix.org`. You can find this on Element in the `Advanced` tab for the room settings.
- Access token: type `Bearer <your_access_token>`. The access token is the [one you got earlier](#getting-an-access-token).
- Message type: `m.text` is the most basic type of plaintext message, whereas `m.notice` is intended for bots and [behaves slightly differently](https://spec.matrix.org/latest/client-server-api/#mnotice).
- Homeserver URL: for example `https://matrix.org`
- Room ID: for example `!VTjWrzxSWgLJnHgDUd:matrix.org`. You can find this on Element in the `Advanced` tab for the room settings.
- Access token: type `Bearer <your_access_token>`. The access token is the [one you got earlier](#getting-an-access-token).
- Message type: `m.text` is the most basic type of plaintext message, whereas `m.notice` is intended for bots and [behaves slightly differently](https://spec.matrix.org/latest/client-server-api/#mnotice).
Add your webhook, then click on the webhook URL. At the bottom now, there will be a `Test Delivery` button. Click this, and you will receive a message on your Matrix room!

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

@ -20,11 +20,12 @@ If you do not have an account yet, you must sign up with [readthedocs first](htt
After sign-up you need to login with your user to access your [dashboard](https://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"
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:
<picture>
<source srcset="/assets/images/integrations/read-the-docs/import-manual.webp" type="image/webp">
<img src="/assets/images/integrations/read-the-docs/import-manual.png" alt="Image of the Import Manual page">
@ -62,7 +63,7 @@ This steps shows how to create a new project on Read the Docs
The button 'Add Webhook' has been clicked and presents a list of possible Webhooks integrations.
The 'Forgejo' entry in the list has been marked with a red border.">
</picture>
8. Under "Target URL" enter the URL you copied from the Read the Docs webhook
9. Under "Trigger On:" select "All Events"
@ -76,6 +77,7 @@ This steps shows how to create a new project on Read the Docs
Congratulation! Your done! To test it, push a commit in your Codeberg Repo and see if the documentation rebuilds. This may take a few minutes.
## Migrate Project
You may migrate a repository that is connected to Read the Docs from another Git forge to Codeberg. In this case, follow these steps:
1. Go to Admin->Settings of your Project on Read the Docs

3
content/markdown/index.md
View file

@ -26,6 +26,7 @@ look them up and learn more about Markdown.
{%- 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>
@ -40,4 +41,4 @@ look them up and learn more about Markdown.
</table>
{% endif %}
{% endif %}
{%- endfor %}
{%- endfor %}

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

@ -24,7 +24,7 @@ For example, one line break in a comment leads to a new paragraph.
### Highlighting text sections
In paragraphs, it is possible to highlight passages using **bold** and *italics*.
In paragraphs, it is possible to highlight passages using **bold** and _italics_.
### Bold
@ -49,7 +49,7 @@ This is also __bold text__.
This gets rendered as
This is also __bold text__.
This is also **bold text**.
### Italics
@ -66,7 +66,7 @@ This is *italic text*.
This gets rendered as
This is *italic text*.
This is _italic text_.
```
This is also _italic text_.
@ -79,6 +79,7 @@ This is also _italic text_.
## Forgejo-specific formatting
### Emoticons
Text may contain references to emoticons which are rendered as a small image, similar to an emoji.
You can render these by typing the name of the emoticon you want to use, surrounded by colons (`:`), like this `:codeberg:`.
@ -103,14 +104,14 @@ Use the render hint `mermaid` on the preformatted section containing the code of
E.g.
~~~markdown
```mermaid
graph TD;
A(stuff)-->B[one];
A-->C[two];
A-->D[three];
```
~~~
````markdown
```mermaid
graph TD;
A(stuff)-->B[one];
A-->C[two];
A-->D[three];
```
````
is rendered to:

4
content/markdown/markdown-styleguide.md
View file

@ -14,11 +14,11 @@ Use two stars at the beginning and the end of a section of text to **highlight t
## Italics
Use one star at the beginning and the end of a section to *highlight the section in italics*.
Use one star at the beginning and the end of a section to _highlight the section in italics_.
## Links
Use `[link description](link)` to link to another section, article or website.
Use `[link description](link)` to link to another section, article or website.
To insert a link without a link description, surround the link by less-than `<` and
greater-than `>` characters. This is preferred to just adding an url within the text as it

31
content/markdown/tables-in-markdown.md
View file

@ -21,7 +21,7 @@ A simple table looks like this:
```
| This | is | a |
| --- | --- | --- |
| ------ | ----- | ------- |
| simple | table | example |
The table columns do not have to align in the un-rendered text, but it improves readability to keep everything aligned
@ -40,7 +40,7 @@ The first line of a table forms the head of the table. It is separated from the
```
| Name | Comment |
|:-------|:------------------------------------------------------------------------|
| :----- | :---------------------------------------------------------------------- |
| Alice | Always involved in various communications |
| Bob | A good guy, who likes to communicate with Alice |
| Malroy | Not so nice guy. Tries to mess with the communication of Alice and Bob. |
@ -63,7 +63,7 @@ For example
renders as
| Left oriented rendering |
|:------------------------|
| :---------------------- |
| 150.0 |
| or text |
@ -79,9 +79,9 @@ Whereas:
is rendered as
| Right oriented rendering |
|-------------------------:|
| 150.0 |
| or text |
| -----------------------: |
| 150.0 |
| or text |
If the rendering hint is placed on both sides of the dashed line, the data is rendered as centered:
@ -95,9 +95,9 @@ If the rendering hint is placed on both sides of the dashed line, the data is re
Is rendered as:
| Centered rendering |
|:------------------:|
| 150.0 |
| or text |
| :----------------: |
| 150.0 |
| or text |
Providing no rendering hint leaves it up to the renderer to decide how to render the data. Left-aligned is a common default.
@ -111,26 +111,25 @@ Providing no rendering hint leaves it up to the renderer to decide how to render
Is rendered as:
| Un-hinted rendering |
|---------------------|
| ------------------- |
| 150.0 |
| or text |
## Table variations
Some renderers allow you to omit the delimiting pipe symbols `|` at the side of the table:
```
This | is | a
--- | --- | ---
This | is | a
--- | --- | ---
simple | table | example
```
is rendered as
This | is | a
--- | --- | ---
simple | table | example
| This | is | a |
| ------ | ----- | ------- |
| simple | table | example |
This is even considered an error by some editors.

7
content/markdown/topics.md
View file

@ -50,14 +50,11 @@ This is a topic
===============
```
This is a topic
===============
# This is a topic
```
This is another topic
---------------------
```
This is another topic
---------------------
## This is another topic

3
content/markdown/using-images.md
View file

@ -16,7 +16,7 @@ The syntax of including images is similar to the syntax of links.
![Alternative text](images/image.png "title")
```
![Codeberg Logo](https://design.codeberg.org/logo-kit/horizontal.png "The Codeberg Logo")
![Codeberg Logo](https://design.codeberg.org/logo-kit/horizontal.png 'The Codeberg Logo')
The image link consists of three parts:
@ -28,4 +28,3 @@ The image link consists of three parts:
Image files can be placed within the folder structure of your article or documentation.
Apart from that, images can be referenced by a URL and are thus included from the internet location the URL points to.

18
content/redirects.md
View file

@ -5,14 +5,14 @@ pagination:
size: 1
alias: redirect
redirects:
- {"from": "/git/clone-commit-via-ssh/", "to": "/git/clone-commit-via-cli/"}
- {"from": "/git/clone-commit-via-http/", "to": "/git/clone-commit-via-cli/"}
- {"from": "/advanced/images-in-wiki-pages/", "to": "/getting-started/wiki/"}
- {"from": "/faq/", "to": "/getting-started/faq/"}
- {"from": "/getting-started/communication-from-codeberg/", "to": "/getting-started/email-settings/" }
- {"from": "/improving-codeberg/docs-contributor-faq/", "to": "/improving-documentation/docs-contributor-faq/" }
- {"from": "/advanced/ci/", "to": "/ci/" }
- {"from": "/improving-codeberg/style-guide/", "to": "/improving-documentation/style-guide/" }
permalink: "{{ redirect.from }}"
- { 'from': '/git/clone-commit-via-ssh/', 'to': '/git/clone-commit-via-cli/' }
- { 'from': '/git/clone-commit-via-http/', 'to': '/git/clone-commit-via-cli/' }
- { 'from': '/advanced/images-in-wiki-pages/', 'to': '/getting-started/wiki/' }
- { 'from': '/faq/', 'to': '/getting-started/faq/' }
- { 'from': '/getting-started/communication-from-codeberg/', 'to': '/getting-started/email-settings/' }
- { 'from': '/improving-codeberg/docs-contributor-faq/', 'to': '/improving-documentation/docs-contributor-faq/' }
- { 'from': '/advanced/ci/', 'to': '/ci/' }
- { 'from': '/improving-codeberg/style-guide/', 'to': '/improving-documentation/style-guide/' }
permalink: '{{ redirect.from }}'
layout: redirect
---

6
content/security/2fa.md
View file

@ -136,8 +136,8 @@ You can create as many tokens as you'd like: one for each computer, one for each
If you want to clone a repository using the Git CLI and 2FA enabled, you have two choices:
- use `SSH`: you do not have to do any special configuration, just use your ssh_key to login
- use `HTTPS`: for the login you use your username and your generated accesstoken as a password. First time you enter it, it will be saved for your repository.
- use `SSH`: you do not have to do any special configuration, just use your ssh_key to login
- use `HTTPS`: for the login you use your username and your generated accesstoken as a password. First time you enter it, it will be saved for your repository.
<pre>
$ git clone https://codeberg.org/username/repo.git
@ -159,7 +159,7 @@ Codeberg's instance of Forgejo is using an [OTP library](https://github.com/pque
00:00 00:30 01:00
v v v
| <-----> | <-----> | <----->
^ ^ ^
^ ^ ^
Previous Current Next
```

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

@ -8,7 +8,7 @@ eleventyNavigation:
## What is a GPG keypair?
GPG is an open-source cryptographic software application that implements the [OpenPGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) standard. With a GPG keypair, you can sign or encrypt text. Git allows you to sign your commits, so other collaborators can be assured it was you who created them.
GPG is an open-source cryptographic software application that implements the [OpenPGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) standard. With a GPG keypair, you can sign or encrypt text. Git allows you to sign your commits, so other collaborators can be assured it was you who created them.
## Checking for an Existing GPG keypair
@ -23,7 +23,7 @@ If you are using Linux, this might already be installed. Check by typing `gpg -
{% endadmonition %}
2. Type `gpg --list-secret-keys --keyid-format LONG` into your terminal, and it will list all the keys that you have both a public and a private key for.
3. Look through the output for a key you want. Continue to [Generating a GPG key](#generating-a-gpg-keypair) if there are none, or if there are none that you want to use. If you wish to use one, go to [adding your GPG key to Codeberg](#adding-your-public-gpg-key-to-codeberg).
3. Look through the output for a key you want. Continue to [Generating a GPG key](#generating-a-gpg-keypair) if there are none, or if there are none that you want to use. If you wish to use one, go to [adding your GPG key to Codeberg](#adding-your-public-gpg-key-to-codeberg).
{% admonition "warning" %}
@ -47,6 +47,7 @@ If you haven’t already, be sure to [install](https://gnupg.org/download/index.
1. Type `gpg --list-secret-keys --keyid-format LONG` into the terminal.
2. Select the key you would like to use (most likely the one you just generated). In this example, the GPG key ID is `3AA5C34371567BD2`:
```shell
$ gpg --list-secret-keys --keyid-format LONG
/home/knut/.gnupg/pubring.kbx
@ -56,25 +57,26 @@ sec rsa4096/3AA5C34371567BD2 2021-06-06 [SC] [expires: 2022-06-06]
uid [ultimate] knut <knut@codeberg.org>
ssb rsa4096/42B317FD4BA89E7A 2021-06-06 [E] [expires: 2022-06-06]
```
3. Type `gpg --armor --export <GPG KEY ID>` into the terminal. This will output your public key.
4. Copy the output beginning with `-----BEGIN PGP PUBLIC KEY BLOCK-----` and ending with `-----END PGP PUBLIC KEY BLOCK-----`.
5. Go to the [SSH/GPG Keys tab](https://codeberg.org/user/settings/keys) in your Codeberg settings.
6. Click __Add Key__ in the __Manage GPG Keys__ section, then paste in your public key and click the __Add Key__ button.
6. Click **Add Key** in the **Manage GPG Keys** section, then paste in your public key and click the **Add Key** button.
## Verifying your public GPG key
Anyone can add a random public key; but fortunately, Codeberg provides a mechanism to verify that the key belongs to you.
Every keypair consists of a public and a private key that are connected to one another. Using this private key, you can sign the provided message. If the signed message is valid, Codeberg can confirm that the added key is yours.
Every keypair consists of a public and a private key that are connected to one another. Using this private key, you can sign the provided message. If the signed message is valid, Codeberg can confirm that the 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 by the GPG key you would like to verify.
2. Click on the **Verify** button by the GPG key you would like to verify.
3. Codeberg will show a token. Under its text box you can copy the correct command, and paste it into your terminal.
4. Copy the output including the `-----BEGIN PGP SIGNATURE-----` and `-----END PGP SIGNATURE-----`.
5. Paste it into the large text box and click the __Verify__ button.
5. Paste it into the large text box and click the **Verify** button.
## Telling Git about your GPG key
You will need to tell Git about your key and have it sign new commits for you.
You will need to tell Git about your key and have it sign new commits for you.
1. Open your terminal
2. Type `git config --global user.signingkey <GPG KEY ID>`
@ -100,5 +102,6 @@ After that, log out your session (there's no need to reboot) and you will be abl
{% endadmonition %}
---
> **Attribution**
> This guide is derived from [GitHub Docs](https://docs.github.com), used under CC-BY 4.0.

3
content/security/index.md
View file

@ -12,6 +12,7 @@ This section contains information on how to securely use Codeberg.
{%- 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>
@ -26,4 +27,4 @@ This section contains information on how to securely use Codeberg.
</table>
{% endif %}
{% endif %}
{%- endfor %}
{%- endfor %}

2
content/security/ssh-fingerprint.md
View file

@ -20,7 +20,7 @@ $ git clone git@codeberg.org:Codeberg/Documentation
Cloning into 'Documentation' ...
The authenticity of host 'codeberg.org (159.69.0.178)' can't be established.
ECDSA key fingerprint is SHA256:T9FYDEHELhVkulEKKwge5aVhVTbqCW0MIRwAfpARs/E.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```
When connecting to Codeberg, it is important that you compare the displayed fingerprint

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

@ -14,22 +14,22 @@ It is recommended to use one key per client. This means that if you access your
2. Paste the text below:
```shell
ssh-keygen -t ed25519 -a 100
```
```shell
ssh-keygen -t ed25519 -a 100
```
This will generate a new SSH key.
You can also add a comment to help you identify the client with `-C "comment here"`.
This will generate a new SSH key.
You can also add a comment to help you identify the client with `-C "comment here"`.
```shell
> Generating public/private ed25519 key pair.
```
```shell
> Generating public/private ed25519 key pair.
```
3. When you're prompted to "Enter a file in which to save the key", press <kbd>Enter</kbd>. This accepts the default file location:
```shell
> Enter file in which to save the key (/home/knut/.ssh/id_ed25519): [Press enter]
```
```shell
> Enter file in which to save the key (/home/knut/.ssh/id_ed25519): [Press enter]
```
4. You will be asked for a passphrase; enter one if you'd like, or leave the prompt empty.
@ -41,9 +41,9 @@ Your private key can be protected by a passphrase. This adds a layer of authenti
2. Paste the text below
```shell
ssh-keygen -t ed25519-sk
```
```shell
ssh-keygen -t ed25519-sk
```
3. If you have set one on your key, you'll be prompted for your FIDO2 PIN. Enter it to continue
@ -57,24 +57,27 @@ Keep in mind that now, every time you wish to use Codeberg over SSH, you must ha
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 you can use `xclip` on the command line. You may need to install it from your package manager.
```shell
$ xclip -selection clipboard < ~/.ssh/id_ed25519.pub
```
On Linux you can use `xclip` on the command line. You may need to install it from your package manager.
On Windows you can use `clip`.
```shell
$ clip < ~/.ssh/id_ed25519.pub
```
```shell
$ xclip -selection clipboard < ~/.ssh/id_ed25519.pub
```
On macOS you can use `pbcopy`.
```shell
$ pbcopy < ~/.ssh/id_ed25519.pub
```
On Windows you can use `clip`.
These commands will copy the contents of id_ed25519.pub (your SSH public key) to your clipboard.
```shell
$ clip < ~/.ssh/id_ed25519.pub
```
> Alternatively you can locate the hidden .ssh folder, open the file in your favorite text editor, and copy it to your clipboard.
On macOS you can use `pbcopy`.
```shell
$ pbcopy < ~/.ssh/id_ed25519.pub
```
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
<picture>
@ -82,7 +85,7 @@ Keep in mind that now, every time you wish to use Codeberg over SSH, you must ha
<img src="/assets/images/security/user-settings.png" alt="User Settings">
</picture>
3. Go to the section __SSH / GPG Keys__ and click on __Add key__.
3. Go to the section **SSH / GPG Keys** and click on **Add key**.
<picture>
<source srcset="/assets/images/security/ssh-key/add-ssh-key.webp" type="image/webp">
@ -90,8 +93,8 @@ Keep in mind that now, every time you wish to use Codeberg over SSH, you must ha
</picture>
4. Give an appropriate name for the key.
5. Paste your key string into __Content__ field.
6. Click the __Add key__ button.
5. Paste your key string into **Content** field.
6. Click the **Add key** button.
> You can always access your SSH public keys from `https://codeberg.org/username.keys`, substituting in your Codeberg username.
@ -110,18 +113,18 @@ Hi there, ____! You've successfully authenticated with the key named ____, but F
If this is unexpected, please log in with password and setup Forgejo under another user.
```
*Note: All Codeberg users share a single Unix user named `git` which is used to check out repositories. Depending on the key provided, permission is granted or denied. You can check out all repositories with your key which you have permission for. You can push code to all repositories where you have write access.*
_Note: All Codeberg users share a single Unix user named `git` which is used to check out repositories. Depending on the key provided, permission is granted or denied. You can check out all repositories with your key which you have permission for. You can push code to all repositories where you have write access._
## Verifying your SSH Key
Anyone can add a random SSH key; but fortunately, Codeberg provides a mechanism to verify that the key belongs to you.
Every keypair consists of a public and a private key that are connected to one another. Using this private key, you can sign the provided message. If the signed message is valid, Codeberg can confirm that the added key is yours.
Every keypair consists of a public and a private key that are connected to one another. Using this private key, you can sign the provided message. If the signed message is valid, Codeberg can confirm that the 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.
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.
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.
5. Paste it into the large textbox and click the **Verify** button.
## Telling Git about your SSH key
@ -135,7 +138,7 @@ SSH commit signing is available in Git 2.34 or later. To update your version of
1. Open your terminal.
2. Type `git config --global gpg.format ssh`.
3. Type `git config --global user.signingKey <PATH TO SSH KEY>`, substituting `<PATH TO SSH KEY>` with the path to the key you'd like to use, for example *~/.ssh/id_ed25519*.
3. Type `git config --global user.signingKey <PATH TO SSH KEY>`, substituting `<PATH TO SSH KEY>` with the path to the key you'd like to use, for example _~/.ssh/id_ed25519_.
4. Type `git config --global commit.gpgSign true`.
## Avoid re-typing the passphrase
@ -156,6 +159,7 @@ $ ssh-add # enter your passphrase once, then it is cached.
```
cd /path/to/repository
```
2. Look at the existing remotes with `git remote` :
```
@ -170,6 +174,7 @@ $ ssh-add # enter your passphrase once, then it is cached.
```
You might be using a different name than `origin` for your repository. If you do, remember to use that different name in the following steps.
3. Run `git remote set-url` command followed by the remote name and the remote’s URL:
```

12
cspell.json Normal file
View file

@ -0,0 +1,12 @@
{
"$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
"version": "0.2",
"dictionaries": ["codeberg"],
"dictionaryDefinitions": [
{
"name": "codeberg",
"path": "./.cspell/codeberg.txt",
"addWords": true
}
]
}

2174
pnpm-lock.yaml Normal file
View file

File diff suppressed because it is too large Load diff