hexo-theme-stellar 1.39.0 → 1.40.0

package/layout/page.ejs

@@ -44,8 +44,12 @@ function layoutDiv() {
     el += partial('_partial/main/navbar/article_banner')
   }
   el += `<article class="${articleClass()}">`
-  if (page.content && page.content.length > 0) {
+  if (page.content && String(page.content).trim().length > 0) {
     el += page.content
+  } else {
+    // wiki 项目首页正文为空（剪裁空白后）且配置了 repo 时，
+    // 以该仓库 README.md 作为主页正文（应用层 helper，复用底层远程 md 渲染组件）
+    el += wiki_readme_html(theme.wiki.tree[page.wiki], page)
   }
   if (notebook) {
     el += partial('_partial/main/notebook/note_tags', { notebook: notebook })

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "hexo-theme-stellar",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "description": "Elegant and powerful theme for Hexo.",
   "main": "package.json",
   "scripts": {
     "lint": "eslint .",
-    "test": "node --test",
+    "test": "node ci/check-require-decls.js && node --test",
     "check": "npm run lint && npm test && python3 docs/knowledge/tools/verify.py",
     "release": "node release.js",
     "release:dry": "node release.js --dry-run"
@@ -29,10 +29,12 @@
     "glob": "^10.4.0",
     "hexo-renderer-ejs": "^2.0.0",
     "hexo-renderer-stylus": "^3.0.1",
+    "hexo-pagination": "^3.0.0",
     "probe-image-size": "^7.2.3"
   },
   "homepage": "https://xaoxuu.com/wiki/stellar/",
   "devDependencies": {
-    "eslint": "^9.39.5"
+    "eslint": "^9.39.5",
+    "hexo-util": "^4.0.0"
   }
 }

package/scripts/commands/new-note.js

@@ -36,7 +36,7 @@ hexo.extend.console.register('new-note', 'Create a new note', {
   const frontMatter = [
     '---',
     `title: ${name}`,
-    `date: ${date.getFullYear()}-${String(date.getMonth()+1).padStart(2,'0')}-${String(date.getDate()).padStart(2,'0')} ${String(date.getHours()).padStart(2,'0')}:${String(date.getMinutes()).padStart(2,'0')}:${String(date.getSeconds()).padStart(2,'0')}`,
+    `date: ${date.getFullYear()}-${String(date.getMonth()+1).padStart(2,'0')}-${String(date.getDate()).padStart(2,'0')} ${String(date.getHours()).padStart(2,'0')}:${String(date.getMinutes()).padStart(2,'0')}`,
     `tags: [${tags.map(t => '"'+t+'"').join(', ')}]`,
     `notebook: ${book}`,
     '---',
@@ -46,4 +46,4 @@ hexo.extend.console.register('new-note', 'Create a new note', {
   fs.writeFileSync(filePath, frontMatter);
   console.log(`Created: ${filePath}`);
   callback();
-}); 
+}); 

package/scripts/helpers/category_tree.js

@@ -0,0 +1,11 @@
+/* global hexo */
+'use strict';
+
+const { buildCategoryTree } = require('../lib/category_tree');
+
+hexo.extend.helper.register('category_tree', function(categories) {
+  const list = categories && typeof categories.toArray === 'function'
+    ? categories.toArray()
+    : (categories || []);
+  return buildCategoryTree(list);
+});

package/scripts/helpers/escape_html.js

@@ -0,0 +1,9 @@
+/* global hexo */
+'use strict';
+
+const { escapeHTML } = require('hexo-util');
+
+// 供 EJS 模板使用的 HTML 转义辅助函数：属性值与文本内容均可安全使用。
+hexo.extend.helper.register('escape_html', function(value) {
+  return escapeHTML(value == null ? '' : String(value));
+});

package/scripts/helpers/json_ld.js

@@ -98,6 +98,11 @@ hexo.extend.helper.register('json_ld', function(args) {
 
       if (page.excerpt || page.description) {
         schema.description = this.strip_html(page.description || page.excerpt);
+      } else if (page.wiki) {
+        const proj = this.theme.wiki.tree[page.wiki];
+        if (proj && proj.description) {
+          schema.description = proj.description;
+        }
       } else {
         schema.description = util.truncate(this.strip_html(page.content), {length: 200});
       }

package/scripts/helpers/mdrender.js

@@ -0,0 +1,29 @@
+/* global hexo */
+'use strict';
+
+const { mdrenderHtml, PLACEHOLDER_CLASS } = require('../lib/mdrender_html');
+const { wikiReadmeHtml, isWikiReadmePage } = require('../lib/wiki_readme');
+
+// 远程 Markdown 渲染占位标记（底层组件服务端入口，供 EJS 模板复用）
+hexo.extend.helper.register('mdrender_html', function (src, options = {}) {
+  if (options.ghraw == null) {
+    options.ghraw = hexo.theme.config.api_host.ghraw;
+  }
+  return mdrenderHtml(src, options);
+});
+
+// wiki 项目 README 主页占位（首页正文为空且配置 repo 时输出，否则空串）
+hexo.extend.helper.register('wiki_readme_html', function (proj, page) {
+  return wikiReadmeHtml(proj, page, { ghraw: hexo.theme.config.api_host.ghraw });
+});
+
+// 页面是否包含客户端渲染的远程 md（供 TOC 预留空容器）
+hexo.extend.helper.register('has_remote_md', function (page) {
+  if (!page) {
+    return false;
+  }
+  if (page.content && page.content.indexOf(PLACEHOLDER_CLASS) >= 0) {
+    return true;
+  }
+  return isWikiReadmePage(hexo.theme.config.wiki.tree[page.wiki], page);
+});

package/scripts/helpers/reading_time.js

@@ -0,0 +1,12 @@
+/* global hexo */
+'use strict';
+
+const { countWords, readingMinutes } = require('../lib/reading_time');
+
+hexo.extend.helper.register('word_count', function(page) {
+  return countWords(page && (page.content || page._content || ''));
+});
+
+hexo.extend.helper.register('reading_time', function(page) {
+  return readingMinutes(page && (page.content || page._content || ''));
+});

package/scripts/helpers/related_posts.js

@@ -6,6 +6,10 @@
 
 var util = require('hexo-util');
 
+function esc(v) {
+  return util.escapeHTML(v == null ? '' : String(v))
+}
+
 hexo.extend.helper.register('popular_posts_wrapper', function(args){
   const title = args.title;
   const json = args.json.json;
@@ -18,7 +22,7 @@ hexo.extend.helper.register('popular_posts_wrapper', function(args){
   var returnHTML = "";
   var div = `
     <section class='header'>
-      <div class='title cap theme'>${title}</div>
+      <div class='title cap theme'>${esc(title)}</div>
     </section>
     <section class='body'>
     `;
@@ -28,14 +32,14 @@ hexo.extend.helper.register('popular_posts_wrapper', function(args){
 
   function listItem(obj){
     var el = '';
-    el += '<a class="item" href="' + obj.path + '" title="' + obj.title + '">';
+    el += '<a class="item" href="' + esc(obj.path) + '" title="' + esc(obj.title) + '">';
     var p = posts.filter(p => root + p.path == obj.path)
     if (p && p.length > 0) {
       p = p.data[0];
     }
-    el += '<span class="title">' + obj.title + '</span>';
+    el += '<span class="title">' + esc(obj.title) + '</span>';
     if (obj.excerpt && obj.excerpt.length > 0) {
-      el += '<span class="excerpt">' + util.truncate(util.stripHTML(obj.excerpt), {length: 120}) + '</span>';
+      el += '<span class="excerpt">' + esc(util.truncate(util.stripHTML(obj.excerpt), {length: 120})) + '</span>';
     }
     el +=  '</a>';
     return el;
@@ -47,7 +51,7 @@ hexo.extend.helper.register('popular_posts_wrapper', function(args){
       }
   }
   
-  if (returnHTML != "") returnHTML = "<div class=\"" + cls + "\">" + returnHTML + "</div>";
+  if (returnHTML != "") returnHTML = "<div class=\"" + esc(cls) + "\">" + returnHTML + "</div>";
   div += returnHTML;
   div += '</section>';
   return div;

package/scripts/lib/category_tree.js

@@ -0,0 +1,26 @@
+'use strict';
+
+// 分类嵌套树构建（#564）：基于 parent 关系递归组装，兼容 2/3/4 级
+function buildCategoryTree(list) {
+  const items = (list || []).map(c => ({
+    _id: c._id,
+    name: c.name,
+    path: c.path,
+    parentId: c.parent ? (typeof c.parent === 'object' ? c.parent._id : c.parent) : null,
+    count: (c.posts && c.posts.length) || 0,
+    children: []
+  }));
+  const byId = {};
+  items.forEach(item => { byId[item._id] = item; });
+  const roots = [];
+  items.forEach(item => {
+    if (item.parentId != null && byId[item.parentId]) {
+      byId[item.parentId].children.push(item);
+    } else {
+      roots.push(item);
+    }
+  });
+  return roots;
+}
+
+module.exports = { buildCategoryTree };

package/scripts/lib/mdrender_html.js

@@ -0,0 +1,97 @@
+/**
+ * mdrender_html.js v2 | https://github.com/xaoxuu/hexo-theme-stellar/
+ *
+ * 远程 Markdown 渲染底层组件（通用能力，不包含应用场景逻辑）：
+ * 统一生成 .data-service.ds-mdrender 占位标记。
+ *
+ * 行为：
+ * - src 为 GitHub raw 类地址时，host 替换为调用方传入的 ghraw
+ *   （主题配置 api_host.ghraw，代码不设默认值）；未传 ghraw 时保留 src 原 host；
+ * - 识别后输出 data-base（该 md 所在 raw 目录）；
+ * - 非 GitHub src 原样输出、不带 data-base；
+ * - replace=true 输出 data-replace（客户端原地替换，无外部容器）；
+ * - heading 缺省 true，输出 data-heading（客户端标题适配本地文章格式）。
+ */
+
+'use strict';
+
+// GitHub raw 规范 host：用于识别用户 src 中的规范 raw 地址（GitHub 固有事实，非配置默认值）
+const GITHUB_RAW_HOST = 'raw.githubusercontent.com';
+
+// 占位标记类名（组件契约：服务端生成、services 按需加载、客户端渲染共用）
+const PLACEHOLDER_CLASS = 'ds-mdrender';
+
+/**
+ * 解析 GitHub raw 地址（规范 raw host 或调用方传入的 ghraw 镜像 host）。
+ * 返回 { host, owner, repo, ref, rest }；无法识别时返回 null。
+ */
+function parseGitHubRaw(url, ghrawHost) {
+  if (typeof url !== 'string' || url.length === 0) {
+    return null;
+  }
+  let u;
+  try {
+    u = new URL(url);
+  } catch (e) {
+    return null;
+  }
+  const host = u.hostname || '';
+  if (host !== GITHUB_RAW_HOST && host !== ghrawHost) {
+    return null;
+  }
+  const segs = u.pathname.split('/').filter(s => s.length > 0);
+  if (segs.length < 3) {
+    return null;
+  }
+  return {
+    host: host,
+    owner: segs[0],
+    repo: segs[1],
+    ref: segs[2],
+    rest: segs.slice(3).join('/')
+  };
+}
+
+function escapeAttr(value) {
+  return String(value).replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+}
+
+/**
+ * 生成远程 Markdown 渲染占位标记。
+ * options: { id, replace, heading, ghraw }
+ */
+function mdrenderHtml(src, options = {}) {
+  const parsed = parseGitHubRaw(src, options.ghraw);
+  let url = src;
+  let base = null;
+  if (parsed) {
+    // 未传 ghraw 时保留 src 原 host，不硬编码默认值
+    const ghraw = options.ghraw || parsed.host;
+    const dir = `${parsed.owner}/${parsed.repo}/${parsed.ref}/`;
+    url = `https://${ghraw}/${dir}${parsed.rest}`;
+    base = `https://${ghraw}/${dir}`;
+  }
+  let el = '<div class="data-service ds-mdrender"';
+  el += ` src="${escapeAttr(url)}"`;
+  if (base) {
+    el += ` data-base="${escapeAttr(base)}"`;
+  }
+  if (options.replace === true) {
+    el += ' data-replace="true"';
+  }
+  if (options.heading !== false) {
+    el += ' data-heading="true"';
+  }
+  if (options.id) {
+    el += ` id="${escapeAttr(options.id)}"`;
+  }
+  el += '></div>';
+  return el;
+}
+
+module.exports = {
+  GITHUB_RAW_HOST,
+  PLACEHOLDER_CLASS,
+  parseGitHubRaw,
+  mdrenderHtml
+};

package/scripts/lib/reading_time.js

@@ -0,0 +1,16 @@
+'use strict';
+
+// 阅读信息统计（#302）：中文字符按 1 字计，英文/数字按空格分词计词
+function countWords(content) {
+  const text = String(content || '').replace(/<[^>]*>/g, ' ');
+  const cjk = (text.match(/[\u4e00-\u9fff]/g) || []).length;
+  const latin = (text.replace(/[\u4e00-\u9fff]/g, ' ').match(/[A-Za-z0-9]+(?:[-'][A-Za-z0-9]+)*/g) || []).length;
+  return cjk + latin;
+}
+
+// 混合阅读速度约 300 字/分钟，最少 1 分钟
+function readingMinutes(content, speed = 300) {
+  return Math.max(1, Math.ceil(countWords(content) / speed));
+}
+
+module.exports = { countWords, readingMinutes };

package/scripts/lib/wiki_readme.js

@@ -0,0 +1,57 @@
+/**
+ * wiki_readme.js v1 | https://github.com/xaoxuu/hexo-theme-stellar/
+ *
+ * Wiki 应用层：项目首页正文为空（剪裁空白后）且配置 repo 时，
+ * 以该仓库 README.md 作为主页正文（复用底层远程 md 渲染组件）。
+ */
+
+'use strict';
+
+const { mdrenderHtml } = require('./mdrender_html');
+
+/**
+ * README 地址。host 由调用方从主题配置 api_host.ghraw 传入；
+ * branch 缺省用 GitHub HEAD（自动指向默认分支）。
+ */
+function readmeUrl(repo, branch, host) {
+  return `https://${host}/${repo}/${branch || 'HEAD'}/README.md`;
+}
+
+// 页面正文是否为空（剪裁多余空行、空格后判断）
+function isEmptyContent(page) {
+  return !page || !String(page.content || '').trim();
+}
+
+/**
+ * 判定是否 README 主页：配置了 repo 的项目首页且正文为空。
+ */
+function isWikiReadmePage(proj, page) {
+  if (!proj || !proj.repo || !page || !proj.homepage) {
+    return false;
+  }
+  if (!isEmptyContent(page)) {
+    return false;
+  }
+  return proj.homepage.path === page.path;
+}
+
+/**
+ * 生成 README 主页占位（原地替换模式）；不适用时返回空串。
+ * options: { ghraw }
+ */
+function wikiReadmeHtml(proj, page, options = {}) {
+  if (!isWikiReadmePage(proj, page)) {
+    return '';
+  }
+  return mdrenderHtml(readmeUrl(proj.repo, proj.branch, options.ghraw), {
+    ghraw: options.ghraw,
+    replace: true
+  });
+}
+
+module.exports = {
+  readmeUrl,
+  isEmptyContent,
+  isWikiReadmePage,
+  wikiReadmeHtml
+};

package/scripts/tags/index.js

@@ -48,6 +48,8 @@ hexo.extend.tag.register('audio', require('./lib/audio')(hexo))
 hexo.extend.tag.register('video', require('./lib/video')(hexo))
 hexo.extend.tag.register('rating', require('./lib/rating')(hexo))
 hexo.extend.tag.register('vote', require('./lib/vote')(hexo))
+hexo.extend.tag.register('table', require('./lib/table')(hexo), {ends: true})
+hexo.extend.tag.register('tip', require('./lib/tip')(hexo), {ends: true})
 
 // read 阅读类
 hexo.extend.tag.register('reel', require('./lib/read/reel')(hexo), true)

package/scripts/tags/lib/md.js

@@ -1,20 +1,28 @@
 /**
- * md.js v1.0 | https://github.com/volantis-x/hexo-theme-volantis/
- * contributor: @MHuiG
- * 
+ * md.js v2 | https://github.com/xaoxuu/hexo-theme-stellar/
+ *
  * 格式与官方标签插件一致使用空格分隔，中括号内的是可选参数（中括号不需要写出来）
  *
- * {% md src %}
+ * {% md src [wrap:true|false] %}
+ *
+ * wrap 默认 true：渲染结果保留在 .data-service.ds-mdrender 容器内（现状）；
+ * wrap:false：渲染后占位元素被原地替换，无外部容器（复用底层 data-replace）。
  *
+ * 复用底层组件（scripts/lib/mdrender_html.js）输出渲染占位；
+ * 容器结构与现状一致，标题默认适配本地文章格式（id + headerlink，h1 隐藏）。
  */
 'use strict'
 
+const { mdrenderHtml } = require('../../lib/mdrender_html')
+
 var md_index = 0
 
 module.exports = ctx => function(args) {
-  args = ctx.args.map(args, [''], ['src'])
+  args = ctx.args.map(args, ['wrap'], ['src'])
   const md_id = "md_" + ++md_index
-  return `
-  <div class="data-service ds-mdrender" src="${args.src}" id="${md_id}"></div>
-  `
-}
+  return mdrenderHtml(args.src, {
+    id: md_id,
+    ghraw: ctx.theme.config.api_host.ghraw,
+    replace: args.wrap === 'false'
+  })
+}

package/scripts/tags/lib/table.js

@@ -0,0 +1,22 @@
+/**
+ * table.js v1.0 | https://github.com/xaoxuu/hexo-theme-stellar/
+ * 格式与官方标签插件一致使用空格分隔，中括号内的是可选参数（中括号不需要写出来）
+ *
+ * {% table [style:scroll|wrap|compact] %}
+ * | 列1 | 列2 |
+ * | --- | --- |
+ * | a   | b   |
+ * {% endtable %}
+ */
+
+'use strict'
+
+module.exports = ctx => function(args, content = '') {
+  args = ctx.args.map(args, ['style'], [])
+  const style = ['scroll', 'wrap', 'compact'].includes(args.style) ? args.style : 'scroll'
+  var el = ''
+  el += `<div class="tag-plugin table table-${style}">`
+  el += ctx.render.renderSync({text: content, engine: 'markdown'})
+  el += '</div>'
+  return el
+}

package/scripts/tags/lib/timeline.js

@@ -14,15 +14,15 @@
 
 'use strict'
 
-function layoutNodeTitle(ctx, content) {
-  var el = ''
-  el += '<div class="header">'
-  if (content && content.length > 0) {
-    el += `<span>${content}</span>`
-  }
-  el += '</div>'
-  return el
-}
+function layoutNodeTitle(ctx, content) {
+  var el = ''
+  el += '<div class="header">'
+  if (content && content.length > 0) {
+    el += `<span>${ctx.render.renderSync({text: content, engine: 'markdown'}).split('\n').join('').replace(/<\/?p>/g, '')}</span>`
+  }
+  el += '</div>'
+  return el
+}
 
 function layoutNodeContent(ctx, content) {
   var el = ''

package/scripts/tags/lib/tip.js

@@ -0,0 +1,23 @@
+/**
+ * tip.js v1.0 | https://github.com/xaoxuu/hexo-theme-stellar/
+ * 格式与官方标签插件一致使用空格分隔，中括号内的是可选参数（中括号不需要写出来）
+ *
+ * {% tip text:注解内容 %}词句{% endtip %}
+ */
+
+'use strict'
+
+module.exports = ctx => function(args, content = '') {
+  args = ctx.args.map(args, ['text'], [])
+  const escapeHTML = require('hexo-util').escapeHTML
+  const text = escapeHTML(args.text || '')
+  const inner = ctx.render.renderSync({text: content, engine: 'markdown'})
+    .split('\n').join('')
+    .replace(/<\/?p>/g, '')
+  var el = ''
+  el += `<span class="tag-plugin tip" tabindex="0">`
+  el += `<span class="tip-text">${inner}</span>`
+  el += `<span class="tip-bubble" role="tooltip">${text}</span>`
+  el += '</span>'
+  return el
+}

package/source/css/_common/device.styl

@@ -18,6 +18,7 @@
   float: right
   z-index: 999999
   display: flex
+  align-items: center
   justify-content: center
   flex-direction: column
   gap: $bar-item-gap
@@ -37,6 +38,8 @@
   color: var(--text)
   background: none
   box-sizing: border-box
+  flex: 0 0 auto
+  margin: 0 auto
   width: 36px
   height: 36px
   padding: 4px

package/source/css/_components/list.styl

@@ -13,6 +13,7 @@
     position: absolute
     left: 0
     bottom: -2px
+    border-radius: 2px
     z-index: -1
     width: 100%
     height: 0
@@ -69,11 +70,11 @@
       transform: scale(1.05)
   img
     filter: brightness(var(--img-br)) saturate(var(--img-sat))
-    // 封面放大用 0.5s 缓动，其余属性（亮度/饱和度）保持主题默认 0.2s
-    transition: all .2s ease-out, transform .5s ease-out
-    -moz-transition: all .2s ease-out, transform .5s ease-out
-    -webkit-transition: all .2s ease-out, transform .5s ease-out
-    -o-transition: all .2s ease-out, transform .5s ease-out
+    // 封面放大用 1.5s 缓动，其余属性（亮度/饱和度）保持主题默认 0.2s
+    transition: all .2s ease-out, transform 1.5s ease-out
+    -moz-transition: all .2s ease-out, transform 1.5s ease-out
+    -webkit-transition: all .2s ease-out, transform 1.5s ease-out
+    -o-transition: all .2s ease-out, transform 1.5s ease-out
   .excerpt
     margin: 1rem 0
     @media screen and (max-width: $device-mobile)
@@ -105,6 +106,11 @@
         object-fit: contain
       svg
         color: $c-red
+  .card-tags
+    display: flex
+    flex-wrap: wrap
+    align-items: center
+    gap: 0 .5rem
 
 
 // common article

package/source/css/_components/pages/archives.styl

@@ -42,10 +42,10 @@
 
 .post-list #cats
   padding: 0
+  .cat-item
+    display: block
   a.cat
     display: flex
-    &.child
-      padding-left: 2rem
     padding: .5em 1rem
     border-radius: $border-bar
     color: var(--text-p2)
@@ -72,6 +72,10 @@
       .badge
         opacity: 1
         color: var(--theme)
+  .cat-children
+    margin-left: 1.25rem
+    padding-left: .75rem
+    border-left: 1px dashed var(--text-meta)
 
 .post-list #tags
   display: flex
@@ -103,4 +107,4 @@
 
 @media screen and (min-width: $device-mobile)
   .post-list.author #archive
-    padding: 1rem 0
+    padding: 1rem 0

package/source/css/_components/partial/bread-nav.styl

@@ -4,10 +4,18 @@
   display: flex
   justify-content: space-between
   color: var(--text-banner)
+  .left
+    flex: 1
+    min-width: 0
   .flex-row
     display: flex
     align-items: baseline
     flex-direction: row
+  #breadcrumb
+    .reading.right
+      margin-left: auto
+      white-space: nowrap
+      opacity: .8
   a
     color: var(--text-banner)
     padding: 4px
@@ -50,4 +58,4 @@
     span 
       margin-left: 4px
     &:hover
-      opacity 1
+      opacity 1

package/source/css/_components/sidebar/search.styl

@@ -29,8 +29,9 @@
       background: var(--leftbar-search-line, var(--bg-a100))
       :root[data-theme="dark"] &
         background: var(--leftbar-search-line, var(--bg-a20))
-      @media screen and (prefers-color-scheme: dark)
-        background: var(--leftbar-search-line, var(--bg-a20))
+      :root:not([data-theme]) &
+        @media screen and (prefers-color-scheme: dark)
+          background: var(--leftbar-search-line, var(--bg-a20))
       z-index 0
       trans1 all
     &:after
@@ -62,8 +63,9 @@
       color: var(--text-p3)
       :root[data-theme="dark"] &
         color: var(--text-p2)
-      @media screen and (prefers-color-scheme: dark)
-        color: var(--text-p2)
+      :root:not([data-theme]) &
+        @media screen and (prefers-color-scheme: dark)
+          color: var(--text-p2)
   .search-button 
     border-radius: $border-bar
     display: flex