hexo-theme-stellar 1.39.0 → 1.40.0

package/.claude/skills/stellar-theme-dev/SKILL.md

@@ -29,11 +29,11 @@ description: 主题仓库（hexo-theme-stellar）开发全流程：方案 →
 命令按需执行：
 
 - `scripts/` 有改动 → 必须在主工程（xaoxuu.com）执行 `npm run g` 全量验证（已含 `hexo clean && hexo generate && npx gulp minify`）；`npm run s` 是按需渲染，不能替代。
-- 新增/修改纯函数 → 补充单测并跑 `npm run check`（lint + 单测 + 知识库硬事实核查）。
+- 新增/修改纯函数 → 补充单测并跑 `npm run check`（lint + 单测 + 依赖声明检查 + 知识库硬事实核查）。
 - 知识库有改动 → `python3 docs/knowledge/tools/verify.py` 硬事实核查。
 - UI 方面（样式、模板、前端交互等）改动量不大时无需自检流程，除非用户明确要求。
 - 检查所有受影响页面类型（首页、文章页、Wiki 页等），验证结果记录在方案目录 `checklist.md`。
-- 完成条件：应执行的命令全部通过；首页、文章页、Wiki 页等受影响页面类型均检查通过。
+- 完成条件：应执行的命令全部通过；新增 `require` 均已声明或为 Node 内置模块（test/ 禁止幽灵依赖）；首页、文章页、Wiki 页等受影响页面类型均检查通过。
 
 ### 4. 提交
 

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 1.40.0
+
+> 发布日期：2026-08-14
+
+### 新功能
+- 文章页新增字数与预计阅读时长显示（`article.reading_time`，默认关闭）
+- 文章卡片新增标签展示（最多 5 个，`article.card_tags`，默认关闭）
+- 新增表格标签 `{% table style:scroll|wrap|compact %}`，支持滚动/换行/紧凑三种表格样式
+- 新增气泡注解标签 `{% tip text:... %}词句{% endtip %}`，桌面 hover、移动端点击显示
+- 远程 Markdown 渲染抽象：`{% md %}` 标签新增可选 `wrap` 参数；wiki 项目配置 `repo` 后可直接以仓库 README 作为首页正文
+
+### 修复
+- wiki 项目描述作为页面描述（OG / JSON-LD）的兜底，修复 SEO 描述缺失的问题
+- 声明 hexo-pagination / hexo-util 依赖并新增依赖声明检查门禁，修复幽灵依赖导致的构建问题
+- 时间线节点标题（header）不再渲染 markdown 的问题（#401）
+- 分类页三级及以上分类无法正确展示的问题，改为基于 parent 递归构建嵌套树（#564）
+- 亮暗切换后 topbar 与左栏颜色不同步的问题：navbar/sidebar 暗色样式统一跟随 `data-theme` 开关（#593、#663）
+- iOS Safari 下右下角悬浮控件在玻璃椭圆框中不对齐的问题（#599）
+- artalk 邮件通知链接携带 `?atk_*` 参数导致目录定位失效的问题（#598）
+- waline 最近评论接口返回结构兼容（数组 / `{ data: [...] }`）（#630）
+- memos 新版 v1 接口识别与渲染适配，识别失败仍回退 feature 兜底（#668）
+- new-note 命令生成 front-matter 的 date 对齐为 `YYYY-MM-DD HH:mm`（#594）
+
+### 升级注意（配置变更与破坏性改动）
+- 新增 `article.reading_time`（默认 `false`）与 `article.card_tags`（默认 `false`），需要时设为 `true`
+- 新增 `table`、`tip` 两个标签插件；`table` 默认使用 `scroll` 样式
+
+Full Changelog: [1.39.1...1.40.0](https://github.com/xaoxuu/hexo-theme-stellar/compare/1.39.1...1.40.0)
+
+## 1.39.1
+
+> 发布日期：2026-08-13
+
+### 新功能
+- 置顶文章新增平铺样式配置 `article.pin_style: flat`：首页第一页不再渲染置顶轮播，置顶文章按与轮播一致的排序权重在文章列表靠前平铺展示
+
+### 修复
+- 用户内容统一 HTML 转义并移除圆点 aria-label，修复标题含引号导致构建失败
+
+### 升级注意（配置变更与破坏性改动）
+- 新增 `article.pin_style`（`carousel` / `flat`，默认 `carousel`）：默认行为不变；设置 `flat` 后首页置顶文章改为平铺样式展示
+
+Full Changelog: [1.39.0...1.39.1](https://github.com/xaoxuu/hexo-theme-stellar/compare/1.39.0...1.39.1)
+
 ## 1.39.0
 
 > 发布日期：2026-08-13

package/_config.yml

@@ -1,6 +1,6 @@
 ######## Stellar info ########
 stellar:
-  version: '1.39.0'
+  version: '1.40.0'
   homepage: 'https://xaoxuu.com/wiki/stellar/'
   repo: 'https://github.com/xaoxuu/hexo-theme-stellar'
   main_css: /css/main.css
@@ -180,6 +180,8 @@ notebook:
 
 ######## Article ########
 article:
+  # 置顶文章样式：carousel = 轮播（默认）， flat = 平铺（不渲染轮播，置顶文章在首页文章列表靠前展示，排序规则与轮播一致）
+  pin_style: carousel
   # 文章类型，决定布局风格，可以在 front-matter/topic/wiki 中覆盖此参数
   type: tech # tech: 默认技术类文章, story: 图文类文章，文字和段落间增距大
   # 缩进两个文字宽度，适合文字类博客，可以在 front-matter/topic/wiki 中覆盖此参数
@@ -204,6 +206,10 @@ article:
   related_posts:
     enable: false
     max_count: 5
+  # 文章页是否显示字数和预计阅读时长（#302）
+  reading_time: false
+  # 文章卡片是否显示标签（最多 5 个，#580）
+  card_tags: false
 
 search:
   service: local_search # local_search, algolia_search, todo...
@@ -674,7 +680,7 @@ style:
     image-l: 24px # 非技术类文章插图圆角
     image: 16px # 技术类文章插图圆角
     image-s: 8px # 评论区图片圆角（部分评论支持）
-  corner-shape: superellipse(1.5) # 连续曲率圆角（仅 Chromium 139+ 支持，其余浏览器自动回退普通圆角）：superellipse(1.x) 开启，round 关闭
+  corner-shape: superellipse(1.25) # 连续曲率圆角（仅 Chromium 139+ 支持，其余浏览器自动回退普通圆角）：superellipse(1.x) 开启，round 关闭
   color:
     # 主题色配置（不会根据明暗动态调整，请设置为通用的颜色）
     theme: 'hsl(192 98% 55%)' # 主题色

package/languages/en.yml

@@ -37,6 +37,8 @@ meta:
   license: License
   share: Share
   contributors: Page Contributors
+  word_count: '%s words'
+  reading_time: '%s min read'
   date_suffix:
     just: Just
     min: minutes ago

package/languages/zh-CN.yml

@@ -37,6 +37,8 @@ meta:
   license: 许可协议
   share: 分享文章
   contributors: 本文贡献者
+  word_count: '%s 字'
+  reading_time: '预计阅读 %s 分钟'
   date_suffix:
     just: 刚刚
     min: 分钟前

package/languages/zh-TW.yml

@@ -37,6 +37,8 @@ meta:
   license: 授權條款
   share: 分享文章
   contributors: 本文貢獻者
+  word_count: '%s 字'
+  reading_time: '預計閱讀 %s 分鐘'
   date_suffix:
     just: 剛剛
     min: 分鐘前

package/layout/_partial/comments/artalk/script.ejs

@@ -39,6 +39,14 @@
               },
             <% } %>
           });
+          // artalk 邮件通知链接携带 ?atk_comment=... 等查询参数，
+          // 其 hash 监听会与主题目录定位冲突（#598）：
+          // 初始化并完成评论定位后清理查询参数，避免后续目录/锚点跳转被干扰。
+          if (window.location.search.indexOf('atk_') !== -1) {
+            window.setTimeout(function () {
+              window.history.replaceState(null, '', window.location.pathname + window.location.hash);
+            }, 300);
+          }
         });
       }
       

package/layout/_partial/cover/post_cover.ejs

@@ -28,7 +28,7 @@ function div() {
   }
   el += '<div class="l_cover post' + scrollreveal(' ') + '">';
   el += '<div class="cover">';
-  el += '<div class="lazy img bg" data-bg="' + url + '"></div>';
+  el += '<div class="lazy img bg" data-bg="' + escape_html(url) + '"></div>';
   el += '</div>';
   el += '</div>';
   return el;

package/layout/_partial/head.ejs

@@ -23,14 +23,17 @@ function generate_description() {
   if (theme.open_graph && theme.open_graph.enable) {
     return '';
   }
+  if (page.description) {
+    return '<meta name="description" content="' + truncate(strip_html(page.description), {length: 150}) + '">';
+  }
   if (page.wiki) {
     const proj = theme.wiki.tree[page.wiki]
     if (proj?.description) {
       return '<meta name="description" content="' + proj.description + '">'
     }
   }
-  if (page.description || page.excerpt || page.content) {
-    return '<meta name="description" content="' + truncate(strip_html(page.description || page.excerpt || page.content), {length: 150}) + '">';
+  if (page.excerpt || page.content) {
+    return '<meta name="description" content="' + truncate(strip_html(page.excerpt || page.content), {length: 150}) + '">';
   }
   return '<meta name="description" content="' + config.description + '">';
 }
@@ -66,6 +69,12 @@ function og_args() {
   if (page.layout == 'post' && page.cover) {
     args.twitter_card = 'summary_large_image';
   }
+  if (page.wiki && !page.description) {
+    const proj = theme.wiki.tree[page.wiki];
+    if (proj && proj.description) {
+      args.description = proj.description;
+    }
+  }
   args.image = config.avatar || (config.email ? gravatar(config.email) : null);
   return Object.assign(args, page.open_graph);
 }

package/layout/_partial/main/article/article_footer.ejs

@@ -98,6 +98,9 @@ function layoutDiv() {
     showSharePlugin = true
   }
   if (theme.article.share && showSharePlugin) {
+    function urlenc(v) {
+      return encodeURIComponent(v == null ? '' : String(v))
+    }
     function socialButtons() {
       var el = ''
       theme.article.share.forEach((item, i) => {
@@ -109,20 +112,20 @@ function layoutDiv() {
           if (item == 'wechat') {
             el += ' onclick="util.toggle("qrcode-wechat")"';
           } else if (item == 'weibo') {
-            el += ' href="https://service.weibo.com/share/share.php?url=' + page.permalink;
-            el += '&title=' + page.title + ' - ' + config.title;
+            el += ' href="https://service.weibo.com/share/share.php?url=' + urlenc(page.permalink);
+            el += '&title=' + urlenc(page.title + ' - ' + config.title);
             if (page.layout == 'post' && page.cover) {
-              el += '&pics=' + page.cover;
+              el += '&pics=' + urlenc(page.cover);
             } else if (page.wiki && page.icon) {
-              el += '&pics=' + page.icon;
+              el += '&pics=' + urlenc(page.icon);
             }
-            el += '&summary=' + truncate(page.description || strip_html(page.excerpt || page.content), {length: 120});
+            el += '&summary=' + urlenc(truncate(page.description || strip_html(page.excerpt || page.content), {length: 120}));
             el += '"';
           } else if (item == 'email') {
-            el += ' href="mailto:?subject=' + page.title + ' - ' + config.title + '&'
-            el += 'body=' + page.permalink + '"';
+            el += ' href="mailto:?subject=' + urlenc(page.title + ' - ' + config.title) + '&'
+            el += 'body=' + urlenc(page.permalink) + '"';
           } else if (item == 'link') {
-            el += ' onclick="util.copy("copy-link", "' + __('message.copied') + '")"';
+            el += ' onclick="util.copy("copy-link", "' + escape_html(__('message.copied')) + '")"';
           }
           el += '>';
           el += icon(`share:${item}`)
@@ -135,7 +138,7 @@ function layoutDiv() {
       if (theme.article.share.includes('wechat')) {
         return `
         <div class="qrcode" id="qrcode-wechat" style="opacity:0;height:0">
-          <img src="https://api.qrserver.com/v1/create-qr-code/?size=256x256&data=${page.permalink}"/>
+          <img src="https://api.qrserver.com/v1/create-qr-code/?size=256x256&data=${urlenc(page.permalink)}"/>
         </div>
         `
       } else {
@@ -146,7 +149,7 @@ function layoutDiv() {
     <section id="share">
       <div class="header"><span>${__('meta.share')}</span></div>
       <div class="body">
-        <div class="link"><input class="copy-area" readonly="true" id="copy-link" value="${page.permalink}" /></div>
+        <div class="link"><input class="copy-area" readonly="true" id="copy-link" value="${escape_html(page.permalink)}" /></div>
         <div class="social-wrap dis-select">${socialButtons()}</div>
         ${qrcode()}
       </div>

package/layout/_partial/main/navbar/article_banner.ejs

@@ -41,6 +41,13 @@ function layoutBreadcrumb() {
     } else {
       el += partial('breadcrumb/page')
     }
+  // 字数和预计阅读时长，置于面包屑行右侧（#302）
+  if (page.layout == 'post' && theme.article.reading_time) {
+    var _wc = word_count(page)
+    if (_wc > 0) {
+      el += `<span class="cap reading right">${__("meta.word_count", _wc)} · ${__("meta.reading_time", reading_time(page))}</span>`
+    }
+  }
   // end 3.left.top
   el += `</div>`
   // 3.left.bottom

package/layout/_partial/main/navbar/dateinfo.ejs

@@ -42,4 +42,4 @@ function layoutDiv() {
   return el
 }
 %>
-<%- layoutDiv() %>
+<%- layoutDiv() %>

package/layout/_partial/main/navbar/nav_tabs_blog.ejs

@@ -1,7 +1,10 @@
 <%
 function layoutDiv() {
   var el = '';
-  el += partial('_partial/main/pin_slider', {type: 'post'});
+  // 置顶文章样式为平铺时不渲染轮播，置顶文章改由首页文章列表靠前展示
+  if (theme.article?.pin_style !== 'flat') {
+    el += partial('_partial/main/pin_slider', {type: 'post'});
+  }
   el += '<div class="navbar top">';
   el += '<div class="navbar-blur">';
   el += '<div class="navbar-container">';
@@ -14,7 +17,7 @@ function layoutDiv() {
 
   if (site.categories && site.categories.length > 0) {
     if (page.category) {
-      el += '<a class="active" href="' + pretty_url(config.category_dir) + '">' + __("btn.category") + __("symbol.colon") + page.category + '</a>';
+      el += '<a class="active" href="' + pretty_url(config.category_dir) + '">' + __("btn.category") + __("symbol.colon") + escape_html(page.category) + '</a>';
     } else if (page.layout == "categories") {
       el += '<a class="active" href="' + pretty_url(config.category_dir) + '">' + __("btn.categories") + '</a>';
     } else {
@@ -24,7 +27,7 @@ function layoutDiv() {
 
   if (site.tags && site.tags.length > 0) {
     if (page.tag) {
-      el += '<a class="active" href="' + pretty_url(config.tag_dir) + '">' + __("btn.tag") + __("symbol.colon") + page.tag + '</a>';
+      el += '<a class="active" href="' + pretty_url(config.tag_dir) + '">' + __("btn.tag") + __("symbol.colon") + escape_html(page.tag) + '</a>';
     } else if (page.layout == "tags") {
       el += '<a class="active" href="' + pretty_url(config.tag_dir) + '">' + __("btn.tags") + '</a>';
     } else {

package/layout/_partial/main/navbar/nav_tabs_wiki.ejs

@@ -23,7 +23,7 @@ function layoutDiv() {
       if (tag.name && tag.name.length > 0 && page.tagName === tag.name) {
         el += ' class="active"';
       }
-      el += ' href="' + pretty_url(tag.path) + '">' + tag.name + '</a>';
+      el += ' href="' + escape_html(pretty_url(tag.path)) + '">' + escape_html(tag.name) + '</a>';
       el += '</a>';
     }
   }

package/layout/_partial/main/pin_slider.ejs

@@ -69,18 +69,18 @@ function postSlide(post) {
   var headline = (post.poster != null && post.poster.headline != null && post.poster.headline.length > 0) ? post.poster.headline : post.title
   var subtitle = postSubtitle(post)
   var el = ''
-  el += '<a class="pin-slide post-slide' + (noCover ? ' no-cover' : '') + '" href="' + pretty_url(post.link || post.path) + '"'
+  el += '<a class="pin-slide post-slide' + (noCover ? ' no-cover' : '') + '" href="' + escape_html(pretty_url(post.link || post.path)) + '"'
   if (!noCover) {
-    el += ' style="--pin-cover-url:url(\'' + post.cover.replace(/'/g, '%27') + '\')"'
+    el += ' style="--pin-cover-url:url(\'' + escape_html(post.cover.replace(/'/g, '%27')) + '\')"'
   }
   el += '>'
   if (!noCover) {
-    el += '<img class="pin-slide-bg" src="' + post.cover + '" alt=""/>'
+    el += '<img class="pin-slide-bg" src="' + escape_html(post.cover) + '" alt=""/>'
   }
   el += '<div class="pin-slide-text">'
-  el += '<div class="pin-slide-headline">' + headline + '</div>'
+  el += '<div class="pin-slide-headline">' + escape_html(headline) + '</div>'
   if (subtitle.length > 0) {
-    el += '<div class="pin-slide-caption">' + subtitle + '</div>'
+    el += '<div class="pin-slide-caption">' + escape_html(subtitle) + '</div>'
   }
   el += '</div>'
   el += '</a>'
@@ -90,7 +90,7 @@ function postSlide(post) {
 function projectChips(tags) {
   var caps = ''
   if (tags && tags.length > 0) {
-    caps += '<span class="pin-slide-chip">' + tags.join('</span><span class="pin-slide-chip">') + '</span>'
+    caps += '<span class="pin-slide-chip">' + tags.map(function(t) { return escape_html(t) }).join('</span><span class="pin-slide-chip">') + '</span>'
   }
   return caps
 }
@@ -100,14 +100,14 @@ function wikiSlide(proj) {
   var title = proj.title || proj.name || proj.id
   var excerpt = proj.description || ''
   var el = ''
-  el += '<a class="pin-slide" href="' + pretty_url(proj.homepage?.path || '/') + '">'
-  el += '<img class="pin-slide-bg" src="' + img + '" alt=""/>'
+  el += '<a class="pin-slide" href="' + escape_html(pretty_url(proj.homepage?.path || '/')) + '">'
+  el += '<img class="pin-slide-bg" src="' + escape_html(img) + '" alt=""/>'
   el += '<div class="pin-slide-mask"></div>'
   el += '<div class="pin-slide-info">'
   el += '<div class="pin-slide-caps">' + projectChips(proj.tags) + '</div>'
-  el += '<div class="pin-slide-title">' + title + '</div>'
+  el += '<div class="pin-slide-title">' + escape_html(title) + '</div>'
   if (excerpt.length > 0) {
-    el += '<div class="pin-slide-excerpt">' + excerpt + '</div>'
+    el += '<div class="pin-slide-excerpt">' + escape_html(excerpt) + '</div>'
   }
   el += '</div>'
   el += '</a>'
@@ -125,8 +125,7 @@ if (pinItems.length > 0) {
       slidesHtml += postSlide(item)
     }
     if (pinItems.length > 1) {
-      var label = item.title || item.name || item.id || (si + 1)
-      dotsHtml += '<button type="button" class="pin-slider-dot' + (si == 0 ? ' active' : '') + '" data-index="' + si + '" aria-label="' + label + '"></button>'
+      dotsHtml += '<button type="button" class="pin-slider-dot' + (si == 0 ? ' active' : '') + '" data-index="' + si + '"></button>'
     }
   }
   var groupKey = pinType == 'wiki' ? 'wiki' : 'post'

package/layout/_partial/main/post_list/post_card.ejs

@@ -39,14 +39,14 @@ function div_default() {
     }
     if (cover_url) {
       el += '<div class="post-cover">';
-      el += '<img src="' + cover_url + '"/>';
+      el += '<img src="' + escape_html(cover_url) + '"/>';
       el += '</div>';
     }
   }
 
   // 标题
   el += '<h2 class="post-title">';
-  el += post.title ? post.title : date(post.date, config.date_format);
+  el += post.title ? escape_html(post.title) : date(post.date, config.date_format);
   el += '</h2>';
 
   // 摘要
@@ -57,11 +57,11 @@ function div_default() {
   el += '">';
   el += '<p>';
   if (post.excerpt) {
-    el += strip_html(post.excerpt);
+    el += escape_html(strip_html(post.excerpt));
   } else if (post.description) {
-    el += post.description;
+    el += escape_html(post.description);
   } else if (post.content && theme.article.auto_excerpt > 0) {
-    el += truncate(strip_html(post.content), {length: theme.article.auto_excerpt});
+    el += escape_html(truncate(strip_html(post.content), {length: theme.article.auto_excerpt}));
   }
   el += '</p>';
   el += '</div>';
@@ -87,12 +87,23 @@ function div_default() {
         let lastCat = cats.pop();
         el += '<span class="cap breadcrumb"' + category_color(lastCat) + '>';
         el += icon('default:category')
-        el += `<span>${str}</span>`
+        el += `<span>${escape_html(str)}</span>`
         el += '</span>';
       }
     }
   }
-  // 置顶文章已由列表页 navbar 上方的置顶轮播展示，卡片内不再显示 pin 图标。
+  // 置顶文章由轮播（默认）或首页列表靠前展示（flat 平铺）承担，卡片内不显示 pin 图标。
+  // 文章标签（最多 5 个，#580）
+  if (theme.article.card_tags && post.tags && post.tags.length > 0) {
+    el += '<span class="card-tags">';
+    post.tags.forEach((tag, i) => {
+      if (i >= 5) {
+        return;
+      }
+      el += `<span class="cap tag-chip">#${escape_html(tag.name)}</span>`;
+    });
+    el += '</span>';
+  }
   el += '</div>';
   el += '</article>';
   return el;
@@ -107,22 +118,22 @@ function div_photo() {
       position = 'bottom';
     }
   }
-  el += '<div class="cover" position="' + position + '" style="--cover-url:url(\'' + obj.image.replace(/'/g, '%27') + '\')">';
-  el += '<img src="' + obj.image + '"/>';
+  el += '<div class="cover" position="' + position + '" style="--cover-url:url(\'' + escape_html(obj.image.replace(/'/g, '%27')) + '\')">';
+  el += '<img src="' + escape_html(obj.image) + '"/>';
   if (position.length > 0) {
     el += '<div class="cover-info" position="' + position + '"';
     if (obj.color) {
-      el += 'style="color:' + obj.color + '"';
+      el += 'style="color:' + escape_html(obj.color) + '"';
     }
     el += '>';
     if (obj.topic) {
-      el += '<div class="text topic">' + obj.topic + '</div>';
+      el += '<div class="text topic">' + escape_html(obj.topic) + '</div>';
     }
     if (obj.headline) {
-      el += '<div class="text headline">' + obj.headline + '</div>';
+      el += '<div class="text headline">' + escape_html(obj.headline) + '</div>';
     }
     if (obj.caption) {
-      el += '<div class="text caption">' + obj.caption + '</div>';
+      el += '<div class="text caption">' + escape_html(obj.caption) + '</div>';
     }
     el += '</div>';
 

package/layout/_partial/sidebar/index_leftbar.ejs

@@ -131,10 +131,10 @@ function layoutFooterDiv() {
     if (item.icon && (item.url || item.onclick)) {
       el += '<a class="social"';
       if (item.title) {
-        el += ' title="' + item.title + '"';
+        el += ' title="' + escape_html(item.title) + '"';
       }
       if (item.url) {
-        el += ' href="' + url_for(item.url) + '"';
+        el += ' href="' + escape_html(url_for(item.url)) + '"';
         if (item.url.includes('://')) {
           el += ' target="_blank" rel="external nofollow noopener noreferrer"';
         } else {

package/layout/_partial/widgets/markdown.ejs

@@ -13,7 +13,7 @@ function layoutDiv() {
     el += markdown(item.content);
   }
   if (item.src) {
-    el += `<div class="data-service ds-mdrender" src="${item.src}"></div>`
+    el += mdrender_html(item.src)
   }
   if (item.linklist) {
     el += partial('components/linklist', {item: item.linklist})

package/layout/_partial/widgets/toc.ejs

@@ -38,9 +38,12 @@ function layoutToc(fallback) {
 function layoutDiv(fallback) {
   const tocBody = layoutTocBody()
   const hasToc = tocBody.trim().length > 0
+  // 远程 md 内容由客户端渲染，构建期正文无标题：
+  // 预留空 TOC 容器，渲染完成后由 mdrender.js 填充
+  const hasRemoteMd = has_remote_md(page)
   // 页面是否实际渲染评论区，由 _partial/comments/layout.ejs 标记
   const hasComments = page.cmt_rendered === true
-  if (!hasToc && !hasComments) {
+  if (!hasToc && !hasRemoteMd && !hasComments) {
     return ''
   }
   var el = ''
@@ -50,6 +53,10 @@ function layoutDiv(fallback) {
     el += `<div class="widget-body">`
     el += tocBody
     el += `</div>`
+  } else if (hasRemoteMd) {
+    el += layoutTocHeader()
+    el += `<div class="widget-body">`
+    el += `</div>`
   }
   el += `<div class="widget-footer">`
   el += `<a class="top" onclick="util.scrollTop()">`

package/layout/categories.ejs

@@ -10,14 +10,24 @@ if (page.menu_id == undefined) {
   <%- partial('_partial/main/navbar/nav_tabs_blog') %>
   <div class='post-list'>
     <article class='<%- scrollreveal("") %>' id='cats'>
-      <% site.categories.sort('path').each(function(category){ %>
-        <div>
-          <a class="<%= category.parent ? 'cat child' : 'cat'%>" href="<%= pretty_url(category.path) %>">
-            <span class='name'><%- icon('default:category') %><%- category.name %></span>
-            <span class='badge'>(<%- category.posts.length %>)</span>
-          </a>
-        </div>
-      <% }) %>
+      <%
+      function renderCategoryTree(nodes) {
+        var el = ''
+        nodes.forEach(function(node) {
+          el += `<div class="cat-item">`
+          el += `<a class="cat${node.parentId ? ' child' : ''}" href="${pretty_url(node.path)}">`
+          el += `<span class="name">${icon('default:category')}${escape_html(node.name)}</span>`
+          el += `<span class="badge">(${node.count})</span>`
+          el += `</a>`
+          if (node.children && node.children.length > 0) {
+            el += `<div class="cat-children">${renderCategoryTree(node.children)}</div>`
+          }
+          el += `</div>`
+        })
+        return el
+      }
+      %>
+      <%- renderCategoryTree(category_tree(site.categories)) %>
     </article>
   </div>
 <% } %>

package/layout/index.ejs

@@ -29,8 +29,49 @@ if (homeCmt && homeCmt !== false && is_home_first_page()) {
   }
 }
 
-// 首页第一页渲染置顶轮播时，列表不再重复展示置顶文章
-var pinSliderActive = is_home_first_page()
+// 置顶文章样式：carousel = 轮播（默认），flat = 平铺（首页列表靠前展示）
+var pinStyle = theme.article?.pin_style || 'carousel'
+var pinFlat = pinStyle === 'flat'
+
+// 与 pin_slider.ejs 保持一致的置顶判定与排序权重
+function pinValue(post) {
+  return post.pin != null ? post.pin : post.sticky
+}
+function isPinned(post) {
+  var v = pinValue(post)
+  return v !== false && v != null
+}
+function pinWeight(post) {
+  var v = pinValue(post)
+  if (v === true) {
+    return 1
+  }
+  var n = Number(v)
+  return isNaN(n) ? 0 : n
+}
+
+// 首页第一页渲染置顶轮播时，列表不再重复展示置顶文章（carousel 模式）
+var pinSliderActive = is_home_first_page() && !pinFlat
+
+// flat 模式：首页第一页收集全部置顶文章，按轮播顺序置顶展示
+var flatPins = []
+if (pinFlat && is_home_first_page()) {
+  var allPosts = site.posts.toArray() || []
+  for (var fi = 0; fi < allPosts.length; fi++) {
+    var fpost = allPosts[fi]
+    if (fpost.indexing === false) {
+      continue
+    }
+    if (isPinned(fpost)) {
+      flatPins.push({post: fpost, index: fi})
+    }
+  }
+  flatPins.sort(function(a, b) {
+    var d = pinWeight(b.post) - pinWeight(a.post)
+    // 权重相同保持原顺序（与轮播一致）
+    return d !== 0 ? d : a.index - b.index
+  })
+}
 
 function layout_post_card(layout, post, content) {
   var el = '';
@@ -49,17 +90,32 @@ function layout_post_card(layout, post, content) {
 function layout_post_list(partial) {
   var el = '';
   el += `<div class="post-list post">`;
-  page.posts.each(function(post){
-    if (post.indexing != false) {
-      if (pinSliderActive) {
-        var pinVal = post.pin != null ? post.pin : post.sticky
-        if (pinVal !== false && pinVal != null) {
-          return
+  if (flatPins.length > 0) {
+    var pinnedPaths = {}
+    flatPins.forEach(function(item) {
+      pinnedPaths[item.post.path] = true
+    })
+    flatPins.forEach(function(item) {
+      el += layout_post_card('post', item.post, partial(item.post));
+    })
+    page.posts.each(function(post){
+      if (post.indexing != false && !pinnedPaths[post.path]) {
+        el += layout_post_card('post', post, partial(post));
+      }
+    })
+  } else {
+    page.posts.each(function(post){
+      if (post.indexing != false) {
+        if (pinSliderActive) {
+          var pinVal = pinValue(post)
+          if (pinVal !== false && pinVal != null) {
+            return
+          }
         }
+        el += layout_post_card('post', post, partial(post));
       }
-      el += layout_post_card('post', post, partial(post));
-    }
-  })
+    })
+  }
   el += '</div>';
   return el;
 }