hexo-text-pipeline 0.2.0 → 0.4.0

package/README.md

@@ -125,7 +125,7 @@ Each render cycle replaces the previous snapshot. Add the tap dir to `.gitignore
 
 ## Built-in preset: `obsidian`
 
-Compiles Obsidian Flavored Markdown for Hexo. Enable with `presets: [obsidian]`.
+Compiles Obsidian Flavored Markdown for Hexo. Enable with `presets: [obsidian]` under the `text_pipeline:` key — full walkthrough in [docs/USING-PRESETS.md](docs/USING-PRESETS.md).
 
 | Node | Syntax | Default | Behavior |
 |------|--------|---------|----------|
@@ -139,13 +139,16 @@ Compiles Obsidian Flavored Markdown for Hexo. Enable with `presets: [obsidian]`.
 | `callout` | `> [!type] Title` | **off** | `<div class="callout callout-type">`; off because most renderers/themes already support callouts |
 
 ```yaml
-presets:
-  - name: obsidian
-    config:
-      domain_prefix: ''                  # link prefix for wikilink/mdlink/embed
-      callout: { enable: true }          # opt in
-      embed: { asset_prefix: /images }   # prepended to embedded image paths
-      mermaid: { theme: dark, priority: 15 }   # any node: sub-config + priority override
+text_pipeline:
+  presets:
+    - name: obsidian
+      config:
+        domain_prefix: ''                  # link prefix for wikilink/mdlink/embed
+        callout:
+          enable: true                     # opt in
+          css: ./source/css/callout.css    # optional: replace the built-in styles with your own file(s)
+        embed: { asset_prefix: /images }   # prepended to embedded image paths
+        mermaid: { theme: dark, priority: 15 }   # any node: sub-config + priority override
 ```
 
 ## Installation
@@ -161,7 +164,7 @@ text_pipeline:
   enable: true       # master switch
   debug: false       # verbose logging
   strict: false      # config errors / node failures fail the build (CI)
-  inject_css: true   # nodes' default styles (e.g. callout)
+  inject_css: true   # nodes' default styles (e.g. callout); per-node `css: <file|list>` swaps in your own
   inject_js: true    # nodes' frontend scripts (e.g. mermaid loader)
   presets: []        # built-in name | npm package | ./local/path | { name, config }
   hooks: []          # { script | command, stage, slot, priority, name, timeout, match, enable }
@@ -175,13 +178,14 @@ text_pipeline:
 
 ## Development
 
-Zero runtime dependencies, Node >= 16.
+The only runtime dependency is `hexo-util` (ships with Hexo itself; npm dedupes to the copy your site already has, zero extra install cost). Node >= 16.
 
 ```bash
 npm test   # node --test
 ```
 
 - **Single-file plugins (start here to write a plugin)**: [docs/PLUGINS.md](docs/PLUGINS.md)
+- Using presets (enabling, config layers, debugging): [docs/USING-PRESETS.md](docs/USING-PRESETS.md)
 - Hooks API reference (stage inputs, ctx fields, debugging workflow): [docs/HOOKS-API.md](docs/HOOKS-API.md)
 - Architecture, stage table, node contract: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 - Extending: hook vs preset node vs new preset: [docs/EXTENDING.md](docs/EXTENDING.md)

package/README.zh-CN.md

@@ -125,7 +125,7 @@ text_pipeline:
 
 ## 内置 preset：`obsidian`
 
-把 Obsidian Flavored Markdown 编译为 Hexo 友好输出。`presets: [obsidian]` 启用。
+把 Obsidian Flavored Markdown 编译为 Hexo 友好输出。在 `text_pipeline:` 键下写 `presets: [obsidian]` 启用——完整使用指南见 [docs/USING-PRESETS.zh-CN.md](docs/USING-PRESETS.zh-CN.md)。
 
 | Node | 语法 | 默认 | 行为 |
 |------|------|------|------|
@@ -139,13 +139,16 @@ text_pipeline:
 | `callout` | `> [!type] 标题` | **关** | `<div class="callout callout-type">`；主流渲染器/主题已多自带支持，所以默认关 |
 
 ```yaml
