From 1162b39d1e736f1a1407230056039921427810b4 Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Wed, 15 Nov 2023 21:23:43 +0000 Subject: [PATCH] {admin,developer}/customization: add user interface customization (#244) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewed-on: https://codeberg.org/forgejo/docs/pulls/244 Reviewed-by: Loïc Dachary Co-authored-by: Earl Warren Co-committed-by: Earl Warren (cherry picked from commit 9b2b4fc4f4a4a518cb865cb86cdefe28c60d726d) --- docs/admin/customization.md | 17 +++ docs/admin/index.md | 1 + docs/developer/customization.md | 180 ++++++++++++++++++++++++++++++++ docs/developer/index.md | 1 + 4 files changed, 199 insertions(+) create mode 100644 docs/admin/customization.md create mode 100644 docs/developer/customization.md diff --git a/docs/admin/customization.md b/docs/admin/customization.md new file mode 100644 index 00000000..e928fb38 --- /dev/null +++ b/docs/admin/customization.md @@ -0,0 +1,17 @@ +--- +title: 'Interface customization' +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: + +- 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. + +See also the [developer section on interface customization](../../developer/customization/) for more information. diff --git a/docs/admin/index.md b/docs/admin/index.md index 3e3158a3..4e129fe4 100644 --- a/docs/admin/index.md +++ b/docs/admin/index.md @@ -24,3 +24,4 @@ These documents are targeted to people who run Forgejo on their machines. - [GPG Commit Signatures](./signing/) - [Moderation tools](./moderation/) - [Adopt existing git directories](./adopt/) +- [Interface customization](./customization/) diff --git a/docs/developer/customization.md b/docs/developer/customization.md new file mode 100644 index 00000000..c0c16eb2 --- /dev/null +++ b/docs/developer/customization.md @@ -0,0 +1,180 @@ +--- +title: 'Interface customization' +license: 'Apache-2.0' +origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/administration/customizing-gitea.en-us.md' +--- + +This sections documents the Forgejo interface customization that requires an intimate knowledge of the underlying codebase. The user interface customization documented and supported for Forgejo admins to use [is found in the corresponding administrator guide section](../../admin/customization/). + +Customizing Forgejo is typically done using the `CustomPath` folder - by default this is +the `custom` folder from the working directory (WorkPath), but may be different if your build has +set this differently. This is the central place to override configuration settings, +templates, etc. You can check the `CustomPath` using `forgejo help`. You can also find +the path on the _Configuration_ tab in the _Site Administration_ page. You can override +the `CustomPath` by setting either the `FORGEJO_CUSTOM` environment variable or by +using the `--custom-path` option on the `forgejo` binary. (The option will override the +environment variable.) + +If Forgejo is deployed from binary, all default paths will be relative to the Forgejo +binary. + +Application settings can be found in file `CustomConf` which is by default, +`$FORGEJO_CUSTOM/conf/app.ini` but may be different if your build has set this differently. +Again `forgejo help` will allow you review this variable and you can override it using the +`--config` option on the `forgejo` binary. + +**Note:** Forgejo must perform a full restart to see configuration changes. + +## Serving custom public files + +To make Forgejo serve custom public files (like pages and images), use the folder +`$FORGEJO_CUSTOM/public/` as the webroot. Symbolic links will be followed. +At the moment, only the following files are served: + +- `public/robots.txt` +- files in the `public/.well-known/` folder +- files in the `public/assets/` folder + +For example, a file `image.png` stored in `$FORGEJO_CUSTOM/public/assets/`, can be accessed with +the url `http://forgejo.domain.tld/assets/image.png`. + +## Changing the logo + +To build a custom logo and/or favicon clone the Forgejo source repository, replace `assets/logo.svg` and/or `assets/favicon.svg` and run +`make generate-images`. `assets/favicon.svg` is used for the favicon only. This will update below output files which you can then place in `$FORGEJO_CUSTOM/public/assets/img` on your server: + +- `public/assets/img/logo.svg` - Used for site icon, app icon +- `public/assets/img/logo.png` - Used for Open Graph +- `public/assets/img/avatar_default.png` - Used as the default avatar image +- `public/assets/img/apple-touch-icon.png` - Used on iOS devices for bookmarks +- `public/assets/img/favicon.svg` - Used for favicon +- `public/assets/img/favicon.png` - Used as fallback for browsers that don't support SVG favicons + +## Customizing Forgejo pages and resources + +Forgejo's executable contains all the resources required to run: templates, images, style-sheets +and translations. Any of them can be overridden by placing a replacement in a matching path +inside the `custom` directory. For example, to replace the default `.gitignore` provided +for C++ repositories, we want to replace `options/gitignore/C++`. To do this, a replacement +must be placed in `$FORGEJO_CUSTOM/options/gitignore/C++`. + +Every single page of Forgejo can be changed. Dynamic content is generated using [go templates](https://pkg.go.dev/html/template), +which can be modified by placing replacements below the `$FORGEJO_CUSTOM/templates` directory. + +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. + +### Customizing startpage / homepage + +Copy [`home.tmpl`](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/templates/home.tmpl) for your version of Forgejo from `templates` to `$FORGEJO_CUSTOM/templates`. +Edit as you wish. +Dont forget to restart your Forgejo to apply the changes. + +### Adding links and tabs + +If all you want is to add extra links to the top navigation bar or footer, or extra tabs to the repository view, you can put them in `extra_links.tmpl` (links added to the navbar), `extra_links_footer.tmpl` (links added to the left side of footer), and `extra_tabs.tmpl` inside your `$FORGEJO_CUSTOM/templates/custom/` directory. + +For instance, let's say you are in Germany and must add the famously legally-required "Impressum"/about page, listing who is responsible for the site's content: +just place it under your "$FORGEJO_CUSTOM/public/assets/" directory (for instance `$FORGEJO_CUSTOM/public/assets/impressum.html`) and put a link to it in either `$FORGEJO_CUSTOM/templates/custom/extra_links.tmpl` or `$FORGEJO_CUSTOM/templates/custom/extra_links_footer.tmpl`. + +To match the current style, the link should have the class name "item", and you can use `{{AppSubUrl}}` to get the base URL: +`Impressum` + +You can add new tabs in the same way, putting them in `extra_tabs.tmpl`. +The exact HTML needed to match the style of other tabs is in the file +[`templates/repo/header.tmpl`](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/templates/repo/header.tmpl). + +### Other additions to the page + +Apart from `extra_links.tmpl` and `extra_tabs.tmpl`, there are other useful templates you can put in your `$FORGEJO_CUSTOM/templates/custom/` directory: + +- `header.tmpl`, just before the end of the `` tag where you can add custom CSS files for instance. +- `body_outer_pre.tmpl`, right after the start of ``. +- `body_inner_pre.tmpl`, before the top navigation bar, but already inside the main container `
`. +- `body_inner_post.tmpl`, before the end of the main container. +- `body_outer_post.tmpl`, before the bottom `