chore: refresh docs and adapt workflows for Gitea
This commit is contained in:
KenanZhu committed
1 parent
fec3ace600
commit
f4d96de79e
14 files changed
+986
-505
No files matched your search
@@ -1,54 +1,51 @@
|
||||
# Gitea Mail Templates
|
||||
<!-- DOC-TAGS: {"TRACKER":["BADGE","LATEST-TESTED","UPSTREAM"],"RELEASE":["HEADER","SUMMARY"]} -->
|
||||
|
||||
Polished, drop-in email template themes for self-hosted [Gitea](https://about.gitea.com).
|
||||
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)
|
||||
> 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.
|
||||
|
||||
## Philosophy
|
||||
|
||||
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 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.
|
||||
|
||||
---
|
||||
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 | Style | Audience | Character |
|
||||
|---|---|---|---|
|
||||
|  | **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 | 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 | 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 |
|
||||
| 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 the themes currently included in this repository; new themes can be added as separate directories under `themes/`.
|
||||
|
||||
> 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).
|
||||
|
||||
---
|
||||
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
|
||||
|
||||
### Quick Start
|
||||
### Choose a Package
|
||||
|
||||
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:
|
||||
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
|
||||
@@ -56,147 +53,71 @@ 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/`:
|
||||
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
|
||||
# Locate your Gitea custom directory
|
||||
# (set by GITEA_CUSTOM; defaults shown below)
|
||||
|
||||
# Copy templates (example: Horizon style)
|
||||
mkdir -p /var/lib/gitea/custom/templates/mail
|
||||
cp -r build/themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
|
||||
|
||||
# Restart Gitea
|
||||
cp -r themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
|
||||
systemctl restart gitea
|
||||
```
|
||||
|
||||
### Custom Directory Location
|
||||
|
||||
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` |
|
||||
| Windows | `C:\gitea\custom` |
|
||||
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 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.
|
||||
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.
|
||||
|
||||
```bash
|
||||
cp -r build/themes/terminal/mail/. /var/lib/gitea/custom/templates/mail/
|
||||
systemctl restart gitea
|
||||
```
|
||||
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
|
||||
|
||||
The admin test email does not use custom mail templates. To verify your templates
|
||||
are active, trigger a real email notification. The quickest way is the password
|
||||
reset flow: log out, click **"Forgot password"** on the login page, and check the
|
||||
reset email — it will render with your custom styles.
|
||||
|
||||
---
|
||||
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
|
||||
|
||||
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).
|
||||
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 clone, generate the preview data once, then open the HTML file in a browser:
|
||||
From a source checkout, generate the preview data:
|
||||
|
||||
```bash
|
||||
cd tools
|
||||
go run . preview all
|
||||
cd ..
|
||||
# Open preview/index.html in a browser; no server is needed.
|
||||
```
|
||||
|
||||
### Dev Server (Live Reload)
|
||||
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.
|
||||
|
||||
Start a pure Go development server that watches theme resources, shared framework, lock/cache and fixtures, auto-rebuilds, and pushes live updates via SSE:
|
||||
### Dev Server (Live Reload)
|
||||
|
||||
```bash
|
||||
cd tools
|
||||
go run . dev
|
||||
# Open http://127.0.0.1:3456 in a browser.
|
||||
```
|
||||
|
||||
| Capability | Static | Dev |
|
||||
|-----------|--------|-----|
|
||||
| Go template rendering | [YES] | [YES] |
|
||||
| Theme/template/language switching | [YES] | [YES] |
|
||||
| Live reload on save | [NO] | [YES] |
|
||||
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).
|
||||
|
||||
### Features
|
||||
|
||||
- Theme switcher — browse all available visual styles
|
||||
- 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/Language/View, `↑↓` select within, `d`/`m` viewport
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
gitea-mail-templates/
|
||||
├── 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 # 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 commands (upstream, build, preview, dev, list, create, delete)
|
||||
│ ├── config/ # Config types and templates_config.json loading
|
||||
│ ├── 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
|
||||
├── CONTRIBUTING.md
|
||||
├── LICENSE
|
||||
├── README.md
|
||||
└── .gitignore
|
||||
```
|
||||
|
||||
### 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 |
|
||||
| Control | Options or shortcut |
|
||||
|---|---|
|
||||
| `mail/user/auth/activate.tmpl` | Account activation |
|
||||
| `mail/user/auth/activate_email.tmpl` | Email address verification |
|
||||
| `mail/user/auth/register_notify.tmpl` | New 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 / Pull Request assigned |
|
||||
| `mail/repo/issue/default.tmpl` | Issue / Pull Request updates |
|
||||
| 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
|
||||
|
||||
@@ -206,45 +127,67 @@ These are the official v28.0.0 entrypoints, not individually maintained theme so
|
||||
<!-- RELEASE:SUMMARY -->
|
||||
- **Latest release:** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
|
||||
<!-- /RELEASE:SUMMARY -->
|
||||
- For other Gitea versions, check the [per-version compatibility matrix](COMPATIBILITY.md#compatibility-matrix) before choosing an archive; [PENDING] rows have no verified recommendation. The matching v1.27.2 tag has a known push-notification defect.
|
||||
<!-- TRACKER:UPSTREAM -->
|
||||
- **Upstream Gitea 28.1.0:** [PENDING]
|
||||
<!-- /TRACKER:UPSTREAM -->
|
||||
- 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
|
||||
|
||||
---
|
||||
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.
|
||||
|
||||
## Design Principles
|
||||
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).
|
||||
|
||||
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.
|
||||
## Directory Structure
|
||||
|
||||
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).
|
||||
```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.
|
||||
|
||||
## Documentation
|
||||
### Template Types
|
||||
|
||||
- [English](README.md)
|
||||
- [简体中文](docs/README.zh-CN.md)
|
||||
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
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. A Simplified Chinese translation is available in [docs/](docs/).
|
||||
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
|
||||
|
||||
MIT — see [LICENSE](LICENSE) and [third-party notices](THIRD_PARTY_NOTICES.md). Generated archives retain the official Gitea license and snapshot provenance.
|
||||
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).
|
||||
|
||||
---
|
||||
|
||||
<p align="center">
|
||||
<sub>Not affiliated with the Gitea project. Gitea is a community-managed lightweight code hosting solution written in Go.</sub>
|
||||
</p>
|
||||
This project is not affiliated with Gitea.
|
||||
Reference in new issue
Block a user