-presets:
-  - name: obsidian
-    config:
-      domain_prefix: ''                  # wikilink/mdlink/embed 的链接前缀
-      callout: { enable: true }          # 按需打开
-      embed: { asset_prefix: /images }   # 嵌入图片路径的前缀
-      mermaid: { theme: dark, priority: 15 }   # 任意 node：子配置 + priority 覆盖
+text_pipeline:
+  presets:
+    - name: obsidian
+      config:
+        domain_prefix: ''                  # wikilink/mdlink/embed 的链接前缀
+        callout:
+          enable: true                     # 按需打开
+          css: ./source/css/callout.css    # 可选：用自己的样式文件整体替换内置样式
+        embed: { asset_prefix: /images }   # 嵌入图片路径的前缀
+        mermaid: { theme: dark, priority: 15 }   # 任意 node：子配置 + priority 覆盖
 ```
 
 ## 安装
@@ -161,7 +164,7 @@ text_pipeline:
   enable: true       # 总开关
   debug: false       # 详细日志
   strict: false      # 配置错误 / 节点失败让构建失败（CI 用）
-  inject_css: true   # node 的默认样式（如 callout）
+  inject_css: true   # node 的默认样式（如 callout）；node 子配置 css: <文件|列表> 可换成自己的
   inject_js: true    # node 的前端脚本（如 mermaid 加载器）
   presets: []        # 内置名 | npm 包 | ./本地路径 | { name, config }
   hooks: []          # { script | command, stage, slot, priority, name, timeout, match, enable }
@@ -175,13 +178,14 @@ text_pipeline:
 
 ## 开发
 
-零运行时依赖，Node >= 16。
+唯一运行时依赖是 `hexo-util`（Hexo 本体自带，npm 会直接复用站点已有的那份，零额外安装成本）。Node >= 16。
 
 ```bash
 npm test   # node --test
 ```
 
 - **单文件插件（写插件从这里开始）**：[docs/PLUGINS.zh-CN.md](docs/PLUGINS.zh-CN.md)
+- 使用 preset（启用、配置分层、调试）：[docs/USING-PRESETS.zh-CN.md](docs/USING-PRESETS.zh-CN.md)
 - Hooks 接口文档（stage 输入、ctx 字段、调试工作流）：[docs/HOOKS-API.zh-CN.md](docs/HOOKS-API.zh-CN.md)
 - 架构、stage 表、node 契约：[docs/ARCHITECTURE.zh-CN.md](docs/ARCHITECTURE.zh-CN.md)
 - 扩展指南：hook vs preset node vs 新 preset：[docs/EXTENDING.zh-CN.md](docs/EXTENDING.zh-CN.md)

package/lib/core/engine.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const fs = require('node:fs');
+const path = require('node:path');
 const { normalizeConfig } = require('./config');
 const { STAGES, LATE_FILTER_PRIORITY } = require('./stages');
 const { createRegistry, createPublicApi } = require('./api');
@@ -107,8 +109,22 @@ function register(hexo) {
   const canInject = hexo.extend.injector && typeof hexo.extend.injector.register === 'function';
   const injectAssets = (node) => {
     if (!canInject) return;
-    if (pluginConfig.injectCss && node.css) {
-      hexo.extend.injector.register('head_end', '<style>' + node.css + '</style>');
+    const sub = node.config || {};
+    if (pluginConfig.injectCss) {
+      // 用户样式文件（css: 路径 | 路径列表，相对 Hexo 根目录）直接替换 node 的默认样式
+      const cssFiles = typeof sub.css === 'string' ? [sub.css] : Array.isArray(sub.css) ? sub.css : [];
+      if (cssFiles.length) {
+        for (const file of cssFiles) {
+          try {
+            const userCss = fs.readFileSync(path.resolve(baseDir || process.cwd(), String(file)), 'utf8');
+            hexo.extend.injector.register('head_end', '<style>' + userCss + '</style>');
+          } catch (err) {
+            engineLog.warn('node "' + node.name + '" css file not readable: ' + file + ' (' + (err && err.message) + ')');
+          }
+        }
+      } else if (node.css) {
+        hexo.extend.injector.register('head_end', '<style>' + node.css + '</style>');
+      }
     }
     if (pluginConfig.injectJs && node.js) {
       const js = typeof node.js === 'function' ? node.js(node.config || {}) : node.js;

package/lib/presets/obsidian/converters/callout/styles.js

@@ -1,8 +1,9 @@
 'use strict';
 
 /**
- * 默认样式，经 hexo injector 注入 head_end；text_pipeline.inject_css: false 可关闭，
- * 关闭后结构类名（callout / callout-title / callout-content / data-callout）由主题自行接管。
+ * 默认样式（色板参照 Obsidian 默认主题），经 hexo injector 注入 head_end。
+ * 子配置 css: <文件路径|列表> 可用自己的样式整体替换这份默认；全局 text_pipeline.inject_css: false 全关。
+ * 替换/关闭后结构类名（callout / callout-title / callout-content / data-callout）由用户样式或主题接管。
  */
 module.exports = `
 .callout{--callout-color:68,138,255;border-left:4px solid rgb(var(--callout-color));border-radius:4px;padding:.75rem 1rem;margin:1rem 0;background:rgba(var(--callout-color),.08)}

package/lib/presets/obsidian/converters/mermaid/index.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { escapeHTML } = require('hexo-util');
+
 const DEFAULT_SCRIPT_SRC = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';
 const DEFAULT_CLASS = 'mermaid';
 
@@ -11,10 +13,6 @@ const DEFAULT_CLASS = 'mermaid';
  * 前端脚本默认按需注入（页面没有 .mermaid 元素时不加载 CDN）：
  * converters.mermaid 子配置：class / inject_script / script_src / theme。
  */
