hexo-text-pipeline 0.2.0

package/lib/core/node-contract.js

@@ -0,0 +1,133 @@
+'use strict';
+
+const { STAGES } = require('./stages');
+const guard = require('./markdown-guard');
+
+const DEFAULT_PRIORITY = 10;
+const DEFAULT_STAGE = 'before_post_render';
+
+/**
+ * slot 默认值的唯一出处（按注册路径的角色分）：
+ * - preset node 默认 early——多数变换需要原始文本（围栏代码块还没被 hexo 吞掉）；
+ * - config hook、单文件插件（plugin 目录）与 textPipeline.register 默认 late——
+ *   用户/第三方想看到该 stage 的最终文本。
+ * 任何路径都可以用 slot 字段显式覆盖。
+ */
+const SLOT_DEFAULTS = { preset: 'early', hook: 'late', plugin: 'late', api: 'late' };
+
+/**
+ * 放置字段（stage / slot / priority / match）的唯一归一化与校验入口。
+ * 三条注册路径——preset 加载、config hooks、hexo.textPipeline.register——
+ * 都经过这里：默认值和校验规则只此一份，不会再因入口不同而行为分裂。
+ *
+ * raw 取 { stage?, slot?, priority?, match? }；match（字符串或 RegExp）编译成
+ * test(text) 廉价预判——它只是 test 的声明式写法，两者是同一个概念。
+ * 返回 { placement: { stage, slot, priority, test? } } 或 { error }。
+ */
+function resolvePlacement(raw, role) {
+  if (!SLOT_DEFAULTS[role]) {
+    throw new TypeError('resolvePlacement: unknown role "' + role + '"');
+  }
+
+  const stage = raw.stage === undefined ? DEFAULT_STAGE : raw.stage;
+  if (!STAGES[stage]) {
+    return { error: 'unknown stage "' + stage + '" (valid: ' + Object.keys(STAGES).join(', ') + ')' };
+  }
+
+  const slot = raw.slot === undefined ? SLOT_DEFAULTS[role] : raw.slot;
+  if (slot !== 'early' && slot !== 'late') {
+    return { error: 'invalid slot "' + raw.slot + '" (use early or late)' };
+  }
+
+  if (raw.priority !== undefined && !Number.isFinite(raw.priority)) {
+    return { error: 'priority must be a number, got ' + JSON.stringify(raw.priority) };
+  }
+  const priority = raw.priority === undefined ? DEFAULT_PRIORITY : raw.priority;
+
+  const placement = { stage, slot, priority };
+  if (raw.match !== undefined) {
+    let regex;
+    try {
+      regex = raw.match instanceof RegExp ? raw.match : new RegExp(raw.match);
+    } catch (err) {
+      return { error: 'invalid match regex: ' + (err && err.message) };
+    }
+    placement.test = (text) => regex.test(text);
+  }
+
+  return { placement };
+}
+
+/**
+ * replace DSL → convert 编译。规则形如 [[RegExp, string|fn], ...]：
+ * - pattern 必须是 RegExp（DSL 活在 JS 文件里，正则字面量零成本；不收字符串，
+ *   省掉转义/标志的歧义面）；缺 g 标志自动补全——"replace 列表"的声明式语义
+ *   就是全文替换，只换第一个属于 corner case，请写 convert。
+ * - useGuard 时整组规则套 markdown-guard（跳过围栏+行内代码）。
+ */
+function compileReplace(rules, useGuard) {
+  if (!Array.isArray(rules) || rules.length === 0) {
+    return { error: 'replace must be a non-empty array of [RegExp, replacement] pairs' };
+  }
+
+  const compiled = [];
+  for (const [index, rule] of rules.entries()) {
+    if (!Array.isArray(rule) || rule.length !== 2) {
+      return { error: 'replace[' + index + '] must be a [RegExp, replacement] pair' };
+    }
+    const [pattern, replacement] = rule;
+    if (!(pattern instanceof RegExp)) {
+      return { error: 'replace[' + index + '] pattern must be a RegExp literal (got ' + typeof pattern + ')' };
+    }
+    if (typeof replacement !== 'string' && typeof replacement !== 'function') {
+      return { error: 'replace[' + index + '] replacement must be a string or a function' };
+    }
+    const global = pattern.flags.includes('g') ? pattern : new RegExp(pattern.source, pattern.flags + 'g');
+    compiled.push([global, replacement]);
+  }
+
+  const applyAll = (segment) => {
+    let current = segment;
+    for (const [pattern, replacement] of compiled) {
+      current = current.replace(pattern, replacement);
+    }
+    return current;
+  };
+
+  if (useGuard) {
+    return { convert: (text) => guard.replaceOutsideCode(text, applyAll) };
+  }
+  return { convert: (text) => applyAll(text) };
+}
+
+/**
+ * convert 的唯一裁决入口：convert 与 replace 恰有其一——replace 是 convert 的
+ * 声明式写法（如同 match 之于 test），所有注册路径同一套规则。
+ * node 落在 before_post_render（输入是 markdown）时，replace 编译出的 convert
+ * 自动套 markdown-guard 防误伤代码；需要碰代码块就写 convert。
+ * 返回 { convert } 或 { error }。
+ */
+function resolveConvert(node) {
+  const hasConvert = typeof node.convert === 'function';
+  const hasReplace = node.replace !== undefined;
+  if (hasConvert && hasReplace) {
+    return { error: 'sets both convert and replace; pick one' };
+  }
+  if (hasConvert) {
+    return { convert: node.convert };
+  }
+  if (hasReplace) {
+    const stage = node.stage === undefined ? DEFAULT_STAGE : node.stage;
+    return compileReplace(node.replace, stage === 'before_post_render');
+  }
+  return { error: 'needs a convert(text, ctx) function or a replace rule list' };
+}
+
+module.exports = {
+  resolvePlacement,
+  compileReplace,
+  resolveConvert,
+  DEFAULT_PRIORITY,
+  DEFAULT_STAGE,
+  SLOT_DEFAULTS
+};

