mirror of
https://codeberg.org/forgejo/forgejo.git
synced 2024-08-21 12:08:54 +02:00
This was intended to be a small followup for https://github.com/go-gitea/gitea/pull/23712, but...here we are. 1. Our docs currently use `slug` as the entire URL, which makes refactoring tricky (see https://github.com/go-gitea/gitea/pull/23712). Instead, this PR attempts to make future refactoring easier by using slugs as an extension of the section. (Hugo terminology) - What the above boils down to is this PR attempts to use directory organization as URL management. e.g. `usage/comparison.en-us.md` -> `en-us/usage/comparison/`, `usage/packages/overview.en-us.md` -> `en-us/usage/packages/overview/` - Technically we could even remove `slug`, as Hugo defaults to using filename, however at least with this PR it means `slug` only needs to be the name for the **current file** rather than an entire URL 2. This PR adds appropriate aliases (redirects) for pages, so anything on the internet that links to our docs should hopefully not break. 3. A minor nit I've had for a while, renaming `seek-help` to `support`. It's a minor thing, but `seek-help` has a strange connotation to it. 4. The commits are split such that you can review the first which is the "actual" change, and the second is added redirects so that the first doesn't break links elsewhere. --------- Signed-off-by: jolheiser <john.olheiser@gmail.com>
374 lines
16 KiB
Markdown
374 lines
16 KiB
Markdown
---
|
|
date: "2017-04-15T14:56:00+02:00"
|
|
title: "Customizing Gitea"
|
|
slug: "customizing-gitea"
|
|
weight: 100
|
|
toc: false
|
|
draft: false
|
|
aliases:
|
|
- /en-us/customizing-gitea
|
|
menu:
|
|
sidebar:
|
|
parent: "administration"
|
|
name: "Customizing Gitea"
|
|
identifier: "customizing-gitea"
|
|
weight: 100
|
|
---
|
|
|
|
# Customizing Gitea
|
|
|
|
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,
|
|
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](https://docs.gitea.io/en-us/config-cheat-sheet/)
|
|
- [Complete List](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
|
|
|
|
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](https://docs.gitea.io/en-us/environment-variables/)
|
|
|
|
**Note:** Gitea must perform a full restart to see configuration changes.
|
|
|
|
**Table of Contents**
|
|
|
|
{{< toc >}}
|
|
|
|
## 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.
|
|
|
|
For example, a file `image.png` stored in `$GITEA_CUSTOM/public/`, 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/img` on your server:
|
|
|
|
- `public/img/logo.svg` - Used for site icon, app icon
|
|
- `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
|
|
- `public/img/favicon.svg` - Used for favicon
|
|
- `public/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](https://www.aconvert.com/image/png-to-svg/).
|
|
|
|
## 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](https://golang.org/pkg/html/template/),
|
|
which can be modified by placing replacements below the `$GITEA_CUSTOM/templates` directory.
|
|
|
|
To obtain any embedded file (including templates), the [`gitea embedded` tool]({{< relref "doc/administration/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).
|
|
|
|
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`](https://github.com/go-gitea/gitea/blob/main/templates/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/" 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`.
|
|
|
|
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](https://docs.gitea.io/en-us/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](https://github.com/go-gitea/gitea/blob/main/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 `$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.
|
|
|
|
#### Example: PlantUML
|
|
|
|
You can add [PlantUML](https://plantuml.com/) 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](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
|
|
`$GITEA_CUSTOM/public` folder. Then add the following to `custom/footer.tmpl`:
|
|
|
|
```html
|
|
<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:
|
|
|
|
```plantuml
|
|
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:
|
|
|
|
```html
|
|
<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](https://github.com/beige90/Madeleine.js) and place it under `$GITEA_CUSTOM/public/` folder.
|
|
|
|
You should end-up with a folder structure similar to:
|
|
|
|
```
|
|
$GITEA_CUSTOM/templates
|
|
-- custom
|
|
`-- footer.tmpl
|
|
$GITEA_CUSTOM/public
|
|
-- 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`](https://github.com/go-gitea/gitea/tree/main/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](https://git-scm.com/docs/gitignore) in it to `$GITEA_CUSTOM/options/gitignore`
|
|
|
|
### Labels
|
|
|
|
Starting with Gitea 1.19, you can add a file that follows the [YAML label format](https://github.com/go-gitea/gitea/blob/main/options/label/Advanced.yaml) to `$GITEA_CUSTOM/options/label`:
|
|
|
|
```yaml
|
|
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](https://github.com/go-gitea/gitea/blob/main/options/label/Default) 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]({{< relref "doc/usage/labels.en-us.md" >}}).
|
|
|
|
### 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](https://crowdin.com/project/gitea).
|
|
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`](https://github.com/go-gitea/gitea/tree/main/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](https://gitea.com/gitea/gitea.com/issues/8)
|
|
|
|
## 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](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:
|
|
|
|
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".
|
|
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/css/themes/theme-arc-green.css).
|
|
|
|
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:
|
|
|
|
```css
|
|
:root {
|
|
--fonts-proportional: /* custom proportional fonts */ !important;
|
|
--fonts-monospace: /* custom monospace fonts */ !important;
|
|
--fonts-emoji: /* custom emoji fonts */ !important;
|
|
}
|
|
```
|