How aidenlx/alx-folder-note works
Project type and purpose
• This is an Obsidian plugin written in TypeScript that augments the built-in file explorer with “folder note” functionality (creating and syncing a note with each folder). It is packaged via esbuild, installed into Obsidian via a manifest.json, and depends on the external folder-note-core plugin for core folder-note logic.
File structure
• Top‐level build and config:
• package.json, pnpm-lock.yaml, tsconfig.json, esbuild.config.mjs, scripts/ob-bumper.mjs
• manifest.json (+ manifest-beta.json) defining the plugin’s metadata and entry point
• Source code under src/:
• fn-main.ts – plugin entry (loads settings, registers commands, initializes patches)
• fe-patch.ts – orchestrates front-end patches (applies all fe-handler modules)
• click-handler.ts, drag-patch.ts – event interceptors for click and drag on folders
• settings.ts & settings.less – UI for plugin configuration
• typings/ – TypeScript definitions for Obsidian API and SVG
• Other metadata: CHANGELOG.md, LICENSE, README.md
Review the README for architectural clues
• It describes how the plugin hooks into the Obsidian file explorer to:
• Open or create a folder note when a folder is clicked
• Hide or reveal the note in the explorer
• Sync folder & note names (rename)
• Toggle a folder-focus mode
• Optionally render a Folder Overview codeblock (folderv)
• It calls out an external dependency: folder-note-core
Main components
a. Build & Packaging Subsystem
• Developer machine with PNPM & esbuild.config.mjs → bundles TypeScript + Less → outputs dist/ + plugin manifest
• Scripts folder for version bumping (ob-bumper) and release (release-it.cjs)
b. Plugin Host (Obsidian)
• Obsidian app core loads plugin via manifest.json
• folder-note-core plugin (peer dependency)
c. alx-folder-note Plugin Runtime
• Plugin Entry (fn-main.ts)
– Reads user settings
– Registers commands & context-menu items with Obsidian API
– Invokes fe-patch to apply UI patches
• Event Handlers
– click-handler.ts intercepts folder clicks
– drag-patch.ts intercepts drag events
• Feature Modules
• Style Patches
– fe-handler/*.less for custom CSS injected into the explorer
d. Obsidian File Explorer UI
• Receives patched behaviors and styles
• Interacts with the folder-note-core to create, sync, hide, reveal notes
e. Optional Folder Overview Service
• Codeblock parser for folderv
• Renders dynamic summary cards of folder contents
Relationships and Interactions
• Developer → (build) → Plugin Package
• Obsidian Host loads → Plugin Entry → registers Event Handlers & UI Patches
• UI Patches → modify File Explorer DOM and styles
• Event Handlers → call folder-note-core APIs to create/rename/sync notes
• Settings UI ↔ User & Plugin Entry (two-way binding)
• Optional folderv codeblock parser ↔ folder overview renderer ↔ File Explorer pane
Architectural patterns & design principles
• Modular layering: separation between build, core plugin entry, event handlers, feature modules, and styling
• Patch/Decorator pattern: injecting behavior into Obsidian’s existing file explorer rather than forking it
• Observer pattern: subscribing to user events (click, drag, context-menu) via Obsidian API
• Dependency decoupling: relying on folder-note-core for business logic, while focusing on UI integration
Technology stack to call out
• TypeScript + tsconfig
• Less for styling (compiled via esbuild)
• esbuild (esbuild.config.mjs) for bundling
• PNPM for package management
• Obsidian Plugin API
• External plugin: folder-note-core
Essential elements to capture
• Build pipeline → plugin artifact
• Obsidian loading mechanism (manifest + API registration)
• Core entrypoint (fn-main.ts)
• Separation of concerns: event handlers vs. feature modules vs. styles
• External dependency (folder-note-core)
• User interaction flow: click/drag → plugin → file explorer update