Restructure documentation. Now the documentation has installation, administration, usage, development, contributing the 5 main parts (#23629)

- **Installation**: includes how to install Gitea and related other
tools, also includes upgrade Gitea
- **Administration**: includes how to configure Gitea, customize Gitea
and manage Gitea instance out of Gitea admin UI
- **Usage**: includes how to use Gitea's functionalities. A sub
documentation is about packages, in future we could also include CI/CD
and others.
- **Development**: includes how to integrate with Gitea's API, how to
develop new features within Gitea
- **Contributing**: includes how to contribute code to Gitea
repositories.

After this is merged, I think we can have a sub-documentation of `Usage`
part named `Actions` to describe how to use Gitea actions

---------

Co-authored-by: John Olheiser <john.olheiser@gmail.com>

23 files changed, 1041 insertions, 1821 deletions

diff --git a/docs/content/doc/usage/authentication.en-us.md b/docs/content/doc/usage/authentication.en-us.md
new file mode 100644
index 0000000000..5478ee94f6
--- /dev/null
+++ b/docs/content/doc/usage/authentication.en-us.md
@@ -0,0 +1,350 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Authentication"
+slug: "authentication"
+weight: 10
+toc: false
+draft: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "Authentication"
+    weight: 10
+    identifier: "authentication"
+---
+
+# Authentication
+
+{{< toc >}}
+
+## LDAP (Lightweight Directory Access Protocol)
+
+Both the LDAP via BindDN and the simple auth LDAP share the following fields:
+
+- Authorization Name **(required)**
+
+  - A name to assign to the new method of authorization.
+
+- Host **(required)**
+
+  - The address where the LDAP server can be reached.
+  - Example: `mydomain.com`
+
+- Port **(required)**
+
+  - The port to use when connecting to the server.
+  - Example: `389` for LDAP or `636` for LDAP SSL
+
+- Enable TLS Encryption (optional)
+
+  - Whether to use TLS when connecting to the LDAP server.
+
+- Admin Filter (optional)
+
+  - An LDAP filter specifying if a user should be given administrator
+    privileges. If a user account passes the filter, the user will be
+    privileged as an administrator.
+  - Example: `(objectClass=adminAccount)`
+  - Example for Microsoft Active Directory (AD): `(memberOf=CN=admin-group,OU=example,DC=example,DC=org)`
+
+- Username attribute (optional)
+
+  - The attribute of the user's LDAP record containing the user name. Given
+    attribute value will be used for new Gitea account user name after first
+    successful sign-in. Leave empty to use login name given on sign-in form.
+  - This is useful when supplied login name is matched against multiple
+    attributes, but only single specific attribute should be used for Gitea
+    account name, see "User Filter".
+  - Example: `uid`
+  - Example for Microsoft Active Directory (AD): `sAMAccountName`
+
+- First name attribute (optional)
+
+  - The attribute of the user's LDAP record containing the user's first name.
+    This will be used to populate their account information.
+  - Example: `givenName`
+
+- Surname attribute (optional)
+
+  - The attribute of the user's LDAP record containing the user's surname.
+    This will be used to populate their account information.
+  - Example: `sn`
+
+- E-mail attribute **(required)**
+  - The attribute of the user's LDAP record containing the user's email
+    address. This will be used to populate their account information.
+  - Example: `mail`
+
+### LDAP via BindDN
+
+Adds the following fields:
+
+- Bind DN (optional)
+
+  - The DN to bind to the LDAP server with when searching for the user. This
+    may be left blank to perform an anonymous search.
+  - Example: `cn=Search,dc=mydomain,dc=com`
+
+- Bind Password (optional)
+
+  - The password for the Bind DN specified above, if any. _Note: The password
+    is stored encrypted with the SECRET_KEY on the server. It is still recommended
+    to ensure that the Bind DN has as few privileges as possible._
+
+- User Search Base **(required)**
+
+  - The LDAP base at which user accounts will be searched for.
+  - Example: `ou=Users,dc=mydomain,dc=com`
+
+- User Filter **(required)**
+  - An LDAP filter declaring how to find the user record that is attempting to
+    authenticate. The `%s` matching parameter will be substituted with login
+    name given on sign-in form.
+  - Example: `(&(objectClass=posixAccount)(uid=%s))`
+  - Example for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
+  - To substitute more than once, `%[1]s` should be used instead, e.g. when
+    matching supplied login name against multiple attributes such as user
+    identifier, email or even phone number.
+  - Example: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
+- Enable user synchronization
+  - This option enables a periodic task that synchronizes the Gitea users with
+    the LDAP server. The default period is every 24 hours but that can be
+    changed in the app.ini file. See the _cron.sync_external_users_ section in
+    the [sample
+    app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
+    for detailed comments about that section. The _User Search Base_ and _User
+    Filter_ settings described above will limit which users can use Gitea and
+    which users will be synchronized. When initially run the task will create
+    all LDAP users that match the given settings so take care if working with
+    large Enterprise LDAP directories.
+
+### LDAP using simple auth
+
+Adds the following fields:
+
+- User DN **(required)**
+
+  - A template to use as the user's DN. The `%s` matching parameter will be
+    substituted with login name given on sign-in form.
+  - Example: `cn=%s,ou=Users,dc=mydomain,dc=com`
+  - Example: `uid=%s,ou=Users,dc=mydomain,dc=com`
+
+- User Search Base (optional)
+
+  - The LDAP base at which user accounts will be searched for.
+  - Example: `ou=Users,dc=mydomain,dc=com`
+
+- User Filter **(required)**
+  - An LDAP filter declaring when a user should be allowed to log in. The `%s`
+    matching parameter will be substituted with login name given on sign-in
+    form.
+  - Example: `(&(objectClass=posixAccount)(cn=%s))`
+  - Example: `(&(objectClass=posixAccount)(uid=%s))`
+
+### Verify group membership in LDAP
+
+Uses the following fields:
+
+- Group Search Base (optional)
+
+  - The LDAP DN used for groups.
+  - Example: `ou=group,dc=mydomain,dc=com`
+
+- Group Name Filter (optional)
+
+  - An LDAP filter declaring how to find valid groups in the above DN.
+  - Example: `(|(cn=gitea_users)(cn=admins))`
+
+- User Attribute in Group (optional)
+
+  - Which user LDAP attribute is listed in the group.
+  - Example: `uid`
+
+- Group Attribute for User (optional)
+  - Which group LDAP attribute contains an array above user attribute names.
+  - Example: `memberUid`
+
+## PAM (Pluggable Authentication Module)
+
+This procedure enables PAM authentication.  Users may still be added to the
+system manually using the user administration.  PAM provides a mechanism to
+automatically add users to the current database by testing them against PAM
+authentication.  To work with normal Linux passwords, the user running Gitea
+must also have read access to `/etc/shadow` in order to check the validity of
+the account when logging in using a public key.
+
+**Note**: If a user has added SSH public keys into Gitea, the use of these
+keys _may_ bypass the login check system.  Therefore, if you wish to disable a user who
+authenticates with PAM, you _should_ also manually disable the account in Gitea using the
+built-in user manager.
+
+1. Configure and prepare the installation.
+    - It is recommended that you create an administrative user.
+    - Deselecting automatic sign-up may also be desired.
+1. Once the database has been initialized, log in as the newly created
+administrative user.
+1. Navigate to the user setting (icon in top-right corner), and select
+`Site Administration` -> `Authentication Sources`, and select
+`Add Authentication Source`.
+1. Fill out the field as follows:
+    - `Authentication Type` : `PAM`
+    - `Name` : Any value should be valid here, use "System Authentication" if
+    you'd like.
+    - `PAM Service Name` : Select the appropriate file listed under `/etc/pam.d/`
+    that performs the authentication desired.[^1]
+    - `PAM Email Domain` : The e-mail suffix to append to user authentication.
+    For example, if the login system expects a user called `gituser`, and this
+    field is set to `mail.com`, then Gitea will expect the `user email` field
+    for an authenticated GIT instance to be `gituser@mail.com`.[^2]
+
+**Note**: PAM support is added via [build-time flags](https://docs.gitea.io/en-us/install-from-source/#build),
+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
+`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
+user will log into the Gitea web interface as `gituser` and not `gituser@mail.com`
+
+## SMTP (Simple Mail Transfer Protocol)
+
+This option allows Gitea to log in to an SMTP host as a Gitea user. To
+configure this, set the fields below:
+
+- Authentication Name **(required)**
+
+  - A name to assign to the new method of authorization.
+
+- SMTP Authentication Type **(required)**
+
+  - Type of authentication to use to connect to SMTP host, PLAIN or LOGIN.
+
+- Host **(required)**
+
+  - The address where the SMTP host can be reached.
+  - Example: `smtp.mydomain.com`
+
+- Port **(required)**
+
+  - The port to use when connecting to the server.
+  - Example: `587`
+
+- Allowed Domains
+
+  - Restrict what domains can log in if using a public SMTP host or SMTP host
+    with multiple domains.
+  - Example: `gitea.io,mydomain.com,mydomain2.com`
+
+- Force SMTPS
+
+  - SMTPS will be used by default for connections to port 465, if you wish to use SMTPS
+  for other ports. Set this value.
+  - Otherwise if the server provides the `STARTTLS` extension this will be used.
+
+- Skip TLS Verify
+
+  - Disable TLS verify on authentication.
+
+- This Authentication Source is Activated
+  - Enable or disable this authentication source.
+
+## FreeIPA
+
+- In order to log in to Gitea using FreeIPA credentials, a bind account needs to
+  be created for Gitea:
+
+- On the FreeIPA server, create a `gitea.ldif` file, replacing `dc=example,dc=com`
+  with your DN, and provide an appropriately secure password:
+
+  ```sh
+  dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
+  changetype: add
+  objectclass: account
+  objectclass: simplesecurityobject
+  uid: gitea
+  userPassword: secure password
+  passwordExpirationTime: 20380119031407Z
+  nsIdleTimeout: 0
+  ```
+
+- Import the LDIF (change localhost to an IPA server if needed). A prompt for
+  Directory Manager password will be presented:
+
+  ```sh
+  ldapmodify -h localhost -p 389 -x -D \
+  "cn=Directory Manager" -W -f gitea.ldif
+  ```
+
+- Add an IPA group for gitea_users :
+
+  ```sh
+  ipa group-add --desc="Gitea Users" gitea_users
+  ```
+
+- Note: For errors about IPA credentials, run `kinit admin` and provide the
+  domain admin account password.
+
+- Log in to Gitea as an Administrator and click on "Authentication" under Admin Panel.
+  Then click `Add New Source` and fill in the details, changing all where appropriate.
+
+## SPNEGO with SSPI (Kerberos/NTLM, for Windows only)
+
+Gitea supports SPNEGO single sign-on authentication (the scheme defined by RFC4559) for the web part of the server via the Security Support Provider Interface (SSPI) built in Windows. SSPI works only in Windows environments - when both the server and the clients are running Windows.
+
+Before activating SSPI single sign-on authentication (SSO) you have to prepare your environment:
+
+- Create a separate user account in active directory, under which the `gitea.exe` process will be running (eg. `user` under domain `domain.local`):
+
+- Create a service principal name for the host where `gitea.exe` is running with class `HTTP`:
+
+  - Start `Command Prompt` or `PowerShell` as a privileged domain user (eg. Domain Administrator)
+  - Run the command below, replacing `host.domain.local` with the fully qualified domain name (FQDN) of the server where the web application will be running, and `domain\user` with the name of the account created in the previous step:
+
+  ```sh
+  setspn -A HTTP/host.domain.local domain\user
+  ```
+
+- Sign in (_sign out if you were already signed in_) with the user created
+
+- Make sure that `ROOT_URL` in the `[server]` section of `custom/conf/app.ini` is the fully qualified domain name of the server where the web application will be running - the same you used when creating the service principal name (eg. `host.domain.local`)
+
+- Start the web server (`gitea.exe web`)
+
+- Enable SSPI authentication by adding an `SPNEGO with SSPI` authentication source in `Site Administration -> Authentication Sources`
+
+- Sign in to a client computer in the same domain with any domain user (client computer, different from the server running `gitea.exe`)
+
+- If you are using Chrome or Edge, add the URL of the web app to the Local intranet sites (`Internet Options -> Security -> Local intranet -> Sites`)
+
+- Start Chrome or Edge and navigate to the FQDN URL of Gitea (eg. `http://host.domain.local:3000`)
+
+- Click the `Sign In` button on the dashboard and choose SSPI to be automatically logged in with the same user that is currently logged on to the computer
+
+- If it does not work, make sure that:
+  - You are not running the web browser on the same server where Gitea is running. You should be running the web browser on a domain joined computer (client) that is different from the server. If both the client and server are running on the same computer NTLM will be preferred over Kerberos.
+  - There is only one `HTTP/...` SPN for the host
+  - The SPN contains only the hostname, without the port
+  - You have added the URL of the web app to the `Local intranet zone`
+  - The clocks of the server and client should not differ with more than 5 minutes (depends on group policy)
+  - `Integrated Windows Authentication` should be enabled in Internet Explorer (under `Advanced settings`)
+
+## Reverse Proxy
+
+Gitea supports Reverse Proxy Header authentication, it will read headers as a trusted login user name or user email address. This hasn't been enabled by default, you can enable it with
+
+```ini
+[service]
+ENABLE_REVERSE_PROXY_AUTHENTICATION = true
+```
+
+The default login user name is in the `X-WEBAUTH-USER` header, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_USER` in app.ini. If the user doesn't exist, you can enable automatic registration with `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true`.
+
+The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_EMAIL` in app.ini, this could also be disabled with `ENABLE_REVERSE_PROXY_EMAIL`
+
+If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`.
+
+You can also limit the reverse proxy's IP address range with `REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `REVERSE_PROXY_LIMIT`, you can limit trusted proxies level.
+
+Notice: Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests.
diff --git a/docs/content/doc/usage/authentication.zh-cn.md b/docs/content/doc/usage/authentication.zh-cn.md
new file mode 100644
index 0000000000..403c3f43ce
--- /dev/null
+++ b/docs/content/doc/usage/authentication.zh-cn.md
@@ -0,0 +1,35 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "认证"
+slug: "authentication"
+weight: 10
+toc: false
+draft: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "认证"
+    weight: 10
+    identifier: "authentication"
+---
+
+# 认证
+
+## 反向代理认证
+
+Gitea 支持通过读取反向代理传递的 HTTP 头中的登录名或者 email 地址来支持反向代理来认证。默认是不启用的，你可以用以下配置启用。
+
+```ini
+[service]
+ENABLE_REVERSE_PROXY_AUTHENTICATION = true
+```
+
+默认的登录用户名的 HTTP 头是 `X-WEBAUTH-USER`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_USER` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。
+
+默认的登录用户 Email 的 HTTP 头是 `X-WEBAUTH-EMAIL`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_EMAIL` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。你也可以通过修改 `ENABLE_REVERSE_PROXY_EMAIL` 来启用或停用这个 HTTP 头。
+
+如果设置了 `ENABLE_REVERSE_PROXY_FULL_NAME=true`，则用户的全名会从 `X-WEBAUTH-FULLNAME` 读取，这样在自动创建用户时将使用这个字段作为用户全名，你也可以通过修改 `REVERSE_PROXY_AUTHENTICATION_FULL_NAME` 来变更 HTTP 头。
+
+你也可以通过修改 `REVERSE_PROXY_TRUSTED_PROXIES` 来设置反向代理的IP地址范围，加强安全性，默认值是 `127.0.0.0/8,::1/128`。 通过 `REVERSE_PROXY_LIMIT`， 可以设置最多信任几级反向代理。
+
+注意：反向代理认证不支持认证 API，API 仍旧需要用 access token 来进行认证。
diff --git a/docs/content/doc/usage/authentication.zh-tw.md b/docs/content/doc/usage/authentication.zh-tw.md
new file mode 100644
index 0000000000..958c498fc6
--- /dev/null
+++ b/docs/content/doc/usage/authentication.zh-tw.md
@@ -0,0 +1,18 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "認證"
+slug: "authentication"
+weight: 10
+toc: false
+draft: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "認證"
+    weight: 10
+    identifier: "authentication"
+---
+
+# 認證
+
+## TBD
diff --git a/docs/content/doc/usage/backup-and-restore.en-us.md b/docs/content/doc/usage/backup-and-restore.en-us.md
deleted file mode 100644
index cae097082e..0000000000
--- a/docs/content/doc/usage/backup-and-restore.en-us.md
+++ /dev/null
@@ -1,170 +0,0 @@
----
-date: "2017-01-01T16:00:00+02:00"
-title: "Usage: Backup and Restore"
-slug: "backup-and-restore"
-weight: 11
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "Backup and Restore"
-    weight: 11
-    identifier: "backup-and-restore"
----
-
-# Backup and Restore
-
-Gitea currently has a `dump` command that will save the installation to a ZIP file. This
-file can be unpacked and used to restore an instance.
-
-**Table of Contents**
-
-{{< toc >}}
-
-## Backup Consistency
-
-To ensure the consistency of the Gitea instance, it must be shutdown during backup.
-
-Gitea consists of a database, files and git repositories, all of which change when it is used. For instance, when a migration is in progress, a transaction is created in the database while the git repository is being copied over. If the backup happens in the middle of the migration, the git repository may be incomplete although the database claims otherwise because it was dumped afterwards. The only way to avoid such race conditions is by stopping the Gitea instance during the backups.
-
-## Backup Command (`dump`)
-
-Switch to the user running Gitea: `su git`. Run `./gitea dump -c /path/to/app.ini` in the Gitea installation
-directory. There should be some output similar to the following:
-
-```none
-2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
-2016/12/27 22:32:22 Dumping database...
-2016/12/27 22:32:22 Packing dump files...
-2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
-```
-
-Inside the `gitea-dump-1482906742.zip` file, will be the following:
-
-- `app.ini` - Optional copy of configuration file if originally stored outside of the default `custom/` directory
-- `custom` - All config or customization files in `custom/`.
-- `data` - Data directory in <GITEA_WORK_DIR>, except sessions if you are using file session. This directory includes `attachments`, `avatars`, `lfs`, `indexers`, SQLite file if you are using SQLite.
-- `gitea-db.sql` - SQL dump of database
-- `gitea-repo.zip` - Complete copy of the repository directory.
-- `log/` - Various logs. They are not needed for a recovery or migration.
-
-Intermediate backup files are created in a temporary directory specified either with the
-`--tempdir` command-line parameter or the `TMPDIR` environment variable.
-
-## Backup the database
-
-The SQL dump created by `gitea dump` uses XORM and Gitea admins may prefer to use the native the MySQL and PostgreSQL dump tools instead. There are still open issues when using XORM for dumping the database that may cause problems when attempting to restore it.
-
-```sh
-# mysql
-mysqldump -u$USER -p$PASS --database $DATABASE > gitea-db.sql
-# postgres
-pg_dump -U $USER $DATABASE > gitea-db.sql
-```
-
-### Using Docker (`dump`)
-
-There are a few caveats for using the `dump` command with Docker.
-
-The command has to be executed with the `RUN_USER = <OS_USERNAME>` specified in `gitea/conf/app.ini`; and, for the zipping of the backup folder to occur without permission error the command `docker exec` must be executed inside of the `--tempdir`.
-
-Example:
-
-```none
-docker exec -u <OS_USERNAME> -it -w <--tempdir> $(docker ps -qf 'name=^<NAME_OF_DOCKER_CONTAINER>$') bash -c '/usr/local/bin/gitea dump -c </path/to/app.ini>'
-```
-
-\*Note: `--tempdir` refers to the temporary directory of the docker environment used by Gitea; if you have not specified a custom `--tempdir`, then Gitea uses `/tmp` or the `TMPDIR` environment variable of the docker container. For `--tempdir` adjust your `docker exec` command options accordingly.
-
-The result should be a file, stored in the `--tempdir` specified, along the lines of: `gitea-dump-1482906742.zip`
-
-## Restore Command (`restore`)
-
-There is currently no support for a recovery command. It is a manual process that mostly
-involves moving files to their correct locations and restoring a database dump.
-
-Example:
-
-```sh
-unzip gitea-dump-1610949662.zip
-cd gitea-dump-1610949662
-mv data/conf/app.ini /etc/gitea/conf/app.ini
-mv data/* /var/lib/gitea/data/
-mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/repositories/
-chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
-
-# mysql
-mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE <gitea-db.sql
-# sqlite3
-sqlite3 $DATABASE_PATH <gitea-db.sql
-# postgres
-psql -U $USER -d $DATABASE < gitea-db.sql
-
-service gitea restart
-```
-
-Repository Git Hooks should be regenerated if installation method is changed (eg. binary -> Docker), or if Gitea is installed to a different directory than the previous installation.
-
-With Gitea running, and from the directory Gitea's binary is located, execute: `./gitea admin regenerate hooks`
-
-This ensures that application and configuration file paths in repository Git Hooks are consistent and applicable to the current installation. If these paths are not updated, repository `push` actions will fail.
-
-### Using Docker (`restore`)
-
-There is also no support for a recovery command in a Docker-based gitea instance. The restore process contains the same steps as described in the previous section but with different paths.
-
-Example:
-
-```sh
-# open bash session in container
-docker exec --user git -it 2a83b293548e bash
-# unzip your backup file within the container
-unzip gitea-dump-1610949662.zip
-cd gitea-dump-1610949662
-# restore the gitea data
-mv data/* /data/gitea
-# restore the repositories itself
-mv repos/* /data/git/repositories/
-# adjust file permissions
-chown -R git:git /data
-# Regenerate Git Hooks
-/usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks
-```
-
-The default user in the gitea container is `git` (1000:1000). Please replace `2a83b293548e` with your gitea container id or name.
-
-These are the default paths used in the container:
-
-```text
-DEFAULT CONFIGURATION:
-     CustomPath:  /data/gitea (GITEA_CUSTOM)
-     CustomConf:  /data/gitea/conf/app.ini
-     AppPath:     /usr/local/bin/gitea
-     AppWorkPath: /usr/local/bin
-```
-
-### Using Docker-rootless (`restore`)
-
-The restore workflow in Docker-rootless containers differs only in the directories to be used:
-
-```sh
-# open bash session in container
-docker exec --user git -it 2a83b293548e bash
-# unzip your backup file within the container
-unzip gitea-dump-1610949662.zip
-cd gitea-dump-1610949662
-# restore the app.ini
-mv data/conf/app.ini /etc/gitea/app.ini
-# restore the gitea data
-mv data/* /var/lib/gitea
-# restore the repositories itself
-mv repos/* /var/lib/gitea/git/repositories
-# adjust file permissions
-chown -R git:git /etc/gitea/app.ini /var/lib/gitea
-# Regenerate Git Hooks
-/usr/local/bin/gitea -c '/etc/gitea/app.ini' admin regenerate hooks
-```
diff --git a/docs/content/doc/usage/backup-and-restore.zh-cn.md b/docs/content/doc/usage/backup-and-restore.zh-cn.md
deleted file mode 100644
index 43ad108d95..0000000000
--- a/docs/content/doc/usage/backup-and-restore.zh-cn.md
+++ /dev/null
@@ -1,66 +0,0 @@
----
-date: "2018-06-06T09:33:00+08:00"
-title: "使用：备份与恢复"
-slug: "backup-and-restore"
-weight: 11
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "备份与恢复"
-    weight: 11
-    identifier: "backup-and-restore"
----
-
-# 备份与恢复
-
-Gitea 已经实现了 `dump` 命令可以用来备份所有需要的文件到一个zip压缩文件。该压缩文件可以被用来进行数据恢复。
-
-## 备份命令 (`dump`)
-
-先转到git用户的权限: `su git`. 再Gitea目录运行 `./gitea dump`。一般会显示类似如下的输出：
-
-```
-2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
-2016/12/27 22:32:22 Dumping database...
-2016/12/27 22:32:22 Packing dump files...
-2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
-```
-
-最后生成的 `gitea-dump-1482906742.zip` 文件将会包含如下内容：
-
-* `custom` - 所有保存在 `custom/` 目录下的配置和自定义的文件。
-* `data` - 数据目录下的所有内容不包含使用文件session的文件。该目录包含 `attachments`, `avatars`, `lfs`, `indexers`, 如果使用sqlite 还会包含 sqlite 数据库文件。
-* `gitea-db.sql` - 数据库dump出来的 SQL。
-* `gitea-repo.zip` - Git仓库压缩文件。
-* `log/` - Logs文件，如果用作迁移不是必须的。
-
-中间备份文件将会在临时目录进行创建，如果您要重新指定临时目录，可以用 `--tempdir` 参数，或者用 `TMPDIR` 环境变量。
-
-## Restore Command (`restore`)
-
-当前还没有恢复命令，恢复需要人工进行。主要是把文件和数据库进行恢复。
-
-例如：
-
-```sh
-unzip gitea-dump-1610949662.zip
-cd gitea-dump-1610949662
-mv data/conf/app.ini /etc/gitea/conf/app.ini
-mv data/* /var/lib/gitea/data/
-mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/repositories/
-chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
-
-# mysql
-mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE <gitea-db.sql
-# sqlite3
-sqlite3 $DATABASE_PATH <gitea-db.sql
-# postgres
-psql -U $USER -d $DATABASE < gitea-db.sql
-
-service gitea restart
-```
diff --git a/docs/content/doc/usage/backup-and-restore.zh-tw.md b/docs/content/doc/usage/backup-and-restore.zh-tw.md
deleted file mode 100644
index 18e244b19c..0000000000
--- a/docs/content/doc/usage/backup-and-restore.zh-tw.md
+++ /dev/null
@@ -1,66 +0,0 @@
----
-date: "2017-01-01T16:00:00+02:00"
-title: "用法: 備份與還原"
-slug: "backup-and-restore"
-weight: 11
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "備份與還原"
-    weight: 11
-    identifier: "backup-and-restore"
----
-
-# 備份與還原
-
-Gitea 目前支援 `dump` 指令，用來將資料備份成 zip 檔案，後續會提供還原指令，讓你可以輕易的將備份資料及還原到另外一台機器。
-
-## 備份指令 (`dump`)
-
-首先，切換到執行 Gitea 的使用者: `su git` (請修改成您指定的使用者)，並在安裝目錄內執行 `./gitea dump` 指令，你可以看到 console 畫面如下:
-
-```
-2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
-2016/12/27 22:32:22 Dumping database...
-2016/12/27 22:32:22 Packing dump files...
-2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
-```
-
-備份出來的 `gitea-dump-1482906742.zip` 檔案，檔案內會包含底下內容:
-
-* `custom/conf/app.ini` - 伺服器設定檔。
-* `gitea-db.sql` - SQL 備份檔案。
-* `gitea-repo.zip` - 此 zip 檔案為全部的 repo 目錄。
-   請參考 Config -> repository -> `ROOT` 所設定的路徑。
-* `log/` - 全部 logs 檔案，如果你要 migrate 到其他伺服器，此目錄不用保留。
-
-你可以透過設定 `--tempdir` 指令參數來指定備份檔案目錄，或者是設定 `TMPDIR` 環境變數來達到此功能。
-
-## 還原指令 (`restore`)
-
-持續更新中: 此文件尚未完成.
-
-例:
-
-```sh
-unzip gitea-dump-1610949662.zip
-cd gitea-dump-1610949662
-mv data/conf/app.ini /etc/gitea/conf/app.ini
-mv data/* /var/lib/gitea/data/
-mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/repositories/
-chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
-
-# mysql
-mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE <gitea-db.sql
-# sqlite3
-sqlite3 $DATABASE_PATH <gitea-db.sql
-# postgres
-psql -U $USER -d $DATABASE < gitea-db.sql
-
-service gitea restart
-```
diff --git a/docs/content/doc/usage/clone-filter.en-us.md b/docs/content/doc/usage/clone-filter.en-us.md
new file mode 100644
index 0000000000..7d4ba2d9a8
--- /dev/null
+++ b/docs/content/doc/usage/clone-filter.en-us.md
@@ -0,0 +1,37 @@
+---
+date: "2021-02-02"
+title: "Clone filters (partial clone)"
+slug: "clone-filters"
+weight: 25
+draft: false
+toc: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "Clone filters"
+    weight: 25
+    identifier: "clone-filters"
+---
+
+# Clone filters (partial clone)
+
+Git introduces `--filter` option to `git clone` command, which filters out
+large files and objects (such as blobs) to create partial clone of a repo.
+Clone filters are especially useful for large repo and/or metered connection,
+where full clone (without `--filter`) can be expensive (as all history data
+must be downloaded).
+
+This requires Git version 2.22 or later, both on the Gitea server and on the
+client. For clone filters to work properly, make sure that Git version
+on the client is at least the same as on the server (or later). Login to
+Gitea server as admin and head to Site Administration -> Configuration to
+see Git version of the server.
+
+By default, clone filters are enabled, unless `DISABLE_PARTIAL_CLONE` under
+`[git]` is set to `true`.
+
+See [GitHub blog post: Get up to speed with partial clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/)
+for common use cases of clone filters (blobless and treeless clones), and
+[GitLab docs for partial clone](https://docs.gitlab.com/ee/topics/git/partial_clone.html)
+for more advanced use cases (such as filter by file size and remove
+filters to turn partial clone into full clone).
diff --git a/docs/content/doc/usage/command-line.en-us.md b/docs/content/doc/usage/command-line.en-us.md
deleted file mode 100644
index 70efebd203..0000000000
--- a/docs/content/doc/usage/command-line.en-us.md
+++ /dev/null
@@ -1,553 +0,0 @@
----
-date: "2017-01-01T16:00:00+02:00"
-title: "Usage: Command Line"
-slug: "command-line"
-weight: 10
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "Command Line"
-    weight: 10
-    identifier: "command-line"
----
-
-# Command Line
-
-**Table of Contents**
-
-{{< toc >}}
-
-## Usage
-
-`gitea [global options] command [command or global options] [arguments...]`
-
-## Global options
-
-All global options can be placed at the command level.
-
-- `--help`, `-h`: Show help text and exit. Optional.
-- `--version`, `-v`: Show version and exit. Optional. (example: `Gitea version 1.1.0+218-g7b907ed built with: bindata, sqlite`).
-- `--custom-path path`, `-C path`: Location of the Gitea custom folder. Optional. (default: `AppWorkPath`/custom or `$GITEA_CUSTOM`).
-- `--config path`, `-c path`: Gitea configuration file path. Optional. (default: `custom`/conf/app.ini).
-- `--work-path path`, `-w path`: Gitea `AppWorkPath`. Optional. (default: LOCATION_OF_GITEA_BINARY or `$GITEA_WORK_DIR`)
-
-NB: The defaults custom-path, config and work-path can also be
-changed at build time (if preferred).
-
-## Commands
-
-### web
-
-Starts the server:
-
-- Options:
-  - `--port number`, `-p number`: Port number. Optional. (default: 3000). Overrides configuration file.
-  - `--install-port number`: Port number to run the install page on. Optional. (default: 3000). Overrides configuration file.
-  - `--pid path`, `-P path`: Pidfile path. Optional.
-  - `--quiet`, `-q`: Only emit Fatal logs on the console for logs emitted before logging set up.
-  - `--verbose`: Emit tracing logs on the console for logs emitted before logging is set-up.
-- Examples:
-  - `gitea web`
-  - `gitea web --port 80`
-  - `gitea web --config /etc/gitea.ini --pid /some/custom/gitea.pid`
-- Notes:
-  - Gitea should not be run as root. To bind to a port below 1024, you can use setcap on
-    Linux: `sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea`. This will need to be
-    redone every time you update Gitea.
-
-### admin
-
-Admin operations:
-
-- Commands:
-  - `user`:
-    - `list`:
-      - Options:
-        - `--admin`: List only admin users. Optional.
-      - Description: lists all users that exist
-      - Examples:
-        - `gitea admin user list`
-    - `delete`:
-      - Options:
-        - `--email`: Email of the user to be deleted.
-        - `--username`: Username of user to be deleted.
-        - `--id`: ID of user to be deleted.
-        - One of `--id`, `--username` or `--email` is required. If more than one is provided then all have to match.
-      - Examples:
-        - `gitea admin user delete --id 1`
-    - `create`:
-      - Options:
-        - `--name value`: Username. Required. As of Gitea 1.9.0, use the `--username` flag instead.
-        - `--username value`: Username. Required. New in Gitea 1.9.0.
-        - `--password value`: Password. Required.
-        - `--email value`: Email. Required.
-        - `--admin`: If provided, this makes the user an admin. Optional.
-        - `--access-token`: If provided, an access token will be created for the user. Optional. (default: false).
-        - `--must-change-password`: If provided, the created user will be required to choose a newer password after the
-          initial login. Optional. (default: true).
-        - `--random-password`: If provided, a randomly generated password will be used as the password of the created
-          user. The value of `--password` will be discarded. Optional.
-        - `--random-password-length`: If provided, it will be used to configure the length of the randomly generated
-          password. Optional. (default: 12)
-      - Examples:
-        - `gitea admin user create --username myname --password asecurepassword --email me@example.com`
-    - `change-password`:
-      - Options:
-        - `--username value`, `-u value`: Username. Required.
-        - `--password value`, `-p value`: New password. Required.
-      - Examples:
-        - `gitea admin user change-password --username myname --password asecurepassword`
-    - `must-change-password`:
-      - Args:
-        - `[username...]`: Users that must change their passwords
-      - Options:
-        - `--all`, `-A`: Force a password change for all users
-        - `--exclude username`, `-e username`: Exclude the given user. Can be set multiple times.
-        - `--unset`: Revoke forced password change for the given users
-  - `regenerate`
-    - Options:
-      - `hooks`: Regenerate Git Hooks for all repositories
-      - `keys`: Regenerate authorized_keys file
-    - Examples:
-      - `gitea admin regenerate hooks`
-      - `gitea admin regenerate keys`
-  - `auth`:
-    - `list`:
-      - Description: lists all external authentication sources that exist
-      - Examples:
-        - `gitea admin auth list`
-    - `delete`:
-      - Options:
-        - `--id`: ID of source to be deleted. Required.
-      - Examples:
-        - `gitea admin auth delete --id 1`
-    - `add-oauth`:
-      - Options:
-        - `--name`: Application Name.
-        - `--provider`: OAuth2 Provider.
-        - `--key`: Client ID (Key).
-        - `--secret`: Client Secret.
-        - `--auto-discover-url`: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
-        - `--use-custom-urls`: Use custom URLs for GitLab/GitHub OAuth endpoints.
-        - `--custom-tenant-id`: Use custom Tenant ID for OAuth endpoints.
-        - `--custom-auth-url`: Use a custom Authorization URL (option for GitLab/GitHub).
-        - `--custom-token-url`: Use a custom Token URL (option for GitLab/GitHub).
-        - `--custom-profile-url`: Use a custom Profile URL (option for GitLab/GitHub).
-        - `--custom-email-url`: Use a custom Email URL (option for GitHub).
-        - `--icon-url`: Custom icon URL for OAuth2 login source.
-        - `--skip-local-2fa`: Allow source to override local 2FA. (Optional)
-        - `--scopes`: Additional scopes to request for this OAuth2 source. (Optional)
-        - `--required-claim-name`: Claim name that has to be set to allow users to login with this source. (Optional)
-        - `--required-claim-value`: Claim value that has to be set to allow users to login with this source. (Optional)
-        - `--group-claim-name`: Claim name providing group names for this source. (Optional)
-        - `--admin-group`: Group Claim value for administrator users. (Optional)
-        - `--restricted-group`: Group Claim value for restricted users. (Optional)
-        - `--group-team-map`: JSON mapping between groups and org teams. (Optional)
-        - `--group-team-map-removal`: Activate automatic team membership removal depending on groups. (Optional)
-      - Examples:
-        - `gitea admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE`
-    - `update-oauth`:
-      - Options:
-        - `--id`: ID of source to be updated. Required.
-        - `--name`: Application Name.
-        - `--provider`: OAuth2 Provider.
-        - `--key`: Client ID (Key).
-        - `--secret`: Client Secret.
-        - `--auto-discover-url`: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
-        - `--use-custom-urls`: Use custom URLs for GitLab/GitHub OAuth endpoints.
-        - `--custom-tenant-id`: Use custom Tenant ID for OAuth endpoints.
-        - `--custom-auth-url`: Use a custom Authorization URL (option for GitLab/GitHub).
-        - `--custom-token-url`: Use a custom Token URL (option for GitLab/GitHub).
-        - `--custom-profile-url`: Use a custom Profile URL (option for GitLab/GitHub).
-        - `--custom-email-url`: Use a custom Email URL (option for GitHub).
-        - `--icon-url`: Custom icon URL for OAuth2 login source.
-        - `--skip-local-2fa`: Allow source to override local 2FA. (Optional)
-        - `--scopes`: Additional scopes to request for this OAuth2 source.
-        - `--required-claim-name`: Claim name that has to be set to allow users to login with this source. (Optional)
-        - `--required-claim-value`: Claim value that has to be set to allow users to login with this source. (Optional)
-        - `--group-claim-name`: Claim name providing group names for this source. (Optional)
-        - `--admin-group`: Group Claim value for administrator users. (Optional)
-        - `--restricted-group`: Group Claim value for restricted users. (Optional)
-      - Examples:
-        - `gitea admin auth update-oauth --id 1 --name external-github-updated`
-    - `add-smtp`:
-      - Options:
-        - `--name`: Application Name. Required.
-        - `--auth-type`: SMTP Authentication Type (PLAIN/LOGIN/CRAM-MD5). Default to PLAIN.
-        - `--host`: SMTP host. Required.
-        - `--port`: SMTP port. Required.
-        - `--force-smtps`: SMTPS is always used on port 465. Set this to force SMTPS on other ports.
-        - `--skip-verify`: Skip TLS verify.
-        - `--helo-hostname`: Hostname sent with HELO. Leave blank to send current hostname.
-        - `--disable-helo`: Disable SMTP helo.
-        - `--allowed-domains`: Leave empty to allow all domains. Separate multiple domains with a comma (',').
-        - `--skip-local-2fa`: Skip 2FA to log on.
-        - `--active`: This Authentication Source is Activated.
-        Remarks:
-        `--force-smtps`, `--skip-verify`, `--disable-helo`, `--skip-loca-2fs` and `--active` options can be used in form:
-        - `--option`, `--option=true` to enable
-        - `--option=false` to disable
-        If those options are not specified value would not be changed in `update-smtp` or would use default `false` value in `add-smtp`
-      - Examples:
-        - `gitea admin auth add-smtp --name ldap --host smtp.mydomain.org --port 587 --skip-verify --active`
-    - `update-smtp`:
-      - Options:
-        - `--id`: ID of source to be updated. Required.
-        - other options are shared with `add-smtp`
-      - Examples:
-        - `gitea admin auth update-smtp --id 1 --host smtp.mydomain.org --port 587 --skip-verify=false`
-        - `gitea admin auth update-smtp --id 1 --active=false`
-    - `add-ldap`: Add new LDAP (via Bind DN) authentication source
-      - Options:
-        - `--name value`: Authentication name. Required.
-        - `--not-active`: Deactivate the authentication source.
-        - `--security-protocol value`: Security protocol name. Required.
-        - `--skip-tls-verify`: Disable TLS verification.
-        - `--host value`: The address where the LDAP server can be reached. Required.
-        - `--port value`: The port to use when connecting to the LDAP server. Required.
-        - `--user-search-base value`: The LDAP base at which user accounts will be searched for. Required.
-        - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
-        - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
-        - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
-        - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
-        - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
-        - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
-        - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. Required.
-        - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
-        - `--avatar-attribute value`: The attribute of the user’s LDAP record containing the user’s avatar.
-        - `--bind-dn value`: The DN to bind to the LDAP server with when searching for the user.
-        - `--bind-password value`: The password for the Bind DN, if any.
-        - `--attributes-in-bind`: Fetch attributes in bind DN context.
-        - `--synchronize-users`: Enable user synchronization.
-        - `--page-size value`: Search page size.
-      - Examples:
-        - `gitea admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(uid=%s))" --email-attribute mail`
-    - `update-ldap`: Update existing LDAP (via Bind DN) authentication source
-      - Options:
-        - `--id value`: ID of authentication source. Required.
-        - `--name value`: Authentication name.
-        - `--not-active`: Deactivate the authentication source.
-        - `--security-protocol value`: Security protocol name.
-        - `--skip-tls-verify`: Disable TLS verification.
-        - `--host value`: The address where the LDAP server can be reached.
-        - `--port value`: The port to use when connecting to the LDAP server.
-        - `--user-search-base value`: The LDAP base at which user accounts will be searched for.
-        - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate.
-        - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
-        - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
-        - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
-        - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
-        - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
-        - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address.
-        - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
-        - `--avatar-attribute value`: The attribute of the user’s LDAP record containing the user’s avatar.
-        - `--bind-dn value`: The DN to bind to the LDAP server with when searching for the user.
-        - `--bind-password value`: The password for the Bind DN, if any.
-        - `--attributes-in-bind`: Fetch attributes in bind DN context.
-        - `--synchronize-users`: Enable user synchronization.
-        - `--page-size value`: Search page size.
-      - Examples:
-        - `gitea admin auth update-ldap --id 1 --name "my ldap auth source"`
-        - `gitea admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
-    - `add-ldap-simple`: Add new LDAP (simple auth) authentication source
-      - Options:
-        - `--name value`: Authentication name. Required.
-        - `--not-active`: Deactivate the authentication source.
-        - `--security-protocol value`: Security protocol name. Required.
-        - `--skip-tls-verify`: Disable TLS verification.
-        - `--host value`: The address where the LDAP server can be reached. Required.
-        - `--port value`: The port to use when connecting to the LDAP server. Required.
-        - `--user-search-base value`: The LDAP base at which user accounts will be searched for.
-        - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
-        - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
-        - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
-        - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
-        - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
-        - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
-        - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. Required.
-        - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
-        - `--avatar-attribute value`: The attribute of the user’s LDAP record containing the user’s avatar.
-        - `--user-dn value`: The user’s DN. Required.
-      - Examples:
-        - `gitea admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail`
-    - `update-ldap-simple`: Update existing LDAP (simple auth) authentication source
-      - Options:
-        - `--id value`: ID of authentication source. Required.
-        - `--name value`: Authentication name.
-        - `--not-active`: Deactivate the authentication source.
-        - `--security-protocol value`: Security protocol name.
-        - `--skip-tls-verify`: Disable TLS verification.
-        - `--host value`: The address where the LDAP server can be reached.
-        - `--port value`: The port to use when connecting to the LDAP server.
-        - `--user-search-base value`: The LDAP base at which user accounts will be searched for.
-        - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate.
-        - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
-        - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
-        - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
-        - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
-        - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
-        - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address.
-        - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
-        - `--avatar-attribute value`: The attribute of the user’s LDAP record containing the user’s avatar.
-        - `--user-dn value`: The user’s DN.
-      - Examples:
-        - `gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"`
-        - `gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
-
-### cert
-
-Generates a self-signed SSL certificate. Outputs to `cert.pem` and `key.pem` in the current
-directory and will overwrite any existing files.
-
-- Options:
-  - `--host value`: Comma separated hostnames and ips which this certificate is valid for.
-    Wildcards are supported. Required.
-  - `--ecdsa-curve value`: ECDSA curve to use to generate a key. Optional. Valid options
-    are P224, P256, P384, P521.
-  - `--rsa-bits value`: Size of RSA key to generate. Optional. Ignored if --ecdsa-curve is
-    set. (default: 2048).
-  - `--start-date value`: Creation date. Optional. (format: `Jan 1 15:04:05 2011`).
-  - `--duration value`: Duration which the certificate is valid for. Optional. (default: 8760h0m0s)
-  - `--ca`: If provided, this cert generates it's own certificate authority. Optional.
-- Examples:
-  - `gitea cert --host git.example.com,example.com,www.example.com --ca`
-
-### dump
-
-Dumps all files and databases into a zip file. Outputs into a file like `gitea-dump-1482906742.zip`
-in the current directory.
-
-- Options:
-  - `--file name`, `-f name`: Name of the dump file with will be created. Optional. (default: gitea-dump-[timestamp].zip).
-  - `--tempdir path`, `-t path`: Path to the temporary directory used. Optional. (default: /tmp).
-  - `--skip-repository`, `-R`: Skip the repository dumping. Optional.
-  - `--skip-custom-dir`: Skip dumping of the custom dir. Optional.
-  - `--skip-lfs-data`: Skip dumping of LFS data. Optional.
-  - `--skip-attachment-data`: Skip dumping of attachment data. Optional.
-  - `--skip-package-data`: Skip dumping of package data. Optional.
-  - `--skip-log`: Skip dumping of log data. Optional.
-  - `--database`, `-d`: Specify the database SQL syntax. Optional.
-  - `--verbose`, `-V`: If provided, shows additional details. Optional.
-  - `--type`: Set the dump output format. Optional. (default: zip)
-- Examples:
-  - `gitea dump`
-  - `gitea dump --verbose`
-
-### generate
-
-Generates random values and tokens for usage in configuration file. Useful for generating values
-for automatic deployments.
-
-- Commands:
-  - `secret`:
-    - Options:
-      - `INTERNAL_TOKEN`: Token used for an internal API call authentication.
-      - `JWT_SECRET`: LFS & OAUTH2 JWT authentication secret (LFS_JWT_SECRET is aliased to this option for backwards compatibility).
-      - `SECRET_KEY`: Global secret key.
-    - Examples:
-      - `gitea generate secret INTERNAL_TOKEN`
-      - `gitea generate secret JWT_SECRET`
-      - `gitea generate secret SECRET_KEY`
-
-### keys
-
-Provides an SSHD AuthorizedKeysCommand. Needs to be configured in the sshd config file:
-
-```ini
-...
-# The value of -e and the AuthorizedKeysCommandUser should match the
-# username running Gitea
-AuthorizedKeysCommandUser git
-AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k
-```
-
-The command will return the appropriate authorized_keys line for the
-provided key. You should also set the value
-`SSH_CREATE_AUTHORIZED_KEYS_FILE=false` in the `[server]` section of
-`app.ini`.
-
-NB: opensshd requires the Gitea program to be owned by root and not
-writable by group or others. The program must be specified by an absolute
-path.
-NB: Gitea must be running for this command to succeed.
-
-### migrate
-
-Migrates the database. This command can be used to run other commands before starting the server for the first time.
-This command is idempotent.
-
-### convert
-
-Converts an existing MySQL database from utf8 to utf8mb4.
-
-### doctor
-
-Diagnose the problems of current Gitea instance according the given configuration.
-Currently there are a check list below:
-
-- Check if OpenSSH authorized_keys file id correct
-  When your Gitea instance support OpenSSH, your Gitea instance binary path will be written to `authorized_keys`
-  when there is any public key added or changed on your Gitea instance.
-  Sometimes if you moved or renamed your Gitea binary when upgrade and you haven't run `Update the '.ssh/authorized_keys' file with Gitea SSH keys. (Not needed for the built-in SSH server.)` on your Admin Panel. Then all pull/push via SSH will not be work.
-  This check will help you to check if it works well.
-
-For contributors, if you want to add more checks, you can write a new function like `func(ctx *cli.Context) ([]string, error)` and
-append it to `doctor.go`.
-
-```go
-var checklist = []check{
-	{
-		title: "Check if OpenSSH authorized_keys file id correct",
-		f:     runDoctorLocationMoved,
-    },
-    // more checks please append here
-}
-```
-
-This function will receive a command line context and return a list of details about the problems or error.
-
-#### doctor recreate-table
-
-Sometimes when there are migrations the old columns and default values may be left
-unchanged in the database schema. This may lead to warning such as:
-
-```
-2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync2() [W] Table user Column keep_activity_private db default is , struct default is 0
-```
-
-You can cause Gitea to recreate these tables and copy the old data into the new table
-with the defaults set appropriately by using:
-
-```
-gitea doctor recreate-table user
-```
-
-You can ask Gitea to recreate multiple tables using:
-
-```
-gitea doctor recreate-table table1 table2 ...
-```
-
-And if you would like Gitea to recreate all tables simply call:
-
-```
-gitea doctor recreate-table
-```
-
-It is highly recommended to back-up your database before running these commands.
-
-### manager
-
-Manage running server operations:
-
-- Commands:
-  - `shutdown`: Gracefully shutdown the running process
-  - `restart`: Gracefully restart the running process - (not implemented for windows servers)
-  - `flush-queues`: Flush queues in the running process
-    - Options:
-      - `--timeout value`: Timeout for the flushing process (default: 1m0s)
-      - `--non-blocking`: Set to true to not wait for flush to complete before returning
-  - `logging`: Adjust logging commands
-    - Commands:
-      - `pause`: Pause logging
-        - Notes:
-          - The logging level will be raised to INFO temporarily if it is below this level.
-          - Gitea will buffer logs up to a certain point and will drop them after that point.
-      - `resume`: Resume logging
-      - `release-and-reopen`: Cause Gitea to release and re-open files and connections used for logging (Equivalent to sending SIGUSR1 to Gitea.)
-      - `remove name`: Remove the named logger
-        - Options:
-          - `--group group`, `-g group`: Set the group to remove the sublogger from. (defaults to `default`)
-      - `add`: Add a logger
-        - Commands:
-          - `console`: Add a console logger
-            - Options:
-              - `--group value`, `-g value`: Group to add logger to - will default to "default"
-              - `--name value`, `-n value`: Name of the new logger - will default to mode
-              - `--level value`, `-l value`: Logging level for the new logger
-              - `--stacktrace-level value`, `-L value`: Stacktrace logging level
-              - `--flags value`, `-F value`: Flags for the logger
-              - `--expression value`, `-e value`: Matching expression for the logger
-              - `--prefix value`, `-p value`: Prefix for the logger
-              - `--color`: Use color in the logs
-              - `--stderr`: Output console logs to stderr - only relevant for console
-          - `file`: Add a file logger
-            - Options:
-              - `--group value`, `-g value`: Group to add logger to - will default to "default"
-              - `--name value`, `-n value`: Name of the new logger - will default to mode
-              - `--level value`, `-l value`: Logging level for the new logger
-              - `--stacktrace-level value`, `-L value`: Stacktrace logging level
-              - `--flags value`, `-F value`: Flags for the logger
-              - `--expression value`, `-e value`: Matching expression for the logger
-              - `--prefix value`, `-p value`: Prefix for the logger
-              - `--color`: Use color in the logs
-              - `--filename value`, `-f value`: Filename for the logger -
-              - `--rotate`, `-r`: Rotate logs
-              - `--max-size value`, `-s value`: Maximum size in bytes before rotation
-              - `--daily`, `-d`: Rotate logs daily
-              - `--max-days value`, `-D value`: Maximum number of daily logs to keep
-              - `--compress`, `-z`: Compress rotated logs
-              - `--compression-level value`, `-Z value`: Compression level to use
-          - `conn`: Add a network connection logger
-            - Options:
-              - `--group value`, `-g value`: Group to add logger to - will default to "default"
-              - `--name value`, `-n value`: Name of the new logger - will default to mode
-              - `--level value`, `-l value`: Logging level for the new logger
-              - `--stacktrace-level value`, `-L value`: Stacktrace logging level
-              - `--flags value`, `-F value`: Flags for the logger
-              - `--expression value`, `-e value`: Matching expression for the logger
-              - `--prefix value`, `-p value`: Prefix for the logger
-              - `--color`: Use color in the logs
-              - `--reconnect-on-message`, `-R`: Reconnect to host for every message
-              - `--reconnect`, `-r`: Reconnect to host when connection is dropped
-              - `--protocol value`, `-P value`: Set protocol to use: tcp, unix, or udp (defaults to tcp)
-              - `--address value`, `-a value`: Host address and port to connect to (defaults to :7020)
-          - `smtp`: Add an SMTP logger
-            - Options:
-              - `--group value`, `-g value`: Group to add logger to - will default to "default"
-              - `--name value`, `-n value`: Name of the new logger - will default to mode
-              - `--level value`, `-l value`: Logging level for the new logger
-              - `--stacktrace-level value`, `-L value`: Stacktrace logging level
-              - `--flags value`, `-F value`: Flags for the logger
-              - `--expression value`, `-e value`: Matching expression for the logger
-              - `--prefix value`, `-p value`: Prefix for the logger
-              - `--color`: Use color in the logs
-              - `--username value`, `-u value`: Mail server username
-              - `--password value`, `-P value`: Mail server password
-              - `--host value`, `-H value`: Mail server host (defaults to: 127.0.0.1:25)
-              - `--send-to value`, `-s value`: Email address(es) to send to
-              - `--subject value`, `-S value`: Subject header of sent emails
-  - `processes`: Display Gitea processes and goroutine information
-    - Options:
-      - `--flat`: Show processes as flat table rather than as tree
-      - `--no-system`: Do not show system processes
-      - `--stacktraces`: Show stacktraces for goroutines associated with processes
-      - `--json`: Output as json
-      - `--cancel PID`: Send cancel to process with PID. (Only for non-system processes.)
-
-### dump-repo
-
-Dump-repo dumps repository data from Git/GitHub/Gitea/GitLab:
-
-- Options:
-  - `--git_service service` : Git service, it could be `git`, `github`, `gitea`, `gitlab`, If clone_addr could be recognized, this could be ignored.
-  - `--repo_dir dir`, `-r dir`: Repository dir path to store the data
-  - `--clone_addr addr`: The URL will be clone, currently could be a git/github/gitea/gitlab http/https URL. i.e. https://github.com/lunny/tango.git
-  - `--auth_username lunny`: The username to visit the clone_addr
-  - `--auth_password <password>`: The password to visit the clone_addr
-  - `--auth_token <token>`: The personal token to visit the clone_addr
-  - `--owner_name lunny`: The data will be stored on a directory with owner name if not empty
-  - `--repo_name tango`: The data will be stored on a directory with repository name if not empty
-  - `--units <units>`: Which items will be migrated, one or more units should be separated as comma. wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments are allowed. Empty means all units.
-
-### restore-repo
-
-Restore-repo restore repository data from disk dir:
-
-- Options:
-  - `--repo_dir dir`, `-r dir`: Repository dir path to restore from
-  - `--owner_name lunny`: Restore destination owner name
-  - `--repo_name tango`: Restore destination repository name
-  - `--units <units>`: Which items will be restored, one or more units should be separated as comma. wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments are allowed. Empty means all units.
diff --git a/docs/content/doc/usage/email-setup.en-us.md b/docs/content/doc/usage/email-setup.en-us.md
deleted file mode 100644
index 6d6b18786c..0000000000
--- a/docs/content/doc/usage/email-setup.en-us.md
+++ /dev/null
@@ -1,90 +0,0 @@
----
-date: "2019-10-15T10:10:00+05:00"
-title: "Usage: Email setup"
-slug: "email-setup"
-weight: 12
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "Email setup"
-    weight: 12
-    identifier: "email-setup"
----
-
-# Email setup
-
-**Table of Contents**
-
-{{< toc >}}
-
-Gitea has mailer functionality for sending transactional emails (such as registration confirmation). It can be configured to either use Sendmail (or compatible MTAs like Postfix and msmtp) or directly use SMTP server.
-
-## Using Sendmail
-
-Use `sendmail` command as mailer.
-
-Note: For use in the official Gitea Docker image, please configure with the SMTP version (see the following section).
-
-Note: For Internet-facing sites consult documentation of your MTA for instructions to send emails over TLS. Also set up SPF, DMARC, and DKIM DNS records to make emails sent be accepted as legitimate by various email providers.
-
-```ini
-[mailer]
-ENABLED       = true
-FROM          = gitea@mydomain.com
-MAILER_TYPE   = sendmail
-SENDMAIL_PATH = /usr/sbin/sendmail
-SENDMAIL_ARGS = "--" ; most "sendmail" programs take options, "--" will prevent an email address being interpreted as an option.
-```
-
-## Using SMTP
-
-Directly use SMTP server as relay. This option is useful if you don't want to set up MTA on your instance but you have an account at email provider.
-
-```ini
-[mailer]
-ENABLED        = true
-FROM           = gitea@mydomain.com
-MAILER_TYPE    = smtp
-SMTP_ADDR      = mail.mydomain.com
-SMTP_PORT      = 587
-IS_TLS_ENABLED = true
-USER           = gitea@mydomain.com
-PASSWD         = `password`
-```
-
-Restart Gitea for the configuration changes to take effect.
-
-To send a test email to validate the settings, go to Gitea > Site Administration > Configuration > SMTP Mailer Configuration.
-
-For the full list of options check the [Config Cheat Sheet]({{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}})
-
-Please note: authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through:
-
-- STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
-- SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning.
-- Forced SMTPS connection with `IS_TLS_ENABLED=true`. (These are both known as Implicit TLS.)
-This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
-
-Note that Implicit TLS is recommended by [RFC8314](https://tools.ietf.org/html/rfc8314#section-3) since 2018.
-
-### Gmail
-
-The following configuration should work with GMail's SMTP server:
-
-```ini
-[mailer]
-ENABLED        = true
-HOST           = smtp.gmail.com:465 ; Remove this line for Gitea >= 1.18.0
-SMTP_ADDR      = smtp.gmail.com
-SMTP_PORT      = 465
-FROM           = example.user@gmail.com
-USER           = example.user
-PASSWD         = ***
-MAILER_TYPE    = smtp
-IS_TLS_ENABLED = true
-```
-
-Note that you'll need to create and use an [App password](https://support.google.com/accounts/answer/185833?hl=en) by enabling 2FA on your Google
-account. You won't be able to use your Google account password directly.
diff --git a/docs/content/doc/usage/fail2ban-setup.en-us.md b/docs/content/doc/usage/fail2ban-setup.en-us.md
deleted file mode 100644
index f00551e3ef..0000000000
--- a/docs/content/doc/usage/fail2ban-setup.en-us.md
+++ /dev/null
@@ -1,125 +0,0 @@
----
-date: "2018-05-11T11:00:00+02:00"
-title: "Usage: Setup fail2ban"
-slug: "fail2ban-setup"
-weight: 16
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "Fail2ban setup"
-    weight: 16
-    identifier: "fail2ban-setup"
----
-
-# Fail2ban setup to block users after failed login attempts
-
-**Remember that fail2ban is powerful and can cause lots of issues if you do it incorrectly, so make
-sure to test this before relying on it so you don't lock yourself out.**
-
-Gitea returns an HTTP 200 for bad logins in the web logs, but if you have logging options on in
-`app.ini`, then you should be able to go off of `log/gitea.log`, which gives you something like this
-on a bad authentication from the web or CLI using SSH or HTTP respectively:
-
-```log
-2018/04/26 18:15:54 [I] Failed authentication attempt for user from xxx.xxx.xxx.xxx
-```
-
-```log
-2020/10/15 16:05:09 modules/ssh/ssh.go:143:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
-```
-
-(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
-
-```log
-2020/10/15 16:05:09 modules/ssh/ssh.go:155:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
-```
-
-(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
-
-```log
-2020/10/15 16:05:09 modules/ssh/ssh.go:198:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
-```
-
-(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
-
-```log
-2020/10/15 16:05:09 modules/ssh/ssh.go:213:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
-```
-
-(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
-
-```log
-2020/10/15 16:05:09 modules/ssh/ssh.go:227:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
-```
-
-(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
-
-```log
-2020/10/15 16:05:09 modules/ssh/ssh.go:249:sshConnectionFailed() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
-```
-
-(From 1.15 this new message will available and doesn't have any of the false positive results that above messages from publicKeyHandler do. This will only be logged if the user has completely failed authentication.)
-
-```log
-2020/10/15 16:08:44 ...s/context/context.go:204:HandleText() [E] invalid credentials from xxx.xxx.xxx.xxx
-```
-
-Add our filter in `/etc/fail2ban/filter.d/gitea.conf`:
-
-```ini
-# gitea.conf
-[Definition]
-failregex =  .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
-ignoreregex =
-```
-
-Add our jail in `/etc/fail2ban/jail.d/gitea.conf`:
-
-```ini
-[gitea]
-enabled = true
-filter = gitea
-logpath = /var/lib/gitea/log/gitea.log
-maxretry = 10
-findtime = 3600
-bantime = 900
-action = iptables-allports
-```
-
-If you're using Docker, you'll also need to add an additional jail to handle the **FORWARD**
-chain in **iptables**. Configure it in `/etc/fail2ban/jail.d/gitea-docker.conf`:
-
-```ini
-[gitea-docker]
-enabled = true
-filter = gitea
-logpath = /var/lib/gitea/log/gitea.log
-maxretry = 10
-findtime = 3600
-bantime = 900
-action = iptables-allports[chain="FORWARD"]
-```
-
-Then simply run `service fail2ban restart` to apply your changes. You can check to see if
-fail2ban has accepted your configuration using `service fail2ban status`.
-
-Make sure and read up on fail2ban and configure it to your needs, this bans someone
-for **15 minutes** (from all ports) when they fail authentication 10 times in an hour.
-
-If you run Gitea behind a reverse proxy with Nginx (for example with Docker), you need to add
-this to your Nginx configuration so that IPs don't show up as 127.0.0.1:
-
-```
-proxy_set_header X-Real-IP $remote_addr;
-```
-
-The security options in `app.ini` need to be adjusted to allow the interpretation of the headers
-as well as the list of IP addresses and networks that describe trusted proxy servers
-(See the [configuration cheat sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#security-security) for more information).
-
-```
-REVERSE_PROXY_LIMIT = 1
-REVERSE_PROXY_TRUSTED_PROXIES = 127.0.0.1/8 ; 172.17.0.0/16 for the docker default network
-```
diff --git a/docs/content/doc/usage/fail2ban-setup.zh-cn.md b/docs/content/doc/usage/fail2ban-setup.zh-cn.md
deleted file mode 100644
index 446d192aa6..0000000000
--- a/docs/content/doc/usage/fail2ban-setup.zh-cn.md
+++ /dev/null
@@ -1,92 +0,0 @@
----
-date: "2022-08-01T00:00:00+00:00"
-title: "使用: 设置 Fail2ban"
-slug: "fail2ban-setup"
-weight: 16
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "设置 Fail2ban"
-    weight: 16
-    identifier: "fail2ban-setup"
----
-
-# 使用 Fail2ban 阻止攻击者的暴力登录
-
-**Fail2ban 检查客户端登录日志，将多次登录失败的客户端识别为攻击者并在一段时间内阻止其访问服务。如果你的实例是公开的，这一点尤其重要。请管理员仔细设置 fail2ban，错误的配置将导致防火墙阻止你访问自己的服务器。**
-
-Gitea 会在日志文件 `log/gitea.log` 中记录登录失败的 CLI、SSH 或 HTTP 客户端 IP 地址，而你需要将 Gitea 的日志输出模式从默认的 `console` 更改为 `file`。这表示将日志输出到文件，使得 fail2ban 可以定期扫描日志内容。
-
-当用户的身份验证失败时，日志中会记录此类信息：
-
-```log
-2018/04/26 18:15:54 [I] Failed authentication attempt for user from xxx.xxx.xxx.xxx
-```
-
-```log
-2020/10/15 16:08:44 [E] invalid credentials from xxx.xxx.xxx.xxx
-```
-
-## 设置 Fail2ban
-
-添加日志过滤器规则到配置文件 `/etc/fail2ban/filter.d/gitea.conf`:
-
-```ini
-[Definition]
-failregex =  .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
-ignoreregex =
-```
-
-添加监狱规则到配置文件 `/etc/fail2ban/jail.d/gitea.conf`:
-
-```ini
-[gitea]
-enabled = true
-filter = gitea
-logpath = /var/lib/gitea/log/gitea.log
-maxretry = 10
-findtime = 3600
-bantime = 900
-action = iptables-allports
-```
-
-如果你的 Gitea 实例运行在 Docker 容器中，并且直接将容器端口暴露到外部网络，
-你还需要添加 `chain="FORWARD"` 到监狱规则配置文件 `/etc/fail2ban/jail.d/gitea-docker.conf`
-以适应 Docker 的网络转发规则。但如果你在容器的宿主机上使用 Nginx 反向代理连接到 Gitea 则无需这样配置。
-
-```ini
-[gitea-docker]
-enabled = true
-filter = gitea
-logpath = /var/lib/gitea/log/gitea.log
-maxretry = 10
-findtime = 3600
-bantime = 900
-action = iptables-allports[chain="FORWARD"]
-```
-
-最后，运行 `systemctl restart fail2ban` 即可应用更改。现在，你可以使用 `systemctl status fail2ban` 检查 fail2ban 运行状态。
-
-上述规则规定客户端在 1 小时内，如果登录失败的次数达到 10 次，则通过 iptables 锁定该客户端 IP 地址 15 分钟。
-
-## 设置反向代理
-
-如果你使用 Nginx 反向代理到 Gitea 实例，你还需要设置 Nginx 的 HTTP 头部值 `X-Real-IP` 将真实的客户端 IP 地址传递给 Gitea。否则 Gitea 程序会将客户端地址错误解析为反向代理服务器的地址，例如回环地址 `127.0.0.1`。
-
-```
-proxy_set_header X-Real-IP $remote_addr;
-```
-
-额外注意，在 Gitea 的配置文件 `app.ini` 中存在下列默认值：
-
-```
-REVERSE_PROXY_LIMIT = 1
-REVERSE_PROXY_TRUSTED_PROXIES = 127.0.0.0/8,::1/128
-```
-
-`REVERSE_PROXY_LIMIT` 限制反向代理服务器的层数，设置为 `0` 表示不使用这些标头。
-`REVERSE_PROXY_TRUSTED_PROXIES` 表示受信任的反向代理服务器网络地址，
-经过该网络地址转发来的流量会经过解析 `X-Real-IP` 头部得到真实客户端地址。
-（参考 [configuration cheat sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#security-security)）
diff --git a/docs/content/doc/usage/git-lfs-support.en-us.md b/docs/content/doc/usage/git-lfs-support.en-us.md
deleted file mode 100644
index 8b2c997bf9..0000000000
--- a/docs/content/doc/usage/git-lfs-support.en-us.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-date: "2019-10-06T08:00:00+05:00"
-title: "Usage: Git LFS setup"
-slug: "git-lfs-setup"
-weight: 12
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "Git LFS setup"
-    weight: 12
-    identifier: "git-lfs-setup"
----
-
-# Git Large File Storage setup
-
-To use Gitea's built-in LFS support, you must update the `app.ini` file:
-
-```ini
-[server]
-; Enables git-lfs support. true or false, default is false.
-LFS_START_SERVER = true
-
-[lfs]
-; Where your lfs files reside, default is data/lfs.
-PATH = /home/gitea/data/lfs
-```
-
-**Note**: LFS server support needs at least Git v2.1.2 installed on the server
diff --git a/docs/content/doc/usage/https-support.en-us.md b/docs/content/doc/usage/https-support.en-us.md
deleted file mode 100644
index 7c9024743d..0000000000
--- a/docs/content/doc/usage/https-support.en-us.md
+++ /dev/null
@@ -1,102 +0,0 @@
----
-date: "2018-06-02T11:00:00+02:00"
-title: "Usage: HTTPS setup"
-slug: "https-setup"
-weight: 12
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "HTTPS setup"
-    weight: 12
-    identifier: "https-setup"
----
-
-# HTTPS setup to encrypt connections to Gitea
-
-**Table of Contents**
-
-{{< toc >}}
-
-## Using the built-in server
-
-Before you enable HTTPS, make sure that you have valid SSL/TLS certificates.
-You could use self-generated certificates for evaluation and testing. Please run `gitea cert --host [HOST]` to generate a self signed certificate.
-
-If you are using Apache or nginx on the server, it's recommended to check the [reverse proxy guide]({{< relref "doc/usage/reverse-proxies.en-us.md" >}}).
-
-To use Gitea's built-in HTTPS support, you must change your `app.ini` file:
-
-```ini
-[server]
-PROTOCOL  = https
-ROOT_URL  = https://git.example.com:3000/
-HTTP_PORT = 3000
-CERT_FILE = cert.pem
-KEY_FILE  = key.pem
-```
-
-Note that if your certificate is signed by a third party certificate authority (i.e. not self-signed), then cert.pem should contain the certificate chain. The server certificate must be the first entry in cert.pem, followed by the intermediaries in order (if any). The root certificate does not have to be included because the connecting client must already have it in order to estalbish the trust relationship.
-To learn more about the config values, please checkout the [Config Cheat Sheet](../config-cheat-sheet#server-server).
-
-For the `CERT_FILE` or `KEY_FILE` field, the file path is relative to the `GITEA_CUSTOM` environment variable when it is a relative path. It can be an absolute path as well.
-
-### Setting up HTTP redirection
-
-The Gitea server is only able to listen to one port; to redirect HTTP requests to the HTTPS port, you will need to enable the HTTP redirection service:
-
-```ini
-[server]
-REDIRECT_OTHER_PORT = true
-; Port the redirection service should listen on
-PORT_TO_REDIRECT = 3080
-```
-
-If you are using Docker, make sure that this port is configured in your `docker-compose.yml` file.
-
-## Using ACME (Default: Let's Encrypt)
-
-[ACME](https://tools.ietf.org/html/rfc8555) is a Certificate Authority standard protocol that allows you to automatically request and renew SSL/TLS certificates. [Let's Encrypt](https://letsencrypt.org/) is a free publicly trusted Certificate Authority server using this standard. Only `HTTP-01` and `TLS-ALPN-01` challenges are implemented. In order for ACME challenges to pass and verify your domain ownership, external traffic to the gitea domain on port `80` (`HTTP-01`) or port `443` (`TLS-ALPN-01`) has to be served by the gitea instance. Setting up [HTTP redirection](#setting-up-http-redirection) and port-forwards might be needed for external traffic to route correctly. Normal traffic to port `80` will otherwise be automatically redirected to HTTPS. **You must consent** to the ACME provider's terms of service (default Let's Encrypt's [terms of service](https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf)).
-
-Minimum setup using the default Let's Encrypt:
-
-```ini
-[server]
-PROTOCOL=https
-DOMAIN=git.example.com
-ENABLE_ACME=true
-ACME_ACCEPTTOS=true
-ACME_DIRECTORY=https
-;; Email can be omitted here and provided manually at first run, after which it is cached
-ACME_EMAIL=email@example.com
-```
-
-Minimum setup using a [smallstep CA](https://github.com/smallstep/certificates), refer to [their tutorial](https://smallstep.com/docs/tutorials/acme-challenge) for more information.
-
-```ini
-[server]
-PROTOCOL=https
-DOMAIN=git.example.com
-ENABLE_ACME=true
-ACME_ACCEPTTOS=true
-ACME_URL=https://ca.example.com/acme/acme/directory
-;; Can be omitted if using the system's trust is preferred
-;ACME_CA_ROOT=/path/to/root_ca.crt
-ACME_DIRECTORY=https
-ACME_EMAIL=email@example.com
-```
-
-To learn more about the config values, please checkout the [Config Cheat Sheet](../config-cheat-sheet#server-server).
-
-## Using a reverse proxy
-
-Setup up your reverse proxy as shown in the [reverse proxy guide](../reverse-proxies).
-
-After that, enable HTTPS by following one of these guides:
-
-- [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html)
-- [apache2/httpd](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html)
-- [caddy](https://caddyserver.com/docs/tls)
-
-Note: Enabling HTTPS only at the proxy level is referred as [TLS Termination Proxy](https://en.wikipedia.org/wiki/TLS_termination_proxy). The proxy server accepts incoming TLS connections, decrypts the contents, and passes the now unencrypted contents to Gitea. This is normally fine as long as both the proxy and Gitea instances are either on the same machine, or on different machines within private network (with the proxy is exposed to outside network). If your Gitea instance is separated from your proxy over a public network, or if you want full end-to-end encryption, you can also [enable HTTPS support directly in Gitea using built-in server](#using-the-built-in-server) and forward the connections over HTTPS instead.
diff --git a/docs/content/doc/usage/linked-references.en-us.md b/docs/content/doc/usage/linked-references.en-us.md
index df28137928..721c2cf13e 100644
--- a/docs/content/doc/usage/linked-references.en-us.md
+++ b/docs/content/doc/usage/linked-references.en-us.md
@@ -96,7 +96,7 @@ Sometimes a commit or pull request may fix or bring back a problem documented
 in a particular issue. Gitea supports closing and reopening the referenced
 issues by preceding the reference with a particular _keyword_. Common keywords
 include "closes", "fixes", "reopens", etc. This list can be
-[customized]({{< ref "/doc/advanced/config-cheat-sheet.en-us.md" >}}) by the
+[customized]({{< ref "doc/administration/config-cheat-sheet.en-us.md" >}}) by the
 site administrator.
 
 Example:
diff --git a/docs/content/doc/usage/protected-tags.en-us.md b/docs/content/doc/usage/protected-tags.en-us.md
new file mode 100644
index 0000000000..f7404d32cb
--- /dev/null
+++ b/docs/content/doc/usage/protected-tags.en-us.md
@@ -0,0 +1,57 @@
+---
+date: "2021-05-14T00:00:00-00:00"
+title: "Protected tags"
+slug: "protected-tags"
+weight: 45
+toc: false
+draft: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "Protected tags"
+    weight: 45
+    identifier: "protected-tags"
+---
+
+# Protected tags
+
+Protected tags allow control over who has permission to create or update Git tags. Each rule allows you to match either an individual tag name, or use an appropriate pattern to control multiple tags at once.
+
+**Table of Contents**
+
+{{< toc >}}
+
+## Setting up protected tags
+
+To protect a tag, you need to follow these steps:
+
+1. Go to the repository’s **Settings** > **Tags** page.
+1. Type a pattern to match a name. You can use a single name, a [glob pattern](https://pkg.go.dev/github.com/gobwas/glob#Compile) or a regular expression.
+1. Choose the allowed users and/or teams. If you leave these fields empty no one is allowed to create or modify this tag.
+1. Select **Save** to save the configuration.
+
+## Pattern protected tags
+
+The pattern uses [glob](https://pkg.go.dev/github.com/gobwas/glob#Compile) or regular expressions to match a tag name. For regular expressions you need to enclose the pattern in slashes.
+
+Examples:
+
+| Type  | Pattern Protected Tag    | Possible Matching Tags                  |
+| ----- | ------------------------ | --------------------------------------- |
+| Glob  | `v*`                     | `v`, `v-1`, `version2`                  |
+| Glob  | `v[0-9]`                 | `v0`, `v1` up to `v9`                   |
+| Glob  | `*-release`              | `2.1-release`, `final-release`          |
+| Glob  | `gitea`                  | only `gitea`                            |
+| Glob  | `*gitea*`                | `gitea`, `2.1-gitea`, `1_gitea-release` |
+| Glob  | `{v,rel}-*`              | `v-`, `v-1`, `v-final`, `rel-`, `rel-x` |
+| Glob  | `*`                      | matches all possible tag names          |
+| Regex | `/\Av/`                  | `v`, `v-1`, `version2`                  |
+| Regex | `/\Av[0-9]\z/`           | `v0`, `v1` up to `v9`                   |
+| Regex | `/\Av\d+\.\d+\.\d+\z/`   | `v1.0.17`, `v2.1.0`                     |
+| Regex | `/\Av\d+(\.\d+){0,2}\z/` | `v1`, `v2.1`, `v1.2.34`                 |
+| Regex | `/-release\z/`           | `2.1-release`, `final-release`          |
+| Regex | `/gitea/`                | `gitea`, `2.1-gitea`, `1_gitea-release` |
+| Regex | `/\Agitea\z/`            | only `gitea`                            |
+| Regex | `/^gitea$/`              | only `gitea`                            |
+| Regex | `/\A(v\|rel)-/`          | `v-`, `v-1`, `v-final`, `rel-`, `rel-x` |
+| Regex | `/.+/`                   | matches all possible tag names          |
diff --git a/docs/content/doc/usage/push-to-create.en-us.md b/docs/content/doc/usage/push-to-create.en-us.md
index 7ed3f56368..27b26b16a9 100644
--- a/docs/content/doc/usage/push-to-create.en-us.md
+++ b/docs/content/doc/usage/push-to-create.en-us.md
@@ -19,7 +19,7 @@ Push to create is a feature that allows you to push to a repository that does no
 
 ## Enabling Push To Create
 
-In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet]({{< relref "doc/advanced/config-cheat-sheet.en-us.md#repository-repository" >}}).
+In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet]({{< relref "doc/administration/config-cheat-sheet.en-us.md#repository-repository" >}}).
 
 ## Using Push To Create
 
diff --git a/docs/content/doc/usage/repo-mirror.en-us.md b/docs/content/doc/usage/repo-mirror.en-us.md
new file mode 100644
index 0000000000..9a52282bb3
--- /dev/null
+++ b/docs/content/doc/usage/repo-mirror.en-us.md
@@ -0,0 +1,92 @@
+---
+date: "2021-05-13T00:00:00-00:00"
+title: "Repository Mirror"
+slug: "repo-mirror"
+weight: 45
+toc: false
+draft: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "Repository Mirror"
+    weight: 45
+    identifier: "repo-mirror"
+---
+
+# Repository Mirror
+
+Repository mirroring allows for the mirroring of repositories to and from external sources. You can use it to mirror branches, tags, and commits between repositories.
+
+**Table of Contents**
+
+{{< toc >}}
+
+## Use cases
+
+The following are some possible use cases for repository mirroring:
+
+- You migrated to Gitea but still need to keep your project in another source. In that case, you can simply set it up to mirror to Gitea (pull) and all the essential history of commits, tags, and branches are available in your Gitea instance.
+- You have old projects in another source that you don’t use actively anymore, but don’t want to remove for archiving purposes. In that case, you can create a push mirror so that your active Gitea repository can push its changes to the old location.
+
+## Pulling from a remote repository
+
+For an existing remote repository, you can set up pull mirroring as follows:
+
+1. Select **New Migration** in the **Create...** menu on the top right.
+2. Select the remote repository service.
+3. Enter a repository URL.
+4. If the repository needs authentication fill in your authentication information.
+5. Check the box **This repository will be a mirror**.
+6. Select **Migrate repository** to save the configuration.
+
+The repository now gets mirrored periodically from the remote repository. You can force a sync by selecting **Synchronize Now** in the repository settings.
+
+:exclamation::exclamation: **NOTE:** You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation:
+
+## Pushing to a remote repository
+
+For an existing repository, you can set up push mirroring as follows:
+
+1. In your repository, go to **Settings** > **Repository**, and then the **Mirror Settings** section.
+2. Enter a repository URL.
+3. If the repository needs authentication expand the **Authorization** section and fill in your authentication information. Note that the requested **password** can also be your access token.
+4. Select **Add Push Mirror** to save the configuration.
+
+The repository now gets mirrored periodically to the remote repository. You can force a sync by selecting **Synchronize Now**. In case of an error a message displayed to help you resolve it.
+
+:exclamation::exclamation: **NOTE:** This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation:
+
+### Setting up a push mirror from Gitea to GitHub
+
+To set up a mirror from Gitea to GitHub, you need to follow these steps:
+
+1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the *public_repo* box checked.
+2. Create a repository with that name on GitHub. Unlike Gitea, GitHub does not support creating repositories by pushing to the remote. You can also use an existing remote repo if it has the same commit history as your Gitea repo.
+3. In the settings of your Gitea repo, fill in the **Git Remote Repository URL**: `https://github.com/<your_github_group>/<your_github_project>.git`.
+4. Fill in the **Authorization** fields with your GitHub username and the personal access token as **Password**.
+5. (Optional, available on Gitea 1.18+) Select `Sync when new commits are pushed` so that the mirror will be updated as well as soon as there are changes. You can also disable the periodic sync if you like.
+6. Select **Add Push Mirror** to save the configuration.
+
+The repository pushes shortly thereafter. To force a push, select the **Synchronize Now** button.
+
+### Setting up a push mirror from Gitea to GitLab
+
+To set up a mirror from Gitea to GitLab, you need to follow these steps:
+
+1. Create a [GitLab personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) with *write_repository* scope.
+2. Fill in the **Git Remote Repository URL**: `https://<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`.
+3. Fill in the **Authorization** fields with `oauth2` as **Username** and your GitLab personal access token as **Password**.
+4. Select **Add Push Mirror** to save the configuration.
+
+The repository pushes shortly thereafter. To force a push, select the **Synchronize Now** button.
+
+### Setting up a push mirror from Gitea to Bitbucket
+
+To set up a mirror from Gitea to Bitbucket, you need to follow these steps:
+
+1. Create a [Bitbucket app password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) with the *Repository Write* box checked.
+2. Fill in the **Git Remote Repository URL**: `https://bitbucket.org/<your_bitbucket_group_or_name>/<your_bitbucket_project>.git`.
+3. Fill in the **Authorization** fields with your Bitbucket username and the app password as **Password**.
+4. Select **Add Push Mirror** to save the configuration.
+
+The repository pushes shortly thereafter. To force a push, select the **Synchronize Now** button.
diff --git a/docs/content/doc/usage/reverse-proxies.en-us.md b/docs/content/doc/usage/reverse-proxies.en-us.md
deleted file mode 100644
index b8cebee574..0000000000
--- a/docs/content/doc/usage/reverse-proxies.en-us.md
+++ /dev/null
@@ -1,387 +0,0 @@
----
-date: "2018-05-22T11:00:00+00:00"
-title: "Usage: Reverse Proxies"
-slug: "reverse-proxies"
-weight: 17
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "Reverse Proxies"
-    weight: 16
-    identifier: "reverse-proxies"
----
-
-# Reverse Proxies
-
-**Table of Contents**
-
-{{< toc >}}
-
-## Nginx
-
-If you want Nginx to serve your Gitea instance, add the following `server` section to the `http` section of `nginx.conf`:
-
-```apacheconf
-server {
-    listen 80;
-    server_name git.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-```
-
-## Nginx with a sub-path
-
-In case you already have a site, and you want Gitea to share the domain name, you can setup Nginx to serve Gitea under a sub-path by adding the following `server` section inside the `http` section of `nginx.conf`:
-
-```apacheconf
-server {
-    listen 80;
-    server_name git.example.com;
-
-    # Note: Trailing slash
-    location /git/ { 
-        # Note: Trailing slash
-        proxy_pass http://localhost:3000/;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-```
-
-Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/git/` correctly in your configuration.
-
-## Nginx and serve static resources directly
-
-We can tune the performance in splitting requests into categories static and dynamic.
-
-CSS files, JavaScript files, images and web fonts are static content.
-The front page, a repository view or issue list is dynamic content.
-
-Nginx can serve static resources directly and proxy only the dynamic requests to Gitea.
-Nginx is optimized for serving static content, while the proxying of large responses might be the opposite of that
-(see [https://serverfault.com/q/587386](https://serverfault.com/q/587386)).
-
-Download a snapshot of the Gitea source repository to `/path/to/gitea/`.
-After this, run `make frontend` in the repository directory to generate the static resources. We are only interested in the `public/` directory for this task, so you can delete the rest.
-(You will need to have [Node with npm](https://nodejs.org/en/download/) and `make` installed to generate the static resources)
-
-Depending on the scale of your user base, you might want to split the traffic to two distinct servers,
-or use a cdn for the static files.
-
-### Single node and single domain
-
-Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
-
-```apacheconf
-server {
-    listen 80;
-    server_name git.example.com;
-
-    location /_/static/assets/ {
-        alias /path/to/gitea/public/;
-    }
-
-    location / {
-        proxy_pass http://localhost:3000;
-    }
-}
-```
-
-### Two nodes and two domains
-
-Set `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` in your configuration.
-
-```apacheconf
-# application server running Gitea
-server {
-    listen 80;
-    server_name git.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-    }
-}
-```
-
-```apacheconf
-# static content delivery server
-server {
-    listen 80;
-    server_name cdn.example.com;
-
-    location /gitea/ {
-        alias /path/to/gitea/public/;
-    }
-
-    location / {
-        return 404;
-    }
-}
-```
-
-## Resolving Error: 413 Request Entity Too Large
-
-This error indicates nginx is configured to restrict the file upload size.
-
-In your nginx config file containing your Gitea proxy directive, find the `location { ... }` block for Gitea and add the line
-`client_max_body_size 16M;` to set this limit to 16 megabytes or any other number of choice.
-If you use Git LFS, this will also limit the size of the largest file you will be able to push.
-
-## Apache HTTPD
-
-If you want Apache HTTPD to serve your Gitea instance, you can add the following to your Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
-
-```apacheconf
-<VirtualHost *:80>
-    ...
-    ProxyPreserveHost On
-    ProxyRequests off
-    AllowEncodedSlashes NoDecode
-    ProxyPass / http://localhost:3000/ nocanon
-</VirtualHost>
-```
-
-Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
-
-If you wish to use Let's Encrypt with webroot validation, add the line `ProxyPass /.well-known !` before `ProxyPass` to disable proxying these requests to Gitea.
-
-## Apache HTTPD with a sub-path
-
-In case you already have a site, and you want Gitea to share the domain name, you can setup Apache HTTPD to serve Gitea under a sub-path by adding the following to you Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
-
-```apacheconf
-<VirtualHost *:80>
-    ...
-    <Proxy *>
-         Order allow,deny
-         Allow from all
-    </Proxy>
-    AllowEncodedSlashes NoDecode
-    # Note: no trailing slash after either /git or port
-    ProxyPass /git http://localhost:3000 nocanon
-</VirtualHost>
-```
-
-Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/git/` correctly in your configuration.
-
-Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
-
-## Caddy
-
-If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:
-
-```apacheconf
-git.example.com {
-    reverse_proxy localhost:3000
-}
-```
-
-If you still use Caddy v1, use:
-
-```apacheconf
-git.example.com {
-    proxy / localhost:3000
-}
-```
-
-## Caddy with a sub-path
-
-In case you already have a site, and you want Gitea to share the domain name, you can setup Caddy to serve Gitea under a sub-path by adding the following to your server block in your Caddyfile:
-
-```apacheconf
-git.example.com {
-    route /git/* {
-        uri strip_prefix /git
-        reverse_proxy localhost:3000
-    }
-}
-```
-
-Or, for Caddy v1:
-
-```apacheconf
-git.example.com {
-    proxy /git/ localhost:3000
-}
-```
-
-Then set `[server] ROOT_URL = http://git.example.com/git/` in your configuration.
-
-## IIS
-
-If you wish to run Gitea with IIS. You will need to setup IIS with URL Rewrite as reverse proxy.
-
-1. Setup an empty website in IIS, named let's say, `Gitea Proxy`.
-2. Follow the first two steps in [Microsoft's Technical Community Guide to Setup IIS with URL Rewrite](https://techcommunity.microsoft.com/t5/iis-support-blog/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world/ba-p/846222#M343). That is:
-
-- Install Application Request Routing (ARR for short) either by using the Microsoft Web Platform Installer 5.1 (WebPI) or downloading the extension from [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing)
-- Once the module is installed in IIS, you will see a new Icon in the IIS Administration Console called URL Rewrite.
-- Open the IIS Manager Console and click on the `Gitea Proxy` Website from the tree view on the left. Select and double click the URL Rewrite Icon from the middle pane to load the URL Rewrite interface.
-- Choose the `Add Rule` action from the right pane of the management console and select the `Reverse Proxy Rule` from the `Inbound and Outbound Rules` category.
-- In the Inbound Rules section, set the server name to be the host that Gitea is running on with its port. e.g. if you are running Gitea on the localhost with port 3000, the following should work: `127.0.0.1:3000`
-- Enable SSL Offloading
-- In the Outbound Rules, ensure `Rewrite the domain names of the links in HTTP response` is set and set the `From:` field as above and the `To:` to your external hostname, say: `git.example.com`
-- Now edit the `web.config` for your website to match the following: (changing `127.0.0.1:3000` and `git.example.com` as appropriate)
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<configuration>
-    <system.web>
-        <httpRuntime requestPathInvalidCharacters="" />
-    </system.web>
-    <system.webServer>
-        <security>
-          <requestFiltering>
-            <hiddenSegments>
-              <clear />
-            </hiddenSegments>
-            <denyUrlSequences>
-              <clear />
-            </denyUrlSequences>
-            <fileExtensions allowUnlisted="true">
-              <clear />
-            </fileExtensions>
-          </requestFiltering>
-        </security>
-        <rewrite>
-            <rules useOriginalURLEncoding="false">
-                <rule name="ReverseProxyInboundRule1" stopProcessing="true">
-                    <match url="(.*)" />
-                    <action type="Rewrite" url="http://127.0.0.1:3000{UNENCODED_URL}" />
-                    <serverVariables>
-                        <set name="HTTP_X_ORIGINAL_ACCEPT_ENCODING" value="HTTP_ACCEPT_ENCODING" />
-                        <set name="HTTP_ACCEPT_ENCODING" value="" />
-                    </serverVariables>
-                </rule>
-            </rules>
-            <outboundRules>
-                <rule name="ReverseProxyOutboundRule1" preCondition="ResponseIsHtml1">
-                    <!-- set the pattern correctly here - if you only want to accept http or https -->
-                    <!-- change the pattern and the action value as appropriate -->
-                    <match filterByTags="A, Form, Img" pattern="^http(s)?://127.0.0.1:3000/(.*)" />
-                    <action type="Rewrite" value="http{R:1}://git.example.com/{R:2}" />
-                </rule>
-                <rule name="RestoreAcceptEncoding" preCondition="NeedsRestoringAcceptEncoding">
-                    <match serverVariable="HTTP_ACCEPT_ENCODING" pattern="^(.*)" />
-                    <action type="Rewrite" value="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" />
-                </rule>
-                <preConditions>
-                    <preCondition name="ResponseIsHtml1">
-                        <add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
-                    </preCondition>
-                    <preCondition name="NeedsRestoringAcceptEncoding">
-                        <add input="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" pattern=".+" />
-                    </preCondition>
-                </preConditions>
-            </outboundRules>
-        </rewrite>
-        <urlCompression doDynamicCompression="true" />
-        <handlers>
-          <clear />
-          <add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
-        </handlers>
-        <!-- Map all extensions to the same MIME type, so all files can be
-               downloaded. -->
-        <staticContent>
-          <clear />
-          <mimeMap fileExtension="*" mimeType="application/octet-stream" />
-        </staticContent>
-    </system.webServer>
-</configuration>
-```
-
-## HAProxy
-
-If you want HAProxy to serve your Gitea instance, you can add the following to your HAProxy configuration
-
-add an acl in the frontend section to redirect calls to gitea.example.com to the correct backend
-
-```
-frontend http-in
-    ...
-    acl acl_gitea hdr(host) -i gitea.example.com
-    use_backend gitea if acl_gitea
-    ...
-```
-
-add the previously defined backend section
-
-```
-backend gitea
-    server localhost:3000 check
-```
-
-If you redirect the http content to https, the configuration work the same way, just remember that the connection between HAProxy and Gitea will be done via http so you do not have to enable https in Gitea's configuration.
-
-## HAProxy with a sub-path
-
-In case you already have a site, and you want Gitea to share the domain name, you can setup HAProxy to serve Gitea under a sub-path by adding the following to you HAProxy configuration:
-
-```
-frontend http-in
-    ...
-    acl acl_gitea path_beg /gitea
-    use_backend gitea if acl_gitea
-    ...
-```
-
-With that configuration http://example.com/gitea/ will redirect to your Gitea instance.
-
-then for the backend section
-
-```
-backend gitea
-    http-request replace-path /gitea\/?(.*) \/\1
-    server localhost:3000 check
-```
-
-The added http-request will automatically add a trailing slash if needed and internally remove /gitea from the path to allow it to work correctly with Gitea by setting properly http://example.com/gitea as the root.
-
-Then you **MUST** set something like `[server] ROOT_URL = http://example.com/gitea/` correctly in your configuration.
-
-## Traefik
-
-If you want traefik to serve your Gitea instance, you can add the following label section to your `docker-compose.yaml` (Assuming the provider is docker).
-
-```yaml
-gitea:
-  image: gitea/gitea
-  ...
-  labels:
-    - "traefik.enable=true"
-    - "traefik.http.routers.gitea.rule=Host(`example.com`)"
-    - "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
-```
-
-This config assumes that you are handling HTTPS on the traefik side and using HTTP between Gitea and traefik.
-
-## Traefik with a sub-path
-
-In case you already have a site, and you want Gitea to share the domain name, you can setup Traefik to serve Gitea under a sub-path by adding the following to your `docker-compose.yaml` (Assuming the provider is docker) :
-
-```yaml
-gitea:
-  image: gitea/gitea
-  ...
-  labels:
-    - "traefik.enable=true"
-    - "traefik.http.routers.gitea.rule=Host(`example.com`) && PathPrefix(`/gitea`)"
-    - "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
-    - "traefik.http.middlewares.gitea-stripprefix.stripprefix.prefixes=/gitea"
-    - "traefik.http.routers.gitea.middlewares=gitea-stripprefix"
-```
-
-This config assumes that you are handling HTTPS on the traefik side and using HTTP between Gitea and traefik.
-
-Then you **MUST** set something like `[server] ROOT_URL = http://example.com/gitea/` correctly in your configuration.
diff --git a/docs/content/doc/usage/reverse-proxies.zh-cn.md b/docs/content/doc/usage/reverse-proxies.zh-cn.md
deleted file mode 100644
index f6d92e2a61..0000000000
--- a/docs/content/doc/usage/reverse-proxies.zh-cn.md
+++ /dev/null
@@ -1,138 +0,0 @@
----
-date: "2018-05-22T11:00:00+00:00"
-title: "使用：反向代理"
-slug: "reverse-proxies"
-weight: 17
-toc: false
-draft: false
-menu:
-  sidebar:
-    parent: "usage"
-    name: "反向代理"
-    weight: 16
-    identifier: "reverse-proxies"
----
-
-# 反向代理
-
-**目录**
-
-{{< toc >}}
-
-## 使用 Nginx 作为反向代理服务
-
-如果您想使用 Nginx 作为 Gitea 的反向代理服务，您可以参照以下 `nginx.conf` 配置中 `server` 的 `http` 部分：
-
-```
-server {
-    listen 80;
-    server_name git.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-```
-
-## 使用 Nginx 作为反向代理服务并将 Gitea 路由至一个子路径
-
-如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下 `nginx.conf` 配置中 `server` 的 `http` 部分，为 Gitea 添加路由规则：
-
-```
-server {
-    listen 80;
-    server_name git.example.com;
-
-    # 注意: /git/ 最后需要有一个路径符号
-    location /git/ { 
-        # 注意: 反向代理后端 URL 的最后需要有一个路径符号
-        proxy_pass http://localhost:3000/;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-```
-
-然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
-
-## 使用 Apache HTTPD 作为反向代理服务
-
-如果您想使用 Apache HTTPD 作为 Gitea 的反向代理服务，您可以为您的 Apache HTTPD 作如下配置（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
-
-```
-<VirtualHost *:80>
-    ...
-    ProxyPreserveHost On
-    ProxyRequests off
-    AllowEncodedSlashes NoDecode
-    ProxyPass / http://localhost:3000/ nocanon
-</VirtualHost>
-```
-
-注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
-
-## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径
-
-如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下配置为 Gitea 添加路由规则（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
-
-```
-<VirtualHost *:80>
-    ...
-    <Proxy *>
-         Order allow,deny
-         Allow from all
-    </Proxy>
-    AllowEncodedSlashes NoDecode
-    # 注意: 路径和 URL 后面都不要写路径符号 '/'
-    ProxyPass /git http://localhost:3000 nocanon
-</VirtualHost>
-```
-
-然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
-
-注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
-
-## 使用 Caddy 作为反向代理服务
-
-如果您想使用 Caddy 作为 Gitea 的反向代理服务，您可以在 `Caddyfile` 中添加如下配置：
-
-```
-git.example.com {
-    proxy / http://localhost:3000
-}
-```
-
-## 使用 Caddy 作为反向代理服务并将 Gitea 路由至一个子路径
-
-如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 `Caddyfile` 文件中增加以下配置，为 Gitea 添加路由规则：
-
-```
-git.example.com {
-    # 注意: 路径 /git/ 最后需要有路径符号
-    proxy /git/ http://localhost:3000
-}
-```
-
-然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
-
-## 使用 Traefik 作为反向代理服务
-
-如果您想使用 traefik 作为 Gitea 的反向代理服务，您可以在 `docker-compose.yaml` 中添加 label 部分（假设使用 docker 作为 traefik 的 provider）：
-
-```yaml
-gitea:
-  image: gitea/gitea
-  ...
-  labels:
-    - "traefik.enable=true"
-    - "traefik.http.routers.gitea.rule=Host(`example.com`)"
-    - "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
-```
-
-这份配置假设您使用 traefik 来处理 HTTPS 服务，并在其和 Gitea 之间使用 HTTP 进行通信。
diff --git a/docs/content/doc/usage/secrets.en-us.md b/docs/content/doc/usage/secrets.en-us.md
new file mode 100644
index 0000000000..341ccbae12
--- /dev/null
+++ b/docs/content/doc/usage/secrets.en-us.md
@@ -0,0 +1,36 @@
+---
+date: "2022-12-19T21:26:00+08:00"
+title: "Secrets"
+slug: "usage/secrets"
+draft: false
+toc: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "Secrets"
+    weight: 1
+    identifier: "usage-secrets"
+---
+
+# Secrets
+
+Secrets allow you to store sensitive information in your user, organization or repository.
+Secrets are available on Gitea 1.19+.
+
+# Naming your secrets
+
+The following rules apply to secret names:
+
+- Secret names can only contain alphanumeric characters (`[a-z]`, `[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed.
+
+- Secret names must not start with the `GITHUB_` and `GITEA_` prefix.
+
+- Secret names must not start with a number.
+
+- Secret names are not case-sensitive.
+
+- Secret names must be unique at the level they are created at.
+
+For example, a secret created at the repository level must have a unique name in that repository, and a secret created at the organization level must have a unique name at that level.
+
+If a secret with the same name exists at multiple levels, the secret at the lowest level takes precedence. For example, if an organization-level secret has the same name as a repository-level secret, then the repository-level secret takes precedence.
diff --git a/docs/content/doc/usage/webhooks.en-us.md b/docs/content/doc/usage/webhooks.en-us.md
new file mode 100644
index 0000000000..2cf60cc9cd
--- /dev/null
+++ b/docs/content/doc/usage/webhooks.en-us.md
@@ -0,0 +1,194 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Webhooks"
+slug: "webhooks"
+weight: 10
+toc: false
+draft: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "Webhooks"
+    weight: 30
+    identifier: "webhooks"
+---
+
+# Webhooks
+
+Gitea supports webhooks for repository events. This can be configured in the settings
+page `/:username/:reponame/settings/hooks` by a repository admin. Webhooks can also be configured on a per-organization and whole system basis.
+All event pushes are POST requests. The methods currently supported are:
+
+- Gitea (can also be a GET request)
+- Gogs
+- Slack
+- Discord
+- Dingtalk
+- Telegram
+- Microsoft Teams
+- Feishu
+- Wechatwork
+- Packagist
+
+### Event information
+
+**WARNING**: The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755
+
+The following is an example of event information that will be sent by Gitea to
+a Payload URL:
+
+```
+X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-GitHub-Event: push
+X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gogs-Event: push
+X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gitea-Event: push
+```
+
+```json
+{
+  "secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
+  "ref": "refs/heads/develop",
+  "before": "28e1879d029cb852e4844d9c718537df08844e03",
+  "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
+  "compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
+  "commits": [
+    {
+      "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
+      "message": "Webhooks Yay!",
+      "url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
+      "author": {
+        "name": "Gitea",
+        "email": "someone@gitea.io",
+        "username": "gitea"
+      },
+      "committer": {
+        "name": "Gitea",
+        "email": "someone@gitea.io",
+        "username": "gitea"
+      },
+      "timestamp": "2017-03-13T13:52:11-04:00"
+    }
+  ],
+  "repository": {
+    "id": 140,
+    "owner": {
+      "id": 1,
+      "login": "gitea",
+      "full_name": "Gitea",
+      "email": "someone@gitea.io",
+      "avatar_url": "https://localhost:3000/avatars/1",
+      "username": "gitea"
+    },
+    "name": "webhooks",
+    "full_name": "gitea/webhooks",
+    "description": "",
+    "private": false,
+    "fork": false,
+    "html_url": "http://localhost:3000/gitea/webhooks",
+    "ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
+    "clone_url": "http://localhost:3000/gitea/webhooks.git",
+    "website": "",
+    "stars_count": 0,
+    "forks_count": 1,
+    "watchers_count": 1,
+    "open_issues_count": 7,
+    "default_branch": "master",
+    "created_at": "2017-02-26T04:29:06-05:00",
+    "updated_at": "2017-03-13T13:51:58-04:00"
+  },
+  "pusher": {
+    "id": 1,
+    "login": "gitea",
+    "full_name": "Gitea",
+    "email": "someone@gitea.io",
+    "avatar_url": "https://localhost:3000/avatars/1",
+    "username": "gitea"
+  },
+  "sender": {
+    "id": 1,
+    "login": "gitea",
+    "full_name": "Gitea",
+    "email": "someone@gitea.io",
+    "avatar_url": "https://localhost:3000/avatars/1",
+    "username": "gitea"
+  }
+}
+```
+
+### Example
+
+This is an example of how to use webhooks to run a php script upon push requests to the repository.
+In your repository Settings, under Webhooks, Setup a Gitea webhook as follows:
+
+- Target URL: http://mydomain.com/webhook.php
+- HTTP Method: POST
+- POST Content Type: application/json
+- Secret: 123
+- Trigger On: Push Events
+- Active: Checked
+
+Now on your server create the php file webhook.php
+
+```
+<?php
+
+$secret_key = '123';
+
+// check for POST request
+if ($_SERVER['REQUEST_METHOD'] != 'POST') {
+    error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
+    exit();
+}
+
+// get content type
+$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
+
+if ($content_type != 'application/json') {
+    error_log('FAILED - not application/json - '. $content_type);
+    exit();
+}
+
+// get payload
+$payload = trim(file_get_contents("php://input"));
+
+if (empty($payload)) {
+    error_log('FAILED - no payload');
+    exit();
+}
+
+// get header signature
+$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
+
+if (empty($header_signature)) {
+    error_log('FAILED - header signature missing');
+    exit();
+}
+
+// calculate payload signature
+$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
+
+// check payload signature against header signature
+if ($header_signature !== $payload_signature) {
+    error_log('FAILED - payload signature');
+    exit();
+}
+
+// convert json to array
+$decoded = json_decode($payload, true);
+
+// check for json decode errors
+if (json_last_error() !== JSON_ERROR_NONE) {
+    error_log('FAILED - json decode - '. json_last_error());
+    exit();
+}
+
+// success, do something
+```
+
+There is a Test Delivery button in the webhook settings that allows to test the configuration as well as a list of the most Recent Deliveries.
+
+### Authorization header
+
+**With 1.19**, Gitea hooks can be configured to send an [authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) to the webhook target.
diff --git a/docs/content/doc/usage/webhooks.zh-cn.md b/docs/content/doc/usage/webhooks.zh-cn.md
new file mode 100644
index 0000000000..00ebd7aa9d
--- /dev/null
+++ b/docs/content/doc/usage/webhooks.zh-cn.md
@@ -0,0 +1,32 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Webhooks"
+slug: "webhooks"
+weight: 10
+toc: false
+draft: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "Webhooks"
+    weight: 30
+    identifier: "webhooks"
+---
+
+# Webhooks
+
+Gitea 的存储 webhook。这可以有存储库管路设定页 `/:username/:reponame/settings/hooks` 中的。Webhook 也可以按照组织调整或全系统调整，所有时间的推送都是POST请求
+。此方法目前被下列服务支援：
+
+- Gitea (也可以是 GET 請求)
+- Gogs
+- Slack
+- Discord
+- Dingtalk
+- Telegram
+- Microsoft Teams
+- Feishu
+- Wechatwork
+- Packagist
+
+## TBD
diff --git a/docs/content/doc/usage/webhooks.zh-tw.md b/docs/content/doc/usage/webhooks.zh-tw.md
new file mode 100644
index 0000000000..9e918739a4
--- /dev/null
+++ b/docs/content/doc/usage/webhooks.zh-tw.md
@@ -0,0 +1,188 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Webhook"
+slug: "webhooks"
+weight: 10
+toc: false
+draft: false
+menu:
+  sidebar:
+    parent: "usage"
+    name: "Webhook"
+    weight: 30
+    identifier: "webhooks"
+---
+
+# Webhook
+
+Gitea 的儲存庫事件支援 web hook。這可以有儲存庫管理員在設定頁 `/:username/:reponame/settings/hooks` 中調整。Webhook 也可以按照組織調整或按照全系統調整。
+所有的事件推送都是 POST 請求。此方法目前被下列服務支援：
+
+- Gitea (也可以是 GET 請求)
+- Gogs
+- Slack
+- Discord
+- Dingtalk
+- Telegram
+- Microsoft Teams
+- Feishu
+- Wechatwork
+- Packagist
+
+### 事件資訊
+
+**警告**： Payload 中的 `secret` 欄位已經在 Gitea 1.13.0 棄用，並且將在 1.14.0 移除： https://github.com/go-gitea/gitea/issues/11755
+
+下面是一個將由 Gitea 發送到 Payload URL 的事件資訊的範例：
+
+```
+X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-GitHub-Event: push
+X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gogs-Event: push
+X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gitea-Event: push
+```
+
+```json
+{
+  "secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
+  "ref": "refs/heads/develop",
+  "before": "28e1879d029cb852e4844d9c718537df08844e03",
+  "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
+  "compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
+  "commits": [
+    {
+      "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
+      "message": "Webhooks Yay!",
+      "url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
+      "author": {
+        "name": "Gitea",
+        "email": "someone@gitea.io",
+        "username": "gitea"
+      },
+      "committer": {
+        "name": "Gitea",
+        "email": "someone@gitea.io",
+        "username": "gitea"
+      },
+      "timestamp": "2017-03-13T13:52:11-04:00"
+    }
+  ],
+  "repository": {
+    "id": 140,
+    "owner": {
+      "id": 1,
+      "login": "gitea",
+      "full_name": "Gitea",
+      "email": "someone@gitea.io",
+      "avatar_url": "https://localhost:3000/avatars/1",
+      "username": "gitea"
+    },
+    "name": "webhooks",
+    "full_name": "gitea/webhooks",
+    "description": "",
+    "private": false,
+    "fork": false,
+    "html_url": "http://localhost:3000/gitea/webhooks",
+    "ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
+    "clone_url": "http://localhost:3000/gitea/webhooks.git",
+    "website": "",
+    "stars_count": 0,
+    "forks_count": 1,
+    "watchers_count": 1,
+    "open_issues_count": 7,
+    "default_branch": "master",
+    "created_at": "2017-02-26T04:29:06-05:00",
+    "updated_at": "2017-03-13T13:51:58-04:00"
+  },
+  "pusher": {
+    "id": 1,
+    "login": "gitea",
+    "full_name": "Gitea",
+    "email": "someone@gitea.io",
+    "avatar_url": "https://localhost:3000/avatars/1",
+    "username": "gitea"
+  },
+  "sender": {
+    "id": 1,
+    "login": "gitea",
+    "full_name": "Gitea",
+    "email": "someone@gitea.io",
+    "avatar_url": "https://localhost:3000/avatars/1",
+    "username": "gitea"
+  }
+}
+```
+
+### 範例
+
+此範例示範在發生推送事件時，如何使用 webhook 觸發 php 程式。
+使用下列參數在您的儲存庫設定 Webhook 中建立一個 Gitea webhook：
+
+- 目標 URL： http://mydomain.com/webhook.php
+- HTTP 請求方法：POST
+- POST Content Type：application/json
+- Secret：123
+- 觸發條件：推送事件
+- 啟用：勾選
+
+現在請到您的伺服器上建立 webhook.php 檔案
+
+```
+<?php
+
+$secret_key = '123';
+
+// check for POST request
+if ($_SERVER['REQUEST_METHOD'] != 'POST') {
+    error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
+    exit();
+}
+
+// get content type
+$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
+
+if ($content_type != 'application/json') {
+    error_log('FAILED - not application/json - '. $content_type);
+    exit();
+}
+
+// get payload
+$payload = trim(file_get_contents("php://input"));
+
+if (empty($payload)) {
+    error_log('FAILED - no payload');
+    exit();
+}
+
+// get header signature
+$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
+
+if (empty($header_signature)) {
+    error_log('FAILED - header signature missing');
+    exit();
+}
+
+// calculate payload signature
+$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
+
+// check payload signature against header signature
+if ($header_signature !== $payload_signature) {
+    error_log('FAILED - payload signature');
+    exit();
+}
+
+// convert json to array
+$decoded = json_decode($payload, true);
+
+// check for json decode errors
+if (json_last_error() !== JSON_ERROR_NONE) {
+    error_log('FAILED - json decode - '. json_last_error());
+    exit();
+}
+
+// success, do something
+```
+
+Webhook 設定中有一個傳送測試資料按鈕，它可讓你測試您的設定並將結果顯示於最近傳送記錄。