gogoga outline

by jackweigogoga
5
4
3
2
1
Score: 50/100

Description

Obsidian plugin: a collapsed heading rail on the edge of the editor.

Reviews

No reviews yet.

Stats

7
stars
1,845
downloads
0
forks
37
days
1
days
2
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
2
total issues
0
open issues
2
closed issues
35
commits

Latest Version

3 days ago

Changelog

中文

新增

  • 手机、平板上长按导轨拖动(用户建议):长按后上下滑,短横跟着手指起波浪,旁边浮出标题,正文实时滚到那一节,就像带目录的滚动条;松手就停在那里。

变更

  • 触屏上轻点导轨不再跳转,滑正文时手指擦到导轨也不会误跳;从导轨上开始滑照样滚动正文。

English

Added

  • Long-press the rail on phones and tablets to drag through the outline (user suggestion): the dashes ripple under your finger, the heading name floats beside it, and the note scrolls to that section as you slide up and down — like a scrollbar with a table of contents. Lift your finger to stay there.

Changed

  • On touch screens, a quick tap on the rail no longer jumps to a heading, so brushing the rail while scrolling the note doesn't send you elsewhere. Swiping that starts on the rail still scrolls the note as usual.

完整更新日志 / Full changelog: https://github.com/JackWeiGogoga/gogoga-outline/blob/main/CHANGELOG.zh-CN.md

README file from

Github

gogoga Outline

English | 简体中文

Website: obsidian.gogoga.top — screenshots, features and downloads.

A heading rail pinned to the edge of the editor, in the style of Codex's document navigator. Companion to the gogoga theme, but it depends on nothing from the theme and works anywhere.

The interface follows Obsidian's language setting — English, or Simplified Chinese when Obsidian is set to Chinese.

Demo: hover wave with section previews, click to jump, rest to open the full outline, keyboard navigation

Install

Settings → Community plugins → turn off Restricted mode → Browse, search for gogoga Outline, install it, then click Enable. Updates show up there too.

Manual install

For offline machines (such as a company network) or to pin a specific version:

  1. Open the Releases page and download the three files main.js, manifest.json, styles.css under Assets. Don't download the Source code archives: they are the source code, which Obsidian can't load.
  2. In your vault's folder, go to .obsidian/plugins/, create a folder named gogoga-outline, and put the files in it, so you end up with paths like <vault>/.obsidian/plugins/gogoga-outline/main.js.
    • .obsidian is a hidden folder: press ⌘ ⇧ . in Finder on macOS; on Windows, tick Hidden items under View in File Explorer.
  3. Restart Obsidian (or click the refresh button under Settings → Community plugins), then enable gogoga Outline in the list of installed plugins.

On phones, where moving files around is awkward, use the community plugins browser.

What it does

  • At rest: a column of identical short dashes, one per heading. The dash for the section you are currently reading is accent-colored. In a long note whose dashes would not fit, the rail still stays within the window: only the higher-level headings get a dash (the hidden ones count toward the dash above them), and clicking anywhere on the rail jumps to the nearest dash.
  • On hover: a dock-style wave. Each dash grows by a gaussian falloff of its distance to the cursor, so the crest follows the pointer continuously rather than snapping between items.
  • Preview: the section under the crest shows a card with its heading and the opening lines of that section, markdown stripped. The card slides along as the crest moves.
  • Click: scrolls to that heading.
  • On rest: hold the pointer still on the rail for a moment and the whole outline unfolds beside it, indented by heading level. Scrubbing the wave never triggers it — the timer re-arms on any real movement, so only actually coming to a stop opens the panel.
  • While the panel is open: the rail becomes its scrubber. Running the pointer down the dashes highlights the matching row instead of stacking a preview card on top of the panel; a click commits and closes.

The panel is a plain flyout: the rail does not move. Nothing shifts out from under the cursor mid-gesture, and a fifty-heading note behaves exactly like a five-heading one (the panel scrolls internally and opens with the current section in view). Rows slide in from the rail side with a short per-row stagger.

Leaving either the rail or the panel starts a 180ms close timer that entering the other cancels, which is what lets you cross the gap between them. Escape closes. The Toggle global outline command opens it pinned — it stays until you close it, and takes keyboard focus so up/down/enter navigate it.

One rail per open markdown pane; rails follow pane splits and close with them.

Focus mode and hover highlight (gogoga theme)

Two commands — Toggle focus mode (切换聚焦模式) and Toggle hover line highlight (切换悬停行强调) — switch on writing effects built into the gogoga theme: in focus mode only the paragraph with the cursor stays bright, and hover highlight tints the line under the mouse. Bind them in Settings → Hotkeys; the same switches are at the bottom of this plugin's settings, and the state survives a restart. Under other themes they do nothing.

Settings

