Forgejo & Gitea Gruvbox Theme

Bring the warm, retro-modern, terminal-esque Gruvbox dark aesthetic to your self-hosted Git forge. This repository offers a clean custom theme along with responsive templates for a fully tailored experience.

Screenshots

Expand to see the theme in action

Homepage

GitHub-style 2-Column Repository View

Code Blocks (markdown)

User Dashboard

Explore Repositories

User Profile

Settings

---

Choose Your Setup

Automated releases bundle two different installation flavors. Choose the one that matches your customization preferences:

Option A: The Minimalist (gruvbox-theme)

Perfect if you want a clean, stock Gitea/Forgejo experience styled with the classic Gruvbox palette.

• Included: Custom monospace fonts (Maple Mono, Geist Mono, Lexend) + theme CSS (theme-gruvbox.css).
• Changes: Syntax highlighting, user interfaces, inputs, and general pages styled with the dark Gruvbox palette. Default page structures remain completely unchanged.

Option B: The Revamped (gruvbox-theme-custom-templates)

Perfect if you want a fully customized, workspace-styled developer homepage and GitHub-like page flows.

• Included: Everything in Option A + custom layout files (templates/) + global tweaks (custom.css).
• Visual Additions:
  • Interactive Terminal Mockup (templates/home.tmpl): Redesigns the default landing page into a retro terminal dashboard. Dynamically queries Gitea/Forgejo's search API to render active repository counts, custom system specs, and ASCII graphics.
  • 2-Column Repository View (templates/repo/home.tmpl): Re-organizes Gitea/Forgejo's standard repository home page into a clean, modern two-column view (mirroring GitHub's layout). The file tree resides on the left, while descriptive metadata, topics, size, and language stats sit in a dedicated right sidebar.
  • Polished Repo Elements (templates/repo/sub_menu.tmpl): Streamlines branch/tag dropdowns, pull request triggers, and commit counts.
  • Global Style Injection (templates/custom/header.tmpl): Loads the custom interface overrides dynamically.

---

How to apply the theme?

Note

: Because Forgejo is a fork of Gitea, this setup works identically on both platforms.

1. Download & Extract

1. Get the latest package archive from the releases page for your chosen option.
2. Extract the package files directly into your instance's custom folder (usually named custom in the root of your installation).

Directory Structure after extraction:

custom/
├── public/
│   └── assets/
│       ├── css/
│       │   ├── theme-gruvbox.css
│       │   └── custom.css (Option B only)
│       └── fonts/
│           └── [maple-mono/geist-mono/lexend-woff2-files]
└── templates/ (Option B only)
    ├── home.tmpl
    ├── custom/
    │   └── header.tmpl
    └── repo/
        ├── home.tmpl
        └── sub_menu.tmpl

Note: For Gitea versions prior to v1.20, the CSS folder path should be custom/public/css/ instead.

Docker Compose Mounting

If you are running in Docker, map the extracted folders inside your container:

services:
  forgejo: # or gitea
    # ...
    volumes:
      - /path/to/custom/templates:/data/gitea/templates
      - /path/to/custom/public:/data/gitea/public

2. Enable in your Config

Open your instance's configuration file (usually located at custom/conf/app.ini) and register gruvbox in the [ui] section:

[ui]
; Append 'gruvbox' to the list of active themes
THEMES = forgejo-auto,forgejo-light,forgejo-dark,gitea-dark,gruvbox

; (Optional) Set it as the default theme for guests and new users
DEFAULT_THEME = gruvbox

3. Restart the Service

Restart your Git server to apply the configurations:

# systemd (Binary installation)
sudo systemctl restart forgejo # or gitea

# Docker Compose
docker restart <forgejo_container>

4. Switch Theme on Your Account

If you did not make it the global default, select it inside your user account:

1. Log in to your account.
2. Click your avatar (top-right) and navigate to Settings > Appearance.
3. Under Default Theme, choose gruvbox and click Change Theme.

---

Resources & Help

• Official Forgejo Customization Guide
• Official Gitea Theme Documentation