BiDi Flow Navigator

BiDi Flow Navigator is a highly polished document outline and navigation plugin for Obsidian. Specifically built to handle Bidirectional (BiDi) text (Persian, Arabic, and mixed RTL/LTR) flawlessly, it provides heading tracking, section jumping, reading progress calculation, precise scroll memory across mode switches, customizable themes, and synchronized auto-scrolling across devices.

✨ Features

🔀 True Bidirectional & RTL Text Handling

• Built with modern CSS Logical Properties (margin-inline-start, inset-inline-*), dir="auto", and Unicode bidirectional isolation rules.
• Correctly aligns and structures complex headings containing a mix of Persian, Arabic, English words, numbers, and technical terms.

🏃 Synchronized Auto-Scroll & 5-Button Toolbar

• Symmetrical Action Toolbar: A sleek bottom navigation bar containing:
  • ⏮️ Prev Sibling: Jump backward across headings at the same or higher level.
  • 🔼 Prev Part: Jump backward by page or section.
  • ▶️ Auto Scroll: Smooth, continuous downward scroll with adjustable speed (10 to 200 px/s).
  • 🔽 Next Part: Jump forward by page or section.
  • ⏭️ Next Sibling: Jump forward to the next sibling or parent heading.
• Cross-Window State Synchronization: Toggling Auto-Scroll from the floating window, the right sidebar, or via the command palette synchronizes the play/pause state across all open panels instantly.
• Sub-Pixel Motion Engine: Uses float accumulators to prevent stuttering or truncation at lower reading speeds (10–30 px/s) in both Reading View and Editing View.
• Smart Deep Navigation: Sibling navigation on H1/H2 skips nested subheadings. For H3 and deeper headings, jumping can target the parent section or same-level siblings based on your preference.

🧠 Robust Position Memory & Mode Synchronization

• Remember Last Heading: Remembers your exact active reading location per note and restores it flawlessly when reopening files or restarting Obsidian.
• Editing & Reading View Parity: Employs a robust scrollWithRetry engine that monitors DOM readiness to keep your exact reading position completely perfectly synchronized when toggling between Live Preview/Source and Reading View.

🪟 Adaptable Window System

1. Compact Pill (mini): A tiny, distraction-free floating compass button docked in the corner.
2. Floating Card (floating): A compact floating card with quick controls, responsive height, and an interactive heading tree.
3. Full-Height Rail (full-height): Full-height side dock suitable for large desktop monitors.

• Mobile-Tailored Ergonomics: On mobile phones, the floating window automatically positions itself lower (88px from the top) to stay clear of app headers, uses a compact maximum height, and disables full-height expansion for clean touch navigation.

🎨 Visual Themes & Design

• Color Themes: Includes Default Obsidian, Dracula, Nord, Solarized, and Gruvbox.
• Styles: Choose between Solid and modern translucent Glassmorphism styling.
• Minimalist Finish: Clean, flat borders without heavy drop shadows for a native Obsidian feel.

📊 Outline Features

• Reading Progress Bar: Displays real-time reading progress with optional Persian digits (۴۰٪).
• Heading Search: Real-time filter that instantly auto-expands matching parent branches.
• Section Indicator: Displays the active heading with a level tag (H1–H6) and a counter (۱۵ / ۱۰۱).
• Pure Bilingual UI: Switch completely between English and Persian without mixed-language artifacts.

📸 Screenshots

Desktop: Dual-Window Outline (Floating Card & Sidebar)

Floating card and right sidebar outline working together across Dark, Light, and Warm palettes with synchronized toolbars and Persian heading numerals.

Mobile View & Plugin Settings

Left & Center: Touch-friendly outline on phone devices with ergonomic top clearance. Right: Plugin configuration options.

📥 Installation

Using BRAT (Beta Releases)

1. Install the Obsidian42 - BRAT community plugin.
2. Under BRAT settings, select Add Beta plugin.
3. Enter repository URL:

   https://github.com/mohamad-javad/BCN-bidi-content-nvigator-
   

