diff --git a/docs/developer-guide/theme/api-changelog.md b/docs/developer-guide/theme/api-changelog.md
index 4e666e56..5abf03cf 100644
--- a/docs/developer-guide/theme/api-changelog.md
+++ b/docs/developer-guide/theme/api-changelog.md
@@ -5,6 +5,10 @@ description: 记录每一个版本的主题 API 变更记录，方便开发者
 
 ## 2.25.0
 
+### 主题目录结构 > 新增根目录预览图
+
+在 2.25.0 中，主题可以在根目录提供 `screenshot.png`、`screenshot.jpeg`、`screenshot.jpg` 或 `screenshot.webp` 作为 Console 主题预览图。Halo 会按此顺序识别第一个可读文件，并将访问地址写入 `Theme.status.screenshot`。详细文档可查阅：[目录结构](../../developer-guide/theme/structure.md)。
+
 ### 模板表达式对象 > 新增 `#halo.matchVersion(constraint)` 方法
 
 在 2.25.0 中，我们为主题模板新增了 `#halo.matchVersion(constraint)` 方法，用于判断当前运行的 Halo 版本是否满足指定的语义化版本范围。主题开发者可以用它为依赖新版 Halo 能力的模板片段添加条件渲染，从而避免仅为局部功能提高整个主题的 `spec.requires` 版本要求。详细文档可查阅：[全局变量#halo.matchVersion](../../developer-guide/theme/global-variables.md#halomatchversionconstraint)。
diff --git a/docs/developer-guide/theme/structure.md b/docs/developer-guide/theme/structure.md
index 560973d8..72da5410 100644
--- a/docs/developer-guide/theme/structure.md
+++ b/docs/developer-guide/theme/structure.md
@@ -21,6 +21,7 @@ my-theme
 │   ├── category.html
 │   ├── categories.html
 │   └── archives.html
+├── screenshot.png
 ├── theme.yaml
 └── settings.yaml
 ```
@@ -29,5 +30,6 @@ my-theme
 
 1. `/templates/` - 主题模板目录，存放主题模板文件，所有模板都需要放在这个目录。关于模板的详细说明，请查阅 [模板编写](./template-variables.md)。
 2. `/templates/assets/` - 主题静态资源目录，存放主题的静态资源文件，目前静态资源文件只能放在这个目录，引用方式请查阅 [静态资源](./static-resources)。
-3. `/theme.yaml` - 主题配置文件，配置主题的基本信息，如主题名称、版本、作者等。详细文档请查阅 [配置文件](./config)。
-4. `/settings.yaml` - 主题设置定义文件，配置主题的设置项表单。详细文档请查阅 [设置选项](./settings)。
+3. `/screenshot.png` - 可选的主题预览图文件，支持 `screenshot.png`、`screenshot.jpeg`、`screenshot.jpg` 和 `screenshot.webp`。Halo 会按此顺序识别第一个可读文件，用于 Console 主题预览，并通过 `Theme.status.screenshot` 暴露访问地址。
+4. `/theme.yaml` - 主题配置文件，配置主题的基本信息，如主题名称、版本、作者等。详细文档请查阅 [配置文件](./config)。
+5. `/settings.yaml` - 主题设置定义文件，配置主题的设置项表单。详细文档请查阅 [设置选项](./settings)。