From 563945c50cec4d3bb839a783b8d4604271fdbf09 Mon Sep 17 00:00:00 2001
From: Xinyu Zhou <i@sourcehut.net>
Date: Tue, 1 Nov 2022 07:16:19 +0800
Subject: Refactor docs (#21627)
This patch:
- Rename some files( `.md` to `.en-us.md`), fix missed translation copy
- Update link which shoud be refer to `../hacking-on-gitea/` instead of
`../make/` (outdated)
- Update `_redirects`:
- redirect `/{zh-cn|fr-fr}/make/` to `../hacking-on-gitea/`
- redirect `/zh-cn/third-party-tools/` to `/zh-cn/integrations/`
- Delete duplicated/outdated files.
- Update menu `weight` of developers.zh-cn.md
Signed-off-by: Xinyu Zhou <i@sourcehut.net>
---
.../content/doc/advanced/hacking-on-gitea.zh-cn.md | 43 ----
docs/content/doc/advanced/mail-templates-us.md | 280 ---------------------
docs/content/doc/advanced/mail-templates.en-us.md | 280 +++++++++++++++++++++
docs/content/doc/advanced/make.fr-fr.md | 44 ----
docs/content/doc/advanced/make.zh-cn.md | 45 ----
.../doc/advanced/third-party-tools.zh-cn.md | 39 ---
docs/content/doc/developers.zh-cn.md | 2 +-
.../doc/developers/guidelines-backend.en-us.md | 123 +++++++++
docs/content/doc/developers/guidelines-backend.md | 123 ---------
.../doc/developers/oauth2-provider.en-us.md | 104 ++++++++
docs/content/doc/developers/oauth2-provider.md | 104 --------
docs/content/doc/installation/from-source.en-us.md | 2 +-
docs/content/doc/installation/from-source.fr-fr.md | 2 +-
docs/content/doc/installation/from-source.zh-cn.md | 2 +-
.../doc/installation/on-cloud-provider.en-us.md | 56 +++++
docs/content/doc/installation/on-cloud-provider.md | 56 -----
docs/content/doc/usage/git-lfs-support.en-us.md | 30 +++
docs/content/doc/usage/git-lfs-support.md | 30 ---
docs/content/doc/usage/https-support.en-us.md | 102 ++++++++
docs/content/doc/usage/https-support.md | 102 --------
.../doc/usage/template-repositories.en-us.md | 85 +++++++
docs/content/doc/usage/template-repositories.md | 85 -------
docs/static/_redirects | 3 +
23 files changed, 787 insertions(+), 955 deletions(-)
delete mode 100644 docs/content/doc/advanced/hacking-on-gitea.zh-cn.md
delete mode 100644 docs/content/doc/advanced/mail-templates-us.md
create mode 100644 docs/content/doc/advanced/mail-templates.en-us.md
delete mode 100644 docs/content/doc/advanced/make.fr-fr.md
delete mode 100644 docs/content/doc/advanced/make.zh-cn.md
delete mode 100644 docs/content/doc/advanced/third-party-tools.zh-cn.md
create mode 100644 docs/content/doc/developers/guidelines-backend.en-us.md
delete mode 100644 docs/content/doc/developers/guidelines-backend.md
create mode 100644 docs/content/doc/developers/oauth2-provider.en-us.md
delete mode 100644 docs/content/doc/developers/oauth2-provider.md
create mode 100644 docs/content/doc/installation/on-cloud-provider.en-us.md
delete mode 100644 docs/content/doc/installation/on-cloud-provider.md
create mode 100644 docs/content/doc/usage/git-lfs-support.en-us.md
delete mode 100644 docs/content/doc/usage/git-lfs-support.md
create mode 100644 docs/content/doc/usage/https-support.en-us.md
delete mode 100644 docs/content/doc/usage/https-support.md
create mode 100644 docs/content/doc/usage/template-repositories.en-us.md
delete mode 100644 docs/content/doc/usage/template-repositories.md
(limited to 'docs')
diff --git a/docs/content/doc/advanced/hacking-on-gitea.zh-cn.md b/docs/content/doc/advanced/hacking-on-gitea.zh-cn.md
deleted file mode 100644
index 7ad8019c5e..0000000000
--- a/docs/content/doc/advanced/hacking-on-gitea.zh-cn.md
+++ /dev/null
@@ -1,43 +0,0 @@
----
-date: "2016-12-01T16:00:00+02:00"
-title: "加入 Gitea 开源"
-slug: "hacking-on-gitea"
-weight: 10
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "加入 Gitea 开源"
- weight: 10
- identifier: "hacking-on-gitea"
----
-
-# Hacking on Gitea
-
-首先你需要一些运行环境，这和 [从源代码安装]({{< relref "from-source.zh-cn.md" >}}) 相同，如果你还没有设置好，可以先阅读那个章节。
-
-如果你想为 Gitea 贡献代码，你需要 Fork 这个项目并且以 `master` 为开发分支。Gitea 使用 Govendor
-来管理依赖，因此所有依赖项都被工具自动 copy 在 vendor 子目录下。用下面的命令来下载源码：
-
-```
-go get -d code.gitea.io/gitea
-```
-
-然后你可以在 Github 上 fork [Gitea 项目](https://github.com/go-gitea/gitea)，之后可以通过下面的命令进入源码目录：
-
-```
-cd $GOPATH/src/code.gitea.io/gitea
-```
-
-要创建 pull requests 你还需要在源码中新增一个 remote 指向你 Fork 的地址，直接推送到 origin 的话会告诉你没有写权限：
-
-```
-git remote rename origin upstream
-git remote add origin git@github.com:<USERNAME>/gitea.git
-git fetch --all --prune
-```
-
-然后你就可以开始开发了。你可以看一下 `Makefile` 的内容。`make test` 可以运行测试程序， `make build` 将生成一个 `gitea` 可运行文件在根目录。如果你的提交比较复杂，尽量多写一些单元测试代码。
-
-好了，到这里你已经设置好了所有的开发 Gitea 所需的环境。欢迎成为 Gitea 的 Contributor。
diff --git a/docs/content/doc/advanced/mail-templates-us.md b/docs/content/doc/advanced/mail-templates-us.md
deleted file mode 100644
index bd419a617b..0000000000
--- a/docs/content/doc/advanced/mail-templates-us.md
+++ /dev/null
@@ -1,280 +0,0 @@
----
-date: "2019-10-23T17:00:00-03:00"
-title: "Mail templates"
-slug: "mail-templates"
-weight: 45
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "Mail templates"
- weight: 45
- identifier: "mail-templates"
----
-
-# Mail templates
-
-**Table of Contents**
-
-{{< toc >}}
-
-To craft the e-mail subject and contents for certain operations, Gitea can be customized by using templates. The templates
-for these functions are located under the [`custom` directory](https://docs.gitea.io/en-us/customizing-gitea/).
-Gitea has an internal template that serves as default in case there's no custom alternative.
-
-Custom templates are loaded when Gitea starts. Changes made to them are not recognized until Gitea is restarted again.
-
-## Mail notifications supporting templates
-
-Currently, the following notification events make use of templates:
-
-| Action name | Usage |
-| ----------- | ------------------------------------------------------------------------------------------------------------ |
-| `new` | A new issue or pull request was created. |
-| `comment` | A new comment was created in an existing issue or pull request. |
-| `close` | An issue or pull request was closed. |
-| `reopen` | An issue or pull request was reopened. |
-| `review` | The head comment of a review in a pull request. |
-| `approve` | The head comment of a approving review for a pull request. |
-| `reject` | The head comment of a review requesting changes for a pull request. |
-| `code` | A single comment on the code of a pull request. |
-| `assigned` | Used was assigned to an issue or pull request. |
-| `default` | Any action not included in the above categories, or when the corresponding category template is not present. |
-
-The path for the template of a particular message type is:
-
-```sh
-custom/templates/mail/{action type}/{action name}.tmpl
-```
-
-Where `{action type}` is one of `issue` or `pull` (for pull requests), and `{action name}` is one of the names listed above.
-
-For example, the specific template for a mail regarding a comment in a pull request is:
-
-```sh
-custom/templates/mail/pull/comment.tmpl
-```
-
-However, creating templates for each and every action type/name combination is not required.
-A fallback system is used to choose the appropriate template for an event. The _first existing_
-template on this list is used:
-
-- The specific template for the desired **action type** and **action name**.
-- The template for action type `issue` and the desired **action name**.
-- The template for the desired **action type**, action name `default`.
-- The template for action type `issue`, action name `default`.
-
-The only mandatory template is action type `issue`, action name `default`, which is already embedded in Gitea
-unless it's overridden by the user in the `custom` directory.
-
-## Template syntax
-
-Mail templates are UTF-8 encoded text files that need to follow one of the following formats:
-
-```
-Text and macros for the subject line
-------------
-Text and macros for the mail body
-```
-
-or
-
-```
-Text and macros for the mail body
-```
-
-Specifying a _subject_ section is optional (and therefore also the dash line separator). When used, the separator between
-_subject_ and _mail body_ templates requires at least three dashes; no other characters are allowed in the separator line.
-
-_Subject_ and _mail body_ are parsed by [Golang's template engine](https://golang.org/pkg/text/template/) and
-are provided with a _metadata context_ assembled for each notification. The context contains the following elements:
-
-| Name | Type | Available | Usage |
-| ------------------ | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.FallbackSubject` | string | Always | A default subject line. See Below. |
-| `.Subject` | string | Only in body | The _subject_, once resolved. |
-| `.Body` | string | Always | The message of the issue, pull request or comment, parsed from Markdown into HTML and sanitized. Do not confuse with the _mail body_. |
-| `.Link` | string | Always | The address of the originating issue, pull request or comment. |
-| `.Issue` | models.Issue | Always | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is _not_ a pull request. |
-| `.Comment` | models.Comment | If applicable | If the notification is from a comment added to an issue or pull request, this will contain the information about the comment. |
-| `.IsPull` | bool | Always | `true` if the mail notification is associated with a pull request (i.e. `.Issue.PullRequest` is not `nil`). |
-| `.Repo` | string | Always | Name of the repository, including owner name (e.g. `mike/stuff`) |
-| `.User` | models.User | Always | Owner of the repository from which the event originated. To get the user name (e.g. `mike`),`.User.Name` can be used. |
-| `.Doer` | models.User | Always | User that executed the action triggering the notification event. To get the user name (e.g. `rhonda`), `.Doer.Name` can be used. |
-| `.IsMention` | bool | Always | `true` if this notification was only generated because the user was mentioned in the comment, while not being subscribed to the source. It will be `false` if the recipient was subscribed to the issue or repository. |
-| `.SubjectPrefix` | string | Always | `Re: ` if the notification is about other than issue or pull request creation; otherwise an empty string. |
-| `.ActionType` | string | Always | `"issue"` or `"pull"`. Will correspond to the actual _action type_ independently of which template was selected. |
-| `.ActionName` | string | Always | It will be one of the action types described above (`new`, `comment`, etc.), and will correspond to the actual _action name_ independently of which template was selected. |
-| `.ReviewComments` | []models.Comment | Always | List of code comments in a review. The comment text will be in `.RenderedContent` and the referenced code will be in `.Patch`. |
-
-All names are case sensitive.
-
-### The _subject_ part of the template
-
-The template engine used for the mail _subject_ is golang's [`text/template`](https://golang.org/pkg/text/template/).
-Please refer to the linked documentation for details about its syntax.
-
-The _subject_ is built using the following steps:
-
-- A template is selected according to the type of notification and to what templates are present.
-- The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue
- or pull request).
-- All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces.
-- All leading, trailing and redundant spaces are removed.
-- The string is truncated to its first 256 runes (characters).
-
-If the end result is an empty string, **or** no subject template was available (i.e. the selected template
-did not include a subject part), Gitea's **internal default** will be used.
-
-The internal default (fallback) subject is the equivalent of:
-
-```sh
-{{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#{{.Issue.Index}})
-```
-
-For example: `Re: [mike/stuff] New color palette (#38)`
-
-Gitea's default subject can also be found in the template _metadata_ as `.FallbackSubject` from any of
-the two templates, even if a valid subject template is present.
-
-### The _mail body_ part of the template
-
-The template engine used for the _mail body_ is golang's [`html/template`](https://golang.org/pkg/html/template/).
-Please refer to the linked documentation for details about its syntax.
-
-The _mail body_ is parsed after the mail subject, so there is an additional _metadata_ field which is
-the actual rendered subject, after all considerations.
-
-The expected result is HTML (including structural elements like`<html>`, `<body>`, etc.). Styling
-through `<style>` blocks, `class` and `style` attributes is possible. However, `html/template`
-does some [automatic escaping](https://golang.org/pkg/html/template/#hdr-Contexts) that should be considered.
-
-Attachments (such as images or external style sheets) are not supported. However, other templates can
-be referenced too, for example to provide the contents of a `<style>` element in a centralized fashion.
-The external template must be placed under `custom/mail` and referenced relative to that directory.
-For example, `custom/mail/styles/base.tmpl` can be included using `{{template styles/base}}`.
-
-The mail is sent with `Content-Type: multipart/alternative`, so the body is sent in both HTML
-and text formats. The latter is obtained by stripping the HTML markup.
-
-## Troubleshooting
-
-How a mail is rendered is directly dependent on the capabilities of the mail application. Many mail
-clients don't even support HTML, so they show the text version included in the generated mail.
-
-If the template fails to render, it will be noticed only at the moment the mail is sent.
-A default subject is used if the subject template fails, and whatever was rendered successfully
-from the the _mail body_ is used, disregarding the rest.
-
-Please check [Gitea's logs](https://docs.gitea.io/en-us/logging-configuration/) for error messages in case of trouble.
-
-## Example
-
-`custom/templates/mail/issue/default.tmpl`:
-
-```html
-[{{.Repo}}] @{{.Doer.Name}}
-{{if eq .ActionName "new"}}
- created
-{{else if eq .ActionName "comment"}}
- commented on
-{{else if eq .ActionName "close"}}
- closed
-{{else if eq .ActionName "reopen"}}
- reopened
-{{else}}
- updated
-{{end}}
-{{if eq .ActionType "issue"}}
- issue
-{{else}}
- pull request
-{{end}}
-#{{.Issue.Index}}: {{.Issue.Title}}
-------------
-<!DOCTYPE html>
-<html>
-<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>{{.Subject}}</title>
-</head>
-
-<body>
- {{if .IsMention}}
- <p>
- You are receiving this because @{{.Doer.Name}} mentioned you.
- </p>
- {{end}}
- <p>
- <p>
- <a href="{{AppUrl}}/{{.Doer.LowerName}}">@{{.Doer.Name}}</a>
- {{if not (eq .Doer.FullName "")}}
- ({{.Doer.FullName}})
- {{end}}
- {{if eq .ActionName "new"}}
- created
- {{else if eq .ActionName "close"}}
- closed
- {{else if eq .ActionName "reopen"}}
- reopened
- {{else}}
- updated
- {{end}}
- <a href="{{.Link}}">{{.Repo}}#{{.Issue.Index}}</a>.
- </p>
- {{if not (eq .Body "")}}
- <h3>Message content:</h3>
- <hr>
- {{.Body | Str2html}}
- {{end}}
- </p>
- <hr>
- <p>
- <a href="{{.Link}}">View it on Gitea</a>.
- </p>
-</body>
-</html>
-```
-
-This template produces something along these lines:
-
-### Subject
-
-> [mike/stuff] @rhonda commented on pull request #38: New color palette
-
-### Mail body
-
-> [@rhonda](#) (Rhonda Myers) updated [mike/stuff#38](#).
->
-> #### Message content:
->
-> \_********************************\_********************************
->
-> Mike, I think we should tone down the blues a little.
-> \_********************************\_********************************
->
-> [View it on Gitea](#).
-
-## Advanced
-
-The template system contains several functions that can be used to further process and format
-the messages. Here's a list of some of them:
-
-| Name | Parameters | Available | Usage |
-| ---------------- | ----------- | --------- | --------------------------------------------------------------------------- |
-| `AppUrl` | - | Any | Gitea's URL |
-| `AppName` | - | Any | Set from `app.ini`, usually "Gitea" |
-| `AppDomain` | - | Any | Gitea's host name |
-| `EllipsisString` | string, int | Any | Truncates a string to the specified length; adds ellipsis as needed |
-| `Str2html` | string | Body only | Sanitizes text by removing any HTML tags from it. |
-| `Safe` | string | Body only | Takes the input as HTML; can be used for `.ReviewComments.RenderedContent`. |
-
-These are _functions_, not metadata, so they have to be used:
-
-```html
-Like this: {{Str2html "Escape<my>text"}}
-Or this: {{"Escape<my>text" | Str2html}}
-Or this: {{AppUrl}}
-But not like this: {{.AppUrl}}
-```
diff --git a/docs/content/doc/advanced/mail-templates.en-us.md b/docs/content/doc/advanced/mail-templates.en-us.md
new file mode 100644
index 0000000000..bd419a617b
--- /dev/null
+++ b/docs/content/doc/advanced/mail-templates.en-us.md
@@ -0,0 +1,280 @@
+---
+date: "2019-10-23T17:00:00-03:00"
+title: "Mail templates"
+slug: "mail-templates"
+weight: 45
+toc: false
+draft: false
+menu:
+ sidebar:
+ parent: "advanced"
+ name: "Mail templates"
+ weight: 45
+ identifier: "mail-templates"
+---
+
+# Mail templates
+
+**Table of Contents**
+
+{{< toc >}}
+
+To craft the e-mail subject and contents for certain operations, Gitea can be customized by using templates. The templates
+for these functions are located under the [`custom` directory](https://docs.gitea.io/en-us/customizing-gitea/).
+Gitea has an internal template that serves as default in case there's no custom alternative.
+
+Custom templates are loaded when Gitea starts. Changes made to them are not recognized until Gitea is restarted again.
+
+## Mail notifications supporting templates
+
+Currently, the following notification events make use of templates:
+
+| Action name | Usage |
+| ----------- | ------------------------------------------------------------------------------------------------------------ |
+| `new` | A new issue or pull request was created. |
+| `comment` | A new comment was created in an existing issue or pull request. |
+| `close` | An issue or pull request was closed. |
+| `reopen` | An issue or pull request was reopened. |
+| `review` | The head comment of a review in a pull request. |
+| `approve` | The head comment of a approving review for a pull request. |
+| `reject` | The head comment of a review requesting changes for a pull request. |
+| `code` | A single comment on the code of a pull request. |
+| `assigned` | Used was assigned to an issue or pull request. |
+| `default` | Any action not included in the above categories, or when the corresponding category template is not present. |
+
+The path for the template of a particular message type is:
+
+```sh
+custom/templates/mail/{action type}/{action name}.tmpl
+```
+
+Where `{action type}` is one of `issue` or `pull` (for pull requests), and `{action name}` is one of the names listed above.
+
+For example, the specific template for a mail regarding a comment in a pull request is:
+
+```sh
+custom/templates/mail/pull/comment.tmpl
+```
+
+However, creating templates for each and every action type/name combination is not required.
+A fallback system is used to choose the appropriate template for an event. The _first existing_
+template on this list is used:
+
+- The specific template for the desired **action type** and **action name**.
+- The template for action type `issue` and the desired **action name**.
+- The template for the desired **action type**, action name `default`.
+- The template for action type `issue`, action name `default`.
+
+The only mandatory template is action type `issue`, action name `default`, which is already embedded in Gitea
+unless it's overridden by the user in the `custom` directory.
+
+## Template syntax
+
+Mail templates are UTF-8 encoded text files that need to follow one of the following formats:
+
+```
+Text and macros for the subject line
+------------
+Text and macros for the mail body
+```
+
+or
+
+```
+Text and macros for the mail body
+```
+
+Specifying a _subject_ section is optional (and therefore also the dash line separator). When used, the separator between
+_subject_ and _mail body_ templates requires at least three dashes; no other characters are allowed in the separator line.
+
+_Subject_ and _mail body_ are parsed by [Golang's template engine](https://golang.org/pkg/text/template/) and
+are provided with a _metadata context_ assembled for each notification. The context contains the following elements:
+
+| Name | Type | Available | Usage |
+| ------------------ | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.FallbackSubject` | string | Always | A default subject line. See Below. |
+| `.Subject` | string | Only in body | The _subject_, once resolved. |
+| `.Body` | string | Always | The message of the issue, pull request or comment, parsed from Markdown into HTML and sanitized. Do not confuse with the _mail body_. |
+| `.Link` | string | Always | The address of the originating issue, pull request or comment. |
+| `.Issue` | models.Issue | Always | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is _not_ a pull request. |
+| `.Comment` | models.Comment | If applicable | If the notification is from a comment added to an issue or pull request, this will contain the information about the comment. |
+| `.IsPull` | bool | Always | `true` if the mail notification is associated with a pull request (i.e. `.Issue.PullRequest` is not `nil`). |
+| `.Repo` | string | Always | Name of the repository, including owner name (e.g. `mike/stuff`) |
+| `.User` | models.User | Always | Owner of the repository from which the event originated. To get the user name (e.g. `mike`),`.User.Name` can be used. |
+| `.Doer` | models.User | Always | User that executed the action triggering the notification event. To get the user name (e.g. `rhonda`), `.Doer.Name` can be used. |
+| `.IsMention` | bool | Always | `true` if this notification was only generated because the user was mentioned in the comment, while not being subscribed to the source. It will be `false` if the recipient was subscribed to the issue or repository. |
+| `.SubjectPrefix` | string | Always | `Re: ` if the notification is about other than issue or pull request creation; otherwise an empty string. |
+| `.ActionType` | string | Always | `"issue"` or `"pull"`. Will correspond to the actual _action type_ independently of which template was selected. |
+| `.ActionName` | string | Always | It will be one of the action types described above (`new`, `comment`, etc.), and will correspond to the actual _action name_ independently of which template was selected. |
+| `.ReviewComments` | []models.Comment | Always | List of code comments in a review. The comment text will be in `.RenderedContent` and the referenced code will be in `.Patch`. |
+
+All names are case sensitive.
+
+### The _subject_ part of the template
+
+The template engine used for the mail _subject_ is golang's [`text/template`](https://golang.org/pkg/text/template/).
+Please refer to the linked documentation for details about its syntax.
+
+The _subject_ is built using the following steps:
+
+- A template is selected according to the type of notification and to what templates are present.
+- The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue
+ or pull request).
+- All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces.
+- All leading, trailing and redundant spaces are removed.
+- The string is truncated to its first 256 runes (characters).
+
+If the end result is an empty string, **or** no subject template was available (i.e. the selected template
+did not include a subject part), Gitea's **internal default** will be used.
+
+The internal default (fallback) subject is the equivalent of:
+
+```sh
+{{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#{{.Issue.Index}})
+```
+
+For example: `Re: [mike/stuff] New color palette (#38)`
+
+Gitea's default subject can also be found in the template _metadata_ as `.FallbackSubject` from any of
+the two templates, even if a valid subject template is present.
+
+### The _mail body_ part of the template
+
+The template engine used for the _mail body_ is golang's [`html/template`](https://golang.org/pkg/html/template/).
+Please refer to the linked documentation for details about its syntax.
+
+The _mail body_ is parsed after the mail subject, so there is an additional _metadata_ field which is
+the actual rendered subject, after all considerations.
+
+The expected result is HTML (including structural elements like`<html>`, `<body>`, etc.). Styling
+through `<style>` blocks, `class` and `style` attributes is possible. However, `html/template`
+does some [automatic escaping](https://golang.org/pkg/html/template/#hdr-Contexts) that should be considered.
+
+Attachments (such as images or external style sheets) are not supported. However, other templates can
+be referenced too, for example to provide the contents of a `<style>` element in a centralized fashion.
+The external template must be placed under `custom/mail` and referenced relative to that directory.
+For example, `custom/mail/styles/base.tmpl` can be included using `{{template styles/base}}`.
+
+The mail is sent with `Content-Type: multipart/alternative`, so the body is sent in both HTML
+and text formats. The latter is obtained by stripping the HTML markup.
+
+## Troubleshooting
+
+How a mail is rendered is directly dependent on the capabilities of the mail application. Many mail
+clients don't even support HTML, so they show the text version included in the generated mail.
+
+If the template fails to render, it will be noticed only at the moment the mail is sent.
+A default subject is used if the subject template fails, and whatever was rendered successfully
+from the the _mail body_ is used, disregarding the rest.
+
+Please check [Gitea's logs](https://docs.gitea.io/en-us/logging-configuration/) for error messages in case of trouble.
+
+## Example
+
+`custom/templates/mail/issue/default.tmpl`:
+
+```html
+[{{.Repo}}] @{{.Doer.Name}}
+{{if eq .ActionName "new"}}
+ created
+{{else if eq .ActionName "comment"}}
+ commented on
+{{else if eq .ActionName "close"}}
+ closed
+{{else if eq .ActionName "reopen"}}
+ reopened
+{{else}}
+ updated
+{{end}}
+{{if eq .ActionType "issue"}}
+ issue
+{{else}}
+ pull request
+{{end}}
+#{{.Issue.Index}}: {{.Issue.Title}}
+------------
+<!DOCTYPE html>
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>{{.Subject}}</title>
+</head>
+
+<body>
+ {{if .IsMention}}
+ <p>
+ You are receiving this because @{{.Doer.Name}} mentioned you.
+ </p>
+ {{end}}
+ <p>
+ <p>
+ <a href="{{AppUrl}}/{{.Doer.LowerName}}">@{{.Doer.Name}}</a>
+ {{if not (eq .Doer.FullName "")}}
+ ({{.Doer.FullName}})
+ {{end}}
+ {{if eq .ActionName "new"}}
+ created
+ {{else if eq .ActionName "close"}}
+ closed
+ {{else if eq .ActionName "reopen"}}
+ reopened
+ {{else}}
+ updated
+ {{end}}
+ <a href="{{.Link}}">{{.Repo}}#{{.Issue.Index}}</a>.
+ </p>
+ {{if not (eq .Body "")}}
+ <h3>Message content:</h3>
+ <hr>
+ {{.Body | Str2html}}
+ {{end}}
+ </p>
+ <hr>
+ <p>
+ <a href="{{.Link}}">View it on Gitea</a>.
+ </p>
+</body>
+</html>
+```
+
+This template produces something along these lines:
+
+### Subject
+
+> [mike/stuff] @rhonda commented on pull request #38: New color palette
+
+### Mail body
+
+> [@rhonda](#) (Rhonda Myers) updated [mike/stuff#38](#).
+>
+> #### Message content:
+>
+> \_********************************\_********************************
+>
+> Mike, I think we should tone down the blues a little.
+> \_********************************\_********************************
+>
+> [View it on Gitea](#).
+
+## Advanced
+
+The template system contains several functions that can be used to further process and format
+the messages. Here's a list of some of them:
+
+| Name | Parameters | Available | Usage |
+| ---------------- | ----------- | --------- | --------------------------------------------------------------------------- |
+| `AppUrl` | - | Any | Gitea's URL |
+| `AppName` | - | Any | Set from `app.ini`, usually "Gitea" |
+| `AppDomain` | - | Any | Gitea's host name |
+| `EllipsisString` | string, int | Any | Truncates a string to the specified length; adds ellipsis as needed |
+| `Str2html` | string | Body only | Sanitizes text by removing any HTML tags from it. |
+| `Safe` | string | Body only | Takes the input as HTML; can be used for `.ReviewComments.RenderedContent`. |
+
+These are _functions_, not metadata, so they have to be used:
+
+```html
+Like this: {{Str2html "Escape<my>text"}}
+Or this: {{"Escape<my>text" | Str2html}}
+Or this: {{AppUrl}}
+But not like this: {{.AppUrl}}
+```
diff --git a/docs/content/doc/advanced/make.fr-fr.md b/docs/content/doc/advanced/make.fr-fr.md
deleted file mode 100644
index f30b709f0e..0000000000
--- a/docs/content/doc/advanced/make.fr-fr.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-date: "2017-08-23T09:00:00+02:00"
-title: "Make"
-slug: "make"
-weight: 10
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "Make"
- weight: 30
- identifier: "make"
----
-
-# Make
-
-Gitea fait largement usage de Make pour automatiser les tâches et avoir un développement plus rapide. Ce guide explique comment installer Make.
-
-### Linux
-
-Vous pouvez installer Make avec votre gestionnaire de paquetages
-
-Depuis Ubuntu/Debian:
-
-```bash
-sudo apt-get install build-essential
-```
-
-Depuis Fedora/RHEL/CentOS:
-
-```bash
-sudo yum install make
-```
-
-### Windows
-
-Si vous utilisez Windows, vous pouvez télécharger une des versions suivantes de Make:
-
-- [Simple binaire](http://www.equation.com/servlet/equation.cmd?fa=make). Copiez-le quelque part et mettez à jour `PATH`.
- - [32-bits version](ftp://ftp.equation.com/make/32/make.exe)
- - [64-bits version](ftp://ftp.equation.com/make/64/make.exe)
-- [MinGW](http://www.mingw.org/) inclut un _build_. Le fichier binaire est nommé `mingw32-make.exe` plutôt que `make.exe`. Ajoutez le dossier `bin` à votre `PATH`.
-- [Chocolatey package](https://chocolatey.org/packages/make). Exécutez `choco install make`.
diff --git a/docs/content/doc/advanced/make.zh-cn.md b/docs/content/doc/advanced/make.zh-cn.md
deleted file mode 100644
index 2491dbe231..0000000000
--- a/docs/content/doc/advanced/make.zh-cn.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-date: "2017-01-14T11:00:00-02:00"
-title: "Make 安装"
-slug: "make"
-weight: 10
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "Make 安装"
- weight: 30
- identifier: "make"
----
-
-# 安装 Make
-
-Gitea 大量使用了 Make 工具来自动执行任务并改进开发，本文将介绍如何安装 Make。
-
-### 在 Linux 环境下
-
-可以使用包管理工具来安装 Make。
-
-Ubuntu/Debian 环境，执行以下命令：
-
-```bash
-sudo apt-get install make
-```
-
-Fedora/RHEL/CentOS，执行以下命令：
-
-```bash
-sudo yum install make
-```
-
-### 在 Windows 环境下
-
-您可以参照以下三种方案在 Windows 环境安装 Make：
-
-- 直接使用 [exe文件](http://www.equation.com/servlet/equation.cmd?fa=make)：将适合您系统的exe文件拷贝到某处并添加至环境变量 `PATH` 中。
- - [32 位版本](ftp://ftp.equation.com/make/32/make.exe)
- - [64 位版本](ftp://ftp.equation.com/make/64/make.exe)
-- 使用 [MinGW](http://www.mingw.org/) 工具：
- - 此处使用二进制文件 `mingw32-make.exe` 替代前面提到的 `make.exe`文件。同样您需要将包含此exe文件的 `bin` 目录添加至环境变量 `PATH`中。
-- 通过 [Chocolatey](https://chocolatey.org/packages/make) 安装： 执行 `choco install make` 命令即可。
diff --git a/docs/content/doc/advanced/third-party-tools.zh-cn.md b/docs/content/doc/advanced/third-party-tools.zh-cn.md
deleted file mode 100644
index e961e9ec1f..0000000000
--- a/docs/content/doc/advanced/third-party-tools.zh-cn.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-date: "2019-03-11T21:45:00+00:00"
-title: "高级: 第三方工具"
-slug: "third-party-tools"
-weight: 50
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "第三方工具"
- weight: 50
- identifier: "third-party-tools"
----
-
-# 第三方工具列表
-
-**注意:** 这些工具并没有经过Gitea的检验，在这里列出它们只是为了便捷.
-
-*此列表并不是完整的列表，可以随时咨询如何添加!*
-
-### 持续集成
-
-[BuildKite 连接器](https://github.com/techknowlogick/gitea-buildkite-connector)
-[Jenkins 插件](https://github.com/jenkinsci/gitea-plugin)
-[Gitea搭配Drone](https://docs.drone.io/installation/gitea)
-
-### 迁移
-
-[Gitea安装脚本](https://git.coolaj86.com/coolaj86/gitea-installer.sh)
-[GitHub迁移](https://gitea.com/gitea/migrator)
-
-### 移动端
-
-[安卓客户端GitNex](https://gitlab.com/mmarif4u/gitnex)
-
-### 编辑器扩展
-
-- [Gitea的Visual Studio扩展](https://github.com/maikebing/Gitea.VisualStudio) 从 [Visual Studio 扩展市场](https://marketplace.visualstudio.com/items?itemName=MysticBoy.GiteaExtensionforVisualStudio) 下载
diff --git a/docs/content/doc/developers.zh-cn.md b/docs/content/doc/developers.zh-cn.md
index 0a873102bc..97fb3a9782 100644
--- a/docs/content/doc/developers.zh-cn.md
+++ b/docs/content/doc/developers.zh-cn.md
@@ -8,6 +8,6 @@ draft: false
menu:
sidebar:
name: "开发者"
- weight: 50
+ weight: 55
identifier: "developers"
---
diff --git a/docs/content/doc/developers/guidelines-backend.en-us.md b/docs/content/doc/developers/guidelines-backend.en-us.md
new file mode 100644
index 0000000000..913898be83
--- /dev/null
+++ b/docs/content/doc/developers/guidelines-backend.en-us.md
@@ -0,0 +1,123 @@
+---
+date: "2021-11-01T23:41:00+08:00"
+title: "Guidelines for Backend Development"
+slug: "guidelines-backend"
+weight: 20
+toc: false
+draft: false
+menu:
+ sidebar:
+ parent: "developers"
+ name: "Guidelines for Backend"
+ weight: 20
+ identifier: "guidelines-backend"
+---
+
+# Guidelines for Backend Development
+
+**Table of Contents**
+
+{{< toc >}}
+
+## Background
+
+Gitea uses Golang as the backend programming language. It uses many third-party packages and also write some itself.
+For example, Gitea uses [Chi](https://github.com/go-chi/chi) as basic web framework. [Xorm](https://xorm.io) is an ORM framework that is used to interact with the database.
+So it's very important to manage these packages. Please take the below guidelines before you start to write backend code.
+
+## Package Design Guideline
+
+### Packages List
+
+To maintain understandable code and avoid circular dependencies it is important to have a good code structure. The Gitea backend is divided into the following parts:
+
+- `build`: Scripts to help build Gitea.
+- `cmd`: All Gitea actual sub commands includes web, doctor, serv, hooks, admin and etc. `web` will start the web service. `serv` and `hooks` will be invoked by Git or OpenSSH. Other sub commands could help to maintain Gitea.
+- `tests`: Common test utility functions
+ - `tests/integration`: Integration tests, to test back-end regressions
+ - `tests/e2e`: E2e tests, to test test front-end <> back-end compatibility and visual regressions.
+- `models`: Contains the data structures used by xorm to construct database tables. It also contains functions to query and update the database. Dependencies to other Gitea code should be avoided. You can make exceptions in cases such as logging.
+ - `models/db`: Basic database operations. All other `models/xxx` packages should depend on this package. The `GetEngine` function should only be invoked from `models/`.
+ - `models/fixtures`: Sample data used in unit tests and integration tests. One `yml` file means one table which will be loaded into database when beginning the tests.
+ - `models/migrations`: Stores database migrations between versions. PRs that change a database structure **MUST** also have a migration step.
+- `modules`: Different modules to handle specific functionality in Gitea. Work in Progress: Some of them should be moved to `services`, in particular those that depend on models because they rely on the database.
+ - `modules/setting`: Store all system configurations read from ini files and has been referenced by everywhere. But they should be used as function parameters when possible.
+ - `modules/git`: Package to interactive with `Git` command line or Gogit package.
+- `public`: Compiled frontend files (javascript, images, css, etc.)
+- `routers`: Handling of server requests. As it uses other Gitea packages to serve the request, other packages (models, modules or services) must not depend on routers.
+ - `routers/api` Contains routers for `/api/v1` aims to handle RESTful API requests.
+ - `routers/install` Could only respond when system is in INSTALL mode (INSTALL_LOCK=false).
+ - `routers/private` will only be invoked by internal sub commands, especially `serv` and `hooks`.
+ - `routers/web` will handle HTTP requests from web browsers or Git SMART HTTP protocols.
+- `services`: Support functions for common routing operations or command executions. Uses `models` and `modules` to handle the requests.
+- `templates`: Golang templates for generating the html output.
+
+### Package Dependencies
+
+Since Golang don't support import cycles, we have to decide the package dependencies carefully. There are some levels between those packages. Below is the ideal package dependencies direction.
+
+`cmd` -> `routers` -> `services` -> `models` -> `modules`
+
+From left to right, left packages could depend on right packages, but right packages MUST not depend on left packages. The sub packages on the same level could depend on according this level's rules.
+
+**NOTICE**
+
+Why do we need database transactions outside of `models`? And how?
+Some actions should allow for rollback when database record insertion/update/deletion failed.
+So services must be allowed to create a database transaction. Here is some example,
+
+```go
+// services/repository/repository.go
+func CreateXXXX() error {
+ return db.WithTx(func(ctx context.Context) error {
+ e := db.GetEngine(ctx)
+ // do something, if err is returned, it will rollback automatically
+ if err := issues.UpdateIssue(ctx, repoID); err != nil {
+ // ...
+ return err
+ }
+ // ...
+ return nil
+ })
+}
+```
+
+You should **not** use `db.GetEngine(ctx)` in `services` directly, but just write a function under `models/`.
+If the function will be used in the transaction, just let `context.Context` as the function's first parameter.
+
+```go
+// models/issues/issue.go
+func UpdateIssue(ctx context.Context, repoID int64) error {
+ e := db.GetEngine(ctx)
+
+ // ...
+}
+```
+
+### Package Name
+
+For the top level package, use a plural as package name, i.e. `services`, `models`, for sub packages, use singular,
+i.e. `services/user`, `models/repository`.
+
+### Import Alias
+
+Since there are some packages which use the same package name, it is possible that you find packages like `modules/user`, `models/user`, and `services/user`. When these packages are imported in one Go file, it's difficult to know which package we are using and if it's a variable name or an import name. So, we always recommend to use import aliases. To differ from package variables which are commonly in camelCase, just use **snake_case** for import aliases.
+i.e. `import user_service "code.gitea.io/gitea/services/user"`
+
+### Important Gotchas
+
+- Never write `x.Update(exemplar)` without an explicit `WHERE` clause:
+ - This will cause all rows in the table to be updated with the non-zero values of the exemplar - including IDs.
+ - You should usually write `x.ID(id).Update(exemplar)`.
+- If during a migration you are inserting into a table using `x.Insert(exemplar)` where the ID is preset:
+ - You will need to ``SET IDENTITY_INSERT `table` ON`` for the MSSQL variant (the migration will fail otherwise)
+ - However, you will also need to update the id sequence for postgres - the migration will silently pass here but later insertions will fail:
+ ``SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false)``
+
+### Future Tasks
+
+Currently, we are creating some refactors to do the following things:
+
+- Correct that codes which doesn't follow the rules.
+- There are too many files in `models`, so we are moving some of them into a sub package `models/xxx`.
+- Some `modules` sub packages should be moved to `services` because they depend on `models`.
diff --git a/docs/content/doc/developers/guidelines-backend.md b/docs/content/doc/developers/guidelines-backend.md
deleted file mode 100644
index 913898be83..0000000000
--- a/docs/content/doc/developers/guidelines-backend.md
+++ /dev/null
@@ -1,123 +0,0 @@
----
-date: "2021-11-01T23:41:00+08:00"
-title: "Guidelines for Backend Development"
-slug: "guidelines-backend"
-weight: 20
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "developers"
- name: "Guidelines for Backend"
- weight: 20
- identifier: "guidelines-backend"
----
-
-# Guidelines for Backend Development
-
-**Table of Contents**
-
-{{< toc >}}
-
-## Background
-
-Gitea uses Golang as the backend programming language. It uses many third-party packages and also write some itself.
-For example, Gitea uses [Chi](https://github.com/go-chi/chi) as basic web framework. [Xorm](https://xorm.io) is an ORM framework that is used to interact with the database.
-So it's very important to manage these packages. Please take the below guidelines before you start to write backend code.
-
-## Package Design Guideline
-
-### Packages List
-
-To maintain understandable code and avoid circular dependencies it is important to have a good code structure. The Gitea backend is divided into the following parts:
-
-- `build`: Scripts to help build Gitea.
-- `cmd`: All Gitea actual sub commands includes web, doctor, serv, hooks, admin and etc. `web` will start the web service. `serv` and `hooks` will be invoked by Git or OpenSSH. Other sub commands could help to maintain Gitea.
-- `tests`: Common test utility functions
- - `tests/integration`: Integration tests, to test back-end regressions
- - `tests/e2e`: E2e tests, to test test front-end <> back-end compatibility and visual regressions.
-- `models`: Contains the data structures used by xorm to construct database tables. It also contains functions to query and update the database. Dependencies to other Gitea code should be avoided. You can make exceptions in cases such as logging.
- - `models/db`: Basic database operations. All other `models/xxx` packages should depend on this package. The `GetEngine` function should only be invoked from `models/`.
- - `models/fixtures`: Sample data used in unit tests and integration tests. One `yml` file means one table which will be loaded into database when beginning the tests.
- - `models/migrations`: Stores database migrations between versions. PRs that change a database structure **MUST** also have a migration step.
-- `modules`: Different modules to handle specific functionality in Gitea. Work in Progress: Some of them should be moved to `services`, in particular those that depend on models because they rely on the database.
- - `modules/setting`: Store all system configurations read from ini files and has been referenced by everywhere. But they should be used as function parameters when possible.
- - `modules/git`: Package to interactive with `Git` command line or Gogit package.
-- `public`: Compiled frontend files (javascript, images, css, etc.)
-- `routers`: Handling of server requests. As it uses other Gitea packages to serve the request, other packages (models, modules or services) must not depend on routers.
- - `routers/api` Contains routers for `/api/v1` aims to handle RESTful API requests.
- - `routers/install` Could only respond when system is in INSTALL mode (INSTALL_LOCK=false).
- - `routers/private` will only be invoked by internal sub commands, especially `serv` and `hooks`.
- - `routers/web` will handle HTTP requests from web browsers or Git SMART HTTP protocols.
-- `services`: Support functions for common routing operations or command executions. Uses `models` and `modules` to handle the requests.
-- `templates`: Golang templates for generating the html output.
-
-### Package Dependencies
-
-Since Golang don't support import cycles, we have to decide the package dependencies carefully. There are some levels between those packages. Below is the ideal package dependencies direction.
-
-`cmd` -> `routers` -> `services` -> `models` -> `modules`
-
-From left to right, left packages could depend on right packages, but right packages MUST not depend on left packages. The sub packages on the same level could depend on according this level's rules.
-
-**NOTICE**
-
-Why do we need database transactions outside of `models`? And how?
-Some actions should allow for rollback when database record insertion/update/deletion failed.
-So services must be allowed to create a database transaction. Here is some example,
-
-```go
-// services/repository/repository.go
-func CreateXXXX() error {
- return db.WithTx(func(ctx context.Context) error {
- e := db.GetEngine(ctx)
- // do something, if err is returned, it will rollback automatically
- if err := issues.UpdateIssue(ctx, repoID); err != nil {
- // ...
- return err
- }
- // ...
- return nil
- })
-}
-```
-
-You should **not** use `db.GetEngine(ctx)` in `services` directly, but just write a function under `models/`.
-If the function will be used in the transaction, just let `context.Context` as the function's first parameter.
-
-```go
-// models/issues/issue.go
-func UpdateIssue(ctx context.Context, repoID int64) error {
- e := db.GetEngine(ctx)
-
- // ...
-}
-```
-
-### Package Name
-
-For the top level package, use a plural as package name, i.e. `services`, `models`, for sub packages, use singular,
-i.e. `services/user`, `models/repository`.
-
-### Import Alias
-
-Since there are some packages which use the same package name, it is possible that you find packages like `modules/user`, `models/user`, and `services/user`. When these packages are imported in one Go file, it's difficult to know which package we are using and if it's a variable name or an import name. So, we always recommend to use import aliases. To differ from package variables which are commonly in camelCase, just use **snake_case** for import aliases.
-i.e. `import user_service "code.gitea.io/gitea/services/user"`
-
-### Important Gotchas
-
-- Never write `x.Update(exemplar)` without an explicit `WHERE` clause:
- - This will cause all rows in the table to be updated with the non-zero values of the exemplar - including IDs.
- - You should usually write `x.ID(id).Update(exemplar)`.
-- If during a migration you are inserting into a table using `x.Insert(exemplar)` where the ID is preset:
- - You will need to ``SET IDENTITY_INSERT `table` ON`` for the MSSQL variant (the migration will fail otherwise)
- - However, you will also need to update the id sequence for postgres - the migration will silently pass here but later insertions will fail:
- ``SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false)``
-
-### Future Tasks
-
-Currently, we are creating some refactors to do the following things:
-
-- Correct that codes which doesn't follow the rules.
-- There are too many files in `models`, so we are moving some of them into a sub package `models/xxx`.
-- Some `modules` sub packages should be moved to `services` because they depend on `models`.
diff --git a/docs/content/doc/developers/oauth2-provider.en-us.md b/docs/content/doc/developers/oauth2-provider.en-us.md
new file mode 100644
index 0000000000..c6765f19e7
--- /dev/null
+++ b/docs/content/doc/developers/oauth2-provider.en-us.md
@@ -0,0 +1,104 @@
+---
+date: "2019-04-19:44:00+01:00"
+title: "OAuth2 provider"
+slug: "oauth2-provider"
+weight: 41
+toc: false
+draft: false
+menu:
+ sidebar:
+ parent: "developers"
+ name: "OAuth2 Provider"
+ weight: 41
+ identifier: "oauth2-provider"
+---
+
+# OAuth2 provider
+
+**Table of Contents**
+
+{{< toc >}}
+
+Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0.
+
+## Endpoints
+
+| Endpoint | URL |
+| ------------------------ | ----------------------------------- |
+| OpenID Connect Discovery | `/.well-known/openid-configuration` |
+| Authorization Endpoint | `/login/oauth/authorize` |
+| Access Token Endpoint | `/login/oauth/access_token` |
+| OpenID Connect UserInfo | `/login/oauth/userinfo` |
+| JSON Web Key Set | `/login/oauth/keys` |
+
+## Supported OAuth2 Grants
+
+At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the following extensions:
+
+- [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636)
+- [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
+
+To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings.
+
+## Scopes
+
+Currently Gitea does not support scopes (see [#4300](https://github.com/go-gitea/gitea/issues/4300)) and all third party applications will be granted access to all resources of the user and their organizations.
+
+## Client types
+
+Gitea supports both confidential and public client types, [as defined by RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1).
+
+For public clients, a redirect URI of a loopback IP address such as `http://127.0.0.1/` allows any port. Avoid using `localhost`, [as recommended by RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3).
+
+## Example
+
+**Note:** This example does not use PKCE.
+
+1. Redirect to user to the authorization endpoint in order to get their consent for accessing the resources:
+
+ ```curl
+ https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
+ ```
+
+ The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks.
+
+ 
+
+ The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example:
+
+ ```curl
+ https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
+ ```
+
+2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
+
+ ```curl
+ POST https://[YOUR-GITEA-URL]/login/oauth/access_token
+ ```
+
+ ```json
+ {
+ "client_id": "YOUR_CLIENT_ID",
+ "client_secret": "YOUR_CLIENT_SECRET",
+ "code": "RETURNED_CODE",
+ "grant_type": "authorization_code",
+ "redirect_uri": "REDIRECT_URI"
+ }
+ ```
+
+ Response:
+
+ ```json
+ {
+ "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
+ "token_type": "bearer",
+ "expires_in": 3600,
+ "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
+ }
+ ```
+
+ The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings.
+
+ The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request.
+
+3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources.
diff --git a/docs/content/doc/developers/oauth2-provider.md b/docs/content/doc/developers/oauth2-provider.md
deleted file mode 100644
index c6765f19e7..0000000000
--- a/docs/content/doc/developers/oauth2-provider.md
+++ /dev/null
@@ -1,104 +0,0 @@
----
-date: "2019-04-19:44:00+01:00"
-title: "OAuth2 provider"
-slug: "oauth2-provider"
-weight: 41
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "developers"
- name: "OAuth2 Provider"
- weight: 41
- identifier: "oauth2-provider"
----
-
-# OAuth2 provider
-
-**Table of Contents**
-
-{{< toc >}}
-
-Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0.
-
-## Endpoints
-
-| Endpoint | URL |
-| ------------------------ | ----------------------------------- |
-| OpenID Connect Discovery | `/.well-known/openid-configuration` |
-| Authorization Endpoint | `/login/oauth/authorize` |
-| Access Token Endpoint | `/login/oauth/access_token` |
-| OpenID Connect UserInfo | `/login/oauth/userinfo` |
-| JSON Web Key Set | `/login/oauth/keys` |
-
-## Supported OAuth2 Grants
-
-At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the following extensions:
-
-- [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636)
-- [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
-
-To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings.
-
-## Scopes
-
-Currently Gitea does not support scopes (see [#4300](https://github.com/go-gitea/gitea/issues/4300)) and all third party applications will be granted access to all resources of the user and their organizations.
-
-## Client types
-
-Gitea supports both confidential and public client types, [as defined by RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1).
-
-For public clients, a redirect URI of a loopback IP address such as `http://127.0.0.1/` allows any port. Avoid using `localhost`, [as recommended by RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3).
-
-## Example
-
-**Note:** This example does not use PKCE.
-
-1. Redirect to user to the authorization endpoint in order to get their consent for accessing the resources:
-
- ```curl
- https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
- ```
-
- The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks.
-
- 
-
- The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example:
-
- ```curl
- https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
- ```
-
-2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
-
- ```curl
- POST https://[YOUR-GITEA-URL]/login/oauth/access_token
- ```
-
- ```json
- {
- "client_id": "YOUR_CLIENT_ID",
- "client_secret": "YOUR_CLIENT_SECRET",
- "code": "RETURNED_CODE",
- "grant_type": "authorization_code",
- "redirect_uri": "REDIRECT_URI"
- }
- ```
-
- Response:
-
- ```json
- {
- "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
- "token_type": "bearer",
- "expires_in": 3600,
- "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
- }
- ```
-
- The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings.
-
- The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request.
-
-3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources.
diff --git a/docs/content/doc/installation/from-source.en-us.md b/docs/content/doc/installation/from-source.en-us.md
index 660f996b1e..0be5673be4 100644
--- a/docs/content/doc/installation/from-source.en-us.md
+++ b/docs/content/doc/installation/from-source.en-us.md
@@ -87,7 +87,7 @@ To build from source, the following programs must be present on the system:
- `go` {{< min-go-version >}} or higher, see [here](https://golang.org/dl/)
- `node` {{< min-node-version >}} or higher with `npm`, see [here](https://nodejs.org/en/download/)
-- `make`, see <a href='{{< relref "doc/developers/hacking-on-gitea.en-us.md" >}}#installing-make'>here</a>
+- `make`, see [here]({{< relref "doc/developers/hacking-on-gitea.en-us.md" >}}#installing-make)
Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile)
are provided to keep the build process as simple as possible.
diff --git a/docs/content/doc/installation/from-source.fr-fr.md b/docs/content/doc/installation/from-source.fr-fr.md
index 00f67eab55..6ff4853a22 100644
--- a/docs/content/doc/installation/from-source.fr-fr.md
+++ b/docs/content/doc/installation/from-source.fr-fr.md
@@ -53,7 +53,7 @@ git checkout pr-xyz
## Compilation
-Comme nous regroupons déjà toutes les bibliothèques requises pour compiler Gitea, vous pouvez continuer avec le processus de compilation lui-même. Nous fournissons diverses [tâches Make](https://github.com/go-gitea/gitea/blob/master/Makefile) pour rendre le processus de construction aussi simple que possible. <a href='{{< relref "doc/advanced/make.fr-fr.md" >}}'>Voyez ici comment obtenir Make</a>. Selon vos besoins, vous pourrez éventuellement ajouter diverses options de compilation, vous pouvez choisir entre ces options :
+Comme nous regroupons déjà toutes les bibliothèques requises pour compiler Gitea, vous pouvez continuer avec le processus de compilation lui-même. Nous fournissons diverses [tâches Make](https://github.com/go-gitea/gitea/blob/master/Makefile) pour rendre le processus de construction aussi simple que possible. [Voyez ici comment obtenir Make]({{< relref "doc/developers/hacking-on-gitea.fr-fr.md" >}}#installing-make). Selon vos besoins, vous pourrez éventuellement ajouter diverses options de compilation, vous pouvez choisir entre ces options :
* `bindata`: Intègre toutes les ressources nécessaires à l'exécution d'une instance de Gitea, ce qui rend un déploiement facile car il n'est pas nécessaire de se préoccuper des fichiers supplémentaires.
* `sqlite sqlite_unlock_notify`: Active la prise en charge d'une base de données [SQLite3](https://sqlite.org/), ceci n'est recommandé que pour les petites installations de Gitea.
diff --git a/docs/content/doc/installation/from-source.zh-cn.md b/docs/content/doc/installation/from-source.zh-cn.md
index 008566e57d..659c992346 100644
--- a/docs/content/doc/installation/from-source.zh-cn.md
+++ b/docs/content/doc/installation/from-source.zh-cn.md
@@ -54,7 +54,7 @@ git checkout v{{< version >}}
- `go` {{< min-go-version >}} 或以上版本, 详见[这里](https://golang.google.cn/doc/install)
- `node` {{< min-node-version >}} 或以上版本，并且安装 `npm`, 详见[这里](https://nodejs.org/zh-cn/download/)
-- `make`, 详见[这里]({{< relref "make.zh-cn.md" >}})</a>
+- `make`, 详见[这里]({{< relref "doc/developers/hacking-on-gitea.zh-cn.md" >}})</a>
各种可用的 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)
可以用来使编译过程更方便。
diff --git a/docs/content/doc/installation/on-cloud-provider.en-us.md b/docs/content/doc/installation/on-cloud-provider.en-us.md
new file mode 100644
index 0000000000..7f5dc71905
--- /dev/null
+++ b/docs/content/doc/installation/on-cloud-provider.en-us.md
@@ -0,0 +1,56 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Install on Cloud Provider"
+slug: "install-on-cloud-provider"
+weight: 20
+toc: false
+draft: false
+menu:
+ sidebar:
+ parent: "installation"
+ name: "On cloud provider"
+ weight: 20
+ identifier: "install-on-cloud-provider"
+---
+
+# Installation on Cloud Provider
+
+**Table of Contents**
+
+{{< toc >}}
+
+## Cloudron
+
+Gitea is available as a 1-click install on [Cloudron](https://cloudron.io).
+Cloudron makes it easy to run apps like Gitea on your server and keep them up-to-date and secure.
+
+[](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
+
+The Gitea package is maintained [here](https://git.cloudron.io/cloudron/gitea-app).
+
+There is a [demo instance](https://my.demo.cloudron.io) (username: cloudron password: cloudron) where
+you can experiment with running Gitea.
+
+## Vultr
+
+Gitea can be found in [Vultr](https://www.vultr.com)'s marketplace.
+
+To deploy Gitea to Vultr, have a look at the [Vultr Marketplace](https://www.vultr.com/marketplace/apps/gitea).
+
+## DigitalOcean
+
+[DigitalOcean](https://www.digitalocean.com) has Gitea as droplet in their marketplace.
+
+To deploy Gitea to DigitalOcean, have a look at the [DigitalOcean Marketplace](https://marketplace.digitalocean.com/apps/gitea).
+
+## Linode
+
+[Linode](https://www.linode.com/) has Gitea as an app in their marketplace.
+
+To deploy Gitea to Linode, have a look at the [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
+
+## alwaysdata
+
+[alwaysdata](https://www.alwaysdata.com/) has Gitea as an app in their marketplace.
+
+To deploy Gitea to alwaysdata, have a look at the [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).
diff --git a/docs/content/doc/installation/on-cloud-provider.md b/docs/content/doc/installation/on-cloud-provider.md
deleted file mode 100644
index 7f5dc71905..0000000000
--- a/docs/content/doc/installation/on-cloud-provider.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-date: "2016-12-01T16:00:00+02:00"
-title: "Install on Cloud Provider"
-slug: "install-on-cloud-provider"
-weight: 20
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "installation"
- name: "On cloud provider"
- weight: 20
- identifier: "install-on-cloud-provider"
----
-
-# Installation on Cloud Provider
-
-**Table of Contents**
-
-{{< toc >}}
-
-## Cloudron
-
-Gitea is available as a 1-click install on [Cloudron](https://cloudron.io).
-Cloudron makes it easy to run apps like Gitea on your server and keep them up-to-date and secure.
-
-[](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
-
-The Gitea package is maintained [here](https://git.cloudron.io/cloudron/gitea-app).
-
-There is a [demo instance](https://my.demo.cloudron.io) (username: cloudron password: cloudron) where
-you can experiment with running Gitea.
-
-## Vultr
-
-Gitea can be found in [Vultr](https://www.vultr.com)'s marketplace.
-
-To deploy Gitea to Vultr, have a look at the [Vultr Marketplace](https://www.vultr.com/marketplace/apps/gitea).
-
-## DigitalOcean
-
-[DigitalOcean](https://www.digitalocean.com) has Gitea as droplet in their marketplace.
-
-To deploy Gitea to DigitalOcean, have a look at the [DigitalOcean Marketplace](https://marketplace.digitalocean.com/apps/gitea).
-
-## Linode
-
-[Linode](https://www.linode.com/) has Gitea as an app in their marketplace.
-
-To deploy Gitea to Linode, have a look at the [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
-
-## alwaysdata
-
-[alwaysdata](https://www.alwaysdata.com/) has Gitea as an app in their marketplace.
-
-To deploy Gitea to alwaysdata, have a look at the [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).
diff --git a/docs/content/doc/usage/git-lfs-support.en-us.md b/docs/content/doc/usage/git-lfs-support.en-us.md
new file mode 100644
index 0000000000..8b2c997bf9
--- /dev/null
+++ b/docs/content/doc/usage/git-lfs-support.en-us.md
@@ -0,0 +1,30 @@
+---
+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/git-lfs-support.md b/docs/content/doc/usage/git-lfs-support.md
deleted file mode 100644
index 8b2c997bf9..0000000000
--- a/docs/content/doc/usage/git-lfs-support.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
new file mode 100644
index 0000000000..7c9024743d
--- /dev/null
+++ b/docs/content/doc/usage/https-support.en-us.md
@@ -0,0 +1,102 @@
+---
+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/https-support.md b/docs/content/doc/usage/https-support.md
deleted file mode 100644
index 7c9024743d..0000000000
--- a/docs/content/doc/usage/https-support.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/template-repositories.en-us.md b/docs/content/doc/usage/template-repositories.en-us.md
new file mode 100644
index 0000000000..9a2a23ed2b
--- /dev/null
+++ b/docs/content/doc/usage/template-repositories.en-us.md
@@ -0,0 +1,85 @@
+---
+date: "2019-11-28:00:00+02:00"
+title: "Template Repositories"
+slug: "template-repositories"
+weight: 14
+toc: false
+draft: false
+menu:
+ sidebar:
+ parent: "usage"
+ name: "Template Repositories"
+ weight: 14
+ identifier: "template-repositories"
+---
+
+# Template Repositories
+
+**Table of Contents**
+
+{{< toc >}}
+
+Gitea `1.11.0` and above includes template repositories, and one feature implemented with them is auto-expansion of specific variables within your template files.
+
+To tell Gitea which files to expand, you must include a `template` file inside the `.gitea` directory of the template repository.
+
+Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It closely resembles a traditional `.gitignore`, however there may be slight differences.
+
+## Example `.gitea/template` file
+
+All paths are relative to the base of the repository
+
+```gitignore
+# All .go files, anywhere in the repository
+**.go
+
+# All text files in the text directory
+text/*.txt
+
+# A specific file
+a/b/c/d.json
+
+# Batch files in both upper or lower case can be matched
+**.[bB][aA][tT]
+```
+
+**NOTE:** The `template` file will be removed from the `.gitea` directory when a repository is generated from the template.
+
+## Variable Expansion
+
+In any file matched by the above globs, certain variables will be expanded.
+
+All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, use a double `$$`, such as `$$VAR` or `$${VAR}`
+
+| Variable | Expands To | Transformable |
+| -------------------- | --------------------------------------------------- | ------------- |
+| REPO_NAME | The name of the generated repository | ✓ |
+| TEMPLATE_NAME | The name of the template repository | ✓ |
+| REPO_DESCRIPTION | The description of the generated repository | ✘ |
+| TEMPLATE_DESCRIPTION | The description of the template repository | ✘ |
+| REPO_OWNER | The owner of the generated repository | ✓ |
+| TEMPLATE_OWNER | The owner of the template repository | ✓ |
+| REPO_LINK | The URL to the generated repository | ✘ |
+| TEMPLATE_LINK | The URL to the template repository | ✘ |
+| REPO_HTTPS_URL | The HTTP(S) clone link for the generated repository | ✘ |
+| TEMPLATE_HTTPS_URL | The HTTP(S) clone link for the template repository | ✘ |
+| REPO_SSH_URL | The SSH clone link for the generated repository | ✘ |
+| TEMPLATE_SSH_URL | The SSH clone link for the template repository | ✘ |
+
+## Transformers :robot:
+
+Gitea `1.12.0` adds a few transformers to some of the applicable variables above.
+
+For example, to get `REPO_NAME` in `PASCAL`-case, your template would use `${REPO_NAME_PASCAL}`
+
+Feeding `go-sdk` to the available transformers yields...
+
+| Transformer | Effect |
+| ----------- | ------ |
+| SNAKE | go_sdk |
+| KEBAB | go-sdk |
+| CAMEL | goSdk |
+| PASCAL | GoSdk |
+| LOWER | go-sdk |
+| UPPER | GO-SDK |
+| TITLE | Go-Sdk |
diff --git a/docs/content/doc/usage/template-repositories.md b/docs/content/doc/usage/template-repositories.md
deleted file mode 100644
index 9a2a23ed2b..0000000000
--- a/docs/content/doc/usage/template-repositories.md
+++ /dev/null
@@ -1,85 +0,0 @@
----
-date: "2019-11-28:00:00+02:00"
-title: "Template Repositories"
-slug: "template-repositories"
-weight: 14
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "usage"
- name: "Template Repositories"
- weight: 14
- identifier: "template-repositories"
----
-
-# Template Repositories
-
-**Table of Contents**
-
-{{< toc >}}
-
-Gitea `1.11.0` and above includes template repositories, and one feature implemented with them is auto-expansion of specific variables within your template files.
-
-To tell Gitea which files to expand, you must include a `template` file inside the `.gitea` directory of the template repository.
-
-Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It closely resembles a traditional `.gitignore`, however there may be slight differences.
-
-## Example `.gitea/template` file
-
-All paths are relative to the base of the repository
-
-```gitignore
-# All .go files, anywhere in the repository
-**.go
-
-# All text files in the text directory
-text/*.txt
-
-# A specific file
-a/b/c/d.json
-
-# Batch files in both upper or lower case can be matched
-**.[bB][aA][tT]
-```
-
-**NOTE:** The `template` file will be removed from the `.gitea` directory when a repository is generated from the template.
-
-## Variable Expansion
-
-In any file matched by the above globs, certain variables will be expanded.
-
-All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, use a double `$$`, such as `$$VAR` or `$${VAR}`
-
-| Variable | Expands To | Transformable |
-| -------------------- | --------------------------------------------------- | ------------- |
-| REPO_NAME | The name of the generated repository | ✓ |
-| TEMPLATE_NAME | The name of the template repository | ✓ |
-| REPO_DESCRIPTION | The description of the generated repository | ✘ |
-| TEMPLATE_DESCRIPTION | The description of the template repository | ✘ |
-| REPO_OWNER | The owner of the generated repository | ✓ |
-| TEMPLATE_OWNER | The owner of the template repository | ✓ |
-| REPO_LINK | The URL to the generated repository | ✘ |
-| TEMPLATE_LINK | The URL to the template repository | ✘ |
-| REPO_HTTPS_URL | The HTTP(S) clone link for the generated repository | ✘ |
-| TEMPLATE_HTTPS_URL | The HTTP(S) clone link for the template repository | ✘ |
-| REPO_SSH_URL | The SSH clone link for the generated repository | ✘ |
-| TEMPLATE_SSH_URL | The SSH clone link for the template repository | ✘ |
-
-## Transformers :robot:
-
-Gitea `1.12.0` adds a few transformers to some of the applicable variables above.
-
-For example, to get `REPO_NAME` in `PASCAL`-case, your template would use `${REPO_NAME_PASCAL}`
-
-Feeding `go-sdk` to the available transformers yields...
-
-| Transformer | Effect |
-| ----------- | ------ |
-| SNAKE | go_sdk |
-| KEBAB | go-sdk |
-| CAMEL | goSdk |
-| PASCAL | GoSdk |
-| LOWER | go-sdk |
-| UPPER | GO-SDK |
-| TITLE | Go-Sdk |
diff --git a/docs/static/_redirects b/docs/static/_redirects
index 676181b61f..39bd09f9ba 100644
--- a/docs/static/_redirects
+++ b/docs/static/_redirects
@@ -9,7 +9,10 @@ https://gitea-docs.netlify.com/* https://docs.gitea.io/:splat 302!
/en-us/ci-cd/ /en-us/integrations/ 302!
/en-us/third-party-tools/ /en-us/integrations/ 302!
+/zh-cn/third-party-tools/ /zh-cn/integrations/ 302!
/en-us/make/ /en-us/hacking-on-gitea/ 302!
+/zh-cn/make/ /zh-cn/hacking-on-gitea/ 302!
+/fr-fr/make/ /fr-fr/hacking-on-gitea/ 302!
/en-us/upgrade/ /en-us/upgrade-from-gitea/ 302!
/fr-fr/upgrade/ /fr-fr/upgrade-from-gitea/ 302!
/zh-cn/upgrade/ /zh-cn/upgrade-from-gitea/ 302!
--
cgit v1.2.3