Documentation for Customization is Lacking - Requesting Significant Update #1832

New Issue

GiteaMirror · 2025-11-02T04:14:37-06:00

GiteaMirror commented

2025-11-02 04:14:37 -06:00

Originally created by @methodbox on GitHub (May 28, 2018).

Gitea version (or commit ref): 1.4.1
Git version: 2.3.4
Operating system: ubuntu 16
Database (use [x]):
- PostgreSQL
- MySQL
- MSSQL
- SQLite
Can you reproduce the bug at https://try.gitea.io:
- Yes (provide example URL)
- No
- Not relevant
Log gist:

Description

##Feature Request and Suggestions

The documentation is pretty bad for customizing the UI. It's easy enough to get Gitea running but really we are all looking for a solution that we can integrate into something else, rather than running another copy of the Gitea home page.

The documentation actually makes no mention of this but the templates are built in Vue JS. It would seem some reference as to how to use this along with the binary and build should e included in the documentation.

Additionally, allowing for simply JS and CSS overrides via the /custom/... directories would make this a hell of a lot easier.

It's also very unclear if using custom templates allows/requires copying in the template you're overriding or if this can be done by sideloading the custom template.

Considering forking this so that I can make my own "non-proprietary" version of Gitea since it doesn't seem to be targeted toward personalization at all, which is odd for an open source app.

Screenshots

Originally created by @methodbox on GitHub (May 28, 2018).  - Gitea version (or commit ref): 1.4.1 - Git version: 2.3.4 - Operating system: ubuntu 16 - Database (use `[x]`): - [ ] PostgreSQL - [x] MySQL - [ ] MSSQL - [ ] SQLite - Can you reproduce the bug at https://try.gitea.io: - [ ] Yes (provide example URL) - [ ] No - [x] Not relevant - Log gist: ## Description ##Feature Request and Suggestions The documentation is pretty bad for customizing the UI. It's easy enough to get Gitea running but really we are all looking for a solution that we can integrate into something else, rather than running another copy of the Gitea home page. The documentation actually makes no mention of this but the templates are built in Vue JS. It would seem some reference as to how to use this along with the binary and build should e included in the documentation. Additionally, allowing for simply JS and CSS overrides via the /custom/... directories would make this a hell of a lot easier. It's also very unclear if using custom templates allows/requires copying in the template you're overriding or if this can be done by sideloading the custom template. Considering forking this so that I can make my own "non-proprietary" version of Gitea since it doesn't seem to be targeted toward personalization at all, which is odd for an open source app. ## Screenshots

GiteaMirror closed this issue

2025-11-02 04:14:37 -06:00

GiteaMirror commented

2025-11-02 04:14:38 -06:00

@lunny commented on GitHub (May 29, 2018):

Did you read https://docs.gitea.io/en-us/customizing-gitea/ ?

@lunny commented on GitHub (May 29, 2018): Did you read https://docs.gitea.io/en-us/customizing-gitea/ ?

GiteaMirror commented

2025-11-02 04:14:38 -06:00

@methodbox commented on GitHub (May 29, 2018):

I did and the public files work fine. What doesn’t seem to work is anything to do with templates but the documentation is so vague about how to customize them I’m not sure if I’m even doing it correctly.

The documentation also mentions header and footer.tmpl and links to a source on GitHub for an example, yet doesn’t indicate how to completely override them, only append to them.

That doesn’t allow, for example, removing the Help link from the navigation.

It doesn’t allow me to apply global CSS, or if it does, it’s not documented as to how this would be done.

I can load a custom index page and then link to the rest of the app from there, but then I need to override the CSS on each of those templates.

Since Vue manages its CSS in both a global and local (by template) scope, it’s not clear how this is to be done.

The documentation doesn’t even mention this is Vue, I just know that from Wappalyer and familiarity with their template system.

Loading a file named header.tmpl in custom/templates, for example does not override the default header content as expected based on what I see in the source.

According to that documentation:

“Customizing Gitea pages

The custom/templates folder allows changing every single page of Gitea. Templates to override can be found in the templates directory of Gitea source. Override by making a copy of the file under custom/templates” ... but the templates/custom directory on your GitHub page is full of template files that are empty.

https://github.com/go-gitea/gitea/blob/master/templates/custom/header.tmpl

Copying another file into my custom/templates doesn’t override it.

Does it need to follow the same relative path as your GitHub layout?

I think the massive disconnect might be that your binary doesn’t layout the directories like your source so it’s very difficult to understand where to modify anything.

