Restructure documentation. Now the documentation has installation, ad…

…ministration, 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 <[email protected]>
go-gitea · Mar 23, 2023 · e8433b7 · e8433b7
1 parent df41181
commit e8433b7
Show file tree

Hide file tree

Showing 123 changed files with 261 additions and 346 deletions.
diff --git a/Makefile b/Makefile
@@ -77,6 +77,7 @@ ifeq ($(RACE_ENABLED),true)
 endif
 
 STORED_VERSION_FILE := VERSION
+HUGO_VERSION ?= 0.111.3
 
 ifneq ($(DRONE_TAG),)
 	VERSION ?= $(subst v,,$(DRONE_TAG))
@@ -817,7 +818,7 @@ release-docs: | $(DIST_DIRS) docs
 .PHONY: docs
 docs:
 	@hash hugo > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
-		curl -sL https://github.com/gohugoio/hugo/releases/download/v0.74.3/hugo_0.74.3_Linux-64bit.tar.gz | tar zxf - -C /tmp && mv /tmp/hugo /usr/bin/hugo && chmod +x /usr/bin/hugo; \
+		curl -sL https://github.com/gohugoio/hugo/releases/download/v$(HUGO_VERSION)/hugo_$(HUGO_VERSION)_Linux-64bit.tar.gz | tar zxf - -C /tmp && mv /tmp/hugo /usr/bin/hugo && chmod +x /usr/bin/hugo; \
 	fi
 	cd docs; make trans-copy clean build-offline;
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -2,7 +2,7 @@ THEME := themes/gitea
 PUBLIC := public
 ARCHIVE := https://dl.gitea.com/theme/main.tar.gz
 
-HUGO_PACKAGE := github.com/gohugoio/hugo@v0.82.0
+HUGO_PACKAGE := github.com/gohugoio/hugo@v0.111.3
 
 .PHONY: all
 all: build

diff --git a/docs/config.yaml b/docs/config.yaml
@@ -26,6 +26,11 @@ params:
   repo: "https://github.com/go-gitea/gitea"
   docContentPath: "docs/content"
 
+markup:
+  tableOfContents:
+    startLevel: 1
+    endLevel: 9
+
 outputs:
   home:
     - HTML

diff --git a/docs/content/doc/administration.en-us.md b/docs/content/doc/administration.en-us.md
@@ -0,0 +1,14 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Administration"
+slug: "administration"
+weight: 30
+toc: false
+draft: false
+menu:
+  sidebar:
+    name: "Administration"
+    weight: 20
+    collapse: true
+    identifier: "administration"
+---
diff --git a/docs/content/doc/advanced.fr-fr.md → docs/content/doc/administration.fr-fr.md b/docs/content/doc/advanced.fr-fr.md → docs/content/doc/administration.fr-fr.md
@@ -1,13 +1,13 @@
 ---
 date: "2017-08-23T09:00:00+02:00"
 title: "Avancé"
-slug: "advanced"
+slug: "administration"
 weight: 30
 toc: false
 draft: false
 menu:
   sidebar:
     name: "Avancé"
-    weight: 40
-    identifier: "advanced"
+    weight: 20
+    identifier: "administration"
 ---
diff --git a/docs/content/doc/administration.zh-cn.md b/docs/content/doc/administration.zh-cn.md
@@ -0,0 +1,13 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "运维"
+slug: "administration"
+weight: 30
+toc: false
+draft: false
+menu:
+  sidebar:
+    name: "运维"
+    weight: 20
+    identifier: "administration"
+---
diff --git a/docs/content/doc/administration.zh-tw.md b/docs/content/doc/administration.zh-tw.md
@@ -0,0 +1,13 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "運維"
+slug: "administration"
+weight: 30
+toc: false
+draft: false
+menu:
+  sidebar:
+    name: "運維"
+    weight: 20
+    identifier: "administration"
+---
diff --git a/.../doc/advanced/adding-legal-pages.en-us.md → ...dministration/adding-legal-pages.en-us.md b/.../doc/advanced/adding-legal-pages.en-us.md → ...dministration/adding-legal-pages.en-us.md
@@ -7,10 +7,10 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "Adding Legal Pages"
     identifier: "adding-legal-pages"
