pi-auto-save-to-markdown 0.9.1 → 0.9.2

package/README.md

@@ -150,27 +150,60 @@ I'll trace the middleware order first.
 ````
 
 The body renders user and assistant messages in full (assistant thinking and
-per-turn tool calls are each folded into a collapsed Obsidian callout —
+per-turn tool calls are each folded into a collapsed callout —
 `> [!tldr]- Thinking` and `> [!quote]- Tool Calls · …`), recording every tool
 call with its full raw result: the file is a documentary record that may be
 @-referenced back into a conversation, and a truncated half-result would be
 wasted when the tool is called again and misleading when it is not, while
 local reading (grep, ranged reads) makes size a non-issue. Callouts are used
-instead of HTML `<details>` because Obsidian renders markdown inside HTML
-blocks unreliably; outside Obsidian the callouts degrade to plain blockquotes.
+instead of HTML `<details>` because a callout is plain markdown — meaningful
+in every renderer, a panel where supported and a blockquote everywhere else —
+whereas raw HTML blocks have no such portability: Obsidian does not parse
+markdown inside HTML blocks, and neither does Quartz's remark/CommonMark
+pipeline (invalid HTML there can even break a page outright), so `<details>`
+cannot be relied on to carry content across the tools these files are read in.
 Arguments render as full JSON in inline code spans and results verbatim —
 whitespace intact, nothing capped — in fenced code blocks (with a delimiter
 sized to survive backticks inside the content), so raw tool output renders
 literally instead of being parsed as markdown.
 