package/lib/core/stages.js

@@ -0,0 +1,53 @@
+'use strict';
+
+/**
+ * 管线暴露的全部 stage —— Hexo 渲染管线上所有"文本进、文本出"的执行点
+ * （filter 名与 Hexo 官方一致，见 https://hexo.io/api/filter）。
+ *
+ * 这是本插件的边界：template_locals / server_middleware 等不是文本变换的
+ * filter 不在此暴露，需要时请直接注册 Hexo filter。
+ *
+ * kind 决定 engine 如何接驳 hexo filter：
+ * - 'post'：filter 收 post 数据对象，文本在 data.content（逐篇文章）
+ * - 'string'：filter 收 (text, data) 并返回新文本（整页/资源，data 含 path 等元信息）
+ *
+ * 每个 stage 有两个挂点（slot），engine 各注册一个 hexo filter：
+ * - early：filterPriority（post 类 5），抢在 hexo 内置 filter（backtick_code_block、
+ *   excerpt 等，优先级 10）和其他插件之前——mermaid 等需要原始 markdown 的
+ *   preset node 默认在这里；
+ * - late：LATE_FILTER_PRIORITY（100），在 hexo 内置和其他插件全部跑完之后——
+ *   用户 hook 默认在这里，看到的是该 stage 的最终文本。
+ * node 用 slot 字段在两个挂点间移动。
+ *
+ * 新增 stage 只需在这张表加一项，engine 与 checker 自动覆盖。
+ */
+const LATE_FILTER_PRIORITY = 100;
+const STAGES = {
+  before_post_render: {
+    kind: 'post',
+    filterPriority: 5,
+    description: 'per-post markdown, before markdown rendering'
+  },
+  after_post_render: {
+    kind: 'post',
+    filterPriority: 5,
+    description: 'per-post HTML fragment, after markdown rendering'
+  },
+  'after_render:html': {
+    kind: 'string',
+    filterPriority: 10,
+    description: 'full page HTML, after template rendering'
+  },
+  'after_render:css': {
+    kind: 'string',
+    filterPriority: 10,
+    description: 'generated CSS asset'
+  },
+  'after_render:js': {
+    kind: 'string',
+    filterPriority: 10,
+    description: 'generated JS asset'
+  }
+};
+
+module.exports = { STAGES, LATE_FILTER_PRIORITY };

