# Gitea Mail Templates 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) [![Gitea](https://img.shields.io/badge/Gitea-28.1.0%20%5BPENDING%5D%20%7C%2028.0.0%20tested-yellow)](COMPATIBILITY.md) > Latest release: [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest) 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](docs/images/horizon.png) | **Horizon** | Blue accents, gray text and a centered white card | | ![Terminal](docs/images/terminal.png) | **Terminal** | Dark background, monospace text and green accents | | ![Ember](docs/images/ember.png) | **Ember** | Warm orange palette, serif headings and rounded buttons | | ![Bloom](docs/images/bloom.png) | **Bloom** | Light blue gradients, rounded cards and buttons | | ![Heritage](docs/images/heritage.png) | **Heritage** | Navy and gold accents, double borders and serif text | | ![Neon](docs/images/neon.png) | **Neon** | Dark background, pink and cyan accents and glow effects | | ![Mono](docs/images/mono.png) | **Mono** | Black and white, red accents and square borders | | ![Terra](docs/images/terra.png) | **Terra** | Earth tones, terracotta buttons and serif text | | ![Ink](docs/images/ink.png) | **Ink** | Newspaper layout, sidebar, serif text and drop caps | | ![Aurora](docs/images/aurora.png) | **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//mail/` | Download and extract the archive for the recommended release | | Source checkout | `build/themes//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 `/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 - **Latest tested:** Gitea 28.0.0 - **Latest release:** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest) - **Upstream Gitea 28.1.0:** [PENDING] 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// # 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.