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"
weight: 9
identifier: "customizing-gitea"
---
# Customizing Gitea
2018-01-08 17:48:42 -05:00
Customizing Gitea is typically done using the `custom` folder. This is the central
place to override configuration settings, templates, etc.
2017-11-26 16:44:32 -05:00
2018-01-08 17:48:42 -05:00
If Gitea is deployed from binary, all default paths will be relative to the gitea
binary. If installed from a distribution, these paths will likely be modified to
the Linux Filesystem Standard. Gitea will create required folders, including `custom/` .
Application settings are configured in `custom/conf/app.ini` . Distributions may
provide a symlink for `custom` using `/etc/gitea/` .
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/ )
- [Complete List ](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample )
2017-11-26 16:44:32 -05:00
2018-01-08 17:48:42 -05:00
If the `custom` folder can't be found next to the binary, check the `GITEA_CUSTOM`
environment variable; this can be used to override the default path to something else.
`GITEA_CUSTOM` might, for example, be set by an init script.
- [List of Environment Variables ](https://docs.gitea.io/en-us/specific-variables/ )
**Note:** Gitea must perform a full restart to see configuration changes.
2017-11-26 16:44:32 -05:00
## Customizing /robots.txt
2018-01-08 17:48:42 -05:00
To make Gitea serve a custom `/robots.txt` (default: empty 404), create a file called
`robots.txt` in the `custom` folder with [expected contents ](http://www.robotstxt.org/ ).
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
`custom/public/` as the webroot. Symbolic links will be followed.
2017-11-26 16:44:32 -05:00
2018-01-08 17:48:42 -05:00
For example, a file `image.png` stored in `custom/public/` , can be accessed with
the url `http://gitea.domain.tld/image.png` .
2017-11-26 16:44:32 -05:00
## Changing the default avatar
2018-01-08 17:48:42 -05:00
Place the png image at the following path: `custom/public/img/avatar\_default.png`
2017-11-26 16:44:32 -05:00
## Customizing Gitea pages
2018-01-08 17:48:42 -05:00
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` using a full path structure
matching source.
2017-11-26 16:44:32 -05:00
2018-07-26 05:57:45 -05:00
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
2018-01-11 14:56:40 -05:00
### Adding links and tabs
2017-12-02 19:26:06 -05:00
2018-01-10 01:19:50 -05:00
If all you want is to add extra links to the top navigation bar, or extra tabs to the repository view, you can put them in `extra_links.tmpl` and `extra_tabs.tmpl` inside your `custom/templates/custom/` directory.
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:
just place it under your "custom/public/" directory (for instance `custom/public/impressum.html` ) and put a link to it in `custom/templates/custom/extra_links.tmpl` .
To match the current style, the link should have the class name "item", and you can use `{{AppSubUrl}}` to get the base URL:
`<a class="item" href="{{AppSubUrl}}/impressum.html">Impressum</a>`
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`
([source in GitHub](https://github.com/go-gitea/gitea/blob/master/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 `custom/templates/custom/` directory:
- `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.
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
## Customizing the look of Gitea
Gitea has two built-in themes, the default theme `gitea` , and a dark theme `arc-green` . To change the look of your Gitea install change the value of `DEFAULT_THEME` in the [ui ](https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui ) section of `app.ini` to another one of the available options.
