forgejo/docs/content/doc/advanced/customizing-gitea.en-us.md
techknowlogick f1d6a1fffc
Add the ability to have built in themes in Gitea (#4198)
This makes it easier for user who want to theme but
don't have the ability to know how to customize templates
all that is required is a change in a config option

The reason why I chose the DEFAULT_THEME as variable,
as perhaps in the future we will allow users to chose their
theme whon logged in just like we do with languages
2018-07-05 17:25:04 -04:00

4.5 KiB

date title slug weight toc draft menu
2017-04-15T14:56:00+02:00 Customizing Gitea customizing-gitea 9 false false
sidebar
parent name weight identifier
advanced Customizing Gitea 9 customizing-gitea

Customizing Gitea

Customizing Gitea is typically done using the custom folder. This is the central place to override configuration settings, templates, etc.

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/.

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.

Note: Gitea must perform a full restart to see configuration changes.

Customizing /robots.txt

To make Gitea serve a custom /robots.txt (default: empty 404), create a file called robots.txt in the custom folder with expected contents.

Serving custom public files

To make Gitea serve custom public files (like pages and images), use the folder custom/public/ as the webroot. Symbolic links will be followed.

For example, a file image.png stored in custom/public/, can be accessed with the url http://gitea.domain.tld/image.png.

Changing the default avatar

Place the png image at the following path: custom/public/img/avatar\_default.png

Customizing Gitea pages

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.

Any statement contained inside {{ and }} are Gitea's templete syntax and shouldn't be touched without fully understanding these components.

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.

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)

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.

Customizing gitignores, labels, licenses, locales, and readmes.

Place custom files in corresponding sub-folder under custom/options.

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 section of app.ini to another one of the available options.