package/lib/core/tap.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_DIR = '.text-pipeline-tap';
+
+/**
+ * tap（管线抽头）—— 开发 hook 用的调试模式。开启后在真实渲染过程中，
+ * 把每个 stage 的输入文本和每个改动了文本的 node 的输出落盘：
+ *
+ *   <dir>/<文章或页面路径>/<stage>/00-input.txt        ← 你的 hook 在该 stage 收到的就是这个
+ *   <dir>/<文章或页面路径>/<stage>/01-obsidian:comment.txt
+ *   <dir>/<文章或页面路径>/<stage>/02-hook:my-hook.txt  ← 最后一个文件即该 stage 最终输出
+ *
+ * 配置：
+ * text_pipeline:
+ *   tap:
+ *     enable: true
+ *     match: 'my-post'        # 可选：只抓 source/path 匹配该正则的文章/页面（强烈建议设置）
+ *     dir: .text-pipeline-tap # 可选：输出目录，相对 Hexo 根
+ *
+ * 每轮渲染对同一 stage 重新落盘（先清空再写），目录里永远是最近一次的快照。
+ */
+function sanitize(name) {
+  return String(name).replace(/[^\w.-]+/g, '_').slice(0, 120) || 'unknown';
+}
+
+function createTap(tapConfig, baseDir, log) {
+  if (!tapConfig || tapConfig.enable !== true) return null;
+
+  const root = path.resolve(baseDir || process.cwd(), typeof tapConfig.dir === 'string' && tapConfig.dir ? tapConfig.dir : DEFAULT_DIR);
+
+  let matchRegex = null;
+  if (tapConfig.match !== undefined) {
+    try {
+      matchRegex = new RegExp(tapConfig.match);
+    } catch (err) {
+      log.warn('tap.match is not a valid regex, tap disabled: ' + (err && err.message));
+      return null;
+    }
+  }
+
+  const sequences = new Map(); // stage 目录 → 下一个序号
+
+  return {
+    root,
+    capture(stage, target, label, text) {
+      const id = (target && (target.source || target.path)) || 'unknown';
+      if (matchRegex && !matchRegex.test(id)) return;
+
+      const dir = path.join(root, sanitize(id), sanitize(stage));
+      try {
+        if (label === 'input') {
+          // 新一轮该 stage 的快照：清掉上一轮的
+          fs.rmSync(dir, { recursive: true, force: true });
+          fs.mkdirSync(dir, { recursive: true });
+          sequences.set(dir, 1);
+          fs.writeFileSync(path.join(dir, '00-input.txt'), text);
+          return;
+        }
+        const seq = sequences.get(dir) || 1;
+        sequences.set(dir, seq + 1);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, String(seq).padStart(2, '0') + '-' + sanitize(label) + '.txt'), text);
+      } catch (err) {
+        log.warn('tap write failed: ' + (err && err.message));
+      }
+    }
+  };
+}
+
+module.exports = { createTap, _internal: { sanitize } };

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

@@ -0,0 +1,44 @@
+'use strict';
+
+// node 模板：复制本目录为 converters/<name>/，按需拆出 parse.js / render.js，
+// 完成后在 preset 入口（lib/presets/obsidian/index.js）的 nodes 数组注册。
+// 本目录不在注册表里，仅作起点。
+// 提示：站点专属的变换不需要写 preset node——在站点的 text-pipeline/ 目录
+// 丢一个单文件插件即可（docs/PLUGINS.zh-CN.md），纯函数形态则用 hooks 的 script 条目。
+
+// const { replaceOutsideCode } = require('../../../../core/markdown-guard');
+
+module.exports = {
+  // 短名；配置键：presets[].config.<name>，运行时全名为 obsidian:<name>
+  name: 'template',
+
+  // stage 全表见 lib/core/stages.js。
+  // 'before_post_render'：输入是 markdown，行内替换务必用 markdown-guard 跳过代码。
+  // 'after_post_render'：输入是渲染后的 HTML。
+  stage: 'before_post_render',
+
+  // 可选：默认优先级 10，小者先跑；用户可在配置里覆盖。
+  // priority: 10,
+
+  // 可选：出厂默认关闭（用户 config.<name>.enable 永远优先）。
+  // enabledByDefault: false,
+
+  // 可选：默认 CSS 字符串，engine 会在 inject_css 开启时注入 head_end。
+  // css: require('./styles'),
+
+  // 可选：前端脚本，inject_js 开启时注入 body_end；字符串或 (子配置) => 字符串。
+  // js: (config) => '...',
+
+  // 廉价预判，返回 false 直接跳过 convert。
+  test(content) {
+    return content.includes('TODO-marker');
+  },
+
+  // 必须无副作用：不改 ctx，不读 hexo 全局状态（需要文章索引用 ../post-index）。
+  // ctx = { hexo, stage, pluginConfig, utils, log,
+  //         post（post 类 stage）| file（string 类 stage，{ path }），
+  //         config（node 子配置）, presetConfig }
+  convert(content, ctx) {
+    return content;
+  }
+};

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

