Repository navigation
Releases
1.6.0
Full Changelog: 1.5.0...1.6.0
1.5.0
Full Changelog: 1.4.0...1.5.0
Folder Focus Collapse
English
Folder Focus Collapse keeps the file explorer focused on the note you are working on. When a note is activated, folders outside its path collapse, the active row is brought into view at a stable position, and the row is highlighted so it can be found at a glance. It is a derivative of Auto Folder Collapse: the accordion and inactivity behaviour of the original plugin are preserved, while activation-driven focusing, anchoring, scrolling, highlighting, and bilingual settings are new work introduced by this plugin.
一、Features added by this plugin
1.1 Collapse when a note is activated
Three independent triggers decide when the tree collapses around the active note:
- Click in the editor — clicking into the note body or moving the caret focuses the tree on that note.
- Switch tabs — the active leaf changing triggers the same collapse, including clicking a file in the explorer.
- Open a file — quick switcher, search, and hotkeys can trigger it too. Both tab-switch and file-open triggers are off by default to avoid churn.
The scope of a collapse is controlled by the keep mode:
| Keep mode | Folders left open |
|---|---|
| Active file path only | Only the ancestor chain of the active note. |
| Path + sibling folders | The ancestor chain plus the direct subfolders of the note's parent folder. |
| Path + current folder subtree | The entire subtree of the note's parent folder. |
For Projects/Research/Papers/note.md, the three modes keep respectively Projects/Research/Papers, that chain plus the direct children of Papers, or the whole Papers subtree. None of the modes opens folders on its own; they only decide what survives a collapse. A note at the vault root keeps the whole tree in subtree mode.
The effect is a tree that shows only the current working context. Unrelated folders stop competing for space and attention, so there is no repeated scrolling or scanning through layers to find the note; keeping the ancestor chain open preserves where the note sits in the vault.
1.2 Anchor-first scrolling
After collapsing, the plugin positions the active row instead of merely making it visible. The container is divided into a comfort band from 10% to 78% of its height; the first top-level folder of the active path is treated as an anchor and kept at its pre-collapse screen position whenever the active row still fits in the band. When the ancestor chain is too long for that, the plugin concedes the minimum amount of scroll, and only then falls back to centering the row at a configurable ratio (40% by default, adjustable from 30% to 55%).
Four mutually exclusive scroll modes are available:
| Scroll mode | Behaviour |
|---|---|
| Anchor first (default) | Keeps the top-level folder fixed and centres only when the chain no longer fits. |
| Always center | Places the active row at the configured height on every activation. |
| Only keep visible | Scrolls only when the row is completely out of view, using native scrollIntoView. |
| No scrolling | Collapses only and never writes the scroll position. |
The write happens in the next animation frame, with up to two retries while the row is still mounting. A 250 ms correction window fixes native auto-reveal if it arrives late and pushes the row out of the comfort band, and never fights a result that is already comfortable. Each file-explorer pane is positioned independently, so split view works per pane.
Anchor-first scrolling is not only about bringing the row into view. Its main effect is keeping the tree above the target row visually stable: when the collapse changes the tree height, the top-level folder does not jump up or down, so the sidebar does not visibly shift. Spatial memory stays intact, users do not have to re-establish where things are, and attention is not pulled away by a large scroll. When anchoring cannot cover a long ancestor chain, the centre ratio still lands the row in the natural upper-middle viewing area.
1.3 Active-file highlight
Three highlight styles make the active row easy to spot without relying on scroll position alone:
- Accent fill (default) — theme accent background, contrasting text, rounded corners, semibold label.
- Left bar — native background plus a 3 px accent marker on the left edge.
- Theme default — no injected style.
Styles are scoped to the file explorer and are added or removed as the setting changes or the plugin unloads.
The highlight is not decoration. Its effect is to make the active row the one immediately identifiable element in the list: even when the row sits above the visual centre, the accent fill lets it stand out without scanning row by row. Together with stable positioning, this means users confirm the active note by appearance rather than by scrolling or searching.
1.4 Bilingual settings and in-place updates
The settings tab can follow Obsidian's language automatically or be forced to Chinese or English. Switching the language re-renders every section, setting name, description, and notice. Other settings update in place: for example, changing the scroll mode greys out or restores the centre-position slider without re-rendering the page, so the scroll position and keyboard focus are preserved. A reset button restores every setting to its default.
1.5 Diagnostics and compatibility
- An in-memory debug log records events, per-frame tree height, folder changes, scroll writes, and reveal decisions. It can be exported with the command Export file-explorer switch debug log; measurements do not write to disk.
- A bypass mode disables all collapsing and observes native behaviour only, for side-by-side comparison with Obsidian's own auto-reveal.
- The internal
view.fileItemsAPI is preferred; a DOM fallback handles builds where the API is missing. - Multiple file-explorer panes are supported, and the plugin cleans up listeners and injected classes on unload.
- Settings from earlier versions (
revealActiveFileandrevealStrategy) are migrated automatically to the unifiedrevealMode.
二、Implementation optimization
2.1 Single-frame collapse
The collapse is scheduled in a microtask before the next paint, so the explorer never shows the old tree. When the internal folder API is available, setCollapsed is used and the is-collapsed class is applied immediately as a fast path; the expanded ancestors are mounted in the same frame. A 300 ms accordion-suppression window prevents these programmatic changes from being interpreted as manual gestures.
This is an implementation optimization rather than a user-facing feature. The effect is that a switch completes in one visual step: no old tree, no intermediate height, and no flash of an expanded-then-collapsed chain.
三、Features provided by the original plugin
3.1 Recursive child collapse
Collapsing a folder also collapses all of its descendant folders.
3.2 Exclusive accordion
Expanding a folder collapses every other folder.
3.3 Inactivity auto-collapse
After a configurable idle period (5 minutes by default), all expanded folders collapse. The duration is adjustable from 1 to 60 minutes.
3.4 Settings compatibility
The original keys autoCollapseEnabled, inactivityMinutes, and exclusiveAccordionEnabled are retained, so existing values carry over.
四、Settings reference
| Key | Default | Description |
|---|---|---|
uiLanguage |
auto |
Settings language: follow Obsidian, Chinese, or English. |
collapseOnEditorClick |
on | Collapse when clicking into the editor. |
collapseOnActiveLeafChange |
off | Collapse when the active tab changes. |
collapseOnFileOpen |
off | Collapse when a file opens through other routes. |
keepMode |
path |
Which folders survive a collapse. |
revealMode |
anchor |
Anchor first / always center / only keep visible / no scrolling. |
revealCenterRatio |
40 | Height ratio used when centring (30–55). |
activeFileHighlight |
accent |
Accent fill / left bar / theme default. |
exclusiveAccordionEnabled |
on | Collapse other folders when one is expanded. |
autoCollapseEnabled |
on | Collapse folders after inactivity. |
inactivityMinutes |
5 | Idle minutes before collapsing (1–60). |
debugLogging |
off | Record the switch debug log in memory. |
debugBypass |
off | Observe native behaviour without changing the tree. |
五、Installation
- Copy the
folder-focus-collapsefolder into<vault>/.obsidian/plugins/. - Reload Obsidian and enable Folder Focus Collapse in Settings → Community plugins.
- If Auto Folder Collapse is installed, disable it: both plugins control the same tree and must not run together.
六、Compatibility
- Obsidian 1.0.0 or later; desktop and mobile.
- The plugin prefers Obsidian's internal folder API and falls back to DOM handling when that API is unavailable.
- Existing Auto Folder Collapse settings are read through the shared keys; no manual migration is required.
七、License
MIT. This project is derived from Auto Folder Collapse by Dario Casciato; see LICENSE for the attribution notice.
中文说明
Folder Focus Collapse 让文件树始终围绕你正在编辑的那篇笔记。笔记被激活时,路径之外的目录自动收拢,当前文件行被带到视口中一个稳定的位置,并以醒目的高亮标出。本插件基于 Auto Folder Collapse 二次开发:原插件的手风琴与闲置折叠行为完整保留,激活聚焦、锚点定位、滚动、高亮与中英文设置均为本插件新增。
一、本插件新增的功能
1.1 笔记激活时收拢
三种互相独立的触发方式决定何时围绕当前笔记收拢目录:
- 点击正文:点击正文或移动光标进入当前笔记时,文件树聚焦到该笔记所在路径。
- 切换标签页:活动标签页变化时同样收拢,点击文件树中的文件也会触发。
- 打开文件:快速切换、搜索、快捷键等打开文件的方式也可以触发。后两者默认关闭,避免频繁收拢。
收拢范围由「保持展开的目录」决定:
| 保留模式 | 保持展开的目录 |
|---|---|
| 仅当前文件路径 ... |
1.4.0
Full Changelog: https://github.com/lishuai1993/Folder-Focus-Collapse/commits/1.4.0
Folder Focus Collapse
English
Folder Focus Collapse keeps the file explorer focused on the note you are working on. When a note is activated, folders outside its path collapse, the active row is brought into view at a stable position, and the row is highlighted so it can be found at a glance. It is a derivative of Auto Folder Collapse: the accordion and inactivity behaviour of the original plugin are preserved, while activation-driven focusing, anchoring, scrolling, highlighting, and bilingual settings are new work introduced by this plugin.
一、Features added by this plugin
1.1 Collapse when a note is activated
Three independent triggers decide when the tree collapses around the active note:
- Click in the editor — clicking into the note body or moving the caret focuses the tree on that note.
- Switch tabs — the active leaf changing triggers the same collapse, including clicking a file in the explorer.
- Open a file — quick switcher, search, and hotkeys can trigger it too. Both tab-switch and file-open triggers are off by default to avoid churn.
The scope of a collapse is controlled by the keep mode:
| Keep mode | Folders left open |
|---|---|
| Active file path only | Only the ancestor chain of the active note. |
| Path + sibling folders | The ancestor chain plus the direct subfolders of the note's parent folder. |
| Path + current folder subtree | The entire subtree of the note's parent folder. |
For Projects/Research/Papers/note.md, the three modes keep respectively Projects/Research/Papers, that chain plus the direct children of Papers, or the whole Papers subtree. None of the modes opens folders on its own; they only decide what survives a collapse. A note at the vault root keeps the whole tree in subtree mode.
The effect is a tree that shows only the current working context. Unrelated folders stop competing for space and attention, so there is no repeated scrolling or scanning through layers to find the note; keeping the ancestor chain open preserves where the note sits in the vault.
1.2 Anchor-first scrolling
After collapsing, the plugin positions the active row instead of merely making it visible. The container is divided into a comfort band from 10% to 78% of its height; the first top-level folder of the active path is treated as an anchor and kept at its pre-collapse screen position whenever the active row still fits in the band. When the ancestor chain is too long for that, the plugin concedes the minimum amount of scroll, and only then falls back to centering the row at a configurable ratio (40% by default, adjustable from 30% to 55%).
Four mutually exclusive scroll modes are available:
| Scroll mode | Behaviour |
|---|---|
| Anchor first (default) | Keeps the top-level folder fixed and centres only when the chain no longer fits. |
| Always center | Places the active row at the configured height on every activation. |
| Only keep visible | Scrolls only when the row is completely out of view, using native scrollIntoView. |
| No scrolling | Collapses only and never writes the scroll position. |
The write happens in the next animation frame, with up to two retries while the row is still mounting. A 250 ms correction window fixes native auto-reveal if it arrives late and pushes the row out of the comfort band, and never fights a result that is already comfortable. Each file-explorer pane is positioned independently, so split view works per pane.
Anchor-first scrolling is not only about bringing the row into view. Its main effect is keeping the tree above the target row visually stable: when the collapse changes the tree height, the top-level folder does not jump up or down, so the sidebar does not visibly shift. Spatial memory stays intact, users do not have to re-establish where things are, and attention is not pulled away by a large scroll. When anchoring cannot cover a long ancestor chain, the centre ratio still lands the row in the natural upper-middle viewing area.
1.3 Active-file highlight
Three highlight styles make the active row easy to spot without relying on scroll position alone:
- Accent fill (default) — theme accent background, contrasting text, rounded corners, semibold label.
- Left bar — native background plus a 3 px accent marker on the left edge.
- Theme default — no injected style.
Styles are scoped to the file explorer and are added or removed as the setting changes or the plugin unloads.
The highlight is not decoration. Its effect is to make the active row the one immediately identifiable element in the list: even when the row sits above the visual centre, the accent fill lets it stand out without scanning row by row. Together with stable positioning, this means users confirm the active note by appearance rather than by scrolling or searching.
1.4 Bilingual settings and in-place updates
The settings tab can follow Obsidian's language automatically or be forced to Chinese or English. Switching the language re-renders every section, setting name, description, and notice. Other settings update in place: for example, changing the scroll mode greys out or restores the centre-position slider without re-rendering the page, so the scroll position and keyboard focus are preserved. A reset button restores every setting to its default.
1.5 Diagnostics and compatibility
- An in-memory debug log records events, per-frame tree height, folder changes, scroll writes, and reveal decisions. It can be exported with the command Export file-explorer switch debug log; measurements do not write to disk.
- A bypass mode disables all collapsing and observes native behaviour only, for side-by-side comparison with Obsidian's own auto-reveal.
- The internal
view.fileItemsAPI is preferred; a DOM fallback handles builds where the API is missing. - Multiple file-explorer panes are supported, and the plugin cleans up listeners and injected classes on unload.
- Settings from earlier versions (
revealActiveFileandrevealStrategy) are migrated automatically to the unifiedrevealMode.
二、Implementation optimization
2.1 Single-frame collapse
The collapse is scheduled in a microtask before the next paint, so the explorer never shows the old tree. When the internal folder API is available, setCollapsed is used and the is-collapsed class is applied immediately as a fast path; the expanded ancestors are mounted in the same frame. A 300 ms accordion-suppression window prevents these programmatic changes from being interpreted as manual gestures.
This is an implementation optimization rather than a user-facing feature. The effect is that a switch completes in one visual step: no old tree, no intermediate height, and no flash of an expanded-then-collapsed chain.
三、Features provided by the original plugin
3.1 Recursive child collapse
Collapsing a folder also collapses all of its descendant folders.
3.2 Exclusive accordion
Expanding a folder collapses every other folder.
3.3 Inactivity auto-collapse
After a configurable idle period (5 minutes by default), all expanded folders collapse. The duration is adjustable from 1 to 60 minutes.
3.4 Settings compatibility
The original keys autoCollapseEnabled, inactivityMinutes, and exclusiveAccordionEnabled are retained, so existing values carry over.
四、Settings reference
| Key | Default | Description |
|---|---|---|
uiLanguage |
auto |
Settings language: follow Obsidian, Chinese, or English. |
collapseOnEditorClick |
on | Collapse when clicking into the editor. |
collapseOnActiveLeafChange |
off | Collapse when the active tab changes. |
collapseOnFileOpen |
off | Collapse when a file opens through other routes. |
keepMode |
path |
Which folders survive a collapse. |
revealMode |
anchor |
Anchor first / always center / only keep visible / no scrolling. |
revealCenterRatio |
40 | Height ratio used when centring (30–55). |
activeFileHighlight |
accent |
Accent fill / left bar / theme default. |
exclusiveAccordionEnabled |
on | Collapse other folders when one is expanded. |
autoCollapseEnabled |
on | Collapse folders after inactivity. |
inactivityMinutes |
5 | Idle minutes before collapsing (1–60). |
debugLogging |
off | Record the switch debug log in memory. |
debugBypass |
off | Observe native behaviour without changing the tree. |
五、Installation
- Copy the
folder-focus-collapsefolder into<vault>/.obsidian/plugins/. - Reload Obsidian and enable Folder Focus Collapse in Settings → Community plugins.
- If Auto Folder Collapse is installed, disable it: both plugins control the same tree and must not run together.
六、Compatibility
- Obsidian 1.0.0 or later; desktop and mobile.
- The plugin prefers Obsidian's internal folder API and falls back to DOM handling when that API is unavailable.
- Existing Auto Folder Collapse settings are read through the shared keys; no manual migration is required.
七、License
MIT. This project is derived from Auto Folder Collapse by Dario Casciato; see LICENSE for the attribution notice.
中文说明
Folder Focus Collapse 让文件树始终围绕你正在编辑的那篇笔记。笔记被激活时,路径之外的目录自动收拢,当前文件行被带到视口中一个稳定的位置,并以醒目的高亮标出。本插件基于 Auto Folder Collapse 二次开发:原插件的手风琴与闲置折叠行为完整保留,激活聚焦、锚点定位、滚动、高亮与中英文设置均为本插件新增。
一、本插件新增的功能
1.1 笔记激活时收拢
三种互相独立的触发方式决定何时围绕当前笔记收拢目录:
- 点击正文:点击正文或移动光标进入当前笔记时,文件树聚焦到该笔记所在路径。
- 切换标签页:活动标签页变化时同样收拢,点击文件树中的文件也会触发。
- 打开文件:快速切换、搜索、快捷键等打开文件的方式也可以触发。后两者默认关闭,避免频繁收拢。
收拢范围由「保持展开的目录」决定:
| 保留模式 | 保持展开的目录 |
|---|---|
| 仅当前文件路径 | 只保留当... |