@methodbox commented on GitHub (May 29, 2018): I did and the public files work fine. What doesn’t seem to work is anything to do with templates but the documentation is so vague about how to customize them I’m not sure if I’m even doing it correctly. The documentation also mentions header and footer.tmpl and links to a source on GitHub for an example, yet doesn’t indicate how to completely override them, only append to them. That doesn’t allow, for example, removing the Help link from the navigation. It doesn’t allow me to apply global CSS, or if it does, it’s not documented as to how this would be done. I can load a custom index page and then link to the rest of the app from there, but then I need to override the CSS on each of those templates. Since Vue manages its CSS in both a global and local (by template) scope, it’s not clear how this is to be done. The documentation doesn’t even mention this is Vue, I just know that from Wappalyer and familiarity with their template system. Loading a file named header.tmpl in custom/templates, for example does not override the default header content as expected based on what I see in the source. According to that documentation: “Customizing Gitea pages The custom/templates folder allows changing every single page of Gitea. Templates to override can be found in the templates directory of Gitea source. Override by making a copy of the file under custom/templates” ... but the templates/custom directory on your GitHub page is full of template files that are empty. https://github.com/go-gitea/gitea/blob/master/templates/custom/header.tmpl Copying another file into my custom/templates doesn’t override it. Does it need to follow the same relative path as your GitHub layout? I think the massive disconnect might be that your binary doesn’t layout the directories like your source so it’s very difficult to understand where to modify anything.

GiteaMirror commented

2025-11-02 04:14:38 -06:00

@techknowlogick commented on GitHub (May 29, 2018):

