@wsxjs/wsx-press 0.0.23 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wsxjs/wsx-press",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "description": "A VitePress-like documentation system built with WSXJS",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -28,10 +28,10 @@
   "dependencies": {
     "fuse.js": "^7.0.0",
     "marked": "^12.0.0",
-    "@wsxjs/wsx-core": "0.0.23",
-    "@wsxjs/wsx-logger": "0.0.23",
-    "@wsxjs/wsx-marked-components": "0.0.23",
-    "@wsxjs/wsx-router": "0.0.23"
+    "@wsxjs/wsx-core": "0.0.24",
+    "@wsxjs/wsx-logger": "0.0.24",
+    "@wsxjs/wsx-router": "0.0.24",
+    "@wsxjs/wsx-marked-components": "0.0.24"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
@@ -48,8 +48,8 @@
     "typescript": "^5.0.0",
     "vite": "^5.4.19",
     "vitest": "^2.0.0",
-    "@wsxjs/eslint-plugin-wsx": "0.0.23",
-    "@wsxjs/wsx-vite-plugin": "0.0.23"
+    "@wsxjs/eslint-plugin-wsx": "0.0.24",
+    "@wsxjs/wsx-vite-plugin": "0.0.24"
   },
   "peerDependencies": {
     "typedoc": "^0.26.0",

package/src/client/components/DocPage.wsx

@@ -252,29 +252,45 @@ export default class DocPage extends LightComponent {
             // 创建新的 AbortController
             this.loadingAbortController = new AbortController();
 
-            // 从 RouterUtils 获取当前路由信息（包含参数）
+            // 从 RouterUtils 获取当前路由信息
             const routeInfo = RouterUtils.getCurrentRoute();
-            const params = routeInfo.params as { category?: string; page?: string };
-
-            // 验证参数
-            if (!params.category || !params.page) {
-                logger.warn("Missing route parameters:", { params, routeInfo });
-                // 如果参数为空，可能是路由还未初始化，保持 idle 状态
-                if (Object.keys(params).length === 0) {
-                    logger.debug("Route params not yet initialized, keeping idle state");
-                    this.loadingState = "idle";
+
+            // 从路径中提取文档路径（支持多级路径）
+            // 例如：/docs/guide/essentials/getting-started -> guide/essentials/getting-started
+            let docPath: string;
+            if (routeInfo.path.startsWith("/docs/")) {
+                // 移除 /docs/ 前缀，得到文档路径
+                docPath = routeInfo.path.slice(6); // 移除 "/docs/"
+            } else {
+                // 尝试从 params 获取（向后兼容）
+                const params = routeInfo.params as { category?: string; page?: string };
+                if (params.category && params.page) {
+                    docPath = `${params.category}/${params.page}`;
+                } else {
+                    logger.warn("Invalid document path:", { path: routeInfo.path, params });
+                    // 如果参数为空，可能是路由还未初始化，保持 idle 状态
+                    if (Object.keys(params).length === 0) {
+                        logger.debug("Route params not yet initialized, keeping idle state");
+                        this.loadingState = "idle";
+                        return;
+                    }
+                    this.loadingState = "error";
+                    this.error = new DocumentLoadError(
+                        "Invalid document path: path must start with /docs/",
+                        "INVALID_PARAMS"
+                    );
                     return;
                 }
+            }
+
+            // 验证文档路径不为空
+            if (!docPath || docPath.trim() === "") {
+                logger.warn("Empty document path:", { path: routeInfo.path });
                 this.loadingState = "error";
-                this.error = new DocumentLoadError(
-                    "Missing route parameters: category and page are required",
-                    "INVALID_PARAMS"
-                );
+                this.error = new DocumentLoadError("Document path is empty", "INVALID_PARAMS");
                 return;
             }
 
-            const docPath = `${params.category}/${params.page}`;
-
             // 防止竞态条件：记录当前加载路径
             this.currentLoadingPath = docPath;
             this.isLoading = true;

package/src/client/components/DocSidebar.css

@@ -12,6 +12,28 @@ wsx-doc-sidebar {
     max-height: calc(100vh - 70px);
 }
 
+/* 浅色模式（通过类名，覆盖媒体查询） */
+.light wsx-doc-sidebar,
+[data-theme="light"] wsx-doc-sidebar {
+    background: var(--wsx-press-sidebar-bg, #f9fafb);
+    border-right-color: var(--wsx-press-border, #e5e7eb);
+}
+
+/* 暗色模式（通过类名） */
+.dark wsx-doc-sidebar,
+[data-theme="dark"] wsx-doc-sidebar {
+    background: var(--wsx-press-sidebar-bg, #1f2937);
+    border-right-color: var(--wsx-press-border, #374151);
+}
+
+/* 暗色模式（通过媒体查询作为后备，仅当没有显式类名时） */
+@media (prefers-color-scheme: dark) {
+    html:not(.light):not([data-theme="light"]) wsx-doc-sidebar {
+        background: var(--wsx-press-sidebar-bg, #1f2937);
+        border-right-color: var(--wsx-press-border, #374151);
+    }
+}
+
 .doc-sidebar {
     display: flex;
     flex-direction: column;
@@ -48,6 +70,24 @@ wsx-doc-sidebar {
     margin: 0 0 0.5rem 0;
 }
 
+/* 浅色模式分类标题（覆盖媒体查询） */
+.light .doc-sidebar-category-title,
+[data-theme="light"] .doc-sidebar-category-title {
+    color: var(--wsx-press-text-secondary, #6b7280);
+}
+
+/* 暗色模式分类标题 */
+.dark .doc-sidebar-category-title,
+[data-theme="dark"] .doc-sidebar-category-title {
+    color: var(--wsx-press-text-secondary, #9ca3af);
+}
+
+@media (prefers-color-scheme: dark) {
+    html:not(.light):not([data-theme="light"]) .doc-sidebar-category-title {
+        color: var(--wsx-press-text-secondary, #9ca3af);
+    }
+}
+
 .doc-sidebar-list {
     list-style: none;
     margin: 0;
@@ -75,12 +115,67 @@ wsx-doc-sidebar {
 }
 
 .doc-sidebar-link.active {
-    background: var(--wsx-press-sidebar-active-bg, #eff6ff);
-    color: var(--wsx-press-sidebar-active-color, #2563eb);
-    border-left-color: var(--wsx-press-sidebar-active-color, #2563eb);
+    background: var(--wsx-press-sidebar-active-bg, #fef2f2);
+    color: var(--wsx-press-sidebar-active-color, #dc2626);
+    border-left-color: var(--wsx-press-sidebar-active-color, #dc2626);
     font-weight: 500;
 }
 
+/* 浅色模式链接样式（覆盖媒体查询） */
+.light .doc-sidebar-link,
+[data-theme="light"] .doc-sidebar-link {
+    color: var(--wsx-press-text-primary, #111827);
+}
+
+.light .doc-sidebar-link:hover,
+[data-theme="light"] .doc-sidebar-link:hover {
+    background: var(--wsx-press-sidebar-hover-bg, #f3f4f6);
+    color: var(--wsx-press-text-primary, #111827);
+}
+
+.light .doc-sidebar-link.active,
+[data-theme="light"] .doc-sidebar-link.active {
+    background: var(--wsx-press-sidebar-active-bg, #fef2f2);
+    color: var(--wsx-press-sidebar-active-color, #dc2626);
+    border-left-color: var(--wsx-press-sidebar-active-color, #dc2626);
+}
+
+/* 暗色模式链接样式 */
+.dark .doc-sidebar-link,
+[data-theme="dark"] .doc-sidebar-link {
+    color: var(--wsx-press-text-primary, #e5e7eb);
+}
+
+.dark .doc-sidebar-link:hover,
+[data-theme="dark"] .doc-sidebar-link:hover {
+    background: var(--wsx-press-sidebar-hover-bg, #374151);
+    color: var(--wsx-press-text-primary, #f3f4f6);
+}
+
+.dark .doc-sidebar-link.active,
+[data-theme="dark"] .doc-sidebar-link.active {
+    background: var(--wsx-press-sidebar-active-bg, rgba(220, 38, 38, 0.15));
+    color: var(--wsx-press-sidebar-active-color, #f87171);
+    border-left-color: var(--wsx-press-sidebar-active-color, #f87171);
+}
+
+@media (prefers-color-scheme: dark) {
+    html:not(.light):not([data-theme="light"]) .doc-sidebar-link {
+        color: var(--wsx-press-text-primary, #e5e7eb);
+    }
+
+    html:not(.light):not([data-theme="light"]) .doc-sidebar-link:hover {
+        background: var(--wsx-press-sidebar-hover-bg, #374151);
+        color: var(--wsx-press-text-primary, #f3f4f6);
+    }
+
+    html:not(.light):not([data-theme="light"]) .doc-sidebar-link.active {
+        background: var(--wsx-press-sidebar-active-bg, rgba(220, 38, 38, 0.15));
+        color: var(--wsx-press-sidebar-active-color, #f87171);
+        border-left-color: var(--wsx-press-sidebar-active-color, #f87171);
+    }
+}
+
 /* 响应式设计 */
 @media (max-width: 1024px) {
     wsx-doc-sidebar {

package/src/client/components/DocSidebar.wsx

@@ -103,9 +103,24 @@ export default class DocSidebar extends LightComponent {
         // 按分类名称排序
         const sortedCategories = Object.keys(organized).sort();
 
-        // 对每个分类内的文档排序（按标题）
+        // 对每个分类内的文档排序（优先按 order，然后按标题）
         sortedCategories.forEach((category) => {
-            organized[category].sort((a, b) => a.title.localeCompare(b.title));
+            organized[category].sort((a, b) => {
+                // 如果两个文档都有 order，按 order 排序
+                if (a.order !== undefined && b.order !== undefined) {
+                    return a.order - b.order;
+                }
+                // 如果只有 a 有 order，a 排在前面
+                if (a.order !== undefined) {
+                    return -1;
+                }
+                // 如果只有 b 有 order，b 排在前面
+                if (b.order !== undefined) {
+                    return 1;
+                }
+                // 都没有 order，按标题排序
+                return a.title.localeCompare(b.title);
+            });
         });
 
         return organized;

package/src/client/components/DocTOC.wsx

@@ -105,14 +105,20 @@ export default class DocTOC extends LightComponent {
     private async loadTOC(): Promise<void> {
         try {
             const routeInfo = RouterUtils.getCurrentRoute();
-            const params = routeInfo.params as { category?: string; page?: string };
+            // 从路径中提取 docPath（移除 /docs/ 前缀）
+            let docPath: string;
+            if (routeInfo.path.startsWith("/docs/")) {
+                docPath = routeInfo.path.slice(6); // 移除 "/docs/" 前缀
+            } else {
+                this.items = [];
+                return;
+            }
 
-            if (!params.category || !params.page) {
+            if (!docPath || docPath.trim() === "") {
                 this.items = [];
                 return;
             }
 
-            const docPath = `${params.category}/${params.page}`;
             const tocData = await loadTOCData();
             this.items = tocData[docPath] || [];
 

package/src/node/metadata.ts

@@ -27,7 +27,8 @@ export async function scanDocsMetadata(docsRoot: string): Promise<DocsMetaCollec
         const dirname = path.dirname(relativePath);
         metadata[key] = {
             title: frontmatter.title || path.basename(file, ".md"),
-            category: dirname === "." ? "." : dirname,
+            // 优先使用 frontmatter 中的 category，如果没有则使用 dirname
+            category: frontmatter.category || (dirname === "." ? "." : dirname),
             route: `/docs/${key}`,
             ...frontmatter,
         };
@@ -64,7 +65,25 @@ export function extractFrontmatter(markdown: string): Partial<DocMetadata> {
         if (key && value) {
             // 类型安全的属性赋值
             if (key === "title" || key === "description" || key === "category") {
-                (meta as Record<string, string>)[key] = value;
+                // 移除值两端的引号（如果存在）
+                let cleanValue = value.replace(/^["']|["']$/g, "");
+                // 解码 HTML 实体（如 &quot; -> "）
+                // 使用 Node.js 兼容的方法
+                if (cleanValue.includes("&")) {
+                    cleanValue = cleanValue
+                        .replace(/&quot;/g, '"')
+                        .replace(/&apos;/g, "'")
+                        .replace(/&lt;/g, "<")
+                        .replace(/&gt;/g, ">")
+                        .replace(/&amp;/g, "&");
+                }
+                (meta as Record<string, string>)[key] = cleanValue;
+            } else if (key === "order") {
+                // 解析 order 字段为数字
+                const orderNum = Number.parseInt(value, 10);
+                if (!Number.isNaN(orderNum)) {
+                    meta.order = orderNum;
+                }
             } else if (key === "tags") {
                 // 简单的数组解析（实际应使用 YAML 解析器）
                 meta.tags = value
@@ -101,7 +120,15 @@ export function addPrevNextLinks(metadata: DocsMetaCollection): DocsMetaCollecti
 
     // 为每个类别添加 prev/next
     for (const [_category, keys] of categories) {
-        keys.sort();
+        // 按 order 字段排序（如果存在），然后按 key 排序
+        keys.sort((a, b) => {
+            const orderA = metadata[a].order ?? Number.MAX_SAFE_INTEGER;
+            const orderB = metadata[b].order ?? Number.MAX_SAFE_INTEGER;
+            if (orderA !== orderB) {
+                return orderA - orderB;
+            }
+            return a.localeCompare(b);
+        });
         for (let i = 0; i < keys.length; i++) {
             const key = keys[i];
             metadata[key].prev = i > 0 ? `/docs/${keys[i - 1]}` : null;

package/src/types.ts

@@ -13,6 +13,8 @@ export interface DocMetadata {
     category: string;
     /** 文档路由 */
     route: string;
+    /** 文档顺序（用于控制侧边栏和导航中的显示顺序，数字越小越靠前） */
+    order?: number;
     /** 上一篇文档路由 */
     prev?: string | null;
     /** 下一篇文档路由 */