-function escapeHtml(text) {
-  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-
 function transformMermaidBlocks(content, className) {
   const lines = content.split('\n');
   const out = [];
@@ -42,7 +40,7 @@ function transformMermaidBlocks(content, className) {
         body.push(lines[j]);
       }
       if (closed) {
-        out.push('<pre class="' + className + '">' + escapeHtml(body.join('\n')) + '</pre>');
+        out.push('<pre class="' + className + '">' + escapeHTML(body.join('\n')) + '</pre>');
         i = j;
         continue;
       }

package/lib/presets/obsidian/converters/wikilink/index.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const { slugize } = require('hexo-util');
 const { replaceOutsideCode } = require('../../../../core/markdown-guard');
 const { normalizeBase } = require('../../../../core/config');
 const { getPostIndex, resolvePostByTarget, buildPostHref } = require('../../post-index');
@@ -11,6 +12,8 @@ const { getPostIndex, resolvePostByTarget, buildPostHref } = require('../../post
  * - ![[...]] 是嵌入，归 embed node 管，这里用 lookbehind 跳过
  * - #^block-id 块引用锚点在渲染后的 HTML 里不存在，丢弃锚点只留文章链接
  * - [[#标题]]（无 target 的同页链接）改写为页内锚点
+ * - 锚点用 hexo-util 的 slugize 生成——与 hexo-renderer-marked 给标题生成 id
+ *   的是同一个函数（含 marked.modifyAnchors 配置），保证页内跳转不断
  */
 function parseWikiLink(raw) {
   const firstPipe = raw.indexOf('|');
@@ -24,7 +27,14 @@ function parseWikiLink(raw) {
   return { target, anchor, alias };
 }
 
-function createWikiLinkReplacer(index, domainPrefix) {
+// 与 hexo-renderer-marked 的标题 id 同源：slugize + modifyAnchors（1 小写 / 2 大写）。
+// slug 再过 encodeURIComponent 保证 markdown 链接语法安全（中文等百分号编码后，
+// 浏览器解码 fragment 仍命中原 id）。
+function anchorToHash(anchor, anchorTransform) {
+  return '#' + encodeURIComponent(slugize(anchor, { transform: anchorTransform }));
+}
+
+function createWikiLinkReplacer(index, domainPrefix, anchorTransform) {
   return function replaceWikiLinks(segment) {
     return segment.replace(/(?<!!)\[\[([^\]]+)\]\]/g, (full, inner) => {
       const parsed = parseWikiLink(inner);
@@ -32,7 +42,7 @@ function createWikiLinkReplacer(index, domainPrefix) {
       // 同页链接 [[#标题]]：没有 target，只有锚点
       if (!parsed.target) {
         if (!parsed.anchor || parsed.anchor.startsWith('^')) return full;
-        return '[' + (parsed.alias || parsed.anchor) + '](#' + encodeURIComponent(parsed.anchor) + ')';
+        return '[' + (parsed.alias || parsed.anchor) + '](' + anchorToHash(parsed.anchor, anchorTransform) + ')';
       }
 
       const post = resolvePostByTarget(index, parsed.target);
@@ -42,7 +52,8 @@ function createWikiLinkReplacer(index, domainPrefix) {
       if (!href) return full;
 
       // 块引用锚点（#^id）在 HTML 里没有对应元素，降级为文章链接
-      const anchor = parsed.anchor && !parsed.anchor.startsWith('^') ? '#' + encodeURIComponent(parsed.anchor) : '';
+      const anchor =
+        parsed.anchor && !parsed.anchor.startsWith('^') ? anchorToHash(parsed.anchor, anchorTransform) : '';
       const text = parsed.alias || parsed.target;
 
       return '[' + text + '](' + href + anchor + ')';
@@ -58,7 +69,12 @@ module.exports = {
   },
   convert(content, ctx) {
     const index = getPostIndex(ctx.hexo);
-    const replacer = createWikiLinkReplacer(index, normalizeBase(ctx.presetConfig.domain_prefix));
+    const marked = (ctx.hexo.config && ctx.hexo.config.marked) || {};
+    const replacer = createWikiLinkReplacer(
+      index,
+      normalizeBase(ctx.presetConfig.domain_prefix),
+      marked.modifyAnchors
+    );
     return replaceOutsideCode(content, replacer);
   },
   _internal: { parseWikiLink, createWikiLinkReplacer }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hexo-text-pipeline",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A general-purpose hooks bus for Hexo's render pipeline: hang your own scripts/commands on any text stage (text in, text out, edit-and-use), with a checker system as the safety net. Ships an Obsidian Flavored Markdown preset.",
   "main": "index.js",
   "files": [
@@ -37,5 +37,8 @@
   },
   "engines": {
     "node": ">=16"
+  },
+  "dependencies": {
+    "hexo-util": "^2.7.0 || ^3.0.0 || ^4.0.0"
   }
 }