mGit Custom Theme

Shared Gitea customizations for all mGit instances. This repo is the single source of truth for branding, themes, and template overrides.

Instances

Instance	URL	Host
Primary	`mgit.msbls.de`	mvpsm
Backup (mirror)	`mgit.x.msbls.de`	mgitx

Both run Gitea 1.24.x via Dokploy with this repo cloned to /home/m/gitea-custom/.

How It Works

Gitea supports customization by mounting files into its $GITEA_CUSTOM directory (/data/gitea/ in Docker). The Dokploy compose files bind-mount subdirectories from this repo:

volumes:
  - /home/m/gitea-custom/public:/data/gitea/public:ro
  - /home/m/gitea-custom/templates:/data/gitea/templates:ro
  - /home/m/gitea-custom/options:/data/gitea/options:ro

A cron job on each host runs every 30 minutes to pull changes and restart Gitea if the repo was updated.

File Structure

gitea-custom/
├── public/
│   └── assets/
│       ├── css/
│       │   ├── theme-mgit-dark.css   # Dark theme (CSS variables only)
│       │   └── theme-mgit-light.css  # Light theme (CSS variables only)
│       └── img/
│           ├── logo.svg              # Main logo (200x200)
│           └── favicon.svg           # Favicon (32x32)
├── templates/
│   ├── custom/
│   │   ├── header.tmpl              # Injects Inter font from Google Fonts
│   │   ├── footer.tmpl              # Custom footer script
│   │   ├── body_inner_pre.tmpl      # Empty (available for banners)
│   │   └── extra_links.tmpl         # Empty (available for nav links)
│   └── home.tmpl                    # Custom homepage
└── options/                          # Reserved for locale overrides

Themes

Two custom themes are provided — mGit Dark and mGit Light. They use Gitea's built-in CSS variable system and only override color tokens and font stacks. This approach is forward-compatible with Gitea upgrades because we don't override Gitea's own selectors.

Color palette: Tailwind CSS slate (grays) + blue (primary). Fonts: Inter (proportional), JetBrains Mono (monospace).

To make these themes available, add them to app.ini on each instance:

[ui]
THEMES = gitea-auto,gitea-light,gitea-dark,mgit-light,mgit-dark
DEFAULT_THEME = mgit-dark

In Dokploy, set these as environment variables:

GITEA__ui__THEMES=gitea-auto,gitea-light,gitea-dark,mgit-light,mgit-dark
GITEA__ui__DEFAULT_THEME=mgit-dark

Making Changes

Edit files in this repo and push to main
Changes auto-deploy within 30 minutes via cron on each host
For immediate deployment: ssh <host> "cd /home/m/gitea-custom && git pull" then restart the Gitea container

To restart Gitea after changes:

docker restart $(docker ps -q --filter "ancestor=docker.gitea.com/gitea:1.24.4")

Template Hooks

Gitea provides these injection points in templates/custom/:

File	Purpose
`header.tmpl`	Injected in `<head>` — use for fonts, analytics, extra CSS
`footer.tmpl`	Injected before `</body>` — use for scripts
`body_inner_pre.tmpl`	Before top nav — use for announcement banners
`extra_links.tmpl`	Extra items in the top nav bar
`home.tmpl`	Full homepage override (in `templates/`, not `templates/custom/`)

Adding New Assets

CSS themes: Add public/assets/css/theme-<name>.css and register in THEMES
Images: Add to public/assets/img/ — accessible at /assets/img/<file>
Locale overrides: Add to options/locale/locale_en-US.ini

Design Principles

Work with Gitea, not against it — only override CSS variables, avoid selector overrides
Keep it minimal — less custom CSS = fewer things that break on upgrades
Both themes must stay in sync — same structure, only color values differ