# Gitea Mail Template --- [简体中文](docs/README.zh-CN.md) Gitea Mail Template offers a range of email template styles for self-hosted [Gitea](https://about.gitea.com) instances. > Latest release: [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest) The repository includes several themes for Gitea emails, suitable for most deployment scenarios and use cases. Before installing, consult the [compatibility matrix](COMPATIBILITY.md#compatibility-matrix) for your Gitea version and choose the corresponding release archive. ## Style Gallery The gallery shows how the email templates render in the preview tool. | Preview | Theme | Style Features | |---|---|---| | ![Aurora](docs/images/aurora.png) | **Aurora** | Dark purple background, teal accents and a soft glow | | ![Bloom](docs/images/bloom.png) | **Bloom** | Light blue gradients, rounded cards and buttons | | ![Ember](docs/images/ember.png) | **Ember** | Warm orange tones, serif headings and rounded buttons | | ![Heritage](docs/images/heritage.png) | **Heritage** | Navy and gold, double borders and serif fonts | | ![Horizon](docs/images/horizon.png) | **Horizon** | Blue accents, gray text and a centered white card | | ![Ink](docs/images/ink.png) | **Ink** | Newspaper layout, a sidebar, serif fonts and drop caps | | ![Mono](docs/images/mono.png) | **Mono** | Black and white, red accents and square borders | | ![Neon](docs/images/neon.png) | **Neon** | Dark background, pink and cyan accents and glow effects | | ![Terminal](docs/images/terminal.png) | **Terminal** | Dark background, monospace fonts and green accents | | ![Terra](docs/images/terra.png) | **Terra** | Earth tones, terracotta buttons and serif fonts | Screenshots show only the current default build. Use the [local preview](#preview) to view other email types and languages. See the [screenshot guide](docs/images/README.md) when updating screenshots. ## Installation ### Choose an Installation Source Run `gitea --version` to confirm the version of your deployed Gitea instance, then choose a template version from the [compatibility matrix](COMPATIBILITY.md#compatibility-matrix). > [!WARNING] > We do not recommend building directly from the source repository, as these versions have not yet been fully tested for release readiness. Outdated or missing template parameters that have not been identified may prevent your Gitea instance from starting correctly. > [!TIP] > If you still need to build the email templates from source, follow the steps below. | Source | Email Template Directory | Preparation | |---|---|---| | Release archive | `themes//mail/` | Download and extract the recommended release archive | | Source | `build/themes//mail/` | Build with Go 1.24 or later | To build from source, run the following from the repository root: ```bash cd tools go run . build all cd .. ``` Building usable templates requires resources from the official Gitea repository to ensure consistent source inputs. The command automatically downloads the official files pinned by `gitea.lock.json`. Subsequent builds use the cached resources without downloading them again. For missing files or a damaged cache, see [official snapshot updates](CONTRIBUTING.md#official-snapshot-updates). ### Install a Theme Copy the contents of the selected theme's `mail/` directory into `/templates/mail/`, then restart Gitea to apply the theme. Before copying, confirm the custom directory your instance actually uses. Common deployment paths include: | Deployment | Example Custom Directory | |---|---| | Linux binary | `/var/lib/gitea/custom` | | Docker | `/data/gitea` | | Windows | `C:\gitea\custom` | For example, on a Linux host where systemd manages Gitea, run the following from the extracted release archive directory: ```bash systemctl stop gitea mkdir -p /var/lib/gitea/custom/templates/mail cp -r themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/ systemctl restart gitea ``` > [!TIP] > For templates built from source, change the copy source to `build/themes/horizon/mail/.`. For Docker and Windows deployments, use the appropriate container or service controls to stop and restart Gitea. ### Switch Themes Back up or remove the files installed by the previous theme, choose a new email theme, and repeat the installation steps above. ### Confirm the Theme Is Applied Use a test account to trigger an email notification, such as a password reset, and check its appearance and links. The administration panel's test-email button does not use custom email templates, so it cannot confirm whether the theme has been applied. ## Preview The preview tool included in the repository lets you view how emails render across themes, template types and languages before deployment. ### Static Preview First, generate the preview data in the source repository: ```bash cd tools go run . preview all cd .. ``` Open [preview/index.html](preview/index.html) in a browser. No server is required. ### Development with Live Reload ```bash cd tools go run . dev # Press Ctrl+C in the terminal to stop the server. cd .. ``` Open [http://127.0.0.1:3456](http://127.0.0.1:3456). The Go server watches theme files, the shared framework, the lock file and cache, and preview test data. When a file changes, it rebuilds the email templates and refreshes the page through server-sent events (SSE) to provide live reload. ### Controls and Keyboard Shortcuts | Control | Options or Shortcuts | |---|---| | Theme, template, language and view | `←` / `→` moves between selectors; `↑` / `↓` selects an option | | View | **Modern** displays the rendered result; **Source** displays the generated HTML text | | Viewport | **Desktop** (1386 × 780), **Mobile** (390 × 780); shortcuts `d` / `m` | | Information panel | `p` expands or collapses the panel | > [!WARNING] > The preview renders templates using example data. Browsers and email clients differ in their CSS support, so check the appearance in your target email clients before deployment. ## 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] ## Project Directory Structure The project is organized around a shared framework, theme styles and build tools. Source code and documentation are tracked in version control; downloaded official files, generated templates and preview data are not. ### Tracked in Version Control ```text .github/ # Workflows and maintenance scripts release-notes/ # Release notes for each version scripts/ # Documentation updates, packaging and Gitea release scripts workflows/ # Validation and publication docs/ # Chinese documentation, documentation index and gallery images framework/ # Shared email controls and layout presets layouts/ # Layout presets shared across email types mail/base/ # Header, action buttons, fallback links, sidebar and footer preview/index.html # Preview interface themes// # Theme source files tools/ # Go CLI, build tools and tests builder/ # Official template adaptation and theme generation cli/ # Command definitions and argument handling config/ # Preview configuration loading and validation data/ # Email type descriptions and preview example data preview/ # Email rendering, locale adaptation and development server upstream/ # Official snapshot downloads, verification and translation key discovery gitea.lock.json # Official version tag, commit and file checksums README.md ``` Official templates provide notification content, conditions, subject lines and links. The shared framework handles email presentation, while themes use metadata and CSS to select layouts and define styles. Theme directories do not contain official email source files or translations. ### Not Tracked in Version Control The following files are generated by the build and preview commands or downloaded according to the lock file. They do not need to be maintained manually or committed: ```text build/themes// # Theme build output mail/ # Email templates ready to install in Gitea build.json # Build provenance and generated file checksums build/upstream/ # Official templates, locales, assets and licenses pinned by the lock file dist/ # Default output directory for release archives preview/rendered.js # Preview manifest preview/rendered/.js # Preview data for each locale ``` `build all` generates installable templates for all themes. `preview all` generates both templates and preview data for each locale. On first use, the tools prepare any missing official file cache according to `gitea.lock.json`; subsequent uses verify the cache before proceeding. ### Template Types Gitea currently includes the following 11 email templates [1](#notes): | File | Notification Type | |---|---| | `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` | New release published | | `mail/repo/actions/workflow_run.tmpl` | Actions workflow run | | `mail/repo/issue/assigned.tmpl` | Issue or pull request assignment | | `mail/repo/issue/default.tmpl` | Issue or pull request activity | ## Contributing Contributions to themes, tools, documentation and translations are welcome. The [contributor guide](CONTRIBUTING.md) covers local environment setup, design guidelines, required checks and the release process. ## License This project is licensed under [MIT](LICENSE). Generated release archives retain Gitea's license and snapshot provenance. --- ### Notes [1](#notes): [Mail templates | Gitea Documentation](https://docs.gitea.com/administration/mail-templates/) This project is not affiliated with Gitea.