@@ -0,0 +1,25 @@
+'use strict';
+
+const { replaceOutsideCode } = require('../../../../core/markdown-guard');
+
+/**
+ * Markdown 阶段剥离 Obsidian 块定义标记：行尾的 ` ^block-id`
+ * （以及独占一行的 `^block-id`）。它们只服务于 Obsidian 内部的块引用，
+ * 在 Obsidian 阅读视图里也不可见，不应出现在渲染结果里。
+ */
+function stripBlockIds(content) {
+  // 标记必须在行首独占或跟在空白后（"x^2" 这类行内字面 ^ 不动）
+  return replaceOutsideCode(content, (segment) => segment.replace(/(^|\s+)\^[A-Za-z0-9-]+$/, ''));
+}
+
+module.exports = {
+  name: 'blockid',
+  stage: 'before_post_render',
+  test(content) {
+    return content.includes('^');
+  },
+  convert(content) {
+    return stripBlockIds(content);
+  },
+  _internal: { stripBlockIds }
+};

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

@@ -0,0 +1,84 @@
+'use strict';
+
+const { parseCalloutInner } = require('./parse');
+const { renderCallout } = require('./render');
+const css = require('./styles');
+
+const OPEN_TAG = '<blockquote';
+const CLOSE_TAG = '</blockquote>';
+
+/**
+ * 在 HTML 里找到与 openEnd 处开标签配对的 </blockquote>。
+ * 返回 { closeStart, closeEnd }，未闭合返回 null。
+ */
+function findMatchingClose(html, openEnd) {
+  let depth = 1;
+  let cursor = openEnd;
+
+  while (depth > 0) {
+    const nextOpen = html.indexOf(OPEN_TAG, cursor);
+    const nextClose = html.indexOf(CLOSE_TAG, cursor);
+
+    if (nextClose === -1) return null;
+
+    if (nextOpen !== -1 && nextOpen < nextClose) {
+      depth += 1;
+      cursor = nextOpen + OPEN_TAG.length;
+    } else {
+      depth -= 1;
+      if (depth === 0) {
+        return { closeStart: nextClose, closeEnd: nextClose + CLOSE_TAG.length };
+      }
+      cursor = nextClose + CLOSE_TAG.length;
+    }
+  }
+
+  return null;
+}
+
+function transformCallouts(html) {
+  let result = '';
+  let pos = 0;
+
+  while (pos < html.length) {
+    const open = html.indexOf(OPEN_TAG, pos);
+    if (open === -1) break;
+
+    const openTagEnd = html.indexOf('>', open);
+    if (openTagEnd === -1) break;
+
+    const match = findMatchingClose(html, openTagEnd + 1);
+    if (!match) break;
+
+    const inner = html.slice(openTagEnd + 1, match.closeStart);
+    const parsed = parseCalloutInner(inner);
+
+    result += html.slice(pos, open);
+    if (parsed) {
+      result += renderCallout(parsed, transformCallouts(parsed.body));
+    } else {
+      // 普通引用保留原样，但递归处理内部可能嵌套的 callout
+      result += html.slice(open, openTagEnd + 1) + transformCallouts(inner) + CLOSE_TAG;
+    }
+    pos = match.closeEnd;
+  }
+
+  result += html.slice(pos);
+  return result;
+}
+
+module.exports = {
+  name: 'callout',
+  stage: 'after_post_render',
+  // 主流 markdown 渲染器/主题已多自带 callout 支持，默认关闭避免双重渲染；
+  // 需要时在 preset 配置里 callout: { enable: true } 打开
+  enabledByDefault: false,
+  css,
+  test(content) {
+    return content.includes('[!') && content.includes(OPEN_TAG);
+  },
+  convert(content) {
+    return transformCallouts(content);
+  },
+  _internal: { transformCallouts, findMatchingClose }
+};

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

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * 解析渲染后的 blockquote 内 HTML，识别 Obsidian callout 头部：
+ *   <p>[!type] title<br>body...</p> 或 <p>[!type] title</p><p>body...</p>
+ * 兼容 hexo-renderer-marked 的 breaks: true（<br>）和 breaks: false（\n）两种换行输出。
+ * 返回 { type, fold, title, body }，不是 callout 时返回 null。
+ */
+
+const HEAD_RE = /^\s*<p>\[!([a-zA-Z0-9_-]+)\]([+-])?[ \t]*/;
+
+function findTitleEnd(rest) {
+  const candidates = [];
+
+  const br = rest.match(/<br\s*\/?>(\r?\n)?/);
+  if (br) candidates.push({ index: br.index, length: br[0].length, kind: 'br' });
+
+  const nl = rest.indexOf('\n');
+  if (nl !== -1) candidates.push({ index: nl, length: 1, kind: 'newline' });
+
+  const pEnd = rest.indexOf('</p>');
+  if (pEnd !== -1) candidates.push({ index: pEnd, length: '</p>'.length, kind: 'p-end' });
+
+  if (!candidates.length) {
+    return { index: rest.length, length: 0, kind: 'eof' };
+  }
+
+  candidates.sort((a, b) => a.index - b.index);
+  return candidates[0];
+}
+
+function parseCalloutInner(inner) {
+  const head = inner.match(HEAD_RE);
+  if (!head) return null;
+
+  const type = head[1].toLowerCase();
+  const fold = head[2] || '';
+  const rest = inner.slice(head[0].length);
+
+  const end = findTitleEnd(rest);
+  const title = rest.slice(0, end.index).trim();
+  const after = rest.slice(end.index + end.length);
+
+  let body;
+  if (end.kind === 'p-end') {
+    // 标题独占首段，正文是后续兄弟元素
+    body = after.replace(/^\r?\n/, '');
+  } else if (end.kind === 'eof') {
+    body = '';
+  } else {
+    // 标题和正文同段：去掉标题行后把段落补回去
+    body = '<p>' + after;
+  }
+
+  return { type, fold, title, body: body.trim() };
+}
+
+module.exports = {
+  parseCalloutInner
+};

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

