From efa6607558798c45d703cc3188f384001f76ca5c Mon Sep 17 00:00:00 2001
From: wxiaoguang <29147+wxiaoguang@noreply.gitea.com>
Date: Fri, 3 Apr 2026 18:25:12 +0000
Subject: [PATCH] GitHub-like theme-based image display (#372)

---
 docs/usage/repository/markdown.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/usage/repository/markdown.md b/docs/usage/repository/markdown.md
index b3db34d7..89cd05c0 100644
--- a/docs/usage/repository/markdown.md
+++ b/docs/usage/repository/markdown.md
@@ -76,6 +76,33 @@ It will be rendered with issue titles to:
 * the other issue title (#456)
 ```
 
+## Theme-based image display
+
+Gitea supports the GitHub-like theme-based image display. Supported syntax:
+
+* Use Markdown image
+
+```
+![My-Light](my-light.png#gh-light-mode-only)![My-Dark](my-dark.png#gh-dark-mode-only)
+```
+
+* Use `<img>` HTML tag
+
+```
+<img src="my-light.png#gh-light-mode-only" height="120" width="120"/>
+<img src="my-dark.png#gh-dark-mode-only" height="120" width="120"/>
+```
+
+* Use `<picture>` with `<source media>` (only works for themes with "auto" color preference)
+
+```
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="my-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="my-light.png">
+  <img src="my-light.png">
+</picture>
+```
+
 ## Math expressions
 
 Gitea supports GitHub-like math expression formatting.