Forgejo Theme Forge

A browser-based ThemeBuilder for Forgejo/Gitea themes: choose a researched preset, customize the color system, preview it on a Forgejo-like UI, then export a theme-*.css file.

Why this works for Forgejo

Research summary used by the app:

• Forgejo custom files live under CustomPath / $FORGEJO_CUSTOM. The app config is usually $FORGEJO_CUSTOM/conf/app.ini; distro installs may use /etc/forgejo/app.ini.

• Custom public assets are served from $FORGEJO_CUSTOM/public/assets/.

• A theme CSS file should be placed at $FORGEJO_CUSTOM/public/assets/css/theme-your-slug.css.

• Register the theme name without the theme- prefix or .css suffix in app.ini:

  [ui]
  THEMES = forgejo-auto,forgejo-light,forgejo-dark,your-slug
  DEFAULT_THEME = your-slug
  

• Restart Forgejo after configuration changes. Existing users can also pick a theme in Settings → Appearance.

• Forgejo's upstream themes are CSS-variable-heavy (--color-primary, --color-body, --color-box-body, diff colors, console colors, badge colors, fonts, etc.), so the least-invasive custom theme is usually an import of a base theme plus variable overrides.

Primary references:

• Forgejo interface customization docs: https://forgejo.org/docs/latest/developer/customization/
• Forgejo config cheat sheet ([ui] THEMES, DEFAULT_THEME): https://forgejo.org/docs/latest/admin/config-cheat-sheet/
• Upstream Forgejo dark theme variables: https://codeberg.org/forgejo/forgejo/raw/branch/forgejo/web_src/css/themes/theme-forgejo-dark.css
• Upstream Forgejo light theme variables: https://codeberg.org/forgejo/forgejo/raw/branch/forgejo/web_src/css/themes/theme-forgejo-light.css
• Dark Arc Gitea/Forgejo theme: https://github.com/Jieiku/theme-dark-arc-gitea
• Catppuccin Gitea themes: https://github.com/catppuccin/gitea
• Matt Dark Forgejo/Gitea theme: https://git.matt-barnes.co.uk/mb2g17/matt-dark-forgejo-theme
• Theme Park Gitea docs: https://docs.theme-park.dev/themes/gitea/
• Forgejo theming walkthrough: https://blog.maximlucas.dev/posts/2025-08-28-theming-forgejo/

Development

pnpm install
pnpm run dev
pnpm run build

Export format

The generated CSS imports a built-in base theme and overrides Forgejo variables:

@import url("theme-forgejo-dark.css");

:root {
  --color-primary: #fb923c !important;
  --color-body: #171e26 !important;
  /* ... */
}

If a Forgejo deployment cannot resolve the imported base theme from custom CSS, copy the upstream base theme into the same custom CSS directory first, or paste the generated variable block at the bottom of a copied upstream theme file.

Installed custom theme

themes/theme-clank-preview-square.css is the custom Forgejo theme currently installed on forge.dikka.dev as clank-preview-square. It keeps the green-on-graphite preview colors but avoids broad rounded corners because Forgejo's nested Semantic UI layouts clip and misalign when large radii are applied globally.