mirror of
https://mgit.msbls.de/m/gitea-custom.git
synced 2026-02-06 00:02:08 +00:00
refactor: clean up themes, templates, and add comprehensive README
- Themes now only override CSS variables (no selector overrides) - Removed duplicate styles from header.tmpl (just loads Inter font now) - Cleaned up logo SVG (simpler, no overlapping text) - Improved home page with proper hero layout and sign-in/explore buttons - Added detailed README documenting the setup, deployment, and design principles
This commit is contained in:
m
105
README.md
105
README.md
@@ -1,3 +1,104 @@
|
||||
# gitea-custom
|
||||
# mGit Custom Theme
|
||||
|
||||
Shared Gitea theme and customizations
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```ini
|
||||
[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
|
||||
|
||||
1. Edit files in this repo and push to `main`
|
||||
2. Changes auto-deploy within 30 minutes via cron on each host
|
||||
3. For immediate deployment: `ssh <host> "cd /home/m/gitea-custom && git pull"` then restart the Gitea container
|
||||
|
||||
**To restart Gitea after changes:**
|
||||
```bash
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user