@@ -0,0 +1,40 @@
+'use strict';
+
+/**
+ * 把解析出的 callout 结构渲染为 HTML。
+ * 普通 callout 输出 div 结构；折叠语法 [!type]- / [!type]+ 输出 <details>（+ 为默认展开）。
+ * type 已被 parse 的正则限定为 [a-zA-Z0-9_-]，可直接进入 class/attribute。
+ */
+
+function defaultTitle(type) {
+  return type.charAt(0).toUpperCase() + type.slice(1);
+}
+
+function renderCallout(parsed, bodyHtml) {
+  const type = parsed.type;
+  const title = parsed.title || defaultTitle(type);
+  const classAttr = 'callout callout-' + type;
+  const content = bodyHtml ? '<div class="callout-content">' + bodyHtml + '</div>' : '';
+
+  if (parsed.fold) {
+    const openAttr = parsed.fold === '+' ? ' open' : '';
+    return (
+      '<details class="' + classAttr + '" data-callout="' + type + '"' + openAttr + '>' +
+      '<summary class="callout-title">' + title + '</summary>' +
+      content +
+      '</details>'
+    );
+  }
+
+  return (
+    '<div class="' + classAttr + '" data-callout="' + type + '">' +
+    '<div class="callout-title">' + title + '</div>' +
+    content +
+    '</div>'
+  );
+}
+
+module.exports = {
+  renderCallout,
+  defaultTitle
+};

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

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * 默认样式，经 hexo injector 注入 head_end；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)}
+.callout-title{font-weight:600;color:rgb(var(--callout-color));margin:0 0 .25rem}
+.callout-content>:first-child{margin-top:.25rem}
+.callout-content>:last-child{margin-bottom:0}
+details.callout>summary.callout-title{cursor:pointer}
+.callout[data-callout=tip],.callout[data-callout=hint],.callout[data-callout=important]{--callout-color:0,191,188}
+.callout[data-callout=success],.callout[data-callout=check],.callout[data-callout=done]{--callout-color:68,207,110}
+.callout[data-callout=question],.callout[data-callout=help],.callout[data-callout=faq]{--callout-color:233,196,106}
+.callout[data-callout=warning],.callout[data-callout=caution],.callout[data-callout=attention]{--callout-color:236,117,0}
+.callout[data-callout=danger],.callout[data-callout=error],.callout[data-callout=failure],.callout[data-callout=fail],.callout[data-callout=missing],.callout[data-callout=bug]{--callout-color:233,49,71}
+.callout[data-callout=example]{--callout-color:168,130,255}
+.callout[data-callout=quote],.callout[data-callout=cite],.callout[data-callout=diary]{--callout-color:158,158,158}
+`.trim();

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

@@ -0,0 +1,106 @@
+'use strict';
+
+const { segmentInlineCode } = require('../../../../core/markdown-guard');
+
+/**
+ * Markdown 阶段剥离 Obsidian 注释：行内 %%...%% 与跨行 %% ... %%。
+ * 语义约定（与 Obsidian 一致或取其安全子集）：
+ * - fenced code / inline code 里的 %% 是字面量，不开启注释；
+ * - 注释一旦开启，吞掉直到下一个 %%（中间的代码、围栏一并视为注释内容）；
+ * - 跨行注释的首行残余与末行残余合并成一行；
+ * - 整行都被注释吃掉时不留空行；
+ * - 未闭合的 %% 注释到文件末尾（Obsidian 同此行为）。
+ */
+function stripObsidianComments(content) {
+  const lines = content.split('\n');
+  const out = [];
+
+  let inFence = false;
+  let fenceChar = '';
+  let fenceLen = 0;
+  let inComment = false;
+  let carry = null; // 跨行注释开启行的前缀残余，等闭合行合并
+
+  for (const line of lines) {
+    if (!inComment) {
+      const match = line.match(/^ {0,3}([`~]{3,})/);
+      if (match) {
+        const token = match[1];
+        if (!inFence) {
+          inFence = true;
+          fenceChar = token[0];
+          fenceLen = token.length;
+        } else if (token[0] === fenceChar && token.length >= fenceLen) {
+          inFence = false;
+        }
+        out.push(line);
+        continue;
+      }
+      if (inFence) {
+        out.push(line);
+        continue;
+      }
+    }
+
+    let lineOut = '';
+    let touched = inComment;
+
+    for (const seg of segmentInlineCode(line)) {
+      if (seg.isCode && !inComment) {
+        lineOut += seg.text;
+        continue;
+      }
+      const text = seg.text;
+      let i = 0;
+      while (i < text.length) {
+        const idx = text.indexOf('%%', i);
+        if (idx === -1) {
+          if (!inComment) lineOut += text.slice(i);
+          break;
+        }
+        touched = true;
+        if (!inComment) {
+          lineOut += text.slice(i, idx);
+          inComment = true;
+        } else {
+          inComment = false;
+        }
+        i = idx + 2;
+      }
+    }
+
+    if (inComment) {
+      // 注释延续到下一行：行首残余暂存，整行被吞时什么都不留
+      if (carry === null) carry = lineOut;
+      continue;
+    }
+
+    if (carry !== null) {
+      lineOut = carry + lineOut;
+      carry = null;
+    }
+    if (touched && lineOut === '') {
+      continue; // 整行只有注释，不留空行
+    }
+    out.push(lineOut);
+  }
+
+  // 未闭合注释：carry 是开启行的残余，按 Obsidian 语义其后内容全部隐藏
+  if (carry !== null && carry !== '') {
+    out.push(carry);
+  }
+
+  return out.join('\n');
+}
+
+module.exports = {
+  name: 'comment',
+  stage: 'before_post_render',
+  test(content) {
+    return content.includes('%%');
+  },
+  convert(content) {
+    return stripObsidianComments(content);
+  },
+  _internal: { stripObsidianComments }
+};