Side (Position, left/right), minimum heading count before the rail appears (Minimum headings), whether hovering shows the preview card (Show section preview on hover), how the panel opens (Open mode: Open on rest vs. Hotkey only) and after how long (Rest delay), panel width (Panel width), and how deep the panel goes (Panel depth) — headings below the depth cap are left out of the panel but keep their dash on the rail.

A few more panel options, all off by default:

  • Keep the full outline open: the full outline stays open at the edge of the note instead of the rail, like a docked outline panel, and the note makes room for it. Clicking a heading scrolls to it; Esc doesn't close it; the outline command moves keyboard focus into it. Not on phones.
  • Keep the outline open after clicking: clicking a heading scrolls to it and leaves the panel open; close it with Esc or the command. While it stays open, the section you scroll to is kept in view in the panel.
  • Expand only the current heading: the heading you are reading (or just clicked) is expanded all the way and the headings above it are opened; everything else folds down to Levels shown for other headings (top headings only by default). In a note under one single top heading, that heading counts as the title and levels count from the headings below it. Arrows appear in front of headings: click to expand or collapse one level, double-click to expand the whole branch; ←/→ work too when the panel has focus. Set Levels shown for other headings to All and only the arrows you click fold anything.
  • Fold arrows (off by default): headings with subheadings get an arrow in the full outline and everything starts unfolded; click to fold or unfold that section, double-click to unfold everything under it, or use ←/→ when the panel has focus. Folds last while the note stays open and reset when you switch notes; search ignores them.
  • Show full titles: long headings wrap instead of being cut off.
  • Show headings in their heading style: each row in the full outline takes the color, weight and font your theme gives that heading level, with its size scaled slightly by level too, so levels are easier to tell apart; the row you are reading stays accent-colored.
  • Show heading levels: puts H1, H2, H3… in front of each row of the full outline.

Search headings

To find a heading in a long note, the full outline has a search box at the top. Typing keeps only the matching headings, with their parent headings in a lighter color so you can see which section each one is in; the matched text is highlighted and the number of matches shows on the right. Several words separated by spaces must all appear; case doesn't matter; headings deeper than the panel's level limit are searched too. While searching, the matching dashes on the rail turn accent-colored, so you can see where the results are in the note.

  • Open it: hover the rail and click the magnifier that appears at its top, or use the Search headings command (bind a hotkey in Settings → Hotkeys). Typing while the panel has focus also goes into the search box.
  • Keyboard: ↓/↑ move between matches, Enter jumps; Esc clears the search, and a second Esc closes the panel (with the outline docked, it hands focus back to the note).

$formulas$ in headings render in the panel and the preview card.

Notes on scrolling behavior

Both modes virtualize their DOM, and both therefore trade some smoothness for landing on the right line.

Editing mode branches on cm.viewport, the range CodeMirror has actually rendered. Inside it every line height is measured rather than estimated, so the plugin's own arithmetic is exact and it glides. Outside it, placement is handed to EditorView.scrollIntoView, which re-measures until its target is stable — exact, but instant, since it defers the scroll to its next measure pass and there is no reliable moment to intercept and re-animate.

Two things make the naive approach wrong, and both are easy to miss. CM6 reports block positions relative to the document top while scrollTop is relative to the scroller top, and Obsidian pads the scroller by --file-margins — so lineBlockAt().top used directly is off by that padding (32px by default), in the jump and in current-section tracking alike. And a line that has never been rendered carries an estimated height, so a target computed from the height map drifts by however much unmeasured content lies in between, then drifts further mid-flight as the scroll measures those lines on the way past.

Reading mode is virtualized — sections scroll out of the DOM entirely — so the plugin scrolls smoothly when the target heading is currently rendered and falls back to Obsidian's line-based applyScroll (an instant jump) when it is not. Nearby headings therefore glide and distant ones jump. Current- section tracking in reading mode uses getScroll(), which is line-based and unaffected by virtualization.

Tuning

The wave constants sit at the top of main.js: BASE_W (dash length at rest), MAX_EXTRA (added length at the crest), SIGMA (falloff radius in px), and their height counterparts. Alongside them: DWELL_TOL (how much drift still counts as holding still), CLOSE_GRACE, INDENT_STEP, and the row STAGGER.

A CSS note

Panel rows are <button>s, and Obsidian's core button rules outrank a bare all: unset. The reset therefore repeats itself for :hover and :focus, and everything visual lives in a rule one selector deeper — otherwise the :hover copy of all: unset claws the row's own styling back on hover and the rows render as gray pills.

Community

Bugs and feature requests: please open an issue with a screenshot or recording and the version. Chinese-speaking users can also join the WeChat group: add JackWeiGogoga with the note “gogoga”, or scan the QR code on the community page.

Support

gogoga is free and open source. If this plugin helps you, you can support its development on afdian (爱发电). Obsidian also shows a support button for it in the community directory. Bug reports and ideas help just as much.

Changelog

What changed in each version is in CHANGELOG.md (中文). Add the new version there before releasing: the release notes are taken from it, and the release fails when the entry is missing.

License

MIT, see LICENSE.