Feature: Help Documentation #4022

New Issue

GiteaMirror · 2025-11-02T05:34:35-06:00

GiteaMirror commented

2025-11-02 05:34:35 -06:00

Originally created by @bagasme on GitHub (Sep 27, 2019).

Description

For many users that use Gitea, it would be helpful if there is end-user Help documentation built into Gitea. This way, one can consult the usage documentation (Help in this case) before asking on the forum or opening an issue here.

However, as @lafriks noted on #6998, we couldn't directly adapt from GitHub Help due to copyright issues. Instead, we can use contents from Gitea Docs as starting point. In addition, the help documentation should contains end-user information, from Getting Started with Gitea to Managing Organizations and Using Git. Terms of Service should also be added to Help.

Regarding content license, we choose to use Creative Commons licenses. However, CC licenses have different variants, some of which are considered non-free by distributions (anything with ND or NC clause), so we left with two choices: CC-BY or CC-BY-SA. Feel free to discuss here about license option for the Help documentation. (Note: CC license links above only display human-readable summary, for full legalcode see here for CC-BY and here for CC-BY-SA)

The Help documentation should be built using static site generator (such as Jekyll or Hugo) and should be embedded into Gitea binary. When installing Gitea, one can choose to install Help documentation into subdomain (such as help.gitea.com) or into subdirectory (gitea.com/help).

Originally created by @bagasme on GitHub (Sep 27, 2019). ## Description For many users that use Gitea, it would be helpful if there is end-user _Help_ documentation built into Gitea. This way, one can consult the usage documentation (_Help_ in this case) before asking on the forum or opening an issue here. However, as @lafriks noted on #6998, we couldn't directly adapt from [GitHub Help](https://help.github.com) due to copyright issues. Instead, we can use contents from [Gitea Docs](https://docs.gitea.io) as starting point. In addition, the help documentation should contains end-user information, from `Getting Started with Gitea` to `Managing Organizations` and `Using Git`. `Terms of Service` should also be added to Help. Regarding content license, we choose to use [Creative Commons licenses](https://creativecommons.org/licenses). However, CC licenses have different variants, some of which are considered `non-free` by distributions (anything with ND or NC clause), so we left with two choices: [CC-BY](https://creativecommons.org/licenses/by/4.0) or [CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0). Feel free to discuss here about license option for the Help documentation. (_Note: CC license links above only display human-readable summary, for full legalcode see [here for CC-BY](https://creativecommons.org/licenses/by/4.0/legalcode) and [here for CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0/legalcode)_) The Help documentation should be built using static site generator (such as Jekyll or Hugo) and should be embedded into Gitea binary. When installing Gitea, one can choose to install Help documentation into subdomain (such as `help.gitea.com`) or into subdirectory (`gitea.com/help`).

GiteaMirror added the type/proposal label 2025-11-02 05:34:35 -06:00

GiteaMirror commented

2025-11-02 05:34:36 -06:00

@jamesorlakin commented on GitHub (Oct 12, 2019):

one can choose to install Help documentation into subdomain (such as help.gitea.com)

While a nice idea, I think this would increase complexity for most deployments of Gitea. Anybody using a reverse proxy with SSL will now have to do more configuration to ensure this additional subdomain has a valid certificate and is proxied with the host header intact. This is one of the reasons custom static sites isn't implemented.

Some help guides could be good, but I find Gitea intuitive enough as-is. Instead of extensive documentation (a-la death by PowerPoint) how about just some tooltips or interactive help to explain the behaviour of a function?

@jamesorlakin commented on GitHub (Oct 12, 2019): > one can choose to install Help documentation into subdomain (such as help.gitea.com) While a nice idea, I think this would increase complexity for most deployments of Gitea. Anybody using a reverse proxy with SSL will now have to do more configuration to ensure this additional subdomain has a valid certificate and is proxied with the host header intact. This is one of the reasons custom static sites isn't implemented. Some help guides could be good, but I find Gitea intuitive enough as-is. Instead of extensive documentation _(a-la death by PowerPoint)_ how about just some tooltips or interactive help to explain the behaviour of a function?

GiteaMirror commented

2025-11-02 05:34:36 -06:00

@bagasme commented on GitHub (Oct 13, 2019):

@jamesorlakin I think when site admins choose to install the documentation into subdomain, Gitea will provide reverse proxy configuration that can be added to each proxy's config file.

Did you mean tooltips/interactive help on web interface?

@bagasme commented on GitHub (Oct 13, 2019): @jamesorlakin I think when site admins choose to install the documentation into subdomain, Gitea will provide reverse proxy configuration that can be added to each proxy's config file. Did you mean tooltips/interactive help on web interface?

GiteaMirror referenced this issue

2025-11-02 12:29:18 -06:00

[PR #4022] [MERGED] Add documentation for reverse proxies #17201

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#4022