From 1fa499ec22561676e42bcfd413d2982860137816 Mon Sep 17 00:00:00 2001
From: Tom Riddle <1+root@noreply.sakamoto.best>
Date: Wed, 12 Aug 2026 22:49:15 +0000
Subject: [PATCH] Update README.md

---
 README.md | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8b5a712..31e0b67 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,27 @@
 # Gitea-Themes
 
-List of custom Gitea themes for self-hosted Gitea instance.
\ No newline at end of file
+List of custom Gitea themes for self-hosted Gitea instance.
+
+# Customizing the look of Gitea
+The built-in themes are `gitea-light`, `gitea-dark`, and `gitea-auto` (which automatically adapts to OS settings).
+
+The default theme can be changed via `DEFAULT_THEME` in the [ui](https://docs.gitea.com/administration/config-cheat-sheet/#ui-ui) section of `app.ini`.
+
+Gitea also has support for user themes, which means every user can select which theme should be used. The list of themes a user can choose from can be configured with the `THEMES` value in the [ui](https://docs.gitea.com/administration/config-cheat-sheet/#ui-ui) section of `app.ini`.
+
+To make a custom theme available to all users:
+1. Add a CSS file to `$GITEA_CUSTOM/public/assets/css/theme-<theme-name>.css`. The value of `$GITEA_CUSTOM` of your instance can be queried by calling `gitea help` and looking up the value of “CustomPath”.
+2. Add `<theme-name>` to the comma-separated list of setting `THEMES` in `app.ini`, or leave `THEMES` empty to allow all themes.
+
+A custom theme file named `theme-my-theme.css` will be displayed as `my-theme` on the user’s theme selection page. It could add theme meta information into the custom theme CSS file to provide more information about the theme. If a custom theme is a dark theme, please set the global css variable `--is-dark-theme: true` in the `:root` block. This allows Gitea to adjust the Monaco code editor’s theme accordingly. An “auto” theme could be implemented by using “theme-gitea-auto.css” as a reference.
+
+```css
+gitea-theme-meta-info {
+  --theme-display-name: "My Awesome Theme"; /* this theme will be display as "My Awesome Theme" on the UI */
+}
+:root {
+  --is-dark-theme: true; /* if it is a dark theme */
+  --color-primary: #112233;
+  /* more custom theme variables ... */
+}
+```
\ No newline at end of file