+### Callouts beyond Obsidian
+
+A callout is a blockquote whose first line carries a type marker
+(`> [!note] Title`): renderers that understand the marker draw a titled,
+colored, optionally collapsible panel, and every other renderer still sees a
+perfectly valid blockquote. Obsidian popularized the syntax and extends it
+with fold markers (`-` collapsed, `+` expanded) and arbitrary types; GitHub
+standardized a five-type subset of the same marker (`[!note]` …
+`[!caution]`, no folding) as its "alerts". These files render best in
+Obsidian — custom types and preset-collapsed folds included — but Obsidian is
+far from the only viewer that draws the panels:
+
+- **[Quartz](https://quartz.jzhao.xyz)** — the static-site generator for
+  publishing Obsidian vaults, renders the same callout syntax, folding
+  included.
+- **VS Code** — extensions add the panels to the built-in markdown preview,
+  e.g. Markdown Obsidian Callout, vscode-markdown-obsidian-alert, or
+  Markdown GitHub Alerts & Obsidian Callouts.
+- **Static-site pipelines** — remark plugins render callouts on the web:
+  remark-obsidian-callout (Astro and friends) parses the full Obsidian
+  syntax, remark-github-blockquote-alert the GitHub subset.
+- **The standardized subset** — GitHub itself, Typora (opt-in), and Markdown
+  Preview Enhanced render GitHub's alert types; this plugin's `tldr`/`quote`
+  types and fold markers live outside that subset, so on those surfaces the
+  callouts fall back to plain — still perfectly readable — blockquotes,
+  exactly the graceful degradation the syntax was designed for.
+
 Prompt blocks the client or the agent injects into a user message — the
 editor's active selection, attached or referenced notes, loaded skills — are
-re-rendered from their raw XML (which Obsidian cannot render and would show
-as literal angle-bracket text) into generic callouts. No block is parsed
+re-rendered from their raw XML (which markdown viewers cannot present
+usefully — Obsidian shows it as literal angle-bracket text) into generic
+callouts. No block is parsed
 individually: the title is the tag name in words (`editor_selection` →
 Editor Selection), and the body opens with vault-shaped `path`/`location`
-values as bare Obsidian wikilinks (the aliased filename speaks for itself —
-no `path:` label), followed by the remaining attributes as
+values as bare wikilinks (`[[…|alias]]` is a clickable link in Obsidian,
+Quartz, and Markdown Preview Enhanced alike; the aliased filename speaks for
+itself — no `path:` label), followed by the remaining attributes as
 `**name**: value` items, then the content. Every callout is preset-collapsed
 — user-provided blocks (selections, note attachments) as `> [!quote]-`, even
 when they carry only attributes (the client emits note references as
@@ -204,7 +237,8 @@ Each message block opens with a setext level-1 info header (`User`,
 content typically starts with, and distinguishable from content `#` headings
 when parsing. The header's metadata (local date-time, and the model for
 assistant messages) sits in a small faint `<span>` (`0.5em`, Obsidian's
-`--text-faint` color), so the role stays visually dominant while the details
+`--text-faint` color — renderers without the variable fall back to the
+inherited text color), so the role stays visually dominant while the details
 remain a glance away. Each block ends with a `---` separator wrapped in single
 blank lines (extra blank lines are trimmed), so blocks are easy to tell apart
 both when reading and when splitting the file programmatically. The document

package/README.zh.md

@@ -124,30 +124,57 @@ Assistant <span style="font-size: 0.5em; color: var(--text-faint);">2026-08-29 1
 ````
 
 正文完整渲染 user / assistant 消息（assistant 的 thinking 与每轮工具调用
-分别折叠在可折叠的 Obsidian callout 中——`> [!tldr]- Thinking` 和
+分别折叠在可折叠的 callout 中——`> [!tldr]- Thinking` 和
 `> [!quote]- Tool Calls · …`），每次工具调用连同其完整原始结果一起记录：
 归档文件是可能被 @ 引回对话的史料，截断的半个结果在工具重调时是浪费、在
 不再调用时是误导，而局部阅读（grep、按行段读取）让体积不成问题。之所以用
-callout 而不是 HTML `<details>`，是因为 Obsidian 对 HTML 块内嵌 Markdown 的
-渲染不可靠；在非 Obsidian 环境下 callout 退化为普通引用块。参数以完整 JSON
-包在 inline code 里，结果逐字保真——空白原样、不截断——放在 fenced code
-block 中（分隔符长度会自动压过内容中的反引号序列），工具的原始输出因此按
-字面渲染，不会被当作 Markdown 解析。
+callout 而不是 HTML `<details>`，是因为 callout 是纯 Markdown，在任何渲染器里
+都是有效文本：支持的环境画出可折叠面板，不支持的环境退化为普通引用块；原始
+HTML 块则没有这等待遇——Obsidian 不解析 HTML 块内嵌的 Markdown，Quartz
+（remark/CommonMark 管线）同样如此，无效的 HTML 属性甚至能让整页渲染失败，
+`<details>` 无法跨工具承载内容。参数以完整 JSON 包在 inline code 里，
+结果逐字保真——空白原样、不截断——放在 fenced code block 中（分隔符长度会自动
+压过内容中的反引号序列），工具的原始输出因此按字面渲染，不会被当作 Markdown
+解析。
+
+### Callout 在 Obsidian 之外的渲染
+
+Callout 本质是首行带类型标记的引用块（`> [!note] 标题`）：认得这个标记的
+渲染器把它画成带标题、配色、可折叠的面板，其余渲染器看到的仍是完全合法的
+引用块。这套语法由 Obsidian 发扬光大，并以折叠标记（`-` 收起、`+` 展开）
+和任意类型加以扩展；GitHub 则把同一标记的五种类型（`[!note]` …
+`[!caution]`，无折叠）标准化为自家的 "alerts"。归档文件在 Obsidian 中渲染
+最佳——自定义类型与预设折叠都在——但会画 callout 面板的远不止 Obsidian
+一家：
+
+- **[Quartz](https://quartz.jzhao.xyz)** —— 发布 Obsidian vault 的静态站点
+  生成器，渲染同一套 callout 语法，含折叠。
+- **VS Code** —— 内置 markdown 预览装上扩展即可渲染面板，如 Markdown
+  Obsidian Callout、vscode-markdown-obsidian-alert、Markdown GitHub
+  Alerts & Obsidian Callouts。
+- **静态站点管线** —— remark 插件把 callout 渲染到网页上：
+  remark-obsidian-callout（Astro 等）解析完整 Obsidian 语法，
+  remark-github-blockquote-alert 对应 GitHub 子集。
+- **标准化子集** —— GitHub 本身、Typora（偏好设置中开启）与 Markdown
+  Preview Enhanced 渲染的是 GitHub 的 alert 类型；本插件用到的
+  `tldr`/`quote` 类型与折叠标记不在其列，在这些环境里 callout 于是退化为
+  普通（依旧可读的）引用块——正是该语法与生俱来的优雅降级。
 
 客户端或 agent 注入到用户消息中的提示块——编辑器当前选区、附加或引用的
-笔记、加载的 skill——会从原始 XML（Obsidian 无法渲染，只会显示成裸露的
-尖括号文本）重新渲染为通用 callout。不做任何逐块解析：标题取标记名的分词
-（`editor_selection` → Editor Selection），正文以形似 vault 相对笔记路径的
-`path`/`location` 值开头——直接渲染为不带标签的 Obsidian wikilink（别名
-文件名自解释，`path:` 标签反而冗余），其余属性以 `**属性**: 值` 跟随，
-最后是引用内容。所有 callout 一律预设折叠——用户提供的块（选区、笔记附件）
-为 `> [!quote]-`（仅有属性的自闭合笔记引用同样折叠），agent 侧痕迹（skill）
-为 `> [!note]- Skill · <名称>` 标记（加载的 skill 名称直接进标题，折叠状态
-也能看到是哪个 skill；location 跟在正文，内容丢弃）；连续的同标签块（中间
-只有空白）合并进同一个 callout，一串笔记引用因此收拢为一份列表（skill 标记
-不合并：各自标注各自的 skill）。未知标记原样保留，用户粘贴的
-XML 内容绝不会被误改；回退文件名 slug 也从剥离全部已知块后的纯键入文本
-推导。
+笔记、加载的 skill——会从原始 XML（Markdown 渲染器无法有效呈现，在
+Obsidian 中显示为裸露的尖括号文本）重新渲染为通用 callout。不做任何
+逐块解析：标题取标记名的分词（`editor_selection` → Editor Selection），
+正文以形似 vault 相对笔记路径的 `path`/`location` 值开头——直接渲染为不带
+标签的 wikilink（`[[…|别名]]` 在 Obsidian、Quartz、Markdown Preview 
+Enhanced 等环境里都是可点击链接，别名文件名自解释，`path:` 标签反而冗
+余），其余属性以 `**属性**: 值` 跟随，最后是引用内容。所有 callout 一律
+预设折叠——用户提供的块（选区、笔记附件）为 `> [!quote]-`（仅有属性的自闭
+合笔记引用同样折叠），agent 侧痕迹（skill）为 `> [!note]- Skill · <名称>` 
+标记（加载的 skill 名称直接进标题，折叠状态也能看到是哪个 skill；location 
+跟在正文，内容丢弃）；连续的同标签块（中间只有空白）合并进同一个 callout，
+一串笔记引用因此收拢为一份列表（skill 标记不合并：各自标注各自的 skill）。
+未知标记原样保留，用户粘贴的 XML 内容绝不会被误改；回退文件名 slug 也从剥
+离全部已知块后的纯键入文本推导。
 
 当前识别的注入块标签清单：
 
@@ -167,7 +194,8 @@ XML 内容绝不会被误改；回退文件名 slug 也从剥离全部已知块
 每个消息块以 setext 一级信息头（`User`、`Assistant`，下一行以 `===` 下划）
 开头——高于 AI 内容常见的 `##` 二级标题，解析时也能与内容中的 `#` 一级标题
 区分开。信息头的元数据（本地日期时间，assistant 消息还带模型名）放在一个小号
-浅色 `<span>` 中（`0.5em`，Obsidian 的 `--text-faint` 颜色），角色名因此保持
+浅色 `<span>` 中（`0.5em`，Obsidian 的 `--text-faint` 颜色；无此变量的渲染器
+回退为继承的正文字色），角色名因此保持
 醒目，细节又触手可及。每个消息块以"上下各一个空行"包裹的 `---` 分隔线结尾
 （多余空行会被裁剪），无论是阅读还是程序化切分，都能清楚地区分每个消息块。
 文档标题紧跟在 frontmatter 之后，中间没有空行；追加保存时会顺带修复旧版本

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-auto-save-to-markdown",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Pi extension that automatically saves each completed conversation turn as a markdown file with YAML frontmatter, one file per session-tree branch.",
   "type": "module",
   "license": "MIT",