4. Enable BiDi Flow Navigator under Settings > Community plugins.

Manual Installation

1. Download main.js, manifest.json, and styles.css from the latest Release.
2. Create a folder named bidi-flow-navigator in your vault at .obsidian/plugins/bidi-flow-navigator/.
3. Copy the downloaded files into that folder.
4. Reload Obsidian and enable the plugin in Community Plugins.

⌨️ Commands

⚙️ Settings Reference

• UI Language: Select interface language (English or فارسی).
• Show Floating Widget: Enable or disable the floating note outline.
• Floating Position: Dock the floating widget on the Right or Left side.
• Default Window Mode: Set initial mode (Floating Card, Compact Pill, or Full-Height).
• Floating Window Width: Adjust card width (200px to 420px).
• Color Theme: Select color palette (Default, Dracula, Nord, Solarized, Gruvbox).
• Theme Style: Choose between Solid and Translucent.
• Bottom Action Toolbar: Toggle visibility of the 5-button bottom action bar.
• Auto Scroll Speed: Set scroll rate in pixels per second (10 to 200 px/s).
• Deep Heading Jump Target: Choose whether deeper headings (H3+) jump to their Parent Heading or Sibling Heading.
• Remember Last Heading Position: Automatically return to the last active heading when reopening notes.
• Persian Numerals: Display counters and percentages in Persian digits (۱، ۲، ۳...).
• Reading Progress Bar: Show or hide the top progress bar.
• Search Filter: Enable or disable heading search.
• Heading Level Badges: Show or hide colored badges for H1–H6.

📅 Changelog

v1.2.5

• Robust Scroll Architecture: Completely overhauled the scrolling engine with a robust retry mechanism (scrollWithRetry) that guarantees correct scroll position restoration.
• Smart Mode Switching: Fixed the jump-to-top bug that occurred during the first mode switch between Live Preview and Reading View. The plugin now smartly detects Obsidian's native scroll state and intelligently steps in to restore the previous heading if Obsidian fails to sync properly due to unmounted DOM elements.
• Polished Default Settings: Updated default settings to feature the 'Nord' transparent theme and 'Mini' default window mode.

v1.2.1

• Popout Window Compatibility: Standardized all frame scheduling calls to window.requestAnimationFrame() and window.cancelAnimationFrame().
• CSS Quality Standards: Eliminated all !important declarations by enhancing selector specificity in mobile responsive rules.
• Mobile Comfort Height: Adjusted mobile floating card maximum height to 420px for balanced outline visibility and note reading.

v1.2.0

• Unified Auto-Scroll: Synchronized auto-scroll state across the floating window, sidebar view, and command palette.
• Symmetrical 5-Button Toolbar: Added quick-action navigation controls (Prev Sibling, Prev Part, Auto Scroll, Next Part, Next Sibling).
• Sub-Pixel Motion Engine: Fixed scrolling in Reading View (.markdown-preview-view) and implemented sub-pixel accumulation for smooth movement at speeds below 30 px/s.
• Smart Deep Heading Navigation: Added setting to jump to parent headings when navigating nested sections (H3+).
• Mobile Ergonomics: Lowered floating widget position on mobile phones (top: 88px), reduced maximum card height, and disabled full-height expansion on mobile screens.

v1.1.11

• Heading Memory: Remembers active reading heading per note across sessions.
• Mode Switching Parity: Fixed position loss when toggling between Live Preview and Reading View.
• Localized Themes: Standardized theme names to match the active UI language.
• Mobile Polish: Refined touch handling and card sizing on mobile devices.

v1.1.0

• Theme Palettes: Added Dracula, Nord, Gruvbox, Solarized, and Default themes.
• Visual Styles: Added Solid and Translucent (Glassmorphism) styles.
• Language Switcher: Instant runtime switching between Persian and English.

v1.0.1

• Core Release: 3-mode window system (Mini Pill, Floating Card, Full-Height Rail), bidirectional outline parser, reading progress bar, heading search, and sidebar integration.

📜 License

This project is licensed under the MIT License.