From 7c54e1275394ac5e058ac6f0b2d2cc9f4ef5a96b Mon Sep 17 00:00:00 2001
From: Ryan Wang <i@ryanc.cc>
Date: Mon, 18 May 2026 14:20:47 +0800
Subject: [PATCH] docs: add category-scoped post navigation docs

---
 docs/developer-guide/theme/api-changelog.md   |  8 +++
 .../developer-guide/theme/finder-apis/post.md | 49 +++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/docs/developer-guide/theme/api-changelog.md b/docs/developer-guide/theme/api-changelog.md
index ddd2db57..6928a309 100644
--- a/docs/developer-guide/theme/api-changelog.md
+++ b/docs/developer-guide/theme/api-changelog.md
@@ -3,6 +3,14 @@ title: API 变更日志
 description: 记录每一个版本的主题 API 变更记录，方便开发者适配
 ---
 
+## 2.25.0
+
+### 文章 Finder API > 新增 `cursorByCategory(postName)` 方法
+
+我们为文章 Finder API 新增了 `cursorByCategory(postName)` 方法，用于获取当前文章主分类下的上一篇 / 下一篇文章。主分类为文章 `spec.categories` 中的第一个分类，且只匹配同一分类，不会包含子分类中的文章。
+
+同时，Public API `GET /apis/api.content.halo.run/v1alpha1/posts/{name}/navigation` 新增了可选的 `scope=category` 查询参数，用于获取同一主分类下的文章导航。详细文档可查阅：[文章 Finder API#cursorByCategory](../../developer-guide/theme/finder-apis/post.md#cursorbycategorypostname)。
+
 ## 2.24.1
 
 ### 文章 Finder API > 新增 `random(maxSize)` 方法
diff --git a/docs/developer-guide/theme/finder-apis/post.md b/docs/developer-guide/theme/finder-apis/post.md
index ffc11482..c49def61 100644
--- a/docs/developer-guide/theme/finder-apis/post.md
+++ b/docs/developer-guide/theme/finder-apis/post.md
@@ -103,6 +103,55 @@ postFinder.cursor(postName);
 </div>
 ```
 
+## cursorByCategory(postName)
+
+```js
+postFinder.cursorByCategory(postName);
+```
+
+### 描述
+
+根据文章的 `metadata.name` 获取同一主分类下相邻的文章（上一篇 / 下一篇）。
+
+主分类为文章 `spec.categories` 中的第一个分类。此方法只匹配同一分类下的文章，不会包含子分类中的文章。如果当前文章没有分类、未发布或者不存在，将返回空的导航结果。
+
+:::info[提示]
+上一篇文章是指发布时间较当前文章更早的文章，下一篇文章是指发布时间较当前文章更新的文章。
+:::
+
+对应的 Public API 为：
+
+```bash
+GET /apis/api.content.halo.run/v1alpha1/posts/{name}/navigation?scope=category
+```
+
+### 参数
+
+1. `postName:string` - 文章的唯一标识 `metadata.name`。
+
+### 返回值
+
+[#NavigationPostVo](#navigationpostvo)
+
+### 示例
+
+```html title="/templates/post.html"
+<div th:with="postCursor = ${postFinder.cursorByCategory(post.metadata.name)}">
+  <a
+    th:if="${postCursor.hasPrevious()}"
+    th:href="@{${postCursor.previous.status.permalink}}"
+  >
+    <span th:text="${postCursor.previous.spec.title}"></span>
+  </a>
+  <a
+    th:if="${postCursor.hasNext()}"
+    th:href="@{${postCursor.next.status.permalink}}"
+  >
+    <span th:text="${postCursor.next.spec.title}"></span>
+  </a>
+</div>
+```
+
 ## listAll()
 
 ```js