194 lines
10 KiB
Markdown
194 lines
10 KiB
Markdown
# Gitea Mail Templates
|
||
<!-- DOC-TAGS: {"TRACKER":["BADGE","LATEST-TESTED","UPSTREAM"],"RELEASE":["HEADER","SUMMARY"]} -->
|
||
|
||
Email themes for self-hosted [Gitea](https://about.gitea.com), with a local preview and tools for building custom mail templates.
|
||
|
||
[简体中文](docs/README.zh-CN.md) · [Installation](#installation) · [Preview](#preview) · [Compatibility](COMPATIBILITY.md) · [Contributing](CONTRIBUTING.md)
|
||
|
||
<!-- TRACKER:BADGE -->
|
||
[](COMPATIBILITY.md)
|
||
<!-- /TRACKER:BADGE -->
|
||
|
||
<!-- RELEASE:HEADER -->
|
||
> Latest release: [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
|
||
<!-- /RELEASE:HEADER -->
|
||
|
||
The repository includes ten themes for account, repository, issue and workflow notifications. Gitea supplies notification content and translations; themes provide the visual presentation.
|
||
|
||
The source architecture on `main` is **unreleased** and uses Gitea v28.0.0 as its baseline. It builds templates from locked official inputs and a shared layout framework. Published archives retain their original contents and compatibility. Use the [compatibility matrix](COMPATIBILITY.md#compatibility-matrix) to choose an archive for your Gitea version.
|
||
|
||
## Style Gallery
|
||
|
||
| Preview | Theme | Appearance |
|
||
|---|---|---|
|
||
|  | **Horizon** | Blue accents, gray text and a centered white card |
|
||
|  | **Terminal** | Dark background, monospace text and green accents |
|
||
|  | **Ember** | Warm orange palette, serif headings and rounded buttons |
|
||
|  | **Bloom** | Light blue gradients, rounded cards and buttons |
|
||
|  | **Heritage** | Navy and gold accents, double borders and serif text |
|
||
|  | **Neon** | Dark background, pink and cyan accents and glow effects |
|
||
|  | **Mono** | Black and white, red accents and square borders |
|
||
|  | **Terra** | Earth tones, terracotta buttons and serif text |
|
||
|  | **Ink** | Newspaper layout, sidebar, serif text and drop caps |
|
||
|  | **Aurora** | Dark purple background, teal accents and soft glow effects |
|
||
|
||
Images show the current source build. For other mail types and languages, generate the [local preview](#preview). See the [capture guide](docs/images/README.md) when updating screenshots.
|
||
|
||
## Installation
|
||
|
||
### Choose a Package
|
||
|
||
Check your Gitea version with `gitea --version`, then select a template release from the [compatibility matrix](COMPATIBILITY.md#compatibility-matrix).
|
||
|
||
| Source | Mail template directory | Preparation |
|
||
|---|---|---|
|
||
| Release archive | `themes/<name>/mail/` | Download and extract the archive for the recommended release |
|
||
| Source checkout | `build/themes/<name>/mail/` | Build with Go 1.24 or later |
|
||
|
||
For a source checkout, run from the repository root:
|
||
|
||
```bash
|
||
cd tools
|
||
go run . build all
|
||
cd ..
|
||
```
|
||
|
||
The first build downloads the official files pinned by `gitea.lock.json` if the cache is absent. Later builds verify the cache before use. The root lock file is required; missing or damaged inputs are covered in the [setup and recovery guide](CONTRIBUTING.md#official-snapshot-updates).
|
||
|
||
### Install a Theme
|
||
|
||
Copy the chosen theme's `mail/` contents into `<GITEA_CUSTOM>/templates/mail/`, then restart Gitea. Confirm your instance's custom directory before copying files. Common deployment paths include:
|
||
|
||
| Deployment | Example custom directory |
|
||
|---|---|
|
||
| Linux binary | `/var/lib/gitea/custom` |
|
||
| Docker | `/data/gitea` |
|
||
| Windows | `C:\gitea\custom` |
|
||
|
||
For example, from an extracted release archive on a Linux host managed by systemd:
|
||
|
||
```bash
|
||
mkdir -p /var/lib/gitea/custom/templates/mail
|
||
cp -r themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
|
||
systemctl restart gitea
|
||
```
|
||
|
||
For a source build, use `build/themes/horizon/mail/.` as the copy source. Docker and Windows installations should restart Gitea using their deployment's service or container controls.
|
||
|
||
### Switching Styles
|
||
|
||
Back up existing mail overrides before replacing a theme. Remove the previous theme's installed files, then copy the new theme's complete output. Current source builds include a `build.json` file listing the generated files; for historical archives, refer to the archive contents. Preserve unrelated custom templates.
|
||
|
||
Removing old overrides is especially important when switching from `framed` to `shared` mode: files left behind can keep the previous theme's layout.
|
||
|
||
### Confirming It Works
|
||
|
||
Trigger a notification that uses Gitea's mail templates, such as a password-reset email for a test account, and check its appearance and links. The administration test-email button does not use custom mail templates.
|
||
|
||
## Preview
|
||
|
||
The preview supports theme, mail type and language selection, rendered HTML and source views, desktop/mobile viewports, and a panel showing the example data. The v28.0.0 snapshot contains 11 mail types and 28 languages.
|
||
|
||
### Static Preview
|
||
|
||
From a source checkout, generate the preview data:
|
||
|
||
```bash
|
||
cd tools
|
||
go run . preview all
|
||
cd ..
|
||
```
|
||
|
||
Open [preview/index.html](preview/index.html) in a browser. Generated language bundles load on demand and work over `file://`, so no server is needed. Archives produced by the current packaging script include these bundles; historical archives retain their original preview contents.
|
||
|
||
### Dev Server (Live Reload)
|
||
|
||
```bash
|
||
cd tools
|
||
go run . dev
|
||
```
|
||
|
||
Open [http://127.0.0.1:3456](http://127.0.0.1:3456). The Go server watches theme files, the shared framework, the lock/cache and preview fixtures. Changes trigger a rebuild and browser refresh through server-sent events (SSE).
|
||
|
||
| Control | Options or shortcut |
|
||
|---|---|
|
||
| Theme, template, language and view | `←` / `→` moves between selectors; `↑` / `↓` selects an option |
|
||
| View | **Modern** for rendered HTML; **Source** for generated HTML text |
|
||
| Viewport | **Desktop** (1386 × 780), **Mobile** (390 × 780); `d` / `m` |
|
||
| Information panel | `p` toggles the panel |
|
||
|
||
The preview renders templates using example data. Check your target mail clients separately; browser rendering does not reproduce their CSS support.
|
||
|
||
## Compatibility
|
||
|
||
<!-- TRACKER:LATEST-TESTED -->
|
||
- **Latest tested:** Gitea 28.0.0
|
||
<!-- /TRACKER:LATEST-TESTED -->
|
||
<!-- RELEASE:SUMMARY -->
|
||
- **Latest release:** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
|
||
<!-- /RELEASE:SUMMARY -->
|
||
<!-- TRACKER:UPSTREAM -->
|
||
- **Upstream Gitea 28.1.0:** [PENDING]
|
||
<!-- /TRACKER:UPSTREAM -->
|
||
|
||
The current source architecture targets Gitea 28 and later, with compatibility verified against the locked version. A newer upstream release remains pending until reviewed. Earlier Gitea versions require the packages listed in the [compatibility matrix](COMPATIBILITY.md#compatibility-matrix), which also records the incomplete push-notification fix in v1.27.2.
|
||
|
||
Generated templates use Gitea's built-in functions and official translation keys. Missing translations fall back to English. The locked v28.0.0 catalog has a known Polish invitation formatting defect; preview reports `[UPSTREAM-WARN]` and preserves the official output. See [known limitations](COMPATIBILITY.md#snapshot-driven-source-status).
|
||
|
||
## Directory Structure
|
||
|
||
```text
|
||
gitea.lock.json # Official tag, commit and file checksums
|
||
framework/ # Shared mail controls and layout presets
|
||
themes/<name>/ # Theme metadata (theme.json) and CSS (theme.css)
|
||
tools/ # Go CLI, build tools and tests
|
||
cli/ # Command definitions
|
||
upstream/ # Snapshot downloads, verification and key discovery
|
||
builder/ # Official template adaptation and theme generation
|
||
preview/ # Mail rendering, locale adapter and development server
|
||
config/, data/ # Preview metadata and example contexts
|
||
integration/, qa/ # Optional Gitea and browser checks
|
||
preview/ # Browser UI; generated manifest and language bundles
|
||
docs/ # Simplified Chinese guides and gallery images
|
||
.github/ # Workflows, release notes and packaging/tracking scripts
|
||
build/upstream/ # Downloaded official inputs (ignored)
|
||
build/themes/ # Generated installable templates (ignored)
|
||
```
|
||
|
||
Gitea's official templates define notification data, conditions, subjects and URLs. The shared framework arranges these into headers, action buttons, fallback links and footers. Themes define colors, typography and spacing. See [theme development](CONTRIBUTING.md#adding-a-theme) for the `framed` and `shared` modes.
|
||
|
||
### Template Types
|
||
|
||
Mail types are discovered from the locked snapshot. The v28.0.0 entrypoints are:
|
||
|
||
| File | Notification |
|
||
|---|---|
|
||
| `mail/user/auth/activate.tmpl` | Account activation |
|
||
| `mail/user/auth/activate_email.tmpl` | Email address verification |
|
||
| `mail/user/auth/register_notify.tmpl` | Registration notification |
|
||
| `mail/user/auth/reset_passwd.tmpl` | Password reset |
|
||
| `mail/org/team_invite.tmpl` | Team invitation |
|
||
| `mail/repo/collaborator.tmpl` | Repository collaborator added |
|
||
| `mail/repo/transfer.tmpl` | Repository ownership transfer |
|
||
| `mail/repo/release.tmpl` | Release published |
|
||
| `mail/repo/actions/workflow_run.tmpl` | Actions workflow run |
|
||
| `mail/repo/issue/assigned.tmpl` | Issue or pull request assigned |
|
||
| `mail/repo/issue/default.tmpl` | Issue or pull request activity |
|
||
|
||
## Contributing
|
||
|
||
Contributions to themes, tooling, documentation and translations are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, design guidelines, checks and release procedures.
|
||
|
||
## Documentation
|
||
|
||
- [简体中文使用说明](docs/README.zh-CN.md)
|
||
- [Contributor guide](CONTRIBUTING.md) · [简体中文贡献指南](docs/CONTRIBUTING.zh-CN.md)
|
||
- [Compatibility and template reference](COMPATIBILITY.md)
|
||
- [Gallery capture guide](docs/images/README.md)
|
||
|
||
## License
|
||
|
||
This project is licensed under [MIT](LICENSE). Generated release archives retain Gitea's license and snapshot provenance; see [third-party notices](THIRD_PARTY_NOTICES.md).
|
||
|
||
This project is not affiliated with Gitea.
|