hexo-text-pipeline 0.3.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 }
@@ -182,6 +185,7 @@ 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 }
@@ -182,6 +185,7 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hexo-text-pipeline",
-  "version": "0.3.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": [