chore: simplify workflows and unify tool logging and mail presentation
This commit is contained in:
KenanZhu committed
1 parent
f4d96de79e
commit
c93f2bf8b2
40 files changed
+523
-1515
No files matched your search
@@ -1,51 +1,51 @@
|
||||
# Gitea Mail Templates
|
||||
<!-- DOC-TAGS: {"TRACKER":["BADGE","LATEST-TESTED","UPSTREAM"],"RELEASE":["HEADER","SUMMARY"]} -->
|
||||
# Gitea Mail Template
|
||||
---
|
||||
|
||||
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)
|
||||
|
||||
[简体中文](docs/README.zh-CN.md) · [Installation](#installation) · [Preview](#preview) · [Compatibility](COMPATIBILITY.md) · [Contributing](CONTRIBUTING.md)
|
||||
Gitea Mail Template offers a range of email template styles for self-hosted [Gitea](https://about.gitea.com) instances.
|
||||
|
||||
<!-- 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.
|
||||
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
|
||||
|
||||
| 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 |
|
||||
The gallery shows how the email templates render in the preview tool.
|
||||
|
||||
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.
|
||||
| Preview | Theme | Style Features |
|
||||
|---|---|---|
|
||||
|  | **Aurora** | Dark purple background, teal accents and a soft glow |
|
||||
|  | **Bloom** | Light blue gradients, rounded cards and buttons |
|
||||
|  | **Ember** | Warm orange tones, serif headings and rounded buttons |
|
||||
|  | **Heritage** | Navy and gold, double borders and serif fonts |
|
||||
|  | **Horizon** | Blue accents, gray text and a centered white card |
|
||||
|  | **Ink** | Newspaper layout, a sidebar, serif fonts and drop caps |
|
||||
|  | **Mono** | Black and white, red accents and square borders |
|
||||
|  | **Neon** | Dark background, pink and cyan accents and glow effects |
|
||||
|  | **Terminal** | Dark background, monospace fonts and green accents |
|
||||
|  | **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 a Package
|
||||
### Choose an Installation Source
|
||||
|
||||
Check your Gitea version with `gitea --version`, then select a template release from the [compatibility matrix](COMPATIBILITY.md#compatibility-matrix).
|
||||
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).
|
||||
|
||||
| Source | Mail template directory | Preparation |
|
||||
> [!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/<name>/mail/` | Download and extract the archive for the recommended release |
|
||||
| Source checkout | `build/themes/<name>/mail/` | Build with Go 1.24 or later |
|
||||
| Release archive | `themes/<name>/mail/` | Download and extract the recommended release archive |
|
||||
| Source | `build/themes/<name>/mail/` | Build with Go 1.24 or later |
|
||||
|
||||
For a source checkout, run from the repository root:
|
||||
To build from source, run the following from the repository root:
|
||||
|
||||
```bash
|
||||
cd tools
|
||||
@@ -53,45 +53,45 @@ 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).
|
||||
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 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:
|
||||
Copy the contents of the selected theme's `mail/` directory into `<GITEA_CUSTOM>/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 |
|
||||
| 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:
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
> [!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.
|
||||
|
||||
### Switching Styles
|
||||
### Switch Themes
|
||||
|
||||
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.
|
||||
Back up or remove the files installed by the previous theme, choose a new email theme, and repeat the installation steps above.
|
||||
|
||||
Removing old overrides is especially important when switching from `framed` to `shared` mode: files left behind can keep the previous theme's layout.
|
||||
### Confirm the Theme Is Applied
|
||||
|
||||
### 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.
|
||||
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 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.
|
||||
The preview tool included in the repository lets you view how emails render across themes, template types and languages before deployment.
|
||||
|
||||
### Static Preview
|
||||
|
||||
From a source checkout, generate the preview data:
|
||||
First, generate the preview data in the source repository:
|
||||
|
||||
```bash
|
||||
cd tools
|
||||
@@ -99,69 +99,88 @@ 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.
|
||||
Open [preview/index.html](preview/index.html) in a browser. No server is required.
|
||||
|
||||
### Dev Server (Live Reload)
|
||||
### 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/cache and preview fixtures. Changes trigger a rebuild and browser refresh through server-sent events (SSE).
|
||||
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.
|
||||
|
||||
| Control | Options or shortcut |
|
||||
### Controls and Keyboard Shortcuts
|
||||
|
||||
| Control | Options or Shortcuts |
|
||||
|---|---|
|
||||
| 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 |
|
||||
| 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 |
|
||||
|
||||
The preview renders templates using example data. Check your target mail clients separately; browser rendering does not reproduce their CSS support.
|
||||
> [!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
|
||||
|
||||
<!-- 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.
|
||||
## Project Directory Structure
|
||||
|
||||
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).
|
||||
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.
|
||||
|
||||
## Directory Structure
|
||||
### Tracked in Version Control
|
||||
|
||||
```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)
|
||||
.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_NAME>/ # 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
|
||||
```
|
||||
|
||||
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.
|
||||
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_NAME>/ # 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/<LOCALE>.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
|
||||
|
||||
Mail types are discovered from the locked snapshot. The v28.0.0 entrypoints are:
|
||||
Gitea currently includes the following 11 email templates [1](#notes):
|
||||
|
||||
| File | Notification |
|
||||
| File | Notification Type |
|
||||
|---|---|
|
||||
| `mail/user/auth/activate.tmpl` | Account activation |
|
||||
| `mail/user/auth/activate_email.tmpl` | Email address verification |
|
||||
@@ -170,24 +189,23 @@ Mail types are discovered from the locked snapshot. The v28.0.0 entrypoints are:
|
||||
| `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/release.tmpl` | New release published |
|
||||
| `mail/repo/actions/workflow_run.tmpl` | Actions workflow run |
|
||||
| `mail/repo/issue/assigned.tmpl` | Issue or pull request assigned |
|
||||
| `mail/repo/issue/assigned.tmpl` | Issue or pull request assignment |
|
||||
| `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)
|
||||
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; see [third-party notices](THIRD_PARTY_NOTICES.md).
|
||||
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.
|
||||
Reference in new issue
Block a user