-    weight: 9
+    weight: 110
 ---
 
 Some jurisdictions (such as EU), requires certain legal pages (e.g. Privacy Policy) to be added to website. Follow these steps to add them to your Gitea instance.

diff --git a/...ent/doc/usage/backup-and-restore.en-us.md → ...dministration/backup-and-restore.en-us.md b/...ent/doc/usage/backup-and-restore.en-us.md → ...dministration/backup-and-restore.en-us.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "usage"
+    parent: "administration"
     name: "Backup and Restore"
     weight: 11
     identifier: "backup-and-restore"

diff --git a/...ent/doc/usage/backup-and-restore.zh-cn.md → ...dministration/backup-and-restore.zh-cn.md b/...ent/doc/usage/backup-and-restore.zh-cn.md → ...dministration/backup-and-restore.zh-cn.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "usage"
+    parent: "administration"
     name: "备份与恢复"
     weight: 11
     identifier: "backup-and-restore"

diff --git a/...ent/doc/usage/backup-and-restore.zh-tw.md → ...dministration/backup-and-restore.zh-tw.md b/...ent/doc/usage/backup-and-restore.zh-tw.md → ...dministration/backup-and-restore.zh-tw.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "usage"
+    parent: "administration"
     name: "備份與還原"
     weight: 11
     identifier: "backup-and-restore"

diff --git a/...ontent/doc/advanced/cmd-embedded.en-us.md → .../doc/administration/cmd-embedded.en-us.md b/...ontent/doc/advanced/cmd-embedded.en-us.md → .../doc/administration/cmd-embedded.en-us.md
@@ -7,9 +7,9 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "Embedded data extraction tool"
-    weight: 40
+    weight: 20
     identifier: "cmd-embedded"
 ---
 
@@ -21,7 +21,7 @@ menu:
 
 Gitea's executable contains all the resources required to run: templates, images, style-sheets
 and translations. Any of them can be overridden by placing a replacement in a matching path
-inside the `custom` directory (see [Customizing Gitea]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}})).
+inside the `custom` directory (see [Customizing Gitea]({{< relref "doc/administration/customizing-gitea.en-us.md" >}})).
 
 To obtain a copy of the embedded resources ready for editing, the `embedded` command from the CLI
 can be used from the OS shell interface.
@@ -85,7 +85,7 @@ The default is the current directory.
 The `--custom` flag tells Gitea to extract the files directly into the `custom` directory.
 For this to work, the command needs to know the location of the `app.ini` configuration
 file (`--config`) and, depending of the configuration, be ran from the directory where
-Gitea normally starts. See [Customizing Gitea]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}}) for details.
+Gitea normally starts. See [Customizing Gitea]({{< relref "doc/administration/customizing-gitea.en-us.md" >}}) for details.
 
 The `--overwrite` flag allows any existing files in the destination directory to be overwritten.
 

diff --git a/docs/content/doc/usage/command-line.en-us.md → .../doc/administration/command-line.en-us.md b/docs/content/doc/usage/command-line.en-us.md → .../doc/administration/command-line.en-us.md
@@ -7,9 +7,9 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "usage"
+    parent: "administration"
     name: "Command Line"
-    weight: 10
+    weight: 1
     identifier: "command-line"
 ---
 

diff --git a/.../doc/advanced/config-cheat-sheet.en-us.md → ...dministration/config-cheat-sheet.en-us.md b/.../doc/advanced/config-cheat-sheet.en-us.md → ...dministration/config-cheat-sheet.en-us.md
@@ -7,9 +7,9 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "Config Cheat Sheet"
-    weight: 20
+    weight: 30
     identifier: "config-cheat-sheet"
 ---
 
