2017-11-26 16:44:32 -05:00
---
date: "2017-04-15T14:56:00+02:00"
title: "Customizing Gitea"
slug: "customizing-gitea"
weight: 9
toc: false
draft: false
menu:
sidebar:
parent: "advanced"
name: "Customizing Gitea"
identifier: "customizing-gitea"
2020-01-14 08:34:40 -05:00
weight: 9
2017-11-26 16:44:32 -05:00
---
# Customizing Gitea
2019-04-29 13:08:21 -05:00
Customizing Gitea is typically done using the `CustomPath` folder - by default this is
the `custom` folder from the running directory, but may be different if your build has
set this differently. This is the central place to override configuration settings,
2020-01-20 18:34:23 -05:00
templates, etc. You can check the `CustomPath` using `gitea help` . You can also find
the path on the _Configuration_ tab in the _Site Administration_ page. You can override
2019-04-29 13:08:21 -05:00
the `CustomPath` by setting either the `GITEA_CUSTOM` environment variable or by
using the `--custom-path` option on the `gitea` binary. (The option will override the
environment variable.)
2017-11-26 16:44:32 -05:00
2019-03-09 16:15:45 -05:00
If Gitea is deployed from binary, all default paths will be relative to the Gitea
2018-01-08 17:48:42 -05:00
binary. If installed from a distribution, these paths will likely be modified to
2019-04-29 13:08:21 -05:00
the Linux Filesystem Standard. Gitea will attempt to create required folders, including
`custom/` . Distributions may provide a symlink for `custom` using `/etc/gitea/` .
Application settings can be found in file `CustomConf` which is by default,
2021-01-19 10:50:55 -05:00
`$GITEA_CUSTOM/conf/app.ini` but may be different if your build has set this differently.
2019-04-29 13:08:21 -05:00
Again `gitea help` will allow you review this variable and you can override it using the
`--config` option on the `gitea` binary.
2017-11-26 16:44:32 -05:00
2018-01-08 17:48:42 -05:00
- [Quick Cheat Sheet ](https://docs.gitea.io/en-us/config-cheat-sheet/ )
2021-05-04 11:16:23 -05:00
- [Complete List ](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini )
2017-11-26 16:44:32 -05:00
2019-04-29 13:08:21 -05:00
If the `CustomPath` folder can't be found despite checking `gitea help` , check the `GITEA_CUSTOM`
2018-01-08 17:48:42 -05:00
environment variable; this can be used to override the default path to something else.
2021-01-19 10:50:55 -05:00
`GITEA_CUSTOM` might, for example, be set by an init script. You can check whether the value
is set under the "Configuration" tab on the site administration page.
2018-01-08 17:48:42 -05:00
2021-04-19 10:47:49 -05:00
- [List of Environment Variables ](https://docs.gitea.io/en-us/environment-variables/ )
2018-01-08 17:48:42 -05:00
**Note:** Gitea must perform a full restart to see configuration changes.
2017-11-26 16:44:32 -05:00
2020-12-09 01:47:06 -05:00
**Table of Contents**
2020-12-07 23:52:26 -05:00
{{< toc > }}
2017-11-26 16:44:32 -05:00
## Serving custom public files
2018-01-08 17:48:42 -05:00
To make Gitea serve custom public files (like pages and images), use the folder
2021-01-19 10:50:55 -05:00
`$GITEA_CUSTOM/public/` as the webroot. Symbolic links will be followed.
2017-11-26 16:44:32 -05:00
2021-01-19 10:50:55 -05:00
For example, a file `image.png` stored in `$GITEA_CUSTOM/public/` , can be accessed with
2021-07-04 08:56:40 -05:00
the url `http://gitea.domain.tld/assets/image.png` .
2017-11-26 16:44:32 -05:00
2021-05-07 01:32:29 -05:00
## Changing the logo
2020-12-18 20:17:27 -05:00
2022-05-23 10:54:48 -05:00
To build a custom logo and/or favicon clone the Gitea 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 `$GITEA_CUSTOM/public/img` on your server:
2021-01-01 14:04:35 -05:00
2022-05-23 10:54:48 -05:00
- `public/img/logo.svg` - Used for site icon, app icon
2021-05-07 01:32:29 -05:00
- `public/img/logo.png` - Used for Open Graph
- `public/img/avatar_default.png` - Used as the default avatar image
- `public/img/apple-touch-icon.png` - Used on iOS devices for bookmarks
2022-05-23 10:54:48 -05:00
- `public/img/favicon.svg` - Used for favicon
- `public/img/favicon.png` - Used as fallback for browsers that don't support SVG favicons
2020-12-18 20:17:27 -05:00
2021-05-07 01:32:29 -05:00
In case the source image is not in vector format, you can attempt to convert a raster image using tools like [this ](https://www.aconvert.com/image/png-to-svg/ ).
2017-11-26 16:44:32 -05:00
2020-02-01 21:17:44 -05:00
## Customizing Gitea pages and resources
2017-11-26 16:44:32 -05:00
2020-02-01 21:17:44 -05:00
Gitea'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
2021-01-19 10:50:55 -05:00
must be placed in `$GITEA_CUSTOM/options/gitignore/C++` (see about the location of the `CustomPath`
2020-02-01 21:17:44 -05:00
directory at the top of this document).
2017-11-26 16:44:32 -05:00
2020-02-01 21:17:44 -05:00
Every single page of Gitea can be changed. Dynamic content is generated using [go templates ](https://golang.org/pkg/html/template/ ),
2021-01-19 10:50:55 -05:00
which can be modified by placing replacements below the `$GITEA_CUSTOM/templates` directory.
2020-02-01 21:17:44 -05:00
2021-05-04 11:16:23 -05:00
To obtain any embedded file (including templates), the [`gitea embedded` tool ]({{< relref "doc/advanced/cmd-embedded.en-us.md" >}} ) can be used. Alternatively, they can be found in the [`templates` ](https://github.com/go-gitea/gitea/tree/main/templates ) directory of Gitea source (Note: the example link is from the `main` branch. Make sure to use templates compatible with the release you are using).
2020-02-01 21:17:44 -05:00
Be aware that any statement contained inside `{{` and `}}` are Gitea's template syntax and
2018-01-08 17:48:42 -05:00
shouldn't be touched without fully understanding these components.
2017-11-26 16:44:32 -05:00
2019-10-28 14:11:02 -05:00
### Customizing startpage / homepage
2021-05-04 11:16:23 -05:00
Copy [`home.tmpl` ](https://github.com/go-gitea/gitea/blob/main/templates/home.tmpl ) for your version of Gitea from `templates` to `$GITEA_CUSTOM/templates` .
2019-10-28 14:11:02 -05:00
Edit as you wish.
2021-11-28 08:28:30 -05:00
Dont forget to restart your Gitea to apply the changes.
2019-10-28 14:11:02 -05:00
2018-01-11 14:56:40 -05:00
### Adding links and tabs
2017-12-02 19:26:06 -05:00
2021-01-19 10:50:55 -05:00
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 `$GITEA_CUSTOM/templates/custom/` directory.
2018-01-10 01:19:50 -05:00
2018-01-11 14:56:40 -05:00
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:
2021-01-19 10:50:55 -05:00
just place it under your "$GITEA_CUSTOM/public/" directory (for instance `$GITEA_CUSTOM/public/impressum.html` ) and put a link to it in either `$GITEA_CUSTOM/templates/custom/extra_links.tmpl` or `$GITEA_CUSTOM/templates/custom/extra_links_footer.tmpl` .
2018-01-11 14:56:40 -05:00
To match the current style, the link should have the class name "item", and you can use `{{AppSubUrl}}` to get the base URL:
2021-07-15 14:49:12 -05:00
`<a class="item" href="{{AppSubUrl}}/assets/impressum.html">Impressum</a>`
2018-01-11 14:56:40 -05:00
2020-01-14 08:34:40 -05:00
For more information, see [Adding Legal Pages ](https://docs.gitea.io/en-us/adding-legal-pages ).
2018-01-11 14:56:40 -05:00
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`
2021-05-04 11:16:23 -05:00
([source in GitHub](https://github.com/go-gitea/gitea/blob/main/templates/repo/header.tmpl))
2018-01-11 14:56:40 -05:00
### Other additions to the page
2021-01-19 10:50:55 -05:00
Apart from `extra_links.tmpl` and `extra_tabs.tmpl` , there are other useful templates you can put in your `$GITEA_CUSTOM/templates/custom/` directory:
2018-01-11 14:56:40 -05:00
- `header.tmpl` , just before the end of the `<head>` tag where you can add custom CSS files for instance.
- `body_outer_pre.tmpl` , right after the start of `<body>` .
- `body_inner_pre.tmpl` , before the top navigation bar, but already inside the main container `<div class="full height">` .
- `body_inner_post.tmpl` , before the end of the main container.
- `body_outer_post.tmpl` , before the bottom `<footer>` element.
- `footer.tmpl` , right before the end of the `<body>` tag, a good place for additional Javascript.
2020-01-20 18:34:23 -05:00
#### Example: PlantUML
You can add [PlantUML ](https://plantuml.com/ ) support to Gitea's markdown by using a PlantUML server.
2020-04-06 18:43:17 -05:00
The data is encoded and sent to the PlantUML server which generates the picture. There is an online
demo server at http://www.plantuml.com/plantuml, but if you (or your users) have sensitive data you
2020-01-20 18:34:23 -05:00
can set up your own [PlantUML server ](https://plantuml.com/server ) instead. To set up PlantUML rendering,
copy javascript files from https://gitea.com/davidsvantesson/plantuml-code-highlight and put them in your
2021-01-19 10:50:55 -05:00
`$GITEA_CUSTOM/public` folder. Then add the following to `custom/footer.tmpl` :
2020-01-20 18:34:23 -05:00
```html
< script >
2022-05-05 02:53:38 -05:00
$(async () => {
if (!$('.language-plantuml').length) return;
await Promise.all([
$.getScript('https://your-server.com/deflate.js'),
$.getScript('https://your-server.com/encode.js'),
$.getScript('https://your-server.com/plantuml_codeblock_parse.js'),
]);
// Replace call with address to your plantuml server
parsePlantumlCodeBlocks("https://www.plantuml.com/plantuml");
});
2020-01-20 18:34:23 -05:00
< / script >
```
You can then add blocks like the following to your markdown:
```plantuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
2020-04-06 18:43:17 -05:00
2020-01-20 18:34:23 -05:00
Alice -> Bob: Another authentication Request
Alice < -- Bob: Another authentication Response
```
The script will detect tags with `class="language-plantuml"` , but you can change this by providing a second argument to `parsePlantumlCodeBlocks` .
2020-04-22 12:02:54 -05:00
#### Example: STL Preview
You can display STL file directly in Gitea by adding:
2020-12-09 01:47:06 -05:00
2020-04-22 12:02:54 -05:00
```html
< script >
2020-12-09 01:47:06 -05:00
function lS(src) {
return new Promise(function (resolve, reject) {
let s = document.createElement("script");
s.src = src;
s.addEventListener("load", () => {
resolve();
});
document.body.appendChild(s);
});
}
if ($('.view-raw>a[href$=".stl" i]').length) {
$("body").append(
2021-07-15 14:49:12 -05:00
'< link href = "/assets/Madeleine.js/src/css/Madeleine.css" rel = "stylesheet" > '
2020-12-09 01:47:06 -05:00
);
Promise.all([
2021-07-15 14:49:12 -05:00
lS("/assets/Madeleine.js/src/lib/stats.js"),
lS("/assets/Madeleine.js/src/lib/detector.js"),
lS("/assets/Madeleine.js/src/lib/three.min.js"),
lS("/assets/Madeleine.js/src/Madeleine.js"),
2020-12-09 01:47:06 -05:00
]).then(function () {
$(".view-raw")
.attr("id", "view-raw")
.attr("style", "padding: 0;margin-bottom: -10px;");
new Madeleine({
target: "view-raw",
data: $('.view-raw>a[href$=".stl" i]').attr("href"),
2021-07-15 14:49:12 -05:00
path: "/assets/Madeleine.js/src",
2020-12-09 01:47:06 -05:00
});
$('.view-raw>a[href$=".stl"]').remove();
2020-04-22 12:02:54 -05:00
});
2020-12-09 01:47:06 -05:00
}
2020-04-22 12:02:54 -05:00
< / script >
```
2020-12-09 01:47:06 -05:00
2020-04-22 12:02:54 -05:00
to the file `templates/custom/footer.tmpl`
2022-07-11 22:51:14 -05:00
You also need to download the content of the library [Madeleine.js ](https://github.com/beige90/Madeleine.js ) and place it under `$GITEA_CUSTOM/public/` folder.
2020-04-22 12:02:54 -05:00
2021-07-18 11:21:32 -05:00
You should end-up with a folder structure similar to:
2020-12-09 01:47:06 -05:00
2020-04-22 12:02:54 -05:00
```
2021-01-19 10:50:55 -05:00
$GITEA_CUSTOM/templates
2020-04-22 12:02:54 -05:00
-- custom
`-- footer.tmpl
2021-01-19 10:50:55 -05:00
$GITEA_CUSTOM/public
2020-04-22 12:02:54 -05:00
-- Madeleine.js
|-- LICENSE
|-- README.md
|-- css
| |-- pygment_trac.css
| `-- stylesheet.css
|-- examples
| |-- ajax.html
| |-- index.html
| `-- upload.html
|-- images
| |-- bg_hr.png
| |-- blacktocat.png
| |-- icon_download.png
| `-- sprite_download.png
|-- models
| |-- dino2.stl
| |-- ducati.stl
| |-- gallardo.stl
| |-- lamp.stl
| |-- octocat.stl
| |-- skull.stl
| `-- treefrog.stl
`-- src
|-- Madeleine.js
|-- css
| `-- Madeleine.css
|-- icons
| |-- logo.png
| |-- madeleine.eot
| |-- madeleine.svg
| |-- madeleine.ttf
| `-- madeleine.woff
`-- lib
|-- MadeleineConverter.js
|-- MadeleineLoader.js
|-- detector.js
|-- stats.js
`-- three.min.js
```
2021-11-28 08:28:30 -05:00
Then restart Gitea and open a STL file on your Gitea instance.
2020-04-22 12:02:54 -05:00
2019-07-11 00:27:57 -05:00
## Customizing Gitea mails
2021-01-19 10:50:55 -05:00
The `$GITEA_CUSTOM/templates/mail` folder allows changing the body of every mail of Gitea.
2019-07-11 00:27:57 -05:00
Templates to override can be found in the
2021-05-04 11:16:23 -05:00
[`templates/mail` ](https://github.com/go-gitea/gitea/tree/main/templates/mail )
2019-07-11 00:27:57 -05:00
directory of Gitea source.
2021-01-19 10:50:55 -05:00
Override by making a copy of the file under `$GITEA_CUSTOM/templates/mail` using a
2019-07-11 00:27:57 -05:00
full path structure matching source.
Any statement contained inside `{{` and `}}` are Gitea's template
syntax and shouldn't be touched without fully understanding these components.
2018-11-04 21:21:56 -05:00
## Adding Analytics to Gitea
2021-01-19 10:50:55 -05:00
Google Analytics, Matomo (previously Piwik), and other analytics services can be added to Gitea. To add the tracking code, refer to the `Other additions to the page` section of this document, and add the JavaScript to the `$GITEA_CUSTOM/templates/custom/header.tmpl` file.
2018-11-04 21:21:56 -05:00
2017-11-26 16:44:32 -05:00
## Customizing gitignores, labels, licenses, locales, and readmes.
2018-01-08 17:48:42 -05:00
Place custom files in corresponding sub-folder under `custom/options` .
2018-07-05 16:25:04 -05:00
2019-02-28 07:09:47 -05:00
**NOTE:** The files should not have a file extension, e.g. `Labels` rather than `Labels.txt`
### gitignores
2021-01-19 10:50:55 -05:00
To add custom .gitignore, add a file with existing [.gitignore rules ](https://git-scm.com/docs/gitignore ) in it to `$GITEA_CUSTOM/options/gitignore`
2019-02-28 07:09:47 -05:00
### Labels
2021-05-04 11:16:23 -05:00
To add a custom label set, add a file that follows the [label format ](https://github.com/go-gitea/gitea/blob/main/options/label/Default ) to `$GITEA_CUSTOM/options/label`
2019-02-28 07:09:47 -05:00
`#hex-color label name ; label description`
### Licenses
2021-01-19 10:50:55 -05:00
To add a custom license, add a file with the license text to `$GITEA_CUSTOM/options/license`
2019-02-28 07:09:47 -05:00
### Locales
2021-12-23 22:56:57 -05:00
Locales are managed via our [Crowdin ](https://crowdin.com/project/gitea ).
2021-01-19 10:50:55 -05:00
You can override a locale by placing an altered locale file in `$GITEA_CUSTOM/options/locale` .
2021-05-04 11:16:23 -05:00
Gitea's default locale files can be found in the [`options/locale` ](https://github.com/go-gitea/gitea/tree/main/options/locale ) source folder and these should be used as examples for your changes.
2019-10-28 14:11:02 -05:00
2019-02-28 07:09:47 -05:00
To add a completely new locale, as well as placing the file in the above location, you will need to add the new lang and name to the `[i18n]` section in your `app.ini` . Keep in mind that Gitea will use those settings as **overrides** , so if you want to keep the other languages as well you will need to copy/paste the default values and add your own to them.
```
[i18n]
LANGS = en-US,foo-BAR
NAMES = English,FooBar
```
2022-04-03 04:46:48 -05:00
The first locale will be used as the default if user browser's language doesn't match any locale in the list.
2019-02-28 07:09:47 -05:00
Locales may change between versions, so keeping track of your customized locales is highly encouraged.
### Readmes
2021-01-19 10:50:55 -05:00
To add a custom Readme, add a markdown formatted file (without an `.md` extension) to `$GITEA_CUSTOM/options/readme`
2019-02-28 07:09:47 -05:00
2021-01-19 10:50:55 -05:00
**NOTE:** readme templates support **variable expansion** .
2020-04-06 20:40:38 -05:00
currently there are `{Name}` (name of repository), `{Description}` , `{CloneURL.SSH}` , `{CloneURL.HTTPS}` and `{OwnerName}`
2020-04-06 18:43:17 -05:00
2019-12-01 17:57:24 -05:00
### Reactions
To change reaction emoji's you can set allowed reactions at app.ini
2020-12-09 01:47:06 -05:00
2019-12-01 17:57:24 -05:00
```
[ui]
REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes
```
2020-12-09 01:47:06 -05:00
2019-12-01 17:57:24 -05:00
A full list of supported emoji's is at [emoji list ](https://gitea.com/gitea/gitea.com/issues/8 )
2018-07-05 16:25:04 -05:00
## Customizing the look of Gitea
2021-09-27 09:47:44 -05:00
The default built-in themes are `gitea` (light), `arc-green` (dark), and `auto` (chooses light or dark depending on operating system settings).
2021-08-29 13:26:43 -05:00
The default theme can be changed via `DEFAULT_THEME` in the [ui ](https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui ) section of `app.ini` .
Gitea also has support for user themes, which means every user can select which theme should be used.
The list of themes a user can choose from can be configured with the `THEMES` value in the [ui ](https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui ) section of `app.ini` .
To make a custom theme available to all users:
2022-06-27 11:16:51 -05:00
1. Add a CSS file to `$GITEA_CUSTOM/public/css/theme-<theme-name>.css` .
The value of `$GITEA_CUSTOM` of your instance can be queried by calling `gitea help` and looking up the value of "CustomPath".
2021-08-29 13:26:43 -05:00
2. Add `<theme-name>` to the comma-separated list of setting `THEMES` in `app.ini`
Community themes are listed in [gitea/awesome-gitea#themes ](https://gitea.com/gitea/awesome-gitea#themes ).
The `arc-green` theme source can be found [here ](https://github.com/go-gitea/gitea/blob/main/web_src/less/themes/theme-arc-green.less ).
2020-10-19 15:01:06 -05:00
2021-11-25 02:14:48 -05:00
If your custom theme is considered a dark theme, set the global css variable `--is-dark-theme` to `true` .
2021-11-28 08:28:30 -05:00
This allows Gitea to adjust the Monaco code editor's theme accordingly.
2021-11-25 02:14:48 -05:00
2020-10-19 15:01:06 -05:00
## Customizing fonts
Fonts can be customized using CSS variables:
```css
:root {
--fonts-proportional: /* custom proportional fonts */ !important;
--fonts-monospace: /* custom monospace fonts */ !important;
--fonts-emoji: /* custom emoji fonts */ !important;
}
```