全部插件 / gogoga outline

gogoga outline

贴在编辑区边缘的标题导轨,悬停展开目录,点一下就跳过去。

v0.5.0插件市场已上架MIT

安装

  1. 打开 设置 → 第三方插件,关闭「安全模式」(新版叫「受限模式」)。
  2. 点 浏览,搜索 gogoga outline。
  3. 点 安装,装好后点 启用。以后在「第三方插件」里检查更新。

插件市场的文件实际从 GitHub 下载。如果一直转圈或提示失败,换用离线包安装。

一条固定在编辑区边缘的标题导轨,风格参照 Codex 的文档导航。它是 gogoga 主题的配套插件,但不依赖主题的任何东西, 单独使用也没问题。

界面语言跟随 Obsidian 的语言设置,支持简体中文和英文。

演示:悬停波浪与章节预览、点击跳转、停留展开全局大纲、键盘导航

功能

  • 静止时:一列长短一致的短刻度,每个标题对应一条。当前正在阅读的章节对应的 刻度显示为强调色。
  • 悬停时:程序坞式的波浪。每条刻度按它到光标距离的高斯衰减变长,所以波峰会 连续地跟随指针移动,而不是在条目之间跳格。
  • 预览:波峰所在的章节会显示一张卡片,内容是标题和该章节开头几行(去掉 markdown 标记)。卡片随波峰一起滑动。
  • 点击:滚动到对应标题。
  • 停留时:指针在导轨上静止片刻,完整大纲就会在旁边展开,按标题层级缩进。 在波浪上来回划动永远不会触发它——只要有真正的移动,计时器就会重新开始,所以只有 真正停下来才会打开面板。
  • 面板打开后:导轨变成它的滑块。指针沿刻度往下划,会高亮面板里对应的那一行, 而不是在面板上再叠一张预览卡片;点击即确认并关闭。

面板只是一个普通的浮出层:导轨本身不会移动。手势进行到一半时,光标下面的东西不会 突然挪开;五十个标题的笔记和五个标题的笔记表现完全一样(面板内部滚动,打开时当前 章节就在视野内)。各行从导轨一侧滑入,每行之间有短暂的错开。

离开导轨或面板中的任意一个,都会启动一个 180ms 的关闭计时器,进入另一个则取消它, 这样你才能跨过两者之间的空隙。按 Escape 关闭。展开/收起全局大纲 命令会以固定模式打开 面板——它会一直保持到你关闭为止,并获取键盘焦点,可以用上/下/回车导航。

每个打开的 markdown 面板各有一条导轨;导轨跟随面板拆分,也随面板关闭。

聚焦模式和悬停行强调(gogoga 主题)

「切换聚焦模式」「切换悬停行强调」两个命令用来开关 gogoga 主题自带的写作效果:聚焦模式下只有光标所在的段落保持清晰, 悬停行强调给鼠标所在的行加一层淡底色。可以在 设置 → 快捷键 里绑定快捷键;插件设置页底部也有同样的开关, 开关状态重启后保留。换成别的主题时不起作用。

设置

显示位置(左/右)、导轨出现所需的最少标题数、悬停时是否显示预览卡片、面板的展开方式 (停留展开或仅快捷键)以及停留多久后展开、面板宽度,以及面板展开到第几级标题—— 超过层级上限的标题不会进入面板,但在导轨上仍保留它的刻度。

面板还有几个可选项(默认都关):

  • 完整大纲常驻展开:不用悬停,完整大纲一直显示在笔记边上(代替导轨),正文给它让出位置。点标题跳过去,按 Esc 不会关;「全局大纲」命令改成把键盘焦点放进大纲。手机上不生效。
  • 点击标题后保持大纲打开:点标题跳过去,面板不收起,按 Esc 或再用一次命令关掉。面板开着时滚动正文,当前章节会自动保持在面板的视野里。
  • 只展开当前标题:正在看的(或刚点的)标题全部展开,它的上级一路打开,其余标题折叠到「其他标题显示到第几级」设的层级(默认只显示大标题)。整篇只有一个一级标题时,它当作总标题,层级从它下面一级算起。标题前出现小箭头:单击展开或收起一层,双击整支全部展开;面板获得焦点时也能用 ←/→。
  • 显示完整标题:太长的标题换行显示全文。

标题里的 $公式$ 在面板和预览卡片里照常渲染。

关于滚动行为

两种模式都会对 DOM 做虚拟化,因此都要在平滑度上做些让步,换取准确落到目标行。

