ASCII Banner for Obsidian

把开源的 ascii.rest ASCII 动画库用作 Obsidian 笔记顶部的 banner（横幅）。

• 内置 ascii.rest 官方全部 217 个图案（旋转甜甜圈、京都黄昏、东京雨夜、黑客帝国数字雨……）
• 动态图案原生播放，滚出视口自动暂停，可一键切换静止首帧
• 阅读模式和实时预览（Live Preview）都能看到 banner
• 配置写进笔记 frontmatter，换设备同步不丢；离线也能用

安装（不需要懂代码）

1. 在 Releases 页面下载三个文件：main.js、manifest.json、styles.css。
2. 打开你的 Obsidian 库文件夹，进入 .obsidian/plugins/（看不到 .obsidian 的话，Windows 在资源管理器开启「显示隐藏文件」，macOS 按 ⌘⇧.）。
3. 在里面新建一个文件夹，命名为 ascii-banner，把刚才下载的三个文件放进去。
4. 回到 Obsidian：设置 → 第三方插件，关闭安全模式（如未关闭），在已安装插件列表里启用 ASCII Banner。

也可以用社区插件 BRAT 安装：在 BRAT 里添加本仓库地址即可，之后会自动更新。

使用

打开任意 Markdown 笔记，按 ⌘P（Windows 是 Ctrl+P）打开命令面板：

命令	作用
设置 / 更换 ASCII Banner 图案	打开图案选择器：按名称/分类/描述搜索，右侧实时预览，可选择「动画」或「静止首帧」，点击「应用到当前笔记」
切换 ASCII Banner：动画 ⇄ 静止	当前笔记的图案在播放动画和静止首帧之间切换（不更换图案）
清除 ASCII Banner	移除当前笔记的 banner（不影响正文和其他属性）
刷新 ascii.rest 图案目录	从官网刷新图案显示名称；失败时自动使用内置目录

Banner 会出现在文档内容的最上方，阅读模式和编辑模式都生效。

数据格式

选择结果保存在笔记的 YAML frontmatter 中，不修改正文：

---
ascii-banner:
  version: 1
  piece: kyoto-dusk
  source: https://ascii.rest/kyoto-dusk/
  mode: animated
  fps: 15
  options: {}
---

• piece：必须是内置官方图案 slug；未知 slug 会被忽略。
• mode：animated（默认）或 still。
• fps：可选，0–120，覆盖图案默认帧率。
• options：可选，仅接受 JSON 安全的普通对象（如 {"text": "hello"}），用于支持参数的图案。
• 配置随笔记同步/迁移，不依赖任何本地状态。

动态行为与生命周期

• 动画默认播放；切换为静止时显示该图案的首帧/still 帧。
• 图案滚出视口、文档隐藏或切换到其他笔记时自动暂停/销毁，不在后台占用资源。
• 遵循系统的“减少动态效果”（prefers-reduced-motion）设置。
• 图案加载失败时优先显示缓存帧；没有缓存时显示可读的错误占位，正文不受影响。

安全与隐私

• frontmatter 仅被当作数据解析；不会执行笔记中的脚本、HTML 或任意模块地址。
• 只接受内置官方图案；不支持第三方 src 模块。
• 唯一的网络请求是可选的“刷新图案目录”（读取 ascii.rest 首页的公开链接列表）；失败自动回退到内置目录。
• 插件不包含任何统计或上报。

已知限制

• 移动端可运行，但大尺寸彩色 Canvas 图案（如 200×100 的场景类）在低端设备上可能较耗电；建议使用静止模式或较小图案。
• Live Preview 的 frontmatter 解析器只识别插件自身写入的受限子集；手工书写的复杂 YAML（如多行 options）在 Live Preview 中可能不显示 banner，阅读模式不受影响。
• 选择器预览以较小字号渲染，仅用于确认图案；实际效果以笔记内为准。
• 不支持把动画导出为 GIF/视频，也不支持自定义图案（ascii.rest 官方目录之外）。

验证

npm test          # 26 项单元测试（frontmatter/目录/运行时/阅读模式/Live Preview 解析）
npm run typecheck # TypeScript 严格模式
npm run build     # 产出 main.js

手工验收清单：选择 kyoto-dusk → 阅读模式与 Live Preview 均显示在正文之前；切换静止模式动画停止；切换笔记后旧动画被销毁；清除 banner 后正文与其他 frontmatter 字段不变；断网后仍可浏览内置目录并显示缓存帧；窄窗口下 Canvas 不溢出容器。

许可

本插件以 MIT 发布（见 LICENSE）。内置的 ascii.rest 库以 MIT 发布，版权归 bas3line 所有（见 licenses/ascii.rest.MIT.txt）。