diff --git a/docs/developer-guide/theme/api-changelog.md b/docs/developer-guide/theme/api-changelog.md
index 6928a309..4e666e56 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
 
+### 模板表达式对象 > 新增 `#halo.matchVersion(constraint)` 方法
+
+在 2.25.0 中，我们为主题模板新增了 `#halo.matchVersion(constraint)` 方法，用于判断当前运行的 Halo 版本是否满足指定的语义化版本范围。主题开发者可以用它为依赖新版 Halo 能力的模板片段添加条件渲染，从而避免仅为局部功能提高整个主题的 `spec.requires` 版本要求。详细文档可查阅：[全局变量#halo.matchVersion](../../developer-guide/theme/global-variables.md#halomatchversionconstraint)。
+
 ### 文章 Finder API > 新增 `cursorByCategory(postName)` 方法
 
 我们为文章 Finder API 新增了 `cursorByCategory(postName)` 方法，用于获取当前文章主分类下的上一篇 / 下一篇文章。主分类为文章 `spec.categories` 中的第一个分类，且只匹配同一分类，不会包含子分类中的文章。
diff --git a/docs/developer-guide/theme/global-variables.md b/docs/developer-guide/theme/global-variables.md
index c3b9b1c5..3ed501a6 100644
--- a/docs/developer-guide/theme/global-variables.md
+++ b/docs/developer-guide/theme/global-variables.md
@@ -38,6 +38,36 @@ Halo 目前为模板引擎在全局提供了一些变量，本文档将列出已
 <span th:text="${site.version}"></span>
 ```
 
+## #halo.matchVersion(constraint)
+
+### 描述
+
+用于判断当前运行的 Halo 版本是否满足指定的语义化版本范围，适合在主题模板中为依赖新版 Halo 能力的片段添加兼容判断。
+
+版本范围格式遵循 [Semantic Range Expressions](https://github.com/zafarkhaja/jsemver#range-expressions)，例如 `>=2.25.0`、`>2.0.0 & <3.0.0` 等。
+
+:::tip
+开发版本 `0.0.0` 会始终返回 `true`，以便在本地开发环境中调试主题模板。
+:::
+
+### 示例
+
+仅在 Halo 版本满足要求时渲染模板片段：
+
+```html
+<div th:if="${#halo.matchVersion('>=2.25.0')}">
+  <!-- 这里可以使用仅在 Halo 2.25.0 及以上版本可用的能力 -->
+</div>
+```
+
+判断一个版本范围：
+
+```html
+<div th:if="${#halo.matchVersion('>=2.25.0 & <3.0.0')}">
+  <!-- 仅在 Halo 2.x 的指定版本范围内渲染 -->
+</div>
+```
+
 ## theme
 
 ### 描述