编辑模式按 cm.viewport(CodeMirror 实际已渲染的范围)分两种情况处理。在这个范围内, 每一行的高度都是实测而非估算的,所以插件自己的计算是精确的,可以平滑滚动。范围之外, 定位交给 EditorView.scrollIntoView,它会反复测量直到目标稳定——位置精确,但只能瞬间 跳转,因为它把滚动推迟到下一次测量阶段,没有可靠的时机去拦截并重新加动画。

朴素的做法有两处错误,而且都很容易被忽略。CM6 报告的块位置是相对文档顶部的,而 scrollTop 是相对滚动容器顶部的,Obsidian 又用 --file-margins 给滚动容器加了内边距—— 所以直接使用 lineBlockAt().top 会差出这段内边距(默认 32px),跳转和当前章节追踪都会 受影响。另外,从未渲染过的行只有估算高度,所以根据高度表算出的目标会偏移,偏移量取决于 中间有多少未测量的内容;滚动途中经过这些行时会测量它们,目标还会进一步漂移。

阅读模式是虚拟化的——章节滚出视野后会被整个移出 DOM——所以当目标标题当前已渲染时, 插件会平滑滚动;未渲染时则回退到 Obsidian 基于行号的 applyScroll(瞬间跳转)。 因此近处的标题会平滑滑过去,远处的会直接跳过去。阅读模式下的当前章节追踪使用 getScroll(),它基于行号,不受虚拟化影响。

调参

波浪相关常量位于 main.js 顶部:BASE_W(静止时的刻度长度)、MAX_EXTRA(波峰处增加 的长度)、SIGMA(衰减半径,单位 px),以及对应的高度常量。旁边还有:DWELL_TOL (多大的漂移仍算作静止)、CLOSE_GRACE、INDENT_STEP,以及行的 STAGGER。

一个 CSS 细节

面板中的行是 <button>,而 Obsidian 核心的按钮规则优先级高于单独的 all: unset。 因此重置规则针对 :hover 和 :focus 又各写了一遍,所有视觉样式都放在多一层选择器的 规则里——否则 :hover 那份 all: unset 会在悬停时把行自身的样式抹掉,行就会显示成 灰色胶囊。

更新日志

0.5.0
2026-11-08

新增

  • 设置里新增「完整大纲常驻展开」(默认关):完整大纲一直显示在笔记边上,代替导轨,像固定的大纲面板,正文给它让出位置;点标题跳转、按 Esc 都不会收起。手机上不生效。(#1)
0.4.2
2026-10-31

修复

  • 整篇只有一个一级标题时,「其他标题显示到第几级」设成 1 和 2 看起来一样(这个一级标题是所有标题的上级,总是打开)。现在它当作总标题,层级从它下面一级算起:设成 1 只显示二级标题,设成 2 显示到三级。
0.4.1
2026-10-31

变更

  • 「只展开当前章节」改为「只展开当前标题」:以前按一级标题划分章节,整篇只有一个一级标题时等于全部展开;现在只展开正在看的那个标题和它的上级,其余标题折叠到「其他标题显示到第几级」设的层级。
0.4.0
2026-10-31

新增

  • 新设置「点击标题后保持大纲打开」:点标题跳过去,大纲不收起,按 Esc 或再用一次命令关掉。开着的时候滚动正文,正在看的章节一直保持在大纲可见范围里。
  • 新设置「只展开当前章节」:正在看的(或刚点的)那一章全部展开,其他章节只显示大标题,显示到第几级由「其他章节显示到第几级」决定。标题前的小箭头单击展开或收起一层,双击整支展开;大纲有键盘焦点时 ←/→ 也一样。展开、收起时,被点的那一行停在原位不动。
  • 新设置「显示完整标题」:太长的标题换行显示全文,不再省略成一行。
  • 标题里的公式在大纲和章节预览里照常渲染。
查看全部 9 个版本
0.3.0
2026-10-21

新增

  • 切换 gogoga 主题「聚焦模式」和「悬停行强调」的命令,可以绑快捷键。
0.2.1
2026-10-18

新增

  • 爱发电赞助链接。
0.2.0
2026-10-15

新增

  • 界面支持英文和简体中文,跟随 Obsidian 的语言设置。
  • 英文 README,另附简体中文版。
0.1.1
2026-10-15

改进

  • README 加演示 GIF。
0.1.0
2026-10-14

首个公开版本。

新增

  • 编辑器边缘的标题导轨:每个标题一道短横,当前所在的章节高亮。
  • 鼠标经过时像程序坞一样起伏,悬停的章节显示预览卡片,点击跳到那个标题。
  • 鼠标在导轨上停一下就展开全局大纲;命令可以固定打开大纲,并用键盘上下选择。
  • 阅读模式和编辑模式都能准确跳转,分屏时每个窗格各有一条导轨。