@@ -753,7 +753,7 @@ and
 - `FORCE_TRUST_SERVER_CERT`: **false**: If set to `true`, completely ignores server certificate validation errors. This option is unsafe. Consider adding the certificate to the system trust store instead.
 - `USER`: **\<empty\>**: Username of mailing user (usually the sender's e-mail address).
 - `PASSWD`: **\<empty\>**: Password of mailing user.  Use \`your password\` for quoting if you use special characters in the password.
-  - Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or SMTP host is localhost. See [Email Setup]({{< relref "doc/usage/email-setup.en-us.md" >}}) for more information.
+  - Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or SMTP host is localhost. See [Email Setup]({{< relref "doc/administration/email-setup.en-us.md" >}}) for more information.
 - `ENABLE_HELO`: **true**: Enable HELO operation.
 - `HELO_HOSTNAME`: **(retrieved from system)**: HELO hostname.
 - `FROM`: **\<empty\>**: Mail from address, RFC 5322. This can be just an email address, or the "Name" \<[email protected]\> format.

diff --git a/.../doc/advanced/config-cheat-sheet.zh-cn.md → ...dministration/config-cheat-sheet.zh-cn.md b/.../doc/advanced/config-cheat-sheet.zh-cn.md → ...dministration/config-cheat-sheet.zh-cn.md
@@ -7,9 +7,9 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "配置说明"
-    weight: 20
+    weight: 30
     identifier: "config-cheat-sheet"
 ---
 

diff --git a/...t/doc/advanced/customizing-gitea.en-us.md → ...administration/customizing-gitea.en-us.md b/...t/doc/advanced/customizing-gitea.en-us.md → ...administration/customizing-gitea.en-us.md
@@ -7,10 +7,10 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "Customizing Gitea"
     identifier: "customizing-gitea"
-    weight: 9
+    weight: 100
 ---
 
 # Customizing Gitea
@@ -84,7 +84,7 @@ directory at the top of this document).
 Every single page of Gitea can be changed. Dynamic content is generated using [go templates](https://golang.org/pkg/html/template/),
 which can be modified by placing replacements below the `$GITEA_CUSTOM/templates` directory.
 
-To obtain any embedded file (including templates), the [`gitea embedded` tool]({{< relref "doc/advanced/cmd-embedded.en-us.md" >}}) can be used. Alternatively, they can be found in the [`templates`](https://github.com/go-gitea/gitea/tree/main/templates) directory of Gitea source (Note: the example link is from the `main` branch. Make sure to use templates compatible with the release you are using).
+To obtain any embedded file (including templates), the [`gitea embedded` tool]({{< relref "doc/administration/cmd-embedded.en-us.md" >}}) can be used. Alternatively, they can be found in the [`templates`](https://github.com/go-gitea/gitea/tree/main/templates) directory of Gitea source (Note: the example link is from the `main` branch. Make sure to use templates compatible with the release you are using).
 
 Be aware that any statement contained inside `{{` and `}}` are Gitea's template syntax and
 shouldn't be touched without fully understanding these components.

diff --git a/...t/doc/advanced/customizing-gitea.zh-cn.md → ...administration/customizing-gitea.zh-cn.md b/...t/doc/advanced/customizing-gitea.zh-cn.md → ...administration/customizing-gitea.zh-cn.md
@@ -7,9 +7,9 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "自定义 Gitea 配置"
-    weight: 9
+    weight: 100
     identifier: "customizing-gitea"
 ---
 

diff --git a/docs/content/doc/usage/email-setup.en-us.md → ...t/doc/administration/email-setup.en-us.md b/docs/content/doc/usage/email-setup.en-us.md → ...t/doc/administration/email-setup.en-us.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "usage"
+    parent: "administration"
     name: "Email setup"
     weight: 12
     identifier: "email-setup"
@@ -58,7 +58,7 @@ 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" >}})
+For the full list of options check the [Config Cheat Sheet]({{< relref "doc/administration/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:
 

diff --git a/...c/advanced/environment-variables.en-us.md → ...nistration/environment-variables.en-us.md b/...c/advanced/environment-variables.en-us.md → ...nistration/environment-variables.en-us.md
@@ -7,9 +7,9 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "Environment variables"
-    weight: 20
+    weight: 10
     identifier: "environment-variables"
 ---
 

diff --git a/...c/advanced/environment-variables.zh-cn.md → ...nistration/environment-variables.zh-cn.md b/...c/advanced/environment-variables.zh-cn.md → ...nistration/environment-variables.zh-cn.md
@@ -7,9 +7,9 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "环境变量清单"
-    weight: 20
+    weight: 10
     identifier: "environment-variables"
 ---
 

diff --git a/.../doc/advanced/external-renderers.en-us.md → ...dministration/external-renderers.en-us.md b/.../doc/advanced/external-renderers.en-us.md → ...dministration/external-renderers.en-us.md
@@ -7,9 +7,9 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "External renderers"
-    weight: 40
+    weight: 60
     identifier: "external-renderers"
 ---
 

diff --git a/...content/doc/usage/fail2ban-setup.en-us.md → ...oc/administration/fail2ban-setup.en-us.md b/...content/doc/usage/fail2ban-setup.en-us.md → ...oc/administration/fail2ban-setup.en-us.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "usage"
+    parent: "administration"
     name: "Fail2ban setup"
     weight: 16
     identifier: "fail2ban-setup"

diff --git a/...content/doc/usage/fail2ban-setup.zh-cn.md → ...oc/administration/fail2ban-setup.zh-cn.md b/...content/doc/usage/fail2ban-setup.zh-cn.md → ...oc/administration/fail2ban-setup.zh-cn.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "usage"
+    parent: "administration"
     name: "设置 Fail2ban"
     weight: 16
     identifier: "fail2ban-setup"

diff --git a/...ontent/doc/usage/git-lfs-support.en-us.md → ...c/administration/git-lfs-support.en-us.md b/...ontent/doc/usage/git-lfs-support.en-us.md → ...c/administration/git-lfs-support.en-us.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "usage"
+    parent: "administration"
     name: "Git LFS setup"
     weight: 12
     identifier: "git-lfs-setup"

diff --git a/.../content/doc/usage/https-support.en-us.md → ...doc/administration/https-support.en-us.md b/.../content/doc/usage/https-support.en-us.md → ...doc/administration/https-support.en-us.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "usage"
+    parent: "administration"
     name: "HTTPS setup"
     weight: 12
     identifier: "https-setup"
@@ -24,7 +24,7 @@ menu:
 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" >}}).
+If you are using Apache or nginx on the server, it's recommended to check the [reverse proxy guide]({{< relref "doc/administration/reverse-proxies.en-us.md" >}}).
 
 To use Gitea's built-in HTTPS support, you must change your `app.ini` file:
 

diff --git a/...c/advanced/logging-documentation.en-us.md → ...nistration/logging-documentation.en-us.md b/...c/advanced/logging-documentation.en-us.md → ...nistration/logging-documentation.en-us.md
@@ -7,9 +7,9 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "Logging Configuration"
-    weight: 55
+    weight: 40
     identifier: "logging-configuration"
 ---
 

diff --git a/...tent/doc/advanced/mail-templates.en-us.md → ...oc/administration/mail-templates.en-us.md b/...tent/doc/advanced/mail-templates.en-us.md → ...oc/administration/mail-templates.en-us.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "Mail templates"
     weight: 45
     identifier: "mail-templates"

diff --git a/...ontent/doc/advanced/repo-indexer.en-us.md → .../doc/administration/repo-indexer.en-us.md b/...ontent/doc/advanced/repo-indexer.en-us.md → .../doc/administration/repo-indexer.en-us.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "advanced"
+    parent: "administration"
     name: "Repository indexer"
     weight: 45
     identifier: "repo-indexer"

diff --git a/...ontent/doc/usage/reverse-proxies.en-us.md → ...c/administration/reverse-proxies.en-us.md b/...ontent/doc/usage/reverse-proxies.en-us.md → ...c/administration/reverse-proxies.en-us.md
@@ -7,7 +7,7 @@ toc: false
 draft: false
 menu:
   sidebar:
-    parent: "usage"
+    parent: "administration"
     name: "Reverse Proxies"
     weight: 16
     identifier: "reverse-proxies"
@@ -48,7 +48,7 @@ server {
     server_name git.example.com;
 
     # Note: Trailing slash
-    location /git/ { 
+    location /git/ {
         # Note: Trailing slash
         proxy_pass http://localhost:3000/;
         proxy_set_header Host $host;