The specific file you linked to (https://github.com/go-gitea/gitea/blob/master/templates/custom/header.tmpl) has the purpose of injecting content into the header without having to keep the other templates up to date, as what the projects template system does is if a file exists on disk then the binary uses it instead of the one it has saved (assuming you are using a binary that has the original binary files embedded). You could actually use that file to inject global CSS.

The files in the folder linked were actually made to make what you are trying to do easier.

I personally use header.tmpl in templates/custom to apply a dark theme to my Gitea install.

I've attached a file tree of my Gitea install with the contents of the "custom" directory (In standard installs the directory is likely called custom, but I have a non-standard install), note the templates directory location, and how it is at the same level as the conf directory (where app.ini is located).

The files in the templates directory are mostly golang html template files which contain some Vuejs components.

An example of removing the help tab in the menu, to accomplish this:

Copy the contents of templates/base/head.tmpl
Remove the following lines: 951309f76a/templates/base/head.tmpl (L234-L237)
Put that content into custom/templates/base/head.tmpl (in the screenshot above it would be gitea/templates/base/head.tmpl)
Restart the binary

Rather than forking the project an alternative is perhaps contribute back to this project.

@techknowlogick commented on GitHub (May 29, 2018): The specific file you linked to (https://github.com/go-gitea/gitea/blob/master/templates/custom/header.tmpl) has the purpose of injecting content into the header without having to keep the other templates up to date, as what the projects template system does is if a file exists on disk then the binary uses it instead of the one it has saved (assuming you are using a binary that has the original binary files embedded). You could actually use that file to inject global CSS. The files in the folder linked were actually made to make what you are trying to do easier. I personally use header.tmpl in templates/custom to apply a dark theme to my Gitea install. I've attached a file tree of my Gitea install with the contents of the "custom" directory (In standard installs the directory is likely called custom, but I have a non-standard install), note the templates directory location, and how it is at the same level as the conf directory (where app.ini is located). ![screen shot 2018-05-29 at 12 35 08 am](https://user-images.githubusercontent.com/164197/40638254-34c6e554-62d8-11e8-9f93-60a4a4839e8e.png) The files in the templates directory are mostly golang html template files which contain some Vuejs components. An example of removing the help tab in the menu, to accomplish this: 1. Copy the contents of `templates/base/head.tmpl` 2. Remove the following lines: https://github.com/go-gitea/gitea/blob/951309f76aab22e3742e8872bf0642fcea2570ae/templates/base/head.tmpl#L234-L237 3. Put that content into `custom/templates/base/head.tmpl` (in the screenshot above it would be `gitea/templates/base/head.tmpl`) 4. Restart the binary Rather than forking the project an alternative is perhaps contribute back to this project.

GiteaMirror commented

2025-11-02 04:14:38 -06:00

@methodbox commented on GitHub (May 29, 2018):

Thanks a lot! It would be great to see something like your explanation in the documentation, as well.

As far as contributing, I will definitely consider that but I don’t know Go beyond very entry level stuff.

I am quite solid with Vue and Javascript in general though.

What I was actually considering is maybe creating some kind of plugin using the API that would create a custom project directory and user templates as a boilerplate for customizations.

That’s just an stream of consciousness idea, so let me know what you think.

If there’s some way I could contribute that you’d suggest specifically I’d love to.

@methodbox commented on GitHub (May 29, 2018): Thanks a lot! It would be great to see something like your explanation in the documentation, as well. As far as contributing, I will definitely consider that but I don’t know Go beyond very entry level stuff. I am quite solid with Vue and Javascript in general though. What I was actually considering is maybe creating some kind of plugin using the API that would create a custom project directory and user templates as a boilerplate for customizations. That’s just an stream of consciousness idea, so let me know what you think. If there’s some way I could contribute that you’d suggest specifically I’d love to.

GiteaMirror commented

2025-11-02 04:14:38 -06:00

@techknowlogick commented on GitHub (May 29, 2018):

Everything I mentioned can be found in the link that @lunny commented above. If you'd like to add to the documentation or clarify any content the page you can submit a PR to is: https://github.com/go-gitea/gitea/blob/master/docs/content/doc/advanced/customizing-gitea.en-us.md

Here is the Contributors guide: https://github.com/go-gitea/gitea/blob/master/CONTRIBUTING.md

No knowledge of Golang is required to contribute to this project, there are many other ways, such as writing documentation, providing community support, etc..

I'm going to close this issue now, and direct you to the forum where you are able to ask more direct questions for support such as "How to remove the help tab from Navigation".

@techknowlogick commented on GitHub (May 29, 2018): Everything I mentioned can be found in the link that @lunny commented above. If you'd like to add to the documentation or clarify any content the page you can submit a PR to is: https://github.com/go-gitea/gitea/blob/master/docs/content/doc/advanced/customizing-gitea.en-us.md Here is the Contributors guide: https://github.com/go-gitea/gitea/blob/master/CONTRIBUTING.md No knowledge of Golang is required to contribute to this project, there are many other ways, such as writing documentation, providing community support, etc.. I'm going to close this issue now, and direct you to the [forum](https://discourse.gitea.io/) where you are able to ask more direct questions for support such as "How to remove the help tab from Navigation".

GiteaMirror commented

2025-11-02 04:14:38 -06:00

@methodbox commented on GitHub (May 30, 2018):

I know that link generally explains this but it does not specifically explain it, and as it is doing what you explained using the binary does not work.

I used exactly the same folder structure prior to opening this issue with header.tmpl, modified it (removed a link) and saw no change.

I even put a .tmpl file in there and tried putting giberish to see if I could even trigger an error and it didn’t work.

But I’m sorry, no the documentation does not include the level of detail of your post (like the folder tree, for example) and the binary does not build out that folder tree. It creates custom/conf/app.ini and that’s it.

If you don’t feel the documentation is lacking, fine. But I’m not sure it’s clear to you that people don’t necessarily know the structure of your app and this:

“The custom/templates folder allows changing every single page of Gitea”

Doesn’t seem to work as expected.

Also, your documentation says to use custom/templates.

In your tree, you clearly have templates/custom/header.

In your source it is the same as your example.

Which is it?

@methodbox commented on GitHub (May 30, 2018): I know that link generally explains this but it does not specifically explain it, and as it is doing what you explained using the binary does not work. I used exactly the same folder structure prior to opening this issue with header.tmpl, modified it (removed a link) and saw no change. I even put a .tmpl file in there and tried putting giberish to see if I could even trigger an error and it didn’t work. But I’m sorry, no the documentation does *not* include the level of detail of your post (like the folder tree, for example) and the binary does not build out that folder tree. It creates custom/conf/app.ini and that’s it. If you don’t feel the documentation is lacking, fine. But I’m not sure it’s clear to you that people don’t necessarily know the structure of your app and this: “The custom/templates folder allows changing every single page of Gitea” Doesn’t seem to work as expected. Also, your documentation says to use custom/templates. In your tree, you clearly have templates/custom/header. In your source it is the same as your example. Which is it?

GiteaMirror commented

2025-11-02 04:14:39 -06:00

@lafriks commented on GitHub (May 30, 2018):

Did you restart gitea after adding custom template file?

@lafriks commented on GitHub (May 30, 2018): Did you restart gitea after adding custom template file?

GiteaMirror commented

2025-11-02 04:14:39 -06:00

@sapk commented on GitHub (May 30, 2018):

You are misled by the two custom term.

templates/custom/header.tmpl is a empty file that can be overridden by custom/templates/custom/header.tmpl. Those specifics files are there to be load/overridden without modifying the template and don't break across update/modification. For details, those files are imported here https://github.com/go-gitea/gitea/blob/master/templates/base/head.tmpl#L130

But you can also completely rewrite the template like templates/home.tmpl under custom/templates/home.tmpl and be able to edit the home page.

Please read carefully the documentation and full of help comments of nice contributors and user of gitea that take time to write them.
Please like allready said before go to "the forum where you are able to ask more direct questions for support"
And feel free to contribute to the project by any means like contributing to the docs if you feel it is not clear.

@sapk commented on GitHub (May 30, 2018): You are misled by the two `custom` term. `templates/custom/header.tmpl` is a empty file that can be overridden by `custom/templates/custom/header.tmpl`. Those specifics files are there to be load/overridden without modifying the template and don't break across update/modification. For details, those files are imported here https://github.com/go-gitea/gitea/blob/master/templates/base/head.tmpl#L130 But you can also completely rewrite the template like `templates/home.tmpl` under `custom/templates/home.tmpl` and be able to edit the home page. Please read carefully the documentation and full of help comments of nice contributors and user of gitea that take time to write them. Please like allready said before go to "the forum where you are able to ask more direct questions for support" And feel free to contribute to the project by any means like contributing to the docs if you feel it is not clear.

GiteaMirror referenced this issue

2025-11-02 12:01:40 -06:00

[PR #1832] [MERGED] Fix pull request compare link #16072

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#1832