Vertical Tabs for Obsidian

Vertical Tabs is a workspace manager for Obsidian designed to solve the limitations of the default horizontal tab layout. It introduces a vertical list of tabs, making it easier to manage, group, and organize a large number of open notes without losing readability as tabs become narrower.

Key features include:

• Tab Organization: Grouping and organizing tabs for efficient navigation.
• Enhanced Navigation: Advanced tab navigation with customizable presets (e.g., IDE mode), an extended keyboard tab switcher, and a tab history browser.
• Workspace Management: Per-tab zooming, Zen mode, ephemeral tabs, and automatic tab deduplication.
• Customization: Ability to create personalized tab navigation strategies.

The plugin supports a tab zoom feature that adjusts the visual scale of tabs. This is implemented by patching ItemView and applying a CSS variable --vt-tab-zoom-factor to the view's container element.

• Requirement: enableTabZoom must be enabled in settings.
• Mechanism: The zoom factor is stored in the view's ephemeral state to ensure it persists during the view's lifecycle.

When a tab is closed, the plugin can automatically select a new active tab based on the configured tabClosingBehavior. This is controlled via the TabClosingBehavior enum.

Supported behaviors:

• ActiveLeft: Selects the tab to the left of the closed tab.
• ActiveRight: Selects the tab to the right, or falls back to the left if no right tab exists.
• ActiveRecent: Selects the tab that was most recently active among the remaining tabs.

The plugin patches WorkspaceLeaf.openFile and WorkspaceLeaf.canNavigate to implement several advanced behaviors:

• Deduplication: If enabled, the plugin checks if a file is already open in another leaf. If a match is found, it avoids opening a duplicate and instead focuses the existing leaf and detaches the current one. This can be scoped to deduplicateTabs, deduplicateSameGroupTabs, deduplicateSidebarTabs, or deduplicatePopupTabs.
• Ephemeral Tabs: Controlled by ephemeralTabs setting, these tabs follow specific navigation rules.
• Smart Navigation: Uses executeSmartNavigation to decide if a navigation request should proceed based on the current view state.
• Always Open in New Tab: If alwaysOpenInNewTab is enabled, canNavigate returns false to force new tab creation.

The plugin uses GroupViewType to define how a group of tabs (a WorkspaceParent) is rendered and behaves. You can identify or change the layout mode of a workspace group using these types.

Available view types:

• GroupViewType.Default: The standard vertical tab view.
• GroupViewType.ContinuousView: A continuous scrolling view. When active, it respects settings for showing metadata (vt-continuous-view-show-metadata) and backlinks (vt-continuous-view-show-backlinks).
• GroupViewType.ColumnView: A column-based layout.
• GroupViewType.MissionControlView: A specialized view for overviewing many leaves, which enables dragging and specific zoom factors.

export enum GroupViewType {
	Default = "vt-default-view",
	ContinuousView = "vt-continuous-view",
	ColumnView = "vt-column-view",
	MissionControlView = "vt-mission-control-view",
}

The plugin implements a 'View Cue' system to allow users to navigate through tabs using indices (e.g., 1-8). This system maps user-facing indices to actual Obsidian WorkspaceLeaf objects, accounting for an offset that allows cycling through groups of tabs.

• mapViewCueIndex: Converts a real index to a user-facing ViewCueIndex (which can be a number, or special tokens like VIEW_CUE_NEXT (→) or VIEW_CUE_PREV (←)).
• convertBackToRealIndex: Converts a user-facing index back to the actual Obsidian leaf index.
• revealTabOfUserIndex: The primary method to trigger navigation to a specific tab based on the user's perceived index.
• viewCueOffset: An internal offset used to shift the window of visible indices.

To restore the user's previous session (group titles, hidden/collapsed groups, etc.) from local storage, call hydrateViewState(). This should be part of the plugin's onLoad sequence.

// Inside your Obsidian plugin class
async onLoad() {
  hydrateViewState();
  // ... rest of setup
}

The plugin provides a dedicated settings tab (ObsidianVerticalTabsSettingTab) to control various behaviors. Settings are applied by toggling specific CSS classes on the document body.

Key configuration categories include:

• UI Appearance: hideSidebars, showActiveTabs, scrollableTabs, autoHideHorizontalTabs, trimTabNames, zenMode, enableTabZoom.
• Tab Behavior: sidebarExcludeSelf, useTabEditing, ephemeralTabs, alwaysOpenInNewTab, allowWorkspaceSplitOnPhone.
• Advanced Features: backgroundMode, disablePointerInMissionControlView.

The safeDetach function detaches a WorkspaceLeaf from the workspace. If the leaf's view is an instance of FileView, it sets isDetachingFromVT to true to signal the detachment process to the Vertical Tabs plugin. The function catches and ignores errors during detachment, which can occur when detaching Bases during tab deduplication (a known behavior in Obsidian v1.9).

import { WorkspaceLeaf } from "obsidian";
import { safeDetach } from "./services/CloseTabs";

safeDetach(leaf);