+++
date = "2019-03-29T21:37:32+00:00"
publishdate = "2023-12-29T07:08:55+00:00"
title = "Let's Customize Gitea"
slug = "lets-customize-gitea"
author = "Thedro"
tags = ["git","webdev"]
type = "posts"
summary =  "Gitea is an awesome and lightweight Git service that can be hosted anywhere. It is open source and written in Go. "
draft =  ""
syntax =  "1"
toc =  ""
updated =  "2022-03-02"
+++

{{< image source="/images/lets-customize-gitea.png" >}} {{< /image >}}

[Gitea](https://gitea.io) is an awesome and
{{< sidenote mark="lightweight" set="right" >}}It is lightweight enough to run
comfortably on a `512` MB Raspberry Pi.{{< /sidenote >}}
[Git](https://git-scm.com/) service that can be hosted anywhere. It is open
source and written in [Golang.](https://go.dev/doc/) Many of my
[own projects](https://www.thedroneely.com/git/thedroneely/dotfiles) are hosted
across multiple Gitea instances. A standard Gitea installation will look a bit
bare.

{{< image source="/images/standard-gitea-instance.png" >}} {{< /image >}}

We can {{< sidenote mark="customize" set="right" >}}Check out my template hacks
[here.](https://www.thedroneely.com/git/thedroneely/gitea-templates/tree/)
{{< /sidenote >}} many aspects of Gitea by overriding its default templates.
This allows us to change the header, footer, and navigation sections with ease.
You can also override public resources like images.

To start overriding the templates, create the folder `custom` in Gitea's home
folder or working directory.

```shell {options="hl_lines=1"}
drwxr-xr-x 4 gitea gitea 4096 Mar 29 17:03 custom
drwxr-xr-x 6 gitea gitea 4096 Jan 17 03:40 data
-rw-r--r-- 1 gitea gitea 73   Mar 29 17:29 .gitconfig
srw-rw-rw- 1 gitea gitea 0    Mar 29 17:29 gitea.socket
drwxr-xr-x 3 gitea gitea 4096 Mar 29 15:52 log
drwxr----- 3 gitea gitea 4096 Jan 17 06:44 .pki
drwxr-xr-x 3 gitea gitea 4096 Jan 17 06:44 repos
drwx------ 2 gitea gitea 4096 Jan 17 05:49 .ssh
```

We will change some elements of the navigation bar and override the favicons. To
do this, the `custom` folder will have the following file structure.

```text
custom
|__ public
|   |__ img
|       |__ favicon.ico
|       |__ favicon.png
|__ templates
    |__ base
        |__ head_navbar.tmpl
```

The navigation elements are templated by the source file
[`base/head_navbar.tmpl`](https://github.com/go-gitea/gitea/blob/master/templates/base/head_navbar.tmpl)
and can be overridden by the path `custom/templates/base/head_navbar.tmpl`.

Match the template files with your Gitea version using the repository
{{< sidenote mark="tags" set="right" >}}Use the release
[tag](https://github.com/go-gitea/gitea/tags) that matches your Gitea
version.{{< /sidenote >}} or you may experience runtime errors.

You can view the {{< sidenote mark="directory" set="left" >}}The **live**
repository master is used here to demonstrate.{{< /sidenote >}} override
structure of the templates by
[looking directly at the source files.](https://github.com/go-gitea/gitea/tree/master/templates)
You must restart the Gitea instance for changes to take effect.

## The Customization

Let's copy
[`base/head_navbar.tmpl`](https://raw.githubusercontent.com/go-gitea/gitea/master/templates/base/head_navbar.tmpl)
to our local path at `custom/templates/base/head_navbar.tmpl` and replace the
brand icon and link.

```diff
@@ -1,7 +1,8 @@
<div class="ui container" id="navbar">
  <div class="item brand" style="justify-content: space-between;">
-   <a href="{{AppSubUrl}}/">
-     <img class="ui mini image" src="{{AppSubUrl}}/img/gitea-sm.png">
+   <a title="Head back to https://www.thedroneely.com" href="/">
+     <img style="display: inline; border-radius: 6px;" class="ui mini image" src="/android-chrome-192x192.png">
+     <span style="margin-left: 0.65em;">www.thedroneely.com</span>
    </a>
  <div class="ui basic icon button mobile-only" id="navbar-expand-toggle">
    <i class="sidebar icon"></i>
```

Finally let's disable the help button in the navigation bar by adjusting the
template.

```diff
@@ -118,7 +119,7 @@
{{else}}
- <a class="item" target="_blank" rel="noopener noreferrer" href="https://docs.gitea.io">{{.i18n.Tr "help"}}</a>
+ <!-- <a class="item" target="_blank" rel="noopener noreferrer" href="https://docs.gitea.io">{{.i18n.Tr "help"}}</a> -->
  <div class="right stackable menu">
    {{if .ShowRegistrationButton}}
      <a class="item{{if .PageIsSignUp}} active{{end}}" href="{{AppSubUrl}}/user/sign_up">
```

The {{< sidenote mark="favicons" set="left" >}}Ensure that you bypass your
browser's cache to see the changes.{{< /sidenote >}} can be overridden by
placing the files `favicon.ico` and `favicon.png` inside `custom/public/img`.

## Caching and Changes

Gitea uses a
[service worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
that caches files {{< sidenote mark="aggressively." set="left" >}}Gitea is
bloated on the front-end. {{< /sidenote >}} This means that some changes may not
show up immediately. Clear the browser cache (history) or "hard refresh" the
{{< sidenote mark="page" set="right" >}}Or unregister the service
worker.{{< /sidenote >}} to view the changes.

## The Results

This guide did not contain drastic changes to Gitea, however the sky is the
limit. You can {{< sidenote mark="see" set="left" >}} **Note:** No longer
available. Switched my `git` front-end to
[cgit](https://git.zx2c4.com/cgit/about/). {{< /sidenote >}} the
results of my changes by visiting
[this website's self hosted Git server.](https://www.thedroneely.com/git/thedroneely/gitea-templates/)