From bb25f85ce8f559fa3e9f462ad1027b5b5a8e2da3 Mon Sep 17 00:00:00 2001 From: John Olheiser Date: Thu, 27 Apr 2023 22:33:41 -0500 Subject: Refactor docs (#23752) This was intended to be a small followup for https://github.com/go-gitea/gitea/pull/23712, but...here we are. 1. Our docs currently use `slug` as the entire URL, which makes refactoring tricky (see https://github.com/go-gitea/gitea/pull/23712). Instead, this PR attempts to make future refactoring easier by using slugs as an extension of the section. (Hugo terminology) - What the above boils down to is this PR attempts to use directory organization as URL management. e.g. `usage/comparison.en-us.md` -> `en-us/usage/comparison/`, `usage/packages/overview.en-us.md` -> `en-us/usage/packages/overview/` - Technically we could even remove `slug`, as Hugo defaults to using filename, however at least with this PR it means `slug` only needs to be the name for the **current file** rather than an entire URL 2. This PR adds appropriate aliases (redirects) for pages, so anything on the internet that links to our docs should hopefully not break. 3. A minor nit I've had for a while, renaming `seek-help` to `support`. It's a minor thing, but `seek-help` has a strange connotation to it. 4. The commits are split such that you can review the first which is the "actual" change, and the second is added redirects so that the first doesn't break links elsewhere. --------- Signed-off-by: jolheiser --- docs/content/doc/help/_index.en-us.md | 0 docs/content/doc/help/_index.zh-cn.md | 0 docs/content/doc/help/_index.zh-tw.md | 0 docs/content/doc/help/faq.en-us.md | 6 ++- docs/content/doc/help/search.de-de.md | 18 --------- docs/content/doc/help/search.en-us.md | 18 --------- docs/content/doc/help/search.fr-fr.md | 18 --------- docs/content/doc/help/search.nl-nl.md | 18 --------- docs/content/doc/help/search.pt-br.md | 18 --------- docs/content/doc/help/search.zh-cn.md | 18 --------- docs/content/doc/help/search.zh-tw.md | 18 --------- docs/content/doc/help/seek-help.en-us.md | 67 ------------------------------- docs/content/doc/help/seek-help.zh-cn.md | 23 ----------- docs/content/doc/help/seek-help.zh-tw.md | 33 --------------- docs/content/doc/help/support.en-us.md | 69 ++++++++++++++++++++++++++++++++ docs/content/doc/help/support.zh-cn.md | 25 ++++++++++++ docs/content/doc/help/support.zh-tw.md | 35 ++++++++++++++++ 17 files changed, 133 insertions(+), 251 deletions(-) create mode 100644 docs/content/doc/help/_index.en-us.md create mode 100644 docs/content/doc/help/_index.zh-cn.md create mode 100644 docs/content/doc/help/_index.zh-tw.md delete mode 100644 docs/content/doc/help/search.de-de.md delete mode 100644 docs/content/doc/help/search.en-us.md delete mode 100644 docs/content/doc/help/search.fr-fr.md delete mode 100644 docs/content/doc/help/search.nl-nl.md delete mode 100644 docs/content/doc/help/search.pt-br.md delete mode 100644 docs/content/doc/help/search.zh-cn.md delete mode 100644 docs/content/doc/help/search.zh-tw.md delete mode 100644 docs/content/doc/help/seek-help.en-us.md delete mode 100644 docs/content/doc/help/seek-help.zh-cn.md delete mode 100644 docs/content/doc/help/seek-help.zh-tw.md create mode 100644 docs/content/doc/help/support.en-us.md create mode 100644 docs/content/doc/help/support.zh-cn.md create mode 100644 docs/content/doc/help/support.zh-tw.md (limited to 'docs/content/doc/help') diff --git a/docs/content/doc/help/_index.en-us.md b/docs/content/doc/help/_index.en-us.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/content/doc/help/_index.zh-cn.md b/docs/content/doc/help/_index.zh-cn.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/content/doc/help/_index.zh-tw.md b/docs/content/doc/help/_index.zh-tw.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 4847e8e03b..53215e18a5 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -5,6 +5,8 @@ slug: "faq" weight: 5 toc: false draft: false +aliases: + - /en-us/faq menu: sidebar: parent: "help" @@ -17,7 +19,7 @@ menu: This page contains some common questions and answers. -For more help resources, check all [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}). +For more help resources, check all [Support Options]({{< relref "doc/help/support.en-us.md" >}}). **Table of Contents** @@ -408,7 +410,7 @@ Stdout on systemd goes to the journal by default. Try using `journalctl`, `journ Similarly, stdout on docker can be viewed using `docker logs `. -To collect logs for help and issue report, see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}). +To collect logs for help and issue report, see [Support Options]({{< relref "doc/help/support.en-us.md" >}}). ## Initial logging diff --git a/docs/content/doc/help/search.de-de.md b/docs/content/doc/help/search.de-de.md deleted file mode 100644 index d22e9c1b2e..0000000000 --- a/docs/content/doc/help/search.de-de.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -date: "2019-11-12T16:00:00+02:00" -title: "Search" -slug: "search" -weight: 1 -toc: false -draft: false -sitemap: - priority : 1 -layout: "search" ---- - - -This file exists solely to respond to /search URL with the related `search` layout template. - -No content shown here is rendered, all content is based in the template layouts/doc/search.html - -Setting a very low sitemap priority will tell search engines this is not important content. diff --git a/docs/content/doc/help/search.en-us.md b/docs/content/doc/help/search.en-us.md deleted file mode 100644 index d22e9c1b2e..0000000000 --- a/docs/content/doc/help/search.en-us.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -date: "2019-11-12T16:00:00+02:00" -title: "Search" -slug: "search" -weight: 1 -toc: false -draft: false -sitemap: - priority : 1 -layout: "search" ---- - - -This file exists solely to respond to /search URL with the related `search` layout template. - -No content shown here is rendered, all content is based in the template layouts/doc/search.html - -Setting a very low sitemap priority will tell search engines this is not important content. diff --git a/docs/content/doc/help/search.fr-fr.md b/docs/content/doc/help/search.fr-fr.md deleted file mode 100644 index 421f7830b2..0000000000 --- a/docs/content/doc/help/search.fr-fr.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -date: "2019-11-12T16:00:00+02:00" -title: "Chercher" -slug: "search" -weight: 1 -toc: false -draft: false -sitemap: - priority : 1 -layout: "search" ---- - - -This file exists solely to respond to /search URL with the related `search` layout template. - -No content shown here is rendered, all content is based in the template layouts/doc/search.html - -Setting a very low sitemap priority will tell search engines this is not important content. diff --git a/docs/content/doc/help/search.nl-nl.md b/docs/content/doc/help/search.nl-nl.md deleted file mode 100644 index d22e9c1b2e..0000000000 --- a/docs/content/doc/help/search.nl-nl.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -date: "2019-11-12T16:00:00+02:00" -title: "Search" -slug: "search" -weight: 1 -toc: false -draft: false -sitemap: - priority : 1 -layout: "search" ---- - - -This file exists solely to respond to /search URL with the related `search` layout template. - -No content shown here is rendered, all content is based in the template layouts/doc/search.html - -Setting a very low sitemap priority will tell search engines this is not important content. diff --git a/docs/content/doc/help/search.pt-br.md b/docs/content/doc/help/search.pt-br.md deleted file mode 100644 index d22e9c1b2e..0000000000 --- a/docs/content/doc/help/search.pt-br.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -date: "2019-11-12T16:00:00+02:00" -title: "Search" -slug: "search" -weight: 1 -toc: false -draft: false -sitemap: - priority : 1 -layout: "search" ---- - - -This file exists solely to respond to /search URL with the related `search` layout template. - -No content shown here is rendered, all content is based in the template layouts/doc/search.html - -Setting a very low sitemap priority will tell search engines this is not important content. diff --git a/docs/content/doc/help/search.zh-cn.md b/docs/content/doc/help/search.zh-cn.md deleted file mode 100644 index 778df0d47d..0000000000 --- a/docs/content/doc/help/search.zh-cn.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -date: "2019-11-12T16:00:00+02:00" -title: "搜索" -slug: "search" -weight: 1 -toc: false -draft: false -sitemap: - priority : 1 -layout: "search" ---- - - -This file exists solely to respond to /search URL with the related `search` layout template. - -No content shown here is rendered, all content is based in the template layouts/doc/search.html - -Setting a very low sitemap priority will tell search engines this is not important content. diff --git a/docs/content/doc/help/search.zh-tw.md b/docs/content/doc/help/search.zh-tw.md deleted file mode 100644 index 8f2ce17ec6..0000000000 --- a/docs/content/doc/help/search.zh-tw.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -date: "2019-11-12T16:00:00+02:00" -title: "搜尋" -slug: "search" -weight: 1 -toc: false -draft: false -sitemap: - priority : 1 -layout: "search" ---- - - -This file exists solely to respond to /search URL with the related `search` layout template. - -No content shown here is rendered, all content is based in the template layouts/doc/search.html - -Setting a very low sitemap priority will tell search engines this is not important content. diff --git a/docs/content/doc/help/seek-help.en-us.md b/docs/content/doc/help/seek-help.en-us.md deleted file mode 100644 index 0e56b9a575..0000000000 --- a/docs/content/doc/help/seek-help.en-us.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -date: "2018-05-21T15:00:00+00:00" -title: "Support Options" -slug: "seek-help" -weight: 20 -toc: false -draft: false -menu: - sidebar: - parent: "help" - name: "Support Options" - weight: 20 - identifier: "seek-help" ---- - -# Support Options - -- [Discord](https://discord.gg/Gitea) -- [Discourse Forum](https://discourse.gitea.io/) - -**NOTE:** When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: - -1. Your `app.ini` (with any sensitive data scrubbed as necessary). -2. The Gitea logs, and any other appropriate log files for the situation. - - When using systemd, use `journalctl --lines 1000 --unit gitea` to collect logs. - - When using docker, use `docker logs --tail 1000 ` to collect logs. - - By default, the logs are outputted to console. If you need to collect logs from files, - you could copy the following config into your `app.ini` (remove all other `[log]` sections), - then you can find the `*.log` files in Gitea's log directory (default: `%(GITEA_WORK_DIR)/log`). - - ```ini - ; To show all SQL logs, you can also set LOG_SQL=true in the [database] section - [log] - LEVEL=debug - MODE=console,file - ROUTER=console,file - XORM=console,file - ENABLE_XORM_LOG=true - FILE_NAME=gitea.log - [log.file.router] - FILE_NAME=router.log - [log.file.xorm] - FILE_NAME=xorm.log - ``` - -3. Any error messages you are seeing. -4. When possible, try to replicate the issue on [try.gitea.io](https://try.gitea.io) and include steps so that others can reproduce the issue. - - This will greatly improve the chance that the root of the issue can be quickly discovered and resolved. -5. If you meet slow/hanging/deadlock problems, please report the stack trace when the problem occurs: - 1. Enable pprof in `app.ini` and restart Gitea - - ```ini - [server] - ENABLE_PPROF = true - ``` - - 2. Trigger the bug, when Gitea gets stuck, use curl or browser to visit: `http://127.0.0.1:6060/debug/pprof/goroutine?debug=1` (IP must be `127.0.0.1` and port must be `6060`). - 3. If you are using Docker, please use `docker exec -it curl "http://127.0.0.1:6060/debug/pprof/goroutine?debug=1"`. - 4. Report the output (the stack trace doesn't contain sensitive data) - -## Bugs - -If you found a bug, please create an [issue on GitHub](https://github.com/go-gitea/gitea/issues). - -## Chinese Support - -Support for the Chinese language is provided at [Our discourse](https://discourse.gitea.io/c/5-category/5) or QQ Group 328432459. diff --git a/docs/content/doc/help/seek-help.zh-cn.md b/docs/content/doc/help/seek-help.zh-cn.md deleted file mode 100644 index 80febad248..0000000000 --- a/docs/content/doc/help/seek-help.zh-cn.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -date: "2017-01-20T15:00:00+08:00" -title: "需要帮助" -slug: "seek-help" -weight: 20 -toc: false -draft: false -menu: - sidebar: - parent: "help" - name: "需要帮助" - weight: 20 - identifier: "seek-help" ---- - -## 需要帮助? - -如果您在使用或者开发过程中遇到问题，请到以下渠道咨询： - -- 到 [GitHub Issue](https://github.com/go-gitea/gitea/issues) 提问(因为项目维护人员来自世界各地，为保证沟通顺畅，请使用英文提问) -- 中文问题到 [Gitea 论坛](https://discourse.gitea.io/c/5-category/5) 提问 -- 访问 [Discord Gitea 聊天室 - 英文](https://discord.gg/Gitea) -- 加入 QQ群 328432459 获得进一步的支持 diff --git a/docs/content/doc/help/seek-help.zh-tw.md b/docs/content/doc/help/seek-help.zh-tw.md deleted file mode 100644 index f87dad547a..0000000000 --- a/docs/content/doc/help/seek-help.zh-tw.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -date: "2018-05-21T15:00:00+00:00" -title: "取得協助" -slug: "seek-help" -weight: 20 -toc: false -draft: false -menu: - sidebar: - parent: "help" - name: "取得協助" - weight: 20 - identifier: "seek-help" ---- - -# 取得協助 - -- [Discord 聊天室](https://discord.gg/Gitea) -- [Discourse 討論區](https://discourse.gitea.io/) - -**備註：** 尋求支援時，若能先備妥下列資訊將可讓提供協助的人能快速地分析您的問題： - -1. 您的 `app.ini` (必要時清除掉任何機密資訊) -2. `gitea.log` (以及任何有關的日誌檔案) - - 例：如果錯誤和資料庫相關，提供 `xorm.log` 可能會有幫助 -3. 您看到的任何錯誤訊息 -4. 儘可能地在 [try.gitea.io](https://try.gitea.io) 觸發您的問題並記下步驟，以便其他人能重現那個問題。 - - 這將讓我們更有機會快速地找出問題的根源並解決它。 -5. 堆棧跟踪，[請參考英文文檔](https://docs.gitea.io/en-us/seek-help/) - -## 錯誤回報 - -如果您發現錯誤，請到 [GitHub 的 Issue](https://github.com/go-gitea/gitea/issues) 回報。 diff --git a/docs/content/doc/help/support.en-us.md b/docs/content/doc/help/support.en-us.md new file mode 100644 index 0000000000..c6db3d6eb3 --- /dev/null +++ b/docs/content/doc/help/support.en-us.md @@ -0,0 +1,69 @@ +--- +date: "2018-05-21T15:00:00+00:00" +title: "Support Options" +slug: "support" +weight: 20 +toc: false +draft: false +aliases: + - /en-us/seek-help +menu: + sidebar: + parent: "help" + name: "Support Options" + weight: 20 + identifier: "support" +--- + +# Support Options + +- [Discord](https://discord.gg/Gitea) +- [Discourse Forum](https://discourse.gitea.io/) + +**NOTE:** When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: + +1. Your `app.ini` (with any sensitive data scrubbed as necessary). +2. The Gitea logs, and any other appropriate log files for the situation. + - When using systemd, use `journalctl --lines 1000 --unit gitea` to collect logs. + - When using docker, use `docker logs --tail 1000 ` to collect logs. + - By default, the logs are outputted to console. If you need to collect logs from files, + you could copy the following config into your `app.ini` (remove all other `[log]` sections), + then you can find the `*.log` files in Gitea's log directory (default: `%(GITEA_WORK_DIR)/log`). + + ```ini + ; To show all SQL logs, you can also set LOG_SQL=true in the [database] section + [log] + LEVEL=debug + MODE=console,file + ROUTER=console,file + XORM=console,file + ENABLE_XORM_LOG=true + FILE_NAME=gitea.log + [log.file.router] + FILE_NAME=router.log + [log.file.xorm] + FILE_NAME=xorm.log + ``` + +3. Any error messages you are seeing. +4. When possible, try to replicate the issue on [try.gitea.io](https://try.gitea.io) and include steps so that others can reproduce the issue. + - This will greatly improve the chance that the root of the issue can be quickly discovered and resolved. +5. If you meet slow/hanging/deadlock problems, please report the stack trace when the problem occurs: + 1. Enable pprof in `app.ini` and restart Gitea + + ```ini + [server] + ENABLE_PPROF = true + ``` + + 2. Trigger the bug, when Gitea gets stuck, use curl or browser to visit: `http://127.0.0.1:6060/debug/pprof/goroutine?debug=1` (IP must be `127.0.0.1` and port must be `6060`). + 3. If you are using Docker, please use `docker exec -it curl "http://127.0.0.1:6060/debug/pprof/goroutine?debug=1"`. + 4. Report the output (the stack trace doesn't contain sensitive data) + +## Bugs + +If you found a bug, please create an [issue on GitHub](https://github.com/go-gitea/gitea/issues). + +## Chinese Support + +Support for the Chinese language is provided at [Our discourse](https://discourse.gitea.io/c/5-category/5) or QQ Group 328432459. diff --git a/docs/content/doc/help/support.zh-cn.md b/docs/content/doc/help/support.zh-cn.md new file mode 100644 index 0000000000..775dfe83bd --- /dev/null +++ b/docs/content/doc/help/support.zh-cn.md @@ -0,0 +1,25 @@ +--- +date: "2017-01-20T15:00:00+08:00" +title: "需要帮助" +slug: "support" +weight: 20 +toc: false +draft: false +aliases: + - /zh-cn/seek-help +menu: + sidebar: + parent: "help" + name: "需要帮助" + weight: 20 + identifier: "support" +--- + +## 需要帮助? + +如果您在使用或者开发过程中遇到问题，请到以下渠道咨询： + +- 到 [GitHub Issue](https://github.com/go-gitea/gitea/issues) 提问(因为项目维护人员来自世界各地，为保证沟通顺畅，请使用英文提问) +- 中文问题到 [Gitea 论坛](https://discourse.gitea.io/c/5-category/5) 提问 +- 访问 [Discord Gitea 聊天室 - 英文](https://discord.gg/Gitea) +- 加入 QQ群 328432459 获得进一步的支持 diff --git a/docs/content/doc/help/support.zh-tw.md b/docs/content/doc/help/support.zh-tw.md new file mode 100644 index 0000000000..a9c35eaafb --- /dev/null +++ b/docs/content/doc/help/support.zh-tw.md @@ -0,0 +1,35 @@ +--- +date: "2018-05-21T15:00:00+00:00" +title: "取得協助" +slug: "support" +weight: 20 +toc: false +draft: false +aliases: + - /zh-tw/seek-help +menu: + sidebar: + parent: "help" + name: "取得協助" + weight: 20 + identifier: "support" +--- + +# 取得協助 + +- [Discord 聊天室](https://discord.gg/Gitea) +- [Discourse 討論區](https://discourse.gitea.io/) + +**備註：** 尋求支援時，若能先備妥下列資訊將可讓提供協助的人能快速地分析您的問題： + +1. 您的 `app.ini` (必要時清除掉任何機密資訊) +2. `gitea.log` (以及任何有關的日誌檔案) + - 例：如果錯誤和資料庫相關，提供 `xorm.log` 可能會有幫助 +3. 您看到的任何錯誤訊息 +4. 儘可能地在 [try.gitea.io](https://try.gitea.io) 觸發您的問題並記下步驟，以便其他人能重現那個問題。 + - 這將讓我們更有機會快速地找出問題的根源並解決它。 +5. 堆棧跟踪，[請參考英文文檔](https://docs.gitea.io/en-us/seek-help/) + +## 錯誤回報 + +如果您發現錯誤，請到 [GitHub 的 Issue](https://github.com/go-gitea/gitea/issues) 回報。 -- cgit v1.2.3