mirror of
https://codeberg.org/Codeberg/Documentation.git
synced 2026-06-16 05:13:54 -07:00
Lint the documentation (#626)
# Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## Removed - Disable the Markdownlint rule MD024 (`Multiple headings with the same content`). ## Fixed - Syntax errors in `.markdownlint.yaml`. - Markdownlint issues: - Heading levels should only increment by one level at a time([MD001](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md001.md)) - Hard tabs ([MD010](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md010.md)) - Reversed link syntax ([MD011](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md011.md)) - Dollar signs used before commands without showing output ([MD014](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md014.md)) - Multiple top-level headings in the same document ([MD025](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md025.md)) - Trailing punctuation in heading ([MD026](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md026.md)) - Ordered list item prefix([MD029](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md029.md)) - Emphasis used instead of a heading([MD036](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md036.md)) - Fenced code blocks should have a language specified ([MD040](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md040.md)) - Link fragments should be valid ([MD051](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md051.md)) - Link text should be descriptive ([MD059](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md059.md)) - Prettier issues. Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/626 Reviewed-by: Patrick Schratz <pat-s@noreply.codeberg.org> Co-authored-by: Javier Pérez <walpo@noreply.codeberg.org> Co-committed-by: Javier Pérez <walpo@noreply.codeberg.org>
This commit is contained in:
Javier Pérez
Patrick Schratz
parent
c6ac9a9f94
commit
e405ae93ae
31 changed files with 143 additions and 148 deletions
|
|
@ -56,8 +56,6 @@ MD013:
|
|||
tables: false
|
||||
# Include headings
|
||||
headings: true
|
||||
# Include headings
|
||||
headers: true
|
||||
# Strict length checking
|
||||
strict: false
|
||||
# Stern length checking
|
||||
|
|
@ -71,9 +69,7 @@ MD022:
|
|||
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
|
||||
MD024: false
|
||||
|
||||
# MD025/single-title/single-h1 - Multiple top-level headings in the same document
|
||||
MD025:
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ Forgejo Runner is released in both binary and container image (OCI) forms:
|
|||
- Get the last released version:
|
||||
|
||||
```bash
|
||||
$ export RUNNER_VERSION=$(curl -X 'GET' https://code.forgejo.org/api/v1/repos/forgejo/runner/releases/latest | jq .name -r | cut -c 2-)
|
||||
export RUNNER_VERSION=$(curl -X 'GET' https://code.forgejo.org/api/v1/repos/forgejo/runner/releases/latest | jq .name -r | cut -c 2-)
|
||||
```
|
||||
|
||||
You can also manually check directly on the [Forgejo Runner release page](https://code.forgejo.org/forgejo/runner/releases)
|
||||
|
|
@ -61,8 +61,8 @@ 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/v${RUNNER_VERSION}/forgejo-runner-${RUNNER_VERSION}-linux-amd64
|
||||
$ chmod +x forgejo-runner
|
||||
wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v${RUNNER_VERSION}/forgejo-runner-${RUNNER_VERSION}-linux-amd64
|
||||
chmod +x forgejo-runner
|
||||
```
|
||||
|
||||
Make sure to replace `amd64` with `arm64` if your host machine is on ARM.
|
||||
|
|
@ -126,9 +126,9 @@ This method uses the host Docker server by mounting the socket.
|
|||
Podman can work by executing:
|
||||
|
||||
```bash
|
||||
$ podman system service -t 0 &
|
||||
podman system service -t 0 &
|
||||
|
||||
$ DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock ./forgejo-runner daemon
|
||||
DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock ./forgejo-runner daemon
|
||||
```
|
||||
|
||||
{% endadmonition %}
|
||||
|
|
@ -137,8 +137,8 @@ Since this method requires access to the Docker socket, you will need to get the
|
|||
(usually `docker`) in your host machine by running:
|
||||
|
||||
```bash
|
||||
$ id | grep -Po '\d+\(docker\)'
|
||||
$ 996(docker)
|
||||
id | grep -Po '\d+\(docker\)'
|
||||
996(docker)
|
||||
```
|
||||
|
||||
Make sure to replace `996` with the Docker group GID of the host in the following command:
|
||||
|
|
|
|||
|
|
@ -63,8 +63,8 @@ Before starting, you should make sure that you have pip and Python 3 installed o
|
|||
To check, type the following commands in your terminal:
|
||||
|
||||
```bash
|
||||
$ pip --version
|
||||
$ python3 --version
|
||||
pip --version
|
||||
python3 --version
|
||||
```
|
||||
|
||||
If pip and Python are not installed on your Linux machine, please follow the steps described in the articles [pip Installation](https://pip.pypa.io/en/latest/installation/)
|
||||
|
|
@ -87,8 +87,8 @@ The next step is to create a virtual environment. To do so, navigate to the fold
|
|||
described under the section [Setting up the project](#setting-up-the-project):
|
||||
|
||||
```bash
|
||||
$ cd ~/repositories/foobar
|
||||
$ python3 -m venv env
|
||||
cd ~/repositories/foobar
|
||||
python3 -m venv env
|
||||
```
|
||||
|
||||
You can replace the second argument "env" with any other name your like. This will be the folder hosting your virtual environment.
|
||||
|
|
@ -106,13 +106,13 @@ Before you begin performing any tasks on your project, you must activate your vi
|
|||
following command:
|
||||
|
||||
```bash
|
||||
$ . env/bin/activate
|
||||
. env/bin/activate
|
||||
```
|
||||
|
||||
To make sure that you are working inside of your virtual environment, run the command:
|
||||
|
||||
```bash
|
||||
$ which python
|
||||
which python
|
||||
```
|
||||
|
||||
The output of the command above should be the **`env`** folder, e.g.:
|
||||
|
|
@ -124,7 +124,7 @@ The output of the command above should be the **`env`** folder, e.g.:
|
|||
When you are done working on your project, run the following command to leave the virtual environment:
|
||||
|
||||
```bash
|
||||
$ deactivate
|
||||
deactivate
|
||||
```
|
||||
|
||||
### Installing Sphinx in your virtual environment
|
||||
|
|
@ -134,7 +134,7 @@ environment's folder **`env`** in addition to the hidden **`.git`** directory an
|
|||
already described at the end of the section [Creating a Python virtual environment](#creating-a-python-virtual-environment),
|
||||
e.g.:
|
||||
|
||||
```
|
||||
```bash
|
||||
├── myproject
|
||||
│ ├── env
|
||||
│ ├── .git
|
||||
|
|
@ -146,8 +146,8 @@ You will now create an empty directory then navigate to it. For the purpose of t
|
|||
`mydocs`. You can choose any name you'd like:
|
||||
|
||||
```bash
|
||||
$ mkdir mydocs
|
||||
$ cd mydocs
|
||||
mkdir mydocs
|
||||
cd mydocs
|
||||
```
|
||||
|
||||
Running the command `tree -a` should now output the following:
|
||||
|
|
|
|||
|
|
@ -27,7 +27,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/).
|
||||
This project is developed "in-house" by Codeberg. You can find [the source code in our repository](https://codeberg.org/Codeberg/pages-server/).
|
||||
|
||||
See also:
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ For the purpose of this guide, we have chosen to use two separate folders/reposi
|
|||
However, you may want to have a different setup that involves creating a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
|
||||
instead of having folders and repositories in separate locations. With a submodule, your configuration may look like so:
|
||||
|
||||
```
|
||||
```bash
|
||||
├── sources --> This is a git repo
|
||||
│ ├── build
|
||||
│ │ └── html
|
||||
|
|
@ -52,31 +52,31 @@ To copy the content of the `html` folder to your new `pages` folder, run the com
|
|||
We will now initialize an empty repository inside the pages folder. To do this, type the command:
|
||||
|
||||
```bash
|
||||
$ git init
|
||||
git init
|
||||
```
|
||||
|
||||
To check the status of your project’s files, type the command:
|
||||
|
||||
```bash
|
||||
$ git status
|
||||
git status
|
||||
```
|
||||
|
||||
To add all the files that are available in your directory to Git, run the command:
|
||||
|
||||
```bash
|
||||
$ git add -A
|
||||
git add -A
|
||||
```
|
||||
|
||||
Now we will commit:
|
||||
|
||||
```bash
|
||||
$ git commit -m "Example commit message"
|
||||
git commit -m "Example commit message"
|
||||
```
|
||||
|
||||
Repeat these steps in your `source` folder, then push your local commits to the remote repository with the command:
|
||||
|
||||
```bash
|
||||
$ git push origin HEAD:your-remote-branch-name
|
||||
git push origin HEAD:your-remote-branch-name
|
||||
```
|
||||
|
||||
{% admonition "info" "Note" %}
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ eleventyNavigation:
|
|||
|
||||
Redirects can be created with a `_redirects` file with the following format:
|
||||
|
||||
```
|
||||
```text
|
||||
# Comment
|
||||
from to [status]
|
||||
```
|
||||
|
|
@ -30,7 +30,7 @@ from to [status]
|
|||
|
||||
Redirects a specific path.
|
||||
|
||||
```
|
||||
```text
|
||||
/example https://example.com/ 301
|
||||
/path /other-path 301
|
||||
```
|
||||
|
|
@ -39,7 +39,7 @@ Redirects a specific path.
|
|||
|
||||
Redirects all paths to `/index.html` for single-page apps.
|
||||
|
||||
```
|
||||
```text
|
||||
/* /index.html 200
|
||||
```
|
||||
|
||||
|
|
@ -47,7 +47,7 @@ Redirects all paths to `/index.html` for single-page apps.
|
|||
|
||||
Redirects every path under `/articles` to `/posts` while keeping the path.
|
||||
|
||||
```
|
||||
```text
|
||||
/articles/* /posts/:splat 302
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ eleventyNavigation:
|
|||
order: 99
|
||||
---
|
||||
|
||||
## My web browser displays a security warning when I try to access my Codeberg Pages.
|
||||
## My web browser displays a security warning when I try to access my Codeberg Pages
|
||||
|
||||
If your user name or repository name contains a dot, your Codeberg Pages URL (<https://user.name.codeberg.page>
|
||||
or <https://repo.sitory.username.codeberg.page>)
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ Therefore, in this guide, you may need to replace references to just your domain
|
|||
|
||||
{% endadmonition %}
|
||||
|
||||
**Option 1: CNAME record**
|
||||
### 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:
|
||||
|
|
@ -116,7 +116,7 @@ If you need email or others services, you have to use one of the remaining optio
|
|||
|
||||
{% endadmonition %}
|
||||
|
||||
**Option 2: ALIAS record**
|
||||
### Option 2: ALIAS record
|
||||
|
||||
If you cannot use a CNAME record to configure the target you can use this method, which needs two entries instead of one.
|
||||
|
||||
|
|
@ -147,7 +147,7 @@ In the end it should look like this:
|
|||
</tr>
|
||||
</table>
|
||||
|
||||
**Option 3: A/AAAA record**
|
||||
### Option 3: A/AAAA record
|
||||
|
||||
If your service provider does not support `ALIAS records` you can also use `A records` and `AAAA records` instead.
|
||||
|
||||
|
|
@ -199,7 +199,7 @@ In this case, we want our _Personal_ pages available at the URL `https://myself.
|
|||
|
||||
The `.domains` file contains the following:
|
||||
|
||||
```
|
||||
```text
|
||||
myself.example.com
|
||||
frida.codeberg.page
|
||||
pages.frida.codeberg.page
|
||||
|
|
@ -228,7 +228,7 @@ In this case, we want our _Personal_/_Organization_ pages available at the URL `
|
|||
|
||||
The `.domains` file contains the following:
|
||||
|
||||
```
|
||||
```text
|
||||
example.com
|
||||
frida.codeberg.page
|
||||
pages.frida.codeberg.page
|
||||
|
|
@ -253,7 +253,7 @@ In this case, we want our _Project_ pages available at the URL `https://colormix
|
|||
|
||||
The `.domains` file contains the following:
|
||||
|
||||
```
|
||||
```text
|
||||
colormix-app.example.com
|
||||
colormix.frida.codeberg.page
|
||||
pages.colormix.frida.codeberg.page
|
||||
|
|
@ -288,7 +288,7 @@ example discussed before.
|
|||
|
||||
The `.domains` file contains the following:
|
||||
|
||||
```
|
||||
```text
|
||||
example.com
|
||||
colormix.frida.codeberg.page
|
||||
pages.colormix.frida.codeberg.page
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ component.
|
|||
1. First click on the "Add new translation component" Button. You should see
|
||||
this page.
|
||||
|
||||
<img src="/images/codeberg-translate/getting-started/add-component.png" alt="Image the add component page">
|
||||
<img src="/images/codeberg-translate/getting-started/add-component.png" alt="Image the add component page">
|
||||
|
||||
2. Now enter the following:
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ You will not need this in most cases.
|
|||
|
||||
Weblate differs into 2 translation formats: monolingual and bilingual.
|
||||
|
||||
#### Bilingual
|
||||
### Bilingual
|
||||
|
||||
Bilingual means, that the source text live inside the code. See for example the following example from gettext:
|
||||
|
||||
|
|
@ -26,7 +26,7 @@ That means you have language file for the source text. Rather, the source text i
|
|||
|
||||
With Monolingual, you have a extra translation file for your source language.
|
||||
|
||||
## Where can I find these Options:
|
||||
## 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.
|
||||
|
|
|
|||
|
|
@ -52,13 +52,13 @@ git switch -c add-link-to-readme
|
|||
|
||||
In the `README.md` file, we change the line
|
||||
|
||||
```
|
||||
```markdown
|
||||
An example repository for Codeberg Docs.
|
||||
```
|
||||
|
||||
to
|
||||
|
||||
```
|
||||
```markdown
|
||||
An example repository for [Codeberg Docs](https://docs.codeberg.org).
|
||||
```
|
||||
|
||||
|
|
@ -82,13 +82,13 @@ git switch -c update-last-sentence-in-readme
|
|||
|
||||
Again, we'll change the last line, but this time, we'll adjust the text differently, from
|
||||
|
||||
```
|
||||
```markdown
|
||||
An example repository for Codeberg Docs.
|
||||
```
|
||||
|
||||
to
|
||||
|
||||
```
|
||||
```markdown
|
||||
An example repository to use with the Codeberg Documentation.
|
||||
```
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ git merge update-last-sentence-in-readme
|
|||
|
||||
As expected there is a conflict:
|
||||
|
||||
```
|
||||
```bash
|
||||
$ git merge update-last-sentence-in-readme
|
||||
Auto-merging README.md
|
||||
CONFLICT (content): Merge conflict in README.md
|
||||
|
|
@ -138,7 +138,7 @@ Automatic merge failed; fix conflicts and then commit the result.
|
|||
|
||||
Issuing `git status` shows us that there are unmerged paths.
|
||||
|
||||
```
|
||||
```bash
|
||||
$ git status
|
||||
On branch main
|
||||
You have unmerged paths.
|
||||
|
|
@ -154,7 +154,7 @@ no changes added to commit (use "git add" and/or "git commit -a")
|
|||
|
||||
Issuing `git diff` shows the conflict:
|
||||
|
||||
```
|
||||
```bash
|
||||
diff --cc README.md
|
||||
index 616dc84,088249f..0000000
|
||||
--- a/README.md
|
||||
|
|
@ -178,7 +178,7 @@ Git actually added the conflict description into the `README.md` file.
|
|||
|
||||
The end of the file now looks like this:
|
||||
|
||||
```
|
||||
```text
|
||||
<<<<<<< HEAD
|
||||
An example repository for [Codeberg Docs](https://docs.codeberg.org).
|
||||
=======
|
||||
|
|
@ -190,13 +190,13 @@ The conflict description starts with `<<<<<<< HEAD`.
|
|||
The next line shows you that the current `HEAD` (the last commit on the `main` branch before
|
||||
we ran `git merge update-last-sentence-in-readme`) was:
|
||||
|
||||
```
|
||||
```markdown
|
||||
An example repository for [Codeberg Docs](https://docs.codeberg.org).
|
||||
```
|
||||
|
||||
The next line, `=======` separates the current line from the line proposed in the branch that is to be merged.
|
||||
|
||||
```
|
||||
```markdown
|
||||
An example repository to use with the Codeberg Documentation.
|
||||
```
|
||||
|
||||
|
|
@ -210,13 +210,13 @@ Remove all other lines, then the file should be in the form that you want to com
|
|||
|
||||
A possible resolution of this conflict could be:
|
||||
|
||||
```
|
||||
```markdown
|
||||
An example repository to use with the [Codeberg Documentation](https://docs.codeberg.org).
|
||||
```
|
||||
|
||||
Calling `git diff README.md` shows the new line was added, and the two conflicting lines were removed:
|
||||
|
||||
```
|
||||
```diff
|
||||
diff --cc README.md
|
||||
index 616dc84,088249f..0000000
|
||||
--- a/README.md
|
||||
|
|
@ -243,7 +243,7 @@ Closing the editor will complete the resolution of the merge conflict.
|
|||
|
||||
For example:
|
||||
|
||||
```
|
||||
```git
|
||||
commit c10f2c3338979149d7c6fcb815a2072743b5bde6 (HEAD -> main)
|
||||
Merge: 5e2cebd 7b5bf4f
|
||||
Author: Knut <knut@...>
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ There is a large and active community of users in our Matrix chats, which can al
|
|||
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.
|
||||
## Contacting the Codeberg organization
|
||||
|
||||
### Email
|
||||
|
||||
|
|
|
|||
|
|
@ -55,6 +55,6 @@ When you watch a repository (by clicking on the “Watch” button in a reposito
|
|||
|
||||
To stop watching a repository, simply click on “Unwatch” in a repository.
|
||||
|
||||
To list all of your watched repositories, click [here](https://codeberg.org/notifications/watching).
|
||||
You are also able to [list all of your watched repositories](https://codeberg.org/notifications/watching).
|
||||
Alternatively you can click the menu button “Profile and Settings...” in the top-right corner of Codeberg and click on
|
||||
"Subscriptions" in the dropdown.
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ We use the [Codeberg organization](https://codeberg.org/Codeberg) (as well as ot
|
|||
organizations that are linked in its description) to share what we have worked on.
|
||||
More often than not, we also send patches to upstream projects; that way, we all win.
|
||||
|
||||
## Before I start using Codeberg...
|
||||
## Before I start using Codeberg
|
||||
|
||||
### Can I host software and resources without a free and open-source software license?
|
||||
|
||||
|
|
|
|||
|
|
@ -75,7 +75,7 @@ It's okay to only specify owner and repository name, if you want to get started
|
|||
After filling out the fields, click the green "Create Repository" button on the bottom of the page.
|
||||
|
||||
You should now see a screen similar to the one below. If you haven't chosen to generate `LICENSE`, `README` and `.gitignore`
|
||||
the screen might show instructions instead, which will vanish after [your first commit](#making-your-first-commit).
|
||||
the screen might show instructions instead, which will vanish after [your first commit](#making-a-commit).
|
||||
|
||||
<img src="/images/getting-started/first-repository/create-repo-3.png" alt="Repository Main View">
|
||||
|
||||
|
|
@ -246,7 +246,7 @@ Now that you've connected your repository to your local development copy, it's t
|
|||
> 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
|
||||
### 1. Create or edit a file
|
||||
|
||||
Let's modify the `README.md` file.
|
||||
|
||||
|
|
@ -278,7 +278,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
|
||||
### 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`:
|
||||
|
||||
|
|
@ -291,7 +291,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
|
||||
### 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
|
||||
|
|
@ -326,7 +326,7 @@ Date: Sat Sep 26 12:29:57 2020 +0200
|
|||
Initial commit
|
||||
```
|
||||
|
||||
#### 4. Push your changes to Codeberg
|
||||
### 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:
|
||||
|
||||
|
|
@ -373,7 +373,7 @@ After refreshing the repository page, you should now see something similar to th
|
|||
|
||||
Congratulations - you've just made your first source code contribution on Codeberg!
|
||||
|
||||
### Promote your work
|
||||
## 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.
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ still possible.
|
|||
|
||||
Clicking on the "Insert Image" button will make the following text appear in your text editor: ``
|
||||
|
||||
You can read up more on how it works [in a later section](#describing-images-in-markdown).
|
||||
You can read up more on how it works [in a later section](#attaching-images-in-markdown-documents).
|
||||
|
||||
## Adding content using a local Git client
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ eleventyNavigation:
|
|||
order: 20
|
||||
---
|
||||
|
||||
# Git workflow
|
||||
## 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.
|
||||
|
|
@ -15,12 +15,12 @@ The latter option is detailed in the section [Clone & Commit via Web](/git/clone
|
|||
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
|
||||
### 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
|
||||
#### HTTP
|
||||
|
||||
```shell
|
||||
~$ git clone https://codeberg.org/knut/examples.git
|
||||
|
|
@ -31,7 +31,7 @@ remote: Total 3 (delta 0), reused 0 (delta 0)
|
|||
Unpacking objects: 100% (3/3), 214 bytes | 1024 bytes/s, done.
|
||||
```
|
||||
|
||||
### SSH
|
||||
#### SSH
|
||||
|
||||
Before you are able to access Git repositories via SSH, you need to [add an SSH key to your account](/security/ssh-key).
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ remote: Total 3 (delta 0), reused 0 (delta 0)
|
|||
Unpacking objects: 100% (3/3), done.
|
||||
```
|
||||
|
||||
## Edit
|
||||
### Edit
|
||||
|
||||
Modify an existing file:
|
||||
|
||||
|
|
@ -67,7 +67,7 @@ Modify an existing file:
|
|||
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
|
||||
### 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".
|
||||
|
|
@ -88,7 +88,7 @@ Here's an explanation of the command flags used here:
|
|||
- `-a`: automatically stages modified and deleted files for commits.
|
||||
- `-m`: commit message
|
||||
|
||||
## Push
|
||||
### Push
|
||||
|
||||
The last step is to synchronize (_push_) the commit from the local repository to the remote one on Codeberg.
|
||||
|
||||
|
|
@ -108,7 +108,7 @@ To https://codeberg.org/knut/examples.git
|
|||
662e04e..10074d7 main -> main
|
||||
```
|
||||
|
||||
## Pull
|
||||
### 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.
|
||||
|
|
@ -116,16 +116,16 @@ It's even more important when you have collaborators on a project; they may chan
|
|||
pull these modifications before you start working.
|
||||
Because of this, it is recommended to pull before pushing.
|
||||
|
||||
# CLI clients `tea` and `berg` for other actions
|
||||
## CLI clients `tea` and `berg` for other actions
|
||||
|
||||
## Gitea / Forgejo CLI `tea`
|
||||
### 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`
|
||||
### Codeberg CLI `berg`
|
||||
|
||||
The [codeberg-cli project](https://codeberg.org/RobWalt/codeberg-cli), aka. `berg`, is a CLI client that is tailored
|
||||
for Codeberg.
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ Your branch is up to date with 'origin/main'.
|
|||
Changes to be committed:
|
||||
(use "git reset HEAD <file>..." to unstage)
|
||||
|
||||
new file: a
|
||||
new file: a
|
||||
|
||||
$ git commit --amend
|
||||
[main 24e0e06] English
|
||||
|
|
|
|||
|
|
@ -75,7 +75,7 @@ git lfs ls-files
|
|||
|
||||
When you push your changes to Codeberg, Git LFS may tell you to enable locking:
|
||||
|
||||
```
|
||||
```bash
|
||||
Locking support detected on remote "origin". Consider enabling it with:
|
||||
$ git config lfs.https://codeberg.org/your-user-name/your-repository.git/info/lfs.locksverify true
|
||||
```
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ 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.
|
||||
## Join the Codeberg organization
|
||||
|
||||
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.
|
||||
|
|
@ -41,8 +41,8 @@ You're welcome to contribute to Codeberg!
|
|||
We coordinate teams and efforts using our [dedicated Contrib tracker](https://codeberg.org/Codeberg/Contributing).
|
||||
Head there to introduce yourself and find tasks that interest you.
|
||||
|
||||
You should also consider [Joining Codeberg](#join-codeberg-e.v.) where you'll get easier access to internal teams and
|
||||
task forces.
|
||||
You should also consider [Joining Codeberg](#join-the-codeberg-organization) where you'll get easier access to internal
|
||||
teams and task forces.
|
||||
Last but not least, you can always [work on the Codeberg Docs](/improving-documentation/docs-contributor-faq)!
|
||||
|
||||
Codeberg explicitly welcomes newcomers or career changers to its repos, and we will gladly mentor you as resources permit.
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ A style guide is meant to be used as a reference when there is a doubt about a s
|
|||
Think of it as a set of recommendations to avoid time-consuming discussions about grammar, typography, and layout aspects.
|
||||
|
||||
It is not a novel that we expect you to read from A to Z. For instance, if you want to know how to format date and numbers,
|
||||
you can head immediately to the relevant section under [Dates, times, and numbers](#dates%2C-times%2C-and-numbers).
|
||||
you can head immediately to the relevant section under [Dates, times, and numbers](#dates-times-and-numbers).
|
||||
|
||||
In an ideal world, the reviewer is the person that must be in charge of enforcing the guidelines provided in the style guide.
|
||||
|
||||
|
|
@ -223,7 +223,7 @@ said information.
|
|||
|
||||
The syntax is as follows:
|
||||
|
||||
```
|
||||
```text
|
||||
{% raw %}
|
||||
{% admonition "type" "title [optional]" %}
|
||||
|
||||
|
|
|
|||
|
|
@ -140,7 +140,7 @@ Markdown code in descriptions.
|
|||
### Profile Descriptions
|
||||
|
||||
1. Go to [your user settings](https://codeberg.org/user/settings)
|
||||
2. Copy and paste the [Markdown code for the widget](#markdown-widget) in your Biography.
|
||||
2. Copy and paste the [Markdown code for the widget](#modifying-liberapay-widget-for-markdown) in your Biography.
|
||||
|
||||
For more information on profile customization, take a look at the ["Profile customization" in Forgejo's documentation](https://forgejo.org/docs/latest/user/profile/).
|
||||
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ to get the same effect.
|
|||
|
||||
Here are a few examples.
|
||||
|
||||
```
|
||||
```markdown
|
||||
This is **bold text**.
|
||||
```
|
||||
|
||||
|
|
@ -44,8 +44,8 @@ This gets rendered as
|
|||
|
||||
This is **bold text**.
|
||||
|
||||
```
|
||||
This is also __bold text__.
|
||||
```markdown
|
||||
This is also **bold text**.
|
||||
```
|
||||
|
||||
This gets rendered as
|
||||
|
|
@ -61,15 +61,15 @@ to get the same effect.
|
|||
|
||||
Here are a few examples.
|
||||
|
||||
```
|
||||
This is *italic text*.
|
||||
```markdown
|
||||
This is _italic text_.
|
||||
```
|
||||
|
||||
This gets rendered as
|
||||
|
||||
This is _italic text_.
|
||||
|
||||
```
|
||||
```markdown
|
||||
This is also _italic text_.
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ A better way of preformatting a section of text is by starting a section of text
|
|||
|
||||
Here, we use 3 backtick characters on its own line, then our text, then another line containing 3 more backticks.
|
||||
|
||||
```
|
||||
```markdown
|
||||
this
|
||||
is
|
||||
displayed
|
||||
|
|
@ -55,7 +55,7 @@ echo "Hello world"
|
|||
|
||||
The same thing would be rendered without syntax highlighting if the hint is not given:
|
||||
|
||||
```
|
||||
```text
|
||||
#!/bin/bash
|
||||
|
||||
echo "Hello world"
|
||||
|
|
|
|||
|
|
@ -14,9 +14,9 @@ Markdown tables are written ("drawn") using the characters pipe `|`, dash `-` an
|
|||
|
||||
A simple table looks like this:
|
||||
|
||||
```
|
||||
```markdown
|
||||
| This | is | a |
|
||||
| --- | --- | --- |
|
||||
| ------ | ----- | ------- |
|
||||
| simple | table | example |
|
||||
```
|
||||
|
||||
|
|
@ -31,9 +31,9 @@ Some editors automatically align the table structure.
|
|||
|
||||
The first line of a table forms the head of the table. It is separated from the rest of the data by a line of dashes.
|
||||
|
||||
```
|
||||
```markdown
|
||||
| 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. |
|
||||
|
|
@ -53,9 +53,9 @@ If the colon is to the left of the line of dashes separating data from the heade
|
|||
|
||||
For example
|
||||
|
||||
```
|
||||
```markdown
|
||||
| Left oriented rendering |
|
||||
|:------------------------|
|
||||
| :---------------------- |
|
||||
| 150.0 |
|
||||
| or text |
|
||||
```
|
||||
|
|
@ -85,11 +85,11 @@ is rendered as
|
|||
|
||||
If the rendering hint is placed on both sides of the dashed line, the data is rendered as centered:
|
||||
|
||||
```
|
||||
```markdown
|
||||
| Centered rendering |
|
||||
|:------------------:|
|
||||
| 150.0 |
|
||||
| or text |
|
||||
| :----------------: |
|
||||
| 150.0 |
|
||||
| or text |
|
||||
```
|
||||
|
||||
Is rendered as:
|
||||
|
|
@ -119,12 +119,16 @@ Is rendered as:
|
|||
|
||||
Some renderers allow you to omit the delimiting pipe symbols `|` at the side of the table:
|
||||
|
||||
```
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
```markdown
|
||||
This | is | a
|
||||
--- | --- | ---
|
||||
------ | ----- | ---
|
||||
simple | table | example
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
is rendered as
|
||||
|
||||
| This | is | a |
|
||||
|
|
|
|||
|
|
@ -29,32 +29,26 @@ amount of text. Unfortunately, there is no other way to present Topics in Markdo
|
|||
# 1st Topic
|
||||
```
|
||||
|
||||
# 1st Topic
|
||||
|
||||
```shell
|
||||
## 2nd Topic
|
||||
```
|
||||
|
||||
## 2nd Topic
|
||||
|
||||
```shell
|
||||
### 3rd Topic
|
||||
```
|
||||
|
||||
### 3rd Topic
|
||||
|
||||
### Examples of topics with dashes and equal signs
|
||||
|
||||
```
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
```markdown
|
||||
This is a topic
|
||||
===============
|
||||
```
|
||||
|
||||
# This is a topic
|
||||
|
||||
```
|
||||
```markdown
|
||||
This is another topic
|
||||
---------------------
|
||||
```
|
||||
|
||||
## This is another topic
|
||||
<!-- prettier-ignore-end -->
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Hyperlinks have the following markup: `[Link description](link-url)`.
|
|||
|
||||
For example:
|
||||
|
||||
```
|
||||
```markdown
|
||||
[Link to Codeberg](https://codeberg.org/)
|
||||
```
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ You can link to another article by specifying the file or path name URI (a URL,
|
|||
For example, you can link to the introductory article of this section of the documentation by using its
|
||||
path name in the link:
|
||||
|
||||
```
|
||||
```markdown
|
||||
[Link to introductory article](/markdown/)
|
||||
```
|
||||
|
||||
|
|
@ -53,7 +53,7 @@ You can also link to a heading in an article by specifying the heading using a h
|
|||
|
||||
For example, you can link to the heading on "Links without description" in this same article by using:
|
||||
|
||||
```
|
||||
```markdown
|
||||
[Link to the "links-without-description" section](#links-without-description)
|
||||
```
|
||||
|
||||
|
|
@ -65,7 +65,7 @@ You can link to another article's heading using the same syntax.
|
|||
|
||||
For example, you can link to the heading on "Bold" in the article "Introduction to Markdown" by using:
|
||||
|
||||
```
|
||||
```markdown
|
||||
[Link to the bold section](/markdown/introduction-to-markdown/#bold)
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ To use an unordered list (bullet points), simply begin your list items with a da
|
|||
|
||||
For example:
|
||||
|
||||
```
|
||||
```markdown
|
||||
- This
|
||||
- is
|
||||
- a
|
||||
|
|
@ -56,7 +56,7 @@ Gets rendered as:
|
|||
|
||||
Note that the numbers do not have to be in the correct order (even though it is easier to read in the non-rendered form):
|
||||
|
||||
```
|
||||
```markdown
|
||||
1. This
|
||||
1. is
|
||||
1. also
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ This is shown to you right after setting up 2FA:
|
|||
|
||||
Please store this token in a safe place.
|
||||
|
||||
#### Step 5: Done!
|
||||
#### Step 5: Done
|
||||
|
||||
That's it - you have now configured two-factor authentication for your account.
|
||||
|
||||
|
|
@ -90,14 +90,14 @@ Choose a nickname for your key and input it on the `Nickname` input.
|
|||
|
||||
Once you've decided on a nickname, click `Add Security Key` right under the `Nickname` input and follow your browser's instructions.
|
||||
|
||||
#### Step 5: Done!
|
||||
#### Step 5: Done
|
||||
|
||||
WebAuthn is now configured for your account! Now, when you sign in, you'll be given a choice between using TOTP or WebAuthn.
|
||||
|
||||
{% admonition "Tip" %}
|
||||
|
||||
You can very likely use your WebAuthn security key to secure your SSH key, learn more about this on
|
||||
(Adding an SSH key to your account)[/security/ssh-key]).
|
||||
[Adding an SSH key to your account](/security/ssh-key)).
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
|
|
@ -138,7 +138,7 @@ Password for 'https://username@codeberg.org': access-token
|
|||
If you want to permanently save your generated access token you can use the following command to store it globally on
|
||||
your computer:
|
||||
|
||||
```
|
||||
```bash
|
||||
git config --global credential.helper cache
|
||||
```
|
||||
|
||||
|
|
@ -148,7 +148,7 @@ Codeberg's instance of Forgejo is using an [OTP library](https://github.com/pque
|
|||
follows the [RFC 6238 standard](https://datatracker.ietf.org/doc/html/rfc6238) to generate TOTP which uses 30 seconds
|
||||
long time frames to accept your 2FA code.
|
||||
|
||||
```
|
||||
```text
|
||||
00:00 00:30 01:00
|
||||
v v v
|
||||
| <-----> | <-----> | <----->
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ Are you sure you want to continue connecting (yes/no/[fingerprint])?
|
|||
When connecting to Codeberg, it is important that you compare the displayed fingerprint
|
||||
against one of the following fingerprints published by Codeberg:
|
||||
|
||||
```
|
||||
```bash
|
||||
SHA256:6QQmYi4ppFS4/+zSZ5S4IU+4sa6rwvQ4PbhCtPEBekQ codeberg.org (RSA)
|
||||
SHA256:T9FYDEHELhVkulEKKwge5aVhVTbqCW0MIRwAfpARs/E codeberg.org (ECDSA)
|
||||
SHA256:mIlxA9k46MmM6qdJOdMnAQpzGxF4WIVVL+fj+wZbw0g codeberg.org (ED25519)
|
||||
|
|
|
|||
|
|
@ -80,19 +80,19 @@ be prompted to touch it to continue.
|
|||
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
|
||||
xclip -selection clipboard < ~/.ssh/id_ed25519.pub
|
||||
```
|
||||
|
||||
On Windows you can use `clip`.
|
||||
|
||||
```shell
|
||||
$ clip < ~/.ssh/id_ed25519.pub
|
||||
clip < ~/.ssh/id_ed25519.pub
|
||||
```
|
||||
|
||||
On macOS you can use `pbcopy`.
|
||||
|
||||
```shell
|
||||
$ pbcopy < ~/.ssh/id_ed25519.pub
|
||||
pbcopy < ~/.ssh/id_ed25519.pub
|
||||
```
|
||||
|
||||
These commands will copy the contents of id_ed25519.pub (your SSH public key) to your clipboard.
|
||||
|
|
@ -129,7 +129,7 @@ Host codeberg.org
|
|||
Do this simple test:
|
||||
|
||||
```shell
|
||||
$ ssh -T git@codeberg.org
|
||||
ssh -T git@codeberg.org
|
||||
```
|
||||
|
||||
The output should look like this:
|
||||
|
|
@ -160,7 +160,7 @@ added key is yours.
|
|||
|
||||
## Telling Git about your SSH key
|
||||
|
||||
SSH can also be used to sign commits as an alternative for GPG. You can read more about GPG commit signing [here](/security/gpg-key).
|
||||
SSH can also be used to sign commits as an alternative for GPG. You can read more about GPG commit signing [in our documentation](/security/gpg-key).
|
||||
|
||||
{% admonition "note" %}
|
||||
|
||||
|
|
@ -183,42 +183,43 @@ Common desktop environments like macOS or GNOME will offer you to cache your pas
|
|||
If you are working at the command line, you can alternatively do this directly:
|
||||
|
||||
```shell
|
||||
$ eval $(ssh-agent)
|
||||
$ ssh-add # enter your passphrase once, then it is cached.
|
||||
eval $(ssh-agent)
|
||||
ssh-add # enter your passphrase once, then it is cached.
|
||||
```
|
||||
|
||||
## Changing your repository's transport from HTTPS to SSH
|
||||
|
||||
1. Go to the directory where your repository is located:
|
||||
|
||||
```
|
||||
```bash
|
||||
cd /path/to/repository
|
||||
```
|
||||
|
||||
2. Look at the existing remotes with `git remote` :
|
||||
|
||||
```
|
||||
```bash
|
||||
git remote -v
|
||||
```
|
||||
|
||||
It will look similar to this:
|
||||
|
||||
```
|
||||
origin https://codeberg.org/knut/foobar.git (fetch)
|
||||
origin https://codeberg.org/knut/foobar.git (push)
|
||||
```bash
|
||||
origin https://codeberg.org/knut/foobar.git (fetch)
|
||||
origin https://codeberg.org/knut/foobar.git (push)
|
||||
```
|
||||
|
||||
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.
|
||||
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:
|
||||
|
||||
```
|
||||
```bash
|
||||
git remote set-url <remote-name> <remote-url>
|
||||
```
|
||||
|
||||
For example, to change the URL of `origin` to `git@codeberg.org:knut/foobar.git` you would type:
|
||||
|
||||
```
|
||||
```bash
|
||||
git remote set-url origin git@codeberg.org:knut/foobar.git
|
||||
```
|
||||
|
||||
|
|
@ -231,15 +232,15 @@ $ ssh-add # enter your passphrase once, then it is cached.
|
|||
|
||||
4. Verify that your change was successful:
|
||||
|
||||
```
|
||||
```bash
|
||||
git remote -v
|
||||
```
|
||||
|
||||
The output should look like this:
|
||||
|
||||
```
|
||||
origin ssh://git@codeberg.org:knut/foobar.git (fetch)
|
||||
origin ssh://git@codeberg.org:knut/foobar.git (push)
|
||||
```bash
|
||||
origin ssh://git@codeberg.org:knut/foobar.git (fetch)
|
||||
origin ssh://git@codeberg.org:knut/foobar.git (push)
|
||||
```
|
||||
|
||||
> **Attribution**
|
||||
|
|
|
|||
Loading…
Reference in a new issue