foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-20 17:26:56 -05:00
Code Issues Activity

admin/customization: No need to be a developer for custom branding (#427)

Browse source 
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>
This commit is contained in:
Panagiotis "Ivory" Vasilopoulos 2024-02-18 17:22:54 +00:00 committed by Earl Warren
parent 29d9296d14
commit d12a9fee60
2 changed files with 28 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
docs/admin/customization.md
View file

@ -5,13 +5,33 @@ license: 'CC-BY-SA-4.0'
Forgejo currently has limited capabilities for customizing the user interface.
Some settings are provided to customize the look and feel of the Forgejo user interface, such as the default theme or the description that shows on the home page. See a complete list of those settings in the config cheat sheet:
## 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](../config-cheat-sheet/#ui-ui) and below.
- The `APP_NAME` setting in the [Overall section](../config-cheat-sheet/#overall-default)
They are documented and supported to be backward compatible between versions.
It is also possible to customize Forgejo by recompiling from the sources and changing the files. Or by extracting and modifying the relevant files with the `forgejo embedded extract` CLI. In both cases an intimate knowledge of the underlying codebase is necessary to figure out what files should be modified to achieve the desired result. They are considered an internal detail: non backward compatible changes will be introduced without warning in the release notes and they will not be documented.
## Serving custom resources, logos and pages
See also the [developer section on interface customization](../../developer/customization/) for more information.
### 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](../../developer/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](../../developer/from-source), 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**.

6
docs/developer/customization.md
View file

@ -64,7 +64,11 @@ which can be modified by placing replacements below the `$FORGEJO_CUSTOM/templat
To obtain any embedded file (including templates), the `forgejo embedded` CLI can be used. Alternatively, they can be found in the [`templates`](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/templates) directory of Forgejo source.
Be aware that any statement contained inside `{{` and `}}` are Forgejo's template syntax and
shouldn't be touched without fully understanding these components.
should **not** be touched without fully understanding these components.
Forgejo regularly makes backward incompatible changes to its own templates, which makes templates **very likely to break when upgrading Forgejo**.
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.
### Customizing startpage / homepage