chore: migrate mail themes to shared framework and locked upstream inputs
This commit is contained in:
KenanZhu committed
1 parent
5c0589f6f6
commit
fec3ace600
225 files changed
+4718
-15807
No files matched your search
@@ -17,7 +17,7 @@ Polished, drop-in email template themes for self-hosted [Gitea](https://about.gi
|
||||
|
||||
Most self-hosted Gitea instances use the default plain email templates. This project provides **ready-to-deploy, visually polished alternatives** — each designed for a specific community or audience, so you can pick the one that feels right for your users.
|
||||
|
||||
The templates on `main` can replace Gitea's built-in mail templates without patches, plugins, or forks. Check the [compatibility matrix](COMPATIBILITY.md) before using a published archive; older releases may have version-specific limitations.
|
||||
The source on `main` uses locked official Gitea inputs and a reusable control framework. Gitea supplies mail values, notification logic and translations; shared controls organize headers, buttons, fallback URLs and footers, while themes define styling. Official files are downloaded during development/CI, not maintained in this repository. This refactor is unreleased and uses v28.0.0 as its baseline. Source clones must build installable templates first; release archives contain ready-to-copy files. Check the [compatibility matrix](COMPATIBILITY.md) before choosing a published archive.
|
||||
|
||||
---
|
||||
|
||||
@@ -28,17 +28,17 @@ The templates on `main` can replace Gitea's built-in mail templates without patc
|
||||
|  | **Horizon** | Enterprise / Corporate | Blue accent, slate typography, centered cards |
|
||||
|  | **Terminal** | Developers / Tech | Dark mode, monospace, green CLI accents |
|
||||
|  | **Ember** | Community / Open Source | Warm amber, rounded, humanist, inclusive |
|
||||
|  | **Bloom** | Creative / Startup | Frosted glass, soft blue light, iridescent accents |
|
||||
|  | **Heritage** | Education / Research | Navy and gold, serif, classic, authoritative |
|
||||
|  | **Bloom** | Creative / Startup | Blue glass cards, soft gradients, rounded buttons |
|
||||
|  | **Heritage** | Education / Research | Paper texture palette, navy & gold, double borders, serif typography |
|
||||
|  | **Neon** | Gaming / Web3 / Creative Tech | Cyberpunk neon glow, hot pink & cyan, synthwave energy |
|
||||
|  | **Mono** | Design Studios / Editorial | Swiss brutalist, black & white, red accent, zero radius |
|
||||
|  | **Terra** | Sustainability / Wellness | Warm earth tones, organic textures, humanist serif |
|
||||
|  | **Ink** | Publishing / News / Literature | Editorial print, navy & gold, newspaper layout, drop caps |
|
||||
|  | **Terra** | Sustainability / Wellness | Earth tones, terracotta buttons, organic accents, soft cards |
|
||||
|  | **Ink** | Publishing / News / Literature | Newspaper columns, navy & gold rules, editorial serif and drop caps |
|
||||
|  | **Aurora** | Premium SaaS / Mindfulness | Ethereal light gradients, deep purple & teal, atmospheric glow |
|
||||
|
||||
The gallery shows the themes currently included in this repository; new themes can be added as separate directories under `themes/`.
|
||||
|
||||
> Images are screenshots from the [local preview](preview/index.html). See [docs/images/README.md](docs/images/README.md) for capture instructions.
|
||||
> Gallery images show the current shared-framework source build, not historical release archives. Original theme palettes, typography, header treatment and button/fallback controls are preserved. See the [local preview](preview/index.html) and [capture instructions](docs/images/README.md).
|
||||
|
||||
[**Local preview gallery**](preview/index.html) — generate the preview data as described below, then open it in a browser for an interactive style switcher with desktop/mobile viewports and view mode (Modern, Source).
|
||||
|
||||
@@ -48,14 +48,23 @@ The gallery shows the themes currently included in this repository; new themes c
|
||||
|
||||
### Quick Start
|
||||
|
||||
Choose a style, then copy the `mail/` directory into your Gitea custom templates path:
|
||||
For a source clone, build from the committed `gitea.lock.json` first (Go 1.24+; first build downloads locked inputs if the cache is absent). A missing lock is an error; the tool never selects the latest Gitea automatically:
|
||||
|
||||
```bash
|
||||
cd tools
|
||||
go run . build all
|
||||
cd ..
|
||||
```
|
||||
|
||||
Choose a style, then copy its generated `mail/` directory into your Gitea custom templates path. A release archive uses `themes/<name>/mail/` instead of `build/themes/<name>/mail/`:
|
||||
|
||||
```bash
|
||||
# Locate your Gitea custom directory
|
||||
# (set by GITEA_CUSTOM; defaults shown below)
|
||||
|
||||
# Copy templates (example: Horizon style)
|
||||
cp -r themes/horizon/mail/* /var/lib/gitea/custom/templates/mail/
|
||||
mkdir -p /var/lib/gitea/custom/templates/mail
|
||||
cp -r build/themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
|
||||
|
||||
# Restart Gitea
|
||||
systemctl restart gitea
|
||||
@@ -63,7 +72,9 @@ systemctl restart gitea
|
||||
|
||||
### Custom Directory Location
|
||||
|
||||
| Platform | Default Path |
|
||||
The paths below are common deployment examples, not universal defaults. Confirm your instance's configured custom path before copying files.
|
||||
|
||||
| Platform | Example Custom Path |
|
||||
|---|---|
|
||||
| Linux (binary) | `/var/lib/gitea/custom` |
|
||||
| Linux (Docker) | `/data/gitea` |
|
||||
@@ -71,10 +82,10 @@ systemctl restart gitea
|
||||
|
||||
### Switching Styles
|
||||
|
||||
Overwrite the files with a different style. All templates share the exact same variable structure — no configuration changes needed.
|
||||
Back up your current mail overrides before switching styles. Remove files installed by the previous theme (listed in its `build.json`), then install the new theme's complete output. This matters when switching from `framed` to `shared`: stale per-email overrides would continue using the previous layout. Preserve unrelated custom templates.
|
||||
|
||||
```bash
|
||||
cp -r themes/terminal/mail/* /var/lib/gitea/custom/templates/mail/
|
||||
cp -r build/themes/terminal/mail/. /var/lib/gitea/custom/templates/mail/
|
||||
systemctl restart gitea
|
||||
```
|
||||
|
||||
@@ -89,7 +100,13 @@ reset email — it will render with your custom styles.
|
||||
|
||||
## Preview
|
||||
|
||||
Two modes are available — a static preview that needs no server after generation, and a live-reload dev server for design work. A source clone must generate preview data first. Existing v28.0.0 and earlier archives do not contain the preview or gallery screenshots; the updated packaging workflow includes both for future builds.
|
||||
Static preview works without a server after generation; the development server supports live reload. A source clone must generate the manifest and per-language bundles first. The refactor packages all official languages in future archives. Existing v28.0.0 and earlier archives retain their original contents.
|
||||
|
||||
### Official Inputs (`upstream`)
|
||||
|
||||
Run from `tools/`: `go run . upstream prepare` downloads an absent cache using the existing lock; `go run . upstream verify` checks an existing cache offline; `go run . upstream sync --tag vX.Y.Z` explicitly replaces the version and generates the lock. All support `--root <repository-root>` after the subcommand (default `..`).
|
||||
|
||||
Without the root lock, preparation, verification, build and preview fail. Restore the tracked lock for a normal clone; intentional initialization can use `go run . upstream sync --tag v28.0.0`. Sync requires network access, accepts stable Gitea 28+ tags, and does not update documentation or publish releases. Damaged/mismatched caches require inspection and recovery, not an automatic repair. See the [full command and recovery guide](CONTRIBUTING.md#official-snapshot-updates).
|
||||
|
||||
### Static Preview
|
||||
|
||||
@@ -104,28 +121,29 @@ cd ..
|
||||
|
||||
### Dev Server (Live Reload)
|
||||
|
||||
Start a pure Go development server that watches for `.tmpl` changes, auto-rebuilds, and pushes live updates to the browser via SSE:
|
||||
Start a pure Go development server that watches theme resources, shared framework, lock/cache and fixtures, auto-rebuilds, and pushes live updates via SSE:
|
||||
|
||||
```bash
|
||||
cd tools
|
||||
go run . dev
|
||||
# Open http://localhost:3456 in a browser.
|
||||
# Open http://127.0.0.1:3456 in a browser.
|
||||
```
|
||||
|
||||
| Capability | Static | Dev |
|
||||
|-----------|--------|-----|
|
||||
| Go template rendering | [YES] | [YES] |
|
||||
| Theme/template switching | [YES] | [YES] |
|
||||
| Theme/template/language switching | [YES] | [YES] |
|
||||
| Live reload on save | [NO] | [YES] |
|
||||
|
||||
### Features
|
||||
|
||||
- Theme switcher — browse all available visual styles
|
||||
- Template switcher — all 11 email types
|
||||
- Template switcher — mail types discovered from the official snapshot (currently 11)
|
||||
- Language switcher — all official locale files (28 in the v28.0.0 snapshot), loaded on demand
|
||||
- View mode — Modern (rendered preview), Source (raw HTML)
|
||||
- Viewport toggle — Desktop 1386×780 / Mobile 390×780
|
||||
- Parameter panel — mock data per email type
|
||||
- Keyboard shortcuts — `←→` tab between Theme/Template/View, `↑↓` select within, `d`/`m` viewport
|
||||
- Keyboard shortcuts — `←→` tab between Theme/Template/Language/View, `↑↓` select within, `d`/`m` viewport
|
||||
|
||||
---
|
||||
|
||||
@@ -133,17 +151,24 @@ go run . dev
|
||||
|
||||
```
|
||||
gitea-mail-templates/
|
||||
├── themes/ # One directory per visual style, 11 .tmpl files each
|
||||
│ ├── ... # Custom styles are added here as separate directories
|
||||
├── gitea.lock.json # Generated version/commit/checksums, no vendored upstream source
|
||||
├── framework/ # Reusable mail controls and structural layout presets
|
||||
├── themes/ # theme.json and theme.css per style; no mail logic
|
||||
├── build/upstream/ # Downloaded official inputs and license; ignored
|
||||
├── build/themes/ # Generated installable overrides; ignored
|
||||
│ └── <name>/mail/ # Generated files for each source theme
|
||||
├── preview/ # Live preview SPA
|
||||
│ ├── index.html # Style/template/client/viewport switcher
|
||||
│ └── rendered.js # Generated by tools/; ignored in source clones
|
||||
│ ├── index.html # Theme/template/language/view/viewport switcher
|
||||
│ ├── rendered.js # Generated manifest; ignored
|
||||
│ └── rendered/ # Generated per-language JS bundles; ignored
|
||||
├── tools/ # Modular CLI tooling
|
||||
│ ├── tools.go # Main entry point
|
||||
│ ├── cli/ # CLI subcommands (list, create, delete, preview)
|
||||
│ ├── cli/ # CLI commands (upstream, build, preview, dev, list, create, delete)
|
||||
│ ├── config/ # Config types and templates_config.json loading
|
||||
│ ├── data/ # templates_config.json — single source of truth
|
||||
│ ├── preview/ # Template rendering engine
|
||||
│ ├── data/ # Preview metadata and mock contexts
|
||||
│ ├── upstream/ # Snapshot sync and offline verification
|
||||
│ ├── builder/ # Official-context alignment and framework/theme generation
|
||||
│ ├── preview/ # Rendering, locale adapter and dev server
|
||||
│ └── go.mod
|
||||
├── docs/ # Bilingual documentation (English + Simplified Chinese)
|
||||
├── AGENTS.md # AI agent guidance
|
||||
@@ -155,6 +180,8 @@ gitea-mail-templates/
|
||||
|
||||
### Template Types
|
||||
|
||||
These are the official v28.0.0 entrypoints, not individually maintained theme sources. Framework-backed `framed` themes generate them using one alignment layer and shared controls. Optional `shared` mode overrides only the two base partials without adding controls.
|
||||
|
||||
| File | Email Trigger |
|
||||
|---|---|
|
||||
| `mail/user/auth/activate.tmpl` | Account activation |
|
||||
@@ -183,7 +210,7 @@ gitea-mail-templates/
|
||||
<!-- TRACKER:UPSTREAM -->
|
||||
- **Upstream Gitea 28.1.0:** [PENDING]
|
||||
<!-- /TRACKER:UPSTREAM -->
|
||||
- The current source uses Gitea's official template data paths — see [COMPATIBILITY.md](COMPATIBILITY.md) for release-specific limitations
|
||||
- New source architecture targets Gitea 28+ and verifies the pinned snapshot offline; see [COMPATIBILITY.md](COMPATIBILITY.md) for source status and release-specific limitations
|
||||
- Uses only built-in Gitea template functions and official translation keys
|
||||
- No custom template functions or locale patches required
|
||||
|
||||
@@ -191,11 +218,13 @@ gitea-mail-templates/
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Responsive** — Max-width 600px cards; works in all email clients
|
||||
2. **Accessible** — 4.5:1 contrast ratios; semantic HTML
|
||||
3. **Graceful degradation** — Fallback link visible when buttons fail to render
|
||||
4. **Logo support** — References `{{AppUrl}}assets/img/favicon.png` by default
|
||||
5. **Locale-aware** — Notification text uses Gitea's `{{.locale.Tr}}` system; some decorative labels remain theme-specific English text
|
||||
1. **Official mail values** — Preserve notification data, conditions, subjects and functional link targets.
|
||||
2. **Shared controls, separate themes** — One framework owns content alignment and reusable controls; themes own CSS and retain original designs.
|
||||
3. **Responsive** — Current framed themes use 600px cards with 390px mobile previews; test target email clients before deployment.
|
||||
4. **Locale-aware** — Official catalogs supply all text; missing keys follow Gitea's English fallback.
|
||||
5. **Reproducible** — A lightweight lock pins immutable downloads; verified cached builds work offline and install files remain generated.
|
||||
|
||||
Gitea v28.0.0 contains a known Polish invitation placeholder defect. Preview reports `[UPSTREAM-WARN]` and preserves official behavior. Details and validation commands are in [CONTRIBUTING.md](CONTRIBUTING.md#official-snapshot-updates).
|
||||
|
||||
---
|
||||
|
||||
@@ -212,7 +241,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. A Simplified Chinese tran
|
||||
|
||||
## License
|
||||
|
||||
MIT — see [LICENSE](LICENSE). Free to use, modify, and distribute in any Gitea deployment.
|
||||
MIT — see [LICENSE](LICENSE) and [third-party notices](THIRD_PARTY_NOTICES.md). Generated archives retain the official Gitea license and snapshot provenance.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in new issue
Block a user