Theme Plume

Theme Plume

在 Obsidian 阅读视图中渲染 VuePress Theme Plume 的 Markdown 容器语法（::: file-tree、::: tabs、::: steps 等）。

项目来源

本仓库是将 vuepress-theme-plume 的 Markdown 增强能力迁移到 Obsidian 的独立插件，并非上游官方仓库。解析、渲染与样式对齐过程中大量使用了 AI 辅助开发工具（如 Cursor）。

• 仅覆盖 Plume 的 Markdown 容器与阅读视图渲染，不包含 VuePress 站点主题、导航、博客、搜索等。
• 上游主题为 MIT；本仓库同样 MIT，并保留上游版权声明，详见 NOTICE。

功能概览

• ::: 自定义容器：文件树、代码树、选项卡、步骤、提示框、卡片、时间线等（见下表）。
• 容器内正文交给 Obsidian 自带 Markdown 引擎渲染，不内置 markdown-it。
• 代码块信息串中的 title="..." 会显示为 Plume 风格标题栏（src/pipeline/code-fence-titles.ts）。
• 行内 `badge:tip:文本` 徽章（不支持 HTML <Badge>，阅读视图会剥离未知标签）。
• 编辑时 软刷新 Plume 块；命令面板可强制整页重建预览。
• 文件树 / 代码树支持 colored / simple 图标模式（simple 不加载离线 Iconify SVG）。

组件示例稿：examples/plume-components.md — 每种容器的初版写法，可在 Obsidian 阅读视图中打开对照。

在线预览（GitHub Pages）：https://eason596.github.io/obsidian-theme-plume/ — 由 npm run build:demo 将示例稿渲染为静态 HTML（见下方 发布预览站）。

安装

社区插件（推荐）

1. 在 Obsidian 中打开 设置 → 社区插件 → 浏览，搜索 Theme Plume。
2. 安装并启用插件。

若尚未出现在社区目录，可先用下方手动安装或 BRAT 从 GitHub 安装。

提交社区插件（维护者）：登录 community.obsidian.md → Plugins → New plugin → 填写 https://github.com/Eason596/obsidian-theme-plume。首次提交前需已有与 manifest.json 中 version 一致的 GitHub Release（含 main.js、manifest.json、styles.css）。

手动安装（开发构建）

git clone https://github.com/Eason596/obsidian-theme-plume.git
cd obsidian-theme-plume
npm install
npm run build

将以下文件复制到库内插件目录：

<vault>/.obsidian/plugins/theme-plume/
  manifest.json
  main.js
  styles.css

main.js 由 npm run build 生成，未提交到 Git。

在 设置 → 社区插件 中启用 Theme Plume。

升级提示：插件 ID 现为 theme-plume。若曾安装 obsidian-plume 或 vuepress-file-tree，请删除旧插件目录后再安装，避免重复加载。

网络使用说明

本插件默认可离线使用大部分功能。以下能力仅在启用时访问网络（无服务端遥测、无账号要求）：

可在设置中将 Default file-tree icon mode 设为 simple，并避免使用 repo-card，即可在无网络环境下使用核心容器语法。

支持的语法

与 Plume 文档 大体一致；下表对应当前 src/parser.ts / src/render.ts 已实现的块类型。

嵌套容器（如 Card → Collapse → code-tabs）在首段渲染时会递归解析内层块。

完整可运行示例见 examples/plume-components.md（每种组件一节，便于在库内打开验收）。

片段预览

::: tabs#demo
@tab 安装
```bash
npm install
```

@tab:active 配置
::: tip
保存后切换阅读视图即可预览。
:::
:::

@[code-tree](./src)

```ts title="main.ts"
export default class ObsidianPlumePlugin extends Plugin {}
```

架构（v1.0）

核心原则：不重复实现 markdown-it；顶层块在渲染前替换为 HTML 占位符，再填充组件并递归渲染内文。

设置

设置 → Theme Plume：

编辑后预览采用 软刷新（只重绘 Plume 块，不整页 rerender），减轻跳动。异常时可用命令 Theme Plume: Force Refresh Current Preview 做完整重建。

命令面板

开发

npm install
npm run check          # TypeScript
npm test               # Vitest（src/parser.test.ts）
npm run test:legacy    # 旧版脚本测试
npm run dev            # 监听构建 + 生成图标
npm run build          # 类型检查 + 图标生成 + 生产构建 main.js
npm run build:demo     # 生成 docs/index.html（GitHub Pages 预览）

build / dev 会自动执行 npm run generate:icons（依赖 @iconify-json/*）。

测试说明

src/parser.test.ts 中部分用例读取上级目录的 plume-complex-test.md（多仓库工作区中的综合验收稿）。若单独克隆本仓库后 npm test 报找不到该文件，可将综合测试 Markdown 放到 obsidian-theme-plume/../plume-complex-test.md，或仅运行不依赖该 fixture 的用例。

人工验收推荐使用本仓库内的 examples/plume-components.md。

与 VuePress / Plume 的差异

发布预览站（GitHub Pages）

将 examples/plume-components.md 预渲染为静态页面，发布到 GitHub Pages。

本地生成

npm install
npm run build:demo

构建成功时终端会打印 Wrote .../docs/index.html。用浏览器直接打开该文件即可本地预览（file:// 路径）。

若进程以 JavaScript heap out of memory 退出，说明 @[code-tree] 嵌入了过大目录；示例已改为 ../src，构建脚本也会跳过 main.js、offlineIconData.ts 等大文件。

输出目录 docs/：

首次在 GitHub 开启 Pages

1. 推送代码到 main（含 .github/workflows/pages.yml）。
2. 打开仓库 Settings → Pages。
3. Build and deployment → Source 选 GitHub Actions（不要选 “Deploy from branch”）。
4. 推送触发 workflow，或到 Actions 手动运行 Deploy GitHub Pages。
5. 几分钟后访问：https://eason596.github.io/obsidian-theme-plume/

之后每次改 examples/plume-components.md 或样式，推送到 main 会自动重建；也可本地 npm run build:demo 后把 docs/index.html 一并提交。

预览站用 marked 渲染普通 Markdown，与 Obsidian 阅读视图在细节上可能略有差异；Plume 容器样式与 Obsidian 真环境更接近。选项卡、文件树/代码树、折叠手风琴、瀑布流等交互由 docs/demo-client.js 在浏览器中启用（静态 HTML 本身不含事件监听）。

发布新版本

维护者推送 semver 标签后，GitHub Actions 会自动构建并创建 Release（附件含 main.js、manifest.json、styles.css）：

# 1. 更新 manifest.json 与 package.json 中的 version
# 2. 提交并推送
git push origin main
# 3. 打标签并推送（标签须与 manifest version 一致）
git tag 1.0.1
git push origin 1.0.1

发布到 GitHub

已安装 GitHub CLI 并登录后：

scripts\publish-github.cmd

许可证