# Repository Guide

## Scope

- This repository is a static overlay copied into Gitea's custom path; it has no local build, lint, or automated test toolchain.
- Target Gitea 1.27.x; the current files are synchronized with Gitea 1.27.3. Treat upstream theme variables and template structure as version-coupled behavior.

## Themes

- `theme-codecraftsmen-light.css` and `theme-codecraftsmen-dark.css` are self-contained copies of the Gitea 1.27 theme variable sets with CodeCraftsmen overrides.
- Keep their variable names synchronized with the built-in themes from the exact target release. Production Gitea theme assets are hashed, so custom themes must not import built-in theme filenames directly.
- `theme-codecraftsmen-auto.css` selects the custom light and dark themes with `prefers-color-scheme`; verify changes in all three theme modes.
- Keep font and image URLs relative to `public/assets/css/` (`../fonts/...` and `../img/...`) because Gitea serves these files below `/assets/`.
- Preserve `gitea-theme-meta-info`, including both display name and color scheme, so Gitea can discover each theme correctly.
- Do not add overrides under `templates/base/` for branding. Replace the upstream navbar and home page logo images through theme CSS so Gitea template upgrades remain intact.

## Templates

- `templates/custom/header.tmpl` injects Plausible analytics. Every external or inline script must use `nonce="{{ctx.CspScriptNonce}}"` or Gitea's CSP will block it.

## Verification And Deployment

- There is no standalone local renderer. Validate on the target Gitea release across anonymous, authenticated, and administrator pages in light, dark, and auto modes.
- For Gitea upgrades, compare both custom palettes against the built-in light and dark themes from the exact target release before testing.
- Deployment is not automated here. After review, synchronize `public/` and `templates/` to `ansible/roles/gitea/files/theme` in the separate homelab repository.

## Assets

- The bundled fonts and logos are project-supplied and do not grant redistribution rights; do not publish or replace them without confirming the applicable licenses.