hexo-theme-stellar 1.34.0 → 1.36.0

package/layout/_plugins/scrollreveal.ejs

@@ -1,17 +1,81 @@
-<script defer src="<%- conf.js %>"></script>
 <script>
   utils.initPlugin(() => {
-    const els = document.querySelectorAll('.slide-up');
-    if (els.length > 0) {
-      const slideUp = {
-        distance: `<%- conf.distance %>`,
-        duration: `<%- conf.duration %>`,
-        interval: `<%- conf.interval %>`,
-        scale: `<%- conf.scale %>`,
-        opacity: 0,
-        easing: "ease-out"
-      };
-      ScrollReveal().reveal('.slide-up', { ...slideUp });
-    }
+    const els = Array.prototype.slice.call(document.querySelectorAll('.slide-up'));
+    if (els.length === 0) return;
+
+    // 吸顶/固定定位容器内的元素始终在视口内（或由容器控制显隐），
+    // 但 ScrollReveal 按文档坐标判断可见性，会误判这类元素为不可见，
+    // 导致带锚点/恢复滚动位置打开页面时组件一直不显示。
+    // 解决方式：以最近的吸顶/固定祖先作为该组元素的容器，
+    // 使可见性判断恒成立，入场动画保留且不再依赖主文档滚动。
+    const findPinnedContainer = (el) => {
+      let node = el;
+      while (node && node.nodeType === 1) {
+        const pos = window.getComputedStyle(node).position;
+        if (pos === 'sticky' || pos === 'fixed') return node;
+        node = node.parentElement;
+      }
+      return null;
+    };
+
+    const pinnedGroups = new Map(); // 容器 -> 元素列表
+    const targets = [];
+    els.forEach((el) => {
+      const container = findPinnedContainer(el);
+      if (container) {
+        const group = pinnedGroups.get(container) || [];
+        group.push(el);
+        pinnedGroups.set(container, group);
+      } else {
+        targets.push(el);
+      }
+    });
+    if (pinnedGroups.size === 0 && targets.length === 0) return;
+
+    // 加载/初始化失败时兜底显示内容，避免整页空白
+    let fallbackApplied = false;
+    const revealFallback = () => {
+      if (fallbackApplied) return;
+      fallbackApplied = true;
+      document.documentElement.classList.add('sr-fallback');
+    };
+
+    const slideUp = {
+      distance: `<%- conf.distance %>`,
+      duration: `<%- conf.duration %>`,
+      interval: `<%- conf.interval %>`,
+      scale: `<%- conf.scale %>`,
+      opacity: 0,
+      easing: "ease-out"
+    };
+
+    // 看门狗：CDN 长时间无响应时强制显示内容
+    const watchdog = setTimeout(() => revealFallback(), 3000);
+
+    utils.js(`<%- conf.js %>`, { defer: true })
+      .then(() => {
+        if (fallbackApplied) return;
+        if (typeof ScrollReveal !== 'function') {
+          revealFallback();
+          return;
+        }
+        try {
+          const sr = ScrollReveal();
+          if (targets.length > 0) {
+            sr.reveal(targets, { ...slideUp });
+          }
+          pinnedGroups.forEach((group, container) => {
+            sr.reveal(group, { ...slideUp, container: container });
+          });
+          clearTimeout(watchdog);
+        } catch (err) {
+          console.error('[Plugin scrollreveal] 初始化失败:', err);
+          revealFallback();
+        }
+      })
+      .catch((err) => {
+        console.error('[Plugin scrollreveal] 加载失败:', err);
+        revealFallback();
+      });
   }, 'scrollreveal');
 </script>

package/layout/layout.ejs

@@ -69,7 +69,6 @@ if (theme.style.prefers_theme === 'auto') {
     html += `<div class="scripts">`
       html += partial('_partial/scripts')
     html += `</div>`
-    html += `<div class="page-loading-bar"><img src="${theme.default.loading}"></div>`
   html += `</body>`
 html += `</html>`
 %>

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "hexo-theme-stellar",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "description": "Elegant and powerful theme for Hexo.",
   "main": "package.json",
   "scripts": {
-    "test": "echo test"
+    "test": "echo test",
+    "release": "node release.js",
+    "release:dry": "node release.js --dry-run"
   },
   "repository": {
     "type": "git",

package/scripts/events/index.js

@@ -3,6 +3,8 @@
 'use strict';
 
 hexo.on('generateBefore', () => {
+  // 页面路径归一化：xxx.html → xxx/，必须先于所有读取 page.path 的逻辑
+  require('./lib/path_normalize')(hexo);
   // Merge config.
   require('./lib/config')(hexo);
   require('./lib/links')(hexo);
@@ -65,4 +67,3 @@ hexo.extend.filter.register('before_generate', async () => {
   }
 });
 
-

package/scripts/events/lib/doc_tree.js

@@ -4,13 +4,15 @@
 
 'use strict';
 
+const { normalize_path } = require('../../lib/path_utils');
+
 class WikiPage {
   constructor(page) { 
     this.id = page._id
     this.wiki = page.wiki
     this.title = page.title
     this.path = page.path
-    this.path_key = page.path.replace('.html', '')
+    this.path_key = normalize_path(page.path)
     this.layout = page.layout
     this.updated = page.updated
   }
@@ -107,7 +109,7 @@ module.exports = ctx => {
       for (let id of Object.keys(item.tree)) {
         const sec = item.tree[id]
         for (let key of sec) {
-          let hs = sub_pages.filter(p => p.path_key == item.base_dir + key)
+          let hs = sub_pages.filter(p => p.path_key == normalize_path(item.base_dir + key))
           if (hs.length > 0) {
             homepage = hs[0]
             break
@@ -134,8 +136,9 @@ module.exports = ctx => {
       for (let title of Object.keys(item.tree)) {
         var sec = { title: title, pages: []}
         for (let key of item.tree[title]) {
-          sec.pages = sec.pages.concat(sub_pages.filter(p => p.path_key == item.base_dir + key))
-          others = others.filter(p => p.path_key != item.base_dir + key)
+          const pagePathKey = normalize_path(item.base_dir + key)
+          sec.pages = sec.pages.concat(sub_pages.filter(p => p.path_key == pagePathKey))
+          others = others.filter(p => p.path_key != pagePathKey)
         }
         sections.push(sec)
       }

package/scripts/events/lib/merge_posts.js

@@ -5,6 +5,8 @@
 
 'use strict';
 
+const { normalize_path } = require('../../lib/path_utils');
+
 class RelatedPage {
   constructor(page) { 
     this.id = page._id
@@ -12,7 +14,7 @@ class RelatedPage {
     this.topic = page.topic
     this.title = page.title
     this.path = page.path
-    this.path_key = page.path.replace('.html', '')
+    this.path_key = normalize_path(page.path)
     this.layout = page.layout
     this.date = page.date
     this.updated = page.updated

package/scripts/events/lib/notebooks.js

@@ -4,6 +4,8 @@
 
 'use strict'
 
+const { normalize_path } = require('../../lib/path_utils');
+
 class NotePage {
   constructor(page) {
     this.id = page._id
@@ -11,7 +13,7 @@ class NotePage {
     this.title = page.title
     this.tags = page.tags
     this.path = page.path
-    this.path_key = page.path.replace('.html', '')
+    this.path_key = normalize_path(page.path)
     this.layout = page.layout
     this.date = page.date
     this.updated = page.updated || page.date
@@ -39,8 +41,8 @@ function prepareNotebook(id, info, ctx) {
     if (notebook.base_dir.startsWith('/')) {
       notebook.base_dir = notebook.base_dir.substring(1)
     }
-    if (notebook.base_dir.endsWith('/')) {
-      notebook.base_dir = notebook.base_dir.substring(0, notebook.base_dir.length - 1)
+    if (notebook.base_dir.length > 1 && !notebook.base_dir.endsWith('/')) {
+      notebook.base_dir = notebook.base_dir + '/'
     }
   } else {
     const notebooksBaseDir = ctx.theme.config.site_tree.notebooks.base_dir

package/scripts/events/lib/path_normalize.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * 页面路径归一化：将 xxx.html 归一为目录形式 xxx/
+ * 必须在 generateBefore 最早阶段执行（先于 doc_tree / notebooks 等读取 page.path），
+ * 直接改写 Page model 存储，保证 page.permalink、JSON-LD、sitemap、search.json
+ * 与 canonical（尾斜杠格式）一致。
+ */
+module.exports = ctx => {
+  const data = ctx.model('Page').data || {}
+  Object.values(data).forEach(page => {
+    if (!page || typeof page.path !== 'string') {
+      return
+    }
+    if (page.layout === false || page.layout === 'false') {
+      return
+    }
+    if (page.path.endsWith('.html') && !page.path.endsWith('/index.html')) {
+      page.path = page.path.replace(/\.html$/, '/')
+    }
+  })
+}

package/scripts/filters/lib/img_lazyload.js

@@ -5,22 +5,22 @@
 
 'use strict';
 
-const fs = require('hexo-fs');
-
+// 懒加载强制开启：不再读取 enable 配置，no-lazy 是唯一例外
 function lazyProcess(htmlContent) {
-  const cfg = this.theme.config.plugins.lazyload;
-  if (cfg == undefined || cfg.enable != true) {
-    return htmlContent;
-  }
   return htmlContent.replace(/<img(.*?)src="(.*?)"(.*?)>/gi, function(imgTag, src_before, src_value, src_after) {
-    // might be duplicate
-    if (/data-srcset/gi.test(imgTag)) {
+    // 已由 tag 插件输出懒加载标记（data-src / data-srcset）的图片不重复处理
+    if (/data-src/gi.test(imgTag)) {
+      return imgTag;
+    }
+    // 使用 srcset 的图片交给浏览器原生处理，避免占位图与 srcset 冲突
+    if (/srcset=/gi.test(imgTag)) {
       return imgTag;
     }
     if (/src="data:image(.*?)/gi.test(imgTag)) {
       return imgTag;
     }
-    if (imgTag.includes(' no-lazy ')) {
+    // no-lazy 兼容 `no-lazy` / `no-lazy=""` 两种写法
+    if (/\bno-lazy\b/gi.test(imgTag)) {
       return imgTag;
     }
     var newImgTag = imgTag;

package/scripts/generators/search.js

@@ -2,6 +2,7 @@
  * https://github.com/wzpan/hexo-generator-search
  */
 const { stripHTML } = require('hexo-util')
+const { normalize_path } = require('../lib/path_utils')
 
 hexo.extend.generator.register('search_json_generator', function (locals) {
   if (this.theme.config.search.service != 'local_search') { return {} }
@@ -28,7 +29,8 @@ hexo.extend.generator.register('search_json_generator', function (locals) {
       temp_post.title = post.title.trim()
     }
     if (post.path) {
-      temp_post.path = root + post.path
+      const path = normalize_path(root + post.path)
+      temp_post.path = path === '/' ? '/' : path + '/'
     }
     if (cfg.content != false && post.content) {
       var content = stripHTML(post.content.replace(/<span class="line">\d+<\/span>/g, '')).trim()

package/scripts/helpers/json_ld.js

@@ -75,7 +75,8 @@ hexo.extend.helper.register('json_ld', function(args) {
 
   } else if (isPage || this.is_home()) {
 
-    const url = this.is_home() ? config.url : this.pretty_url(page.permalink);
+    // 首页 URL 归一为带尾斜杠形式，与 canonical 保持一致
+    const url = this.is_home() ? config.url.replace(/\/?$/, '/') : this.pretty_url(page.permalink);
     schema = {
       '@context': 'https://schema.org',
       '@type': 'Website',
@@ -119,4 +120,4 @@ hexo.extend.helper.register('json_ld', function(args) {
   }
 
   return `<script type="application/ld+json">${JSON.stringify(schema)}</script>`;
-});
+});

package/scripts/helpers/pretty_url.js

@@ -1,22 +1,21 @@
 'use strict';
 
+const { normalize_path } = require('../lib/path_utils');
+
+hexo.extend.helper.register('normalize_path', function (path = '') {
+  return normalize_path(path);
+});
+
 hexo.extend.helper.register('pretty_url', function (path = '') {
   if (path.startsWith('http://') || path.startsWith('https://')) {
-    // 如果是绝对 URL，直接返回
     return path;
   }
-  
   let url = this.url_for(path);
 
-  // 替换 /index.html → /
-  url = url.replace(/\/index\.html$/, '/');
-
-  // 替换 /about.html → /about/
-  url = url.replace(/\.html$/, '/');
+  url = normalize_path(url);
 
-  // 如果没有扩展名，并且不以 / 结尾，补一个 /
-  const hasExtension = /\.[a-zA-Z0-9]+$/.test(url);
-  if (!hasExtension && !url.endsWith('/')) {
+  // 添加尾 /（根路径 / 除外）
+  if (url !== '/') {
     url += '/';
   }
 

package/scripts/lib/path_utils.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * 统一路径规范化：去除 .html 后缀，输出无尾斜杠的干净路径（path_key 格式）
+ * 用于路径比较和匹配
+ */
+function normalize_path(path = '') {
+  if (path.startsWith('http://') || path.startsWith('https://')) {
+    return path;
+  }
+  // /index.html → /
+  path = path.replace(/\/index\.html$/, '/');
+  // 目录首页（无 .html 后缀形式，如 wiki/stellar/index）→ /
+  path = path.replace(/\/index$/, '/');
+  // /xxx.html → /xxx
+  path = path.replace(/\.html$/, '');
+  // 去除尾 /
+  if (path.length > 1 && path.endsWith('/')) {
+    path = path.slice(0, -1);
+  }
+  return path;
+}
+
+module.exports = { normalize_path };

package/scripts/tags/lib/emoji.js

@@ -3,6 +3,7 @@
  * 格式与官方标签插件一致使用空格分隔，中括号内的是可选参数（中括号不需要写出来）
  *
  * {% emoji [source] name [height:1.75em] %}
+ * {% emoji url:https://example.com/emoji.png [name:alt] [height:1.75em] %}
  *
  */
 
@@ -10,12 +11,26 @@
 
 module.exports = ctx => function(args) {
   const config = ctx.theme.config.tag_plugins.emoji
-  args = ctx.args.map(args, ['height'], ['source', 'name'])
+  args = ctx.args.map(args, ['url', 'height', 'name'], ['source', 'name'])
   var el = ''
+  el += '<span class="tag-plugin emoji">'
+  if (args.url) {
+    // 直接引用外部图片，不再走 source 配置查找
+    el += '<img no-lazy="" class="inline"'
+    el += ' src="' + args.url + '"'
+    if (args.name) {
+      el += ' alt="' + args.name + '"'
+    }
+    if (args.height) {
+      el += ' style="height:' + args.height + '"'
+    }
+    el += '/>'
+    el += '</span>'
+    return el
+  }
   if (args.source == undefined) {
     return el
   }
-  el += '<span class="tag-plugin emoji">'
   if (args.name == undefined) {
     // 省略了 source
     for (let id in config) {

package/scripts/tags/lib/image.js

@@ -16,32 +16,27 @@ module.exports = ctx => function(args) {
   if (args.height) {
     style += 'height:' + args.height + ';'
   }
-  // fancybox
-  var fancybox = false
+  // fancybox 默认开启（不再支持全局关闭），单图可用 fancybox:false 关闭
+  var fancybox = true
   var fancyboxHref = null
-  if (ctx.theme.config.plugins.fancybox && ctx.theme.config.plugins.fancybox.enable) {
-    // 主题配置
-    if (ctx.theme.config.tag_plugins.image && ctx.theme.config.tag_plugins.image.fancybox) {
-      fancybox = ctx.theme.config.tag_plugins.image.fancybox
-    }
-    // 覆盖配置
-    if (args.fancybox && args.fancybox.length > 0) {
-      if (args.fancybox == 'false') {
-        fancybox = false
-      } else if (args.fancybox === 'true') {
-        fancybox = args.fancybox
-      } else {
-        fancybox = true
-        fancyboxHref = args.fancybox
-      }
+  if (args.fancybox && args.fancybox.length > 0) {
+    if (args.fancybox == 'false') {
+      fancybox = false
+    } else if (args.fancybox === 'true') {
+      fancybox = true
+    } else {
+      fancybox = true
+      fancyboxHref = args.fancybox
     }
   }
 
   var safeAlt = require('hexo-util').escapeHTML(args.alt || '')
+  // 懒加载占位图（1x1 透明 PNG），真实地址放在 data-src
+  const loadingImg = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAABGdBTUEAALGPC/xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAAaADAAQAAAABAAAAAQAAAADa6r/EAAAAC0lEQVQIHWNgAAIAAAUAAY27m/MAAAAASUVORK5CYII='
   function img(src, alt, style) {
     let a = '<a data-fancybox'
     let img = ''
-    img += `<img class="lazy" src="${src}" data-src="${src}"`
+    img += `<img class="lazy" src="${loadingImg}" data-src="${src}"`
     if (safeAlt) {
       img += ` alt="${safeAlt}"`
       a += ` data-caption="${safeAlt}"`

package/source/css/_common/html.styl

@@ -10,8 +10,6 @@ html
   -webkit-text-size-adjust: 100%
   -ms-text-size-adjust: 100%
   scroll-padding-top: 8px
-  if hexo-config('style.smooth_scroll')
-    scroll-behavior: smooth
 body
   background: var(--background)
   margin: 0

package/source/css/_components/widgets/toc.styl

@@ -141,7 +141,7 @@
   .widget-body
     grid-template-rows: 0fr
 
-// 编辑本文按钮
+// 操作按钮（回到顶部 / 参与讨论）
 .widget-wrapper.toc .widget-body+.widget-footer:before 
   content: ''
   position absolute
@@ -188,4 +188,4 @@
     a
       background: var(--block)
     a+a
-      margin-top: 4px
+      margin-top: 4px

package/source/css/_plugins/index.styl

@@ -14,9 +14,6 @@ if hexo-config('plugins.copycode.enable')
   @import 'copycode'
 if hexo-config('plugins.tianli_gpt.enable')
   @import 'tianli_gpt'
-if hexo-config('plugins.pjax.enable')
-  @import 'pjax'
-
 if hexo-config('plugins.katex.enable')
   @import 'katex'
 

package/source/css/_plugins/lazyload.styl

@@ -1,9 +1,13 @@
-$lazyTransitionType = hexo-config('plugins.lazyload.transition')
+$lazyTransitionType = hexo-config('dependencies.lazyload.transition')
 $loadingImageSize = 2rem
 
 img:not([src])
   visibility: hidden
 
+.lazy
+  opacity: 0
+  z-index: 1
+
 .lazy-box
   position: relative
   overflow: hidden
@@ -12,26 +16,8 @@ img:not([src])
     background: var(--block)
     min-height: 4rem
 
-// 懒加载
-img[data-ll-status]
-  z-index: 1
-  &:not(.loaded)
-    opacity: 0
-  &.loaded,&.error
-    opacity: 1
-  if $lazyTransitionType == 'blur'
-    trans1 all 0.5s
-    &:not(.loaded)
-      filter blur(20px)
-      -webkit-filter blur(20px)
-    &.loaded,&.error
-      filter none
-      -webkit-filter none
-  else
-    trans1 all 0.38s
-
 // 加载占位动画
-img[data-ll-status]+.lazy-icon
+img.lazy.loading + .lazy-icon
   position: absolute
   width: $loadingImageSize
   height: $loadingImageSize
@@ -45,13 +31,41 @@ img[data-ll-status]+.lazy-icon
   background-position: center
 
 // 加载完成
-img[data-ll-status].loaded
-  &+.lazy-icon
-    display: none
+img.lazy.loaded + .lazy-icon,
+img.lazy.error + .lazy-icon
+  display: none
 
 // 加载失败
-img[data-ll-status].error
+img.lazy.error
   width: $loadingImageSize
   height: $loadingImageSize
-  &+.lazy-icon
-    display: none
+
+// 懒加载完成动画：使用 keyframes 而非 transition，
+// 因为缓存图片可能在 loading 状态被绘制前就完成加载，transition 没有起点会直接闪现
+if $lazyTransitionType == 'blur'
+  .lazy
+    filter: blur(20px)
+    -webkit-filter: blur(20px)
+  .lazy.loaded, .lazy.error
+    opacity: 1
+    filter: none
+    -webkit-filter: none
+    animation: ll-blur-in 0.5s ease-out
+  @keyframes ll-blur-in
+    from
+      opacity: 0
+      filter: blur(20px)
+      -webkit-filter: blur(20px)
+    to
+      opacity: 1
+      filter: none
+      -webkit-filter: none
+else
+  .lazy.loaded, .lazy.error
+    opacity: 1
+    animation: ll-fade-in 0.5s ease-out
+  @keyframes ll-fade-in
+    from
+      opacity: 0
+    to
+      opacity: 1

package/source/css/_plugins/scrollreveal.styl

@@ -1,2 +1,6 @@
 .slide-up
-  visibility: hidden
+  visibility: hidden
+
+// ScrollReveal 加载/初始化失败时强制显示内容，避免空白页
+html.sr-fallback .slide-up
+  visibility: visible !important