forgejo/docs/content/administration/customizing-gitea.en-us.md

date	title	slug	sidebar_position	toc	draft	aliases	menu
2017-04-15T14:56:00+02:00	Customizing Gitea	customizing-gitea	100	false	false	/en-us/customizing-gitea	sidebar parent name identifier sidebar_position administration Customizing Gitea customizing-gitea 100

Customizing Gitea

Customizing Gitea 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 gitea 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 GITEA_CUSTOM environment variable or by using the --custom-path option on the gitea binary. (The option will override the environment variable.)

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 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, $GITEA_CUSTOM/conf/app.ini but may be different if your build has set this differently. Again gitea help will allow you review this variable and you can override it using the --config option on the gitea binary.

• Quick Cheat Sheet
• Complete List

If the CustomPath folder can't be found despite checking gitea help, 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. You can check whether the value is set under the "Configuration" tab on the site administration page.

• List of Environment Variables

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

Serving custom public files

To make Gitea serve custom public files (like pages and images), use the folder $GITEA_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 $GITEA_CUSTOM/public/assets/, can be accessed with the url http://gitea.domain.tld/assets/image.png.

Changing the logo

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

In case the source image is not in vector format, you can attempt to convert a raster image using tools like this.

Customizing Gitea pages and resources

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 must be placed in $GITEA_CUSTOM/options/gitignore/C++ (see about the location of the CustomPath directory at the top of this document).

Every single page of Gitea can be changed. Dynamic content is generated using go templates, which can be modified by placing replacements below the $GITEA_CUSTOM/templates directory.

To obtain any embedded file (including templates), the gitea embedded tool can be used. Alternatively, they can be found in the 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).

Be aware that any statement contained inside {{ and }} are Gitea's template syntax and shouldn't be touched without fully understanding these components.

Customizing startpage / homepage

Copy home.tmpl for your version of Gitea from templates to $GITEA_CUSTOM/templates. Edit as you wish. Dont forget to restart your Gitea 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 $GITEA_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 "$GITEA_CUSTOM/public/assets/" directory (for instance $GITEA_CUSTOM/public/assets/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.

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}}/assets/impressum.html">Impressum</a>

For more information, see Adding Legal Pages.

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 $GITEA_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.

Using Gitea variables

It's possible to use various Gitea variables in your custom templates.

First, temporarily enable development mode: in your app.ini change from RUN_MODE = prod to RUN_MODE = dev. Then add {{ $ | DumpVar }} to any of your templates, restart Gitea and refresh that page; that will dump all available variables.

Find the data that you need, and use the corresponding variable; for example, if you need the name of the repository then you'd use {{.Repository.Name}}.

If you need to transform that data somehow, and aren't familiar with Go, an easy workaround is to add the data to the DOM and add a small JavaScript script block to manipulate the data.

Example: PlantUML

You can add PlantUML support to Gitea's markdown by using a PlantUML server. 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 can set up your own PlantUML server instead. To set up PlantUML rendering, copy JavaScript files from https://gitea.com/davidsvantesson/plantuml-code-highlight and put them in your $GITEA_CUSTOM/public/assets/ folder. Then add the following to custom/footer.tmpl:

<script>
  $(async () => {
    if (!$('.language-plantuml').length) return;
    await Promise.all([
      $.getScript('https://your-gitea-server.com/assets/deflate.js'),
      $.getScript('https://your-gitea-server.com/assets/encode.js'),
      $.getScript('https://your-gitea-server.com/assets/plantuml_codeblock_parse.js'),
    ]);
    // Replace call with address to your plantuml server
    parsePlantumlCodeBlocks("https://www.plantuml.com/plantuml");
  });
</script>

You can then add blocks like the following to your markdown:

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

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.

Example: STL Preview

You can display STL file directly in Gitea by adding:

<script>
  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(
      '<link href="/assets/Madeleine.js/src/css/Madeleine.css" rel="stylesheet">'
    );
    Promise.all([
      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"),
    ]).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"),
        path: "/assets/Madeleine.js/src",
      });
      $('.view-raw>a[href$=".stl"]').remove();
    });
  }
</script>

to the file templates/custom/footer.tmpl

You also need to download the content of the library Madeleine.js and place it under $GITEA_CUSTOM/public/assets/ folder.

You should end-up with a folder structure similar to:

$GITEA_CUSTOM/templates
-- custom
    `-- footer.tmpl

$GITEA_CUSTOM/public/assets/
-- 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

Then restart Gitea and open a STL file on your Gitea instance.

Customizing Gitea mails

The $GITEA_CUSTOM/templates/mail folder allows changing the body of every mail of Gitea. Templates to override can be found in the templates/mail directory of Gitea source. Override by making a copy of the file under $GITEA_CUSTOM/templates/mail using a 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.

Adding Analytics to Gitea

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.

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

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

NOTE: The files should not have a file extension, e.g. Labels rather than Labels.txt

gitignores

To add custom .gitignore, add a file with existing .gitignore rules in it to $GITEA_CUSTOM/options/gitignore

Customizing the git configuration

Starting with Gitea 1.20, you can customize the git configuration via the git.config section.

Enabling signed git pushes

To enable signed git pushes, set these two options:

[git.config]
receive.advertisePushOptions = true
receive.certNonceSeed = <randomstring>

certNonceSeed should be set to a random string and be kept secret.

Labels

Starting with Gitea 1.19, you can add a file that follows the YAML label format to $GITEA_CUSTOM/options/label:

labels:
  - name: "foo/bar"  # name of the label that will appear in the dropdown
    exclusive: true # whether to use the exclusive namespace for scoped labels. scoped delimiter is /
    color: aabbcc # hex colour coding
    description: Some label # long description of label intent

The legacy file format can still be used following the format below, however we strongly recommend using the newer YAML format instead.

#hex-color label name ; label description

For more information, see the labels documentation.

Licenses

To add a custom license, add a file with the license text to $GITEA_CUSTOM/options/license

Locales

Locales are managed via our Crowdin. You can override a locale by placing an altered locale file in $GITEA_CUSTOM/options/locale. Gitea's default locale files can be found in the options/locale source folder and these should be used as examples for your changes.

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

The first locale will be used as the default if user browser's language doesn't match any locale in the list.

Locales may change between versions, so keeping track of your customized locales is highly encouraged.

Readmes

To add a custom Readme, add a markdown formatted file (without an .md extension) to $GITEA_CUSTOM/options/readme

NOTE: readme templates support variable expansion. currently there are {Name} (name of repository), {Description}, {CloneURL.SSH}, {CloneURL.HTTPS} and {OwnerName}

Reactions

To change reaction emoji's you can set allowed reactions at app.ini

[ui]
REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes

A full list of supported emoji's is at emoji list

Customizing the look of Gitea

The default built-in themes are gitea (light), arc-green (dark), and auto (chooses light or dark depending on operating system settings). The default theme can be changed via DEFAULT_THEME in the 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 section of app.ini.

To make a custom theme available to all users:

1. Add a CSS file to $GITEA_CUSTOM/public/assets/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".
2. Add <theme-name> to the comma-separated list of setting THEMES in app.ini

Community themes are listed in gitea/awesome-gitea#themes.

The arc-green theme source can be found here.

If your custom theme is considered a dark theme, set the global css variable --is-dark-theme to true. This allows Gitea to adjust the Monaco code editor's theme accordingly.

Customizing fonts

Fonts can be customized using CSS variables:

:root {
  --fonts-proportional: /* custom proportional fonts */ !important;
  --fonts-monospace: /* custom monospace fonts */ !important;
  --fonts-emoji: /* custom emoji fonts */ !important;
}