d12a9fee60
Preview: https://forgejo.codeberg.page/@docs_pull_427/docs/next/admin/customization/ --- The previous version of this document insinuated that you need to be familiar with Forgejo's source code and compile Forgejo from source for custom branding changes. As of the most recent Forgejo version, this is not necessarily true, as custom files can be served from the CustomPath. Administrators that were not developers therefore dismissed the other guide and its contents without reading this, and I was one of them. I thought it would make sense for this file to provide information on where to put a custom logo. This change does not fix it (this will be done later), but it will reduce the confusion for now. This warning confused me personally and other Forgejo users, as I had one person tell me IRL that they thought that it was not possible to serve a custom logo. Reviewed-on: https://codeberg.org/forgejo/docs/pulls/427 Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org> Co-authored-by: Panagiotis "Ivory" Vasilopoulos <git@n0toose.net> Co-committed-by: Panagiotis "Ivory" Vasilopoulos <git@n0toose.net>
2 KiB
| title | license |
|---|---|
| Interface customization | CC-BY-SA-4.0 |
Forgejo currently has limited capabilities for customizing the user interface.
Configurations and UI settings
Some settings are provided to customize the look and feel of the Forgejo user interface.
This includes the default theme, the name of your Forgejo instance, as well as the description that appears in Forgejo's homepage. A complete list of those settings can be found in the config cheat sheet:
- In the UI section and below.
- The
APP_NAMEsetting in the Overall section
They are documented and supported to be backward compatible between versions.
Serving custom resources, logos and pages
A word of warning (Here be dragons!)
Setting a custom logo for your instance, serving custom public files or modifying pages shown by Forgejo (such as the homepage) is possible. However, they impose an additional maintenance burden on administrators and, most importantly, are unsupported.
Unsupported means that future updates are likely to break your changes without any warning.
Templates
The most dangerous types of modifications are the ones concerning template files (.tmpl) served by Forgejo, as Forgejo issues backward incompatible updates to its templates very regularly.
Before deploying your changes to production or upgrading a modified Forgejo instance, we urge that you test your custom modifications in a testing environment first.
Instructions
For the reasons mentioned above, the instructions on performing such tasks can be found in the developer section on interface customization.
At this stage, it is also worth mentioning that it is possible to customize Forgejo by modifying its source code and compiling the changes, or by extracting and modifying the files of your choice using the command forgejo embedded extract. However, these methods are, for the same reasons as mentioned above, also unsupported.