foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-24 18:09:26 -05:00
Code Issues Activity

Run prettier (#196)

Browse source 
- Format according to prettier.

Co-authored-by: Gusted <postmaster@gusted.xyz>
Reviewed-on: https://codeberg.org/forgejo/website/pulls/196
Reviewed-by: Loïc Dachary <dachary@noreply.codeberg.org>

# Conflicts:
#	v1.19/index.md
#	v1.19/user/project.md
#	v1.19/user/protection.md
#	v1.19/user/wiki.md
#	v1.20/admin/config-cheat-sheet.md
#	v1.20/admin/database-preparation.md
#	v1.20/developer/code-forgejo-org.md
#	v1.20/license.md
#	v1.20/user/api-usage.md
#	v1.20/user/authentication.md
#	v1.20/user/email-settings.md
#	v1.20/user/issue-pull-request-templates.md
#	v1.20/user/oauth2-provider.md
#	v1.20/user/packages/index.md
#	v1.20/user/packages/maven.md
#	v1.20/user/semver.md
This commit is contained in:
Gusted 2023-03-31 20:57:57 +00:00 committed by Caesar Schinas
parent 1d88a5c1a7
commit 04488991b1
No known key found for this signature in database
GPG key ID: AE9108461BEA5ACF
16 changed files with 302 additions and 293 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
developer/code-forgejo-org.md
View file

@ -7,16 +7,16 @@ license: 'CC-BY-SA-4.0'
https://code.forgejo.org is a Forgejo instance running the latest stable
version. It is dedicated to hosting the following repositories:
* Default Forgejo Runner actions https://code.forgejo.org/actions
* Forgejo Runner https://code.forgejo.org/forgejo/runner
* [ACT](https://github.com/nektos/act) soft fork https://code.forgejo.org/forgejo/act
* [Infrastructure as code](https://enough-community.readthedocs.io) used to deploy code.forgejo.org https://code.forgejo.org/forgejo/infrastructure
* [Infrastructure as code](https://enough-community.readthedocs.io) secrets in a private repository
- Default Forgejo Runner actions https://code.forgejo.org/actions
- Forgejo Runner https://code.forgejo.org/forgejo/runner
- [ACT](https://github.com/nektos/act) soft fork https://code.forgejo.org/forgejo/act
- [Infrastructure as code](https://enough-community.readthedocs.io) used to deploy code.forgejo.org https://code.forgejo.org/forgejo/infrastructure
- [Infrastructure as code](https://enough-community.readthedocs.io) secrets in a private repository
To make these repositories easier to find, the following push mirrors are in place:
* https://code.forgejo.org/forgejo/runner => https://codeberg.org/forgejo/runner
* https://code.forgejo.org/forgejo/act => https://codeberg.org/forgejo/act
- https://code.forgejo.org/forgejo/runner => https://codeberg.org/forgejo/runner
- https://code.forgejo.org/forgejo/act => https://codeberg.org/forgejo/act
## Infrastructure

14
index.md
View file

@ -3,10 +3,10 @@ layout: '~/layouts/Markdown.astro'
title: 'Forgejo v1.20 documentation'
---
* [What is Forgejo?](https://forgejo.org/)
* [Installation](https://forgejo.org/download/)
* [FAQ](https://forgejo.org/faq/)
* [Administrator guide](admin)
* [User guide](user)
* [Developer guide](developer)
* [License](license)
- [What is Forgejo?](https://forgejo.org/)
- [Installation](https://forgejo.org/download/)
- [FAQ](https://forgejo.org/faq/)
- [Administrator guide](admin)
- [User guide](user)
- [Developer guide](developer)
- [License](license)

2
license.md
View file

@ -1,6 +1,6 @@
---
layout: '~/layouts/Markdown.astro'
title: "License"
title: 'License'
---
This documentation is licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/deed.en).

2
user/api-usage.md
View file

@ -31,7 +31,7 @@ $ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:pass
{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
```
The ``sha1`` (the token) is only returned once and is not stored in
The `sha1` (the token) is only returned once and is not stored in
plain-text. It will not be displayed when listing tokens with a `GET`
request; e.g.

7
user/authentication.md
View file

@ -190,10 +190,13 @@ and the official binaries provided do not have this enabled. PAM requires that
the necessary libpam dynamic library be available and the necessary PAM
development headers be accessible to the compiler.
[^1]: For example, using standard Linux log-in on Debian "Bullseye" use
[^1]:
For example, using standard Linux log-in on Debian "Bullseye" use
`common-session-noninteractive` - this value may be valid for other flavors of
Debian including Ubuntu and Mint, consult your distribution's documentation.
[^2]: **This is a required field for PAM**. Be aware: In the above example, the
[^2]:
**This is a required field for PAM**. Be aware: In the above example, the
user will log into the Forgejo web interface as `gituser` and not `gituser@mail.com`
## FreeIPA

2
user/email-settings.md
View file

@ -16,7 +16,7 @@ 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 Forgejo:
| Option | Effect |
|:----------------------------|:---------------------------------------------------------------------------------------------------------------|
| :-------------------------- | :----------------------------------------------------------------------------------------------------- |
| Enable Email Notifications | Enables all notifications (default setting) |
| Only Email on Mention | Forgejo will only send an email to this address if your username is mentioned in an issue or a comment |
| Disable Email Notifications | Forgejo will not send any emails to this address |

35
user/issue-pull-request-templates.md
View file

@ -79,16 +79,13 @@ Inside the directory can be multiple markdown (`.md`) or yaml (`.yaml`/`.yml`) i
```md
---
name: "Template Name"
about: "This template is for testing!"
title: "[TEST] "
ref: "main"
name: 'Template Name'
about: 'This template is for testing!'
title: '[TEST] '
ref: 'main'
labels:
- bug
- "help needed"
- 'help needed'
---
This is the template!
@ -106,7 +103,7 @@ This example YAML configuration file defines an issue form using several inputs
```yaml
name: Bug Report
about: File a bug report
title: "[Bug]: "
title: '[Bug]: '
body:
- type: markdown
attributes:
@ -126,7 +123,7 @@ body:
label: What happened?
description: Also tell us, what did you expect to happen?
placeholder: Tell us what you see!
value: "A bug happened!"
value: 'A bug happened!'
validations:
required: true
- type: dropdown
@ -172,7 +169,7 @@ You can use a `markdown` element to display Markdown in your form that provides
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------|--------------------------------------------------------------|----------|--------|---------|--------------|
| ----- | ------------------------------------------------------------ | -------- | ------ | ------- | ------------ |
| value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - |
### Textarea
@ -182,7 +179,7 @@ You can use a `textarea` element to add a multi-line text field to your form. Co
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------|--------------|---------------------------|
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | ------------ | --------------------------- |
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| description | A description of the text area to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-opaque placeholder that renders in the text area when empty. | Optional | String | Empty String | - |
@ -192,7 +189,7 @@ Attributes:
Validations:
| Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| -------- | ---------------------------------------------------- | -------- | ------- | ------- | ------------ |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
### Input
@ -202,7 +199,7 @@ You can use an `input` element to add a single-line text field to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|--------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
| ----------- | ------------------------------------------------------------------------------------------ | -------- | ------ | ------------ | ------------ |
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-transparent placeholder that renders in the field when empty. | Optional | String | Empty String | - |
@ -211,7 +208,7 @@ Attributes:
Validations:
| Key | Description | Required | Type | Default | Valid values |
|-----------|--------------------------------------------------------------------------------------------------|----------|---------|---------|--------------------------------------------------------------------------|
| --------- | ------------------------------------------------------------------------------------------------ | -------- | ------- | ------- | ------------------------------------------------------------------------ |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
| is_number | Prevents form submission until element is filled with a number. | Optional | Boolean | false | - |
| regex | Prevents form submission until element is filled with a value that match the regular expression. | Optional | String | - | a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) |
@ -223,7 +220,7 @@ You can use a `dropdown` element to add a dropdown menu in your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-----------------------------------------------------------------------------------------------------|----------|--------------|--------------|--------------|
| ----------- | --------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------ | ------------ |
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
| description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| multiple | Determines if the user can select more than one option. | Optional | Boolean | false | - |
@ -232,7 +229,7 @@ Attributes:
Validations:
| Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| -------- | ---------------------------------------------------- | -------- | ------- | ------- | ------------ |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
### Checkboxes
@ -242,7 +239,7 @@ You can use the `checkboxes` element to add a set of checkboxes to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
| ----------- | ----------------------------------------------------------------------------------------------------- | -------- | ------ | ------------ | ------------ |
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
| description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | - |
| options | An array of checkboxes that the user can select. For syntax, see below. | Required | Array | - | - |
@ -250,6 +247,6 @@ Attributes:
For each value in the options array, you can set the following keys.
| Key | Description | Required | Type | Default | Options |
|----------|------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|---------|---------|
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------- | ------- |
| label | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String | - | - |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |

2
user/oauth2-provider.md
View file

@ -31,7 +31,7 @@ To use the Authorization Code Grant as a third party application it is required
Forgejo supports the following scopes for tokens:
| Name | Description |
| ---- | ----------- |
| ---------------------------------------- | -------------------------------------------------------------------------------------------- |
| **(no scope)** | Grants read-only access to public user profile and public repositories. |
| **repo** | Full control over all repositories. |
| &nbsp;&nbsp;&nbsp; **repo:status** | Grants read/write access to commit status in all repositories. |

4
user/packages/index.md
View file

@ -8,7 +8,7 @@ title: 'Package Registry'
The following package managers are currently supported:
| Name | Language | Package client |
| ---- | -------- | -------------- |
| ---------------------- | ---------- | -------------------------- |
| [Cargo](cargo) | Rust | `cargo` |
| [Chef](chef) | - | `knife` |
| [Composer](composer) | PHP | `composer` |
@ -40,7 +40,7 @@ and shows a link to the repository on the package site (as well as a link to the
## Access Restrictions
| Package owner type | User | Organization |
|--------------------|------|--------------|
| ------------------ | ----------------------------------------------------------- | -------------------------------------------------------- |
| **read** access | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
| **write** access | owner only | org members with admin or write access to the org |

4
user/packages/maven.md
View file

@ -56,7 +56,7 @@ Afterwards add the following sections to your project `pom.xml` file:
```
| Parameter | Description |
| -------------- | ----------- |
| -------------- | ------------------------------------------------------------------------------------------------ |
| `access_token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). |
| `owner` | The owner of the package. |
@ -115,7 +115,7 @@ mvn deploy:deploy-file -Durl=https://forgejo.example.com/api/packages/{owner}/ma
```
| Parameter | Description |
| -------------- | ----------- |
| --------- | ------------------------- |
| `owner` | The owner of the package. |
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.

2
user/project.md
View file

@ -4,7 +4,7 @@ title: 'Projects'
license: 'CC-BY-SA-4.0'
---
A project is a [kanban board](https://en.wikipedia.org/wiki/Kanban_(development)) to organize issues.
A project is a [kanban board](<https://en.wikipedia.org/wiki/Kanban_(development)>) to organize issues.
![screenshot of the project page](../../../../images/v1.20/user/project/project.png)

2
user/protection.md
View file

@ -17,7 +17,7 @@ To protect a branch, you need to go to the repository’s **Settings** >
![Add a new rule](../../../../images/v1.20/user/protection/branch-protect.png)
The name of the branch can be a glob where / is the separator and **
spans accross separators. For instance `main`, `release/**` or `precious*`.
spans accross separators. For instance `main`, `release/**`or`precious\*`.
If two rules apply to the same branch, the one that has no glob takes
precedence.

23
user/semver.md
View file

@ -10,7 +10,8 @@ license: 'CC-BY-SA-4.0'
- Minor is increased for backwards-compatible new features.
- Major is increased for breaking changes.
*something* could be :
_something_ could be :
- a command, an option or an argument, for a CLI ;
- a route path, a query parameter or a body property, for a REST API ;
- a text node, a button or a field, for a GUI.
@ -21,13 +22,13 @@ Since Forgejo has all of the above, changes to all of those components should be
As of Forgejo v1.19, there are two version numbering schemes:
* [Following the Gitea version](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/CONTRIBUTING/RELEASE.md#release-numbering) which is not a semantic version
* Used to name release files
* Used for tagging releases
* Displayed in the web interface
* Returned by the `/api/v1/version` API endpoint
* Forgejo semantic version
* Returned by the `/api/forgejo/v1/version` API endpoint
- [Following the Gitea version](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/CONTRIBUTING/RELEASE.md#release-numbering) which is not a semantic version
- Used to name release files
- Used for tagging releases
- Displayed in the web interface
- Returned by the `/api/v1/version` API endpoint
- Forgejo semantic version
- Returned by the `/api/forgejo/v1/version` API endpoint
For instance, the semantic version for https://code.forgejo.org can be obtained with:
@ -40,6 +41,6 @@ $ curl https://code.forgejo.org/api/forgejo/v1/version
The structure of the version number is `<major>.<minor>.<patch>+<build>-gitea-<gitea version>` where:
* `<major>.<minor>.<patch>` is conformant to [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200)
* `<build>` is the release build number of an otherwise identical source
* `gitea-<gitea version>` is the Gitea version this Forgejo release depends on
- `<major>.<minor>.<patch>` is conformant to [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200)
- `<build>` is the release build number of an otherwise identical source
- `gitea-<gitea version>` is the Gitea version this Forgejo release depends on

16
user/wiki.md
View file

@ -11,21 +11,24 @@ 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.
> **Warning**
> Be aware that the wiki, once enabled, is accessible for *everyone* who has `read` access to your repository - on public repositories even anonymous 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 anonymous guests can access the wiki.
> The wiki is _not_ a suitable place for storing private information or secrets (like passwords).
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.
No further stylesheets are needed. The Markdown files are automatically rendered according to the selected Forgejo theme.
## 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.
@ -33,6 +36,7 @@ The web UI in your browser is currently limited to adding, updating, and deletin
![Wiki home page with edit buttons](../../../../images/v1.20/user/wiki/wiki_pageview.png)
## Adding content via a local Git client
You can work with the wiki repo as you would with any other Git repo on Forgejo.
```shell
@ -45,6 +49,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
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:
@ -62,7 +67,7 @@ git push
Now, you can reference the image in Markdown, like this:
```markdown
![image alt text](images/image.png "image title")
![image alt text](images/image.png 'image title')
```
After saving your changes, the image should be visible.
@ -70,20 +75,23 @@ After saving your changes, the image should be visible.
> In contrast to embedding external images, images in Git are only rendered after saving the wiki or Markdown file changes.
## 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
```
> 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`