How kemus/obsidian-plugins-annotations works
Project Type and Purpose
• This is a full-stack (frontend-only) plugin for Obsidian, written in TypeScript, bundled via esbuild.
• Purpose: augment Obsidian’s “Community plugins” settings pane with per-plugin annotation fields that users can edit, format in Markdown, and persist.
File Structure
• src/: All TypeScript source modules
• main.ts – entry point, registers the plugin with Obsidian’s API
• settings_tab.ts – defines the UI injection into the Settings pane
• annotation_control.ts & manageAnnotations.ts – business logic for annotation creation, display, persistence
• grammar.pegjs & peggy.mjs – grammar definition + parser for custom parsing of annotations (e.g., Obsidian links)
• defaults*.ts, utils.ts, types*.ts – configuration, utilities, shared type definitions
• legacy_settings/ + versions.json – code paths to migrate old annotation formats
• styles/styles.css – plugin-specific styling to accompany the injected UI
• esbuild.config.mjs – build script, generates dist/main.js and dist/styles.css
• manifest.json – Obsidian plugin manifest (name, version, entry points)
README for Insights
• The plugin hooks into Obsidian’s “Community plugins” pane
• It uses the Obsidian Plugin API to fetch installed plugins, show textareas, and persist data
• User interactions (typing, locking, toggling) lead to data updates in the plugin’s storage
Main Components & Their Relationships
a. Obsidian Host
• Provides Plugin API: register settings pane tab, read/write plugin data, fetch installed plugin metadata
b. Plugin Entry (main.js)
• Bootstraps the plugin, calls app.workspace.registerSettingsTab()
c. SettingsTab UI
• Renders a list of installed plugins + annotation controls
• Uses annotation_control.ts to create/edit UI widgets
d. Annotation Manager
• manageAnnotations.ts handles loading/saving, lock toggles, migrations via defaults_legacy.ts & legacy_settings JSON
e. Storage Layer
• Obsidian’s data store (plugin-specific JSON under .obsidian/plugins/plugins-annotations)
f. Grammar Parser (Peggy)
• grammar.pegjs + peggy.mjs compile-time parser to process Markdown/links in annotations
g. Styles
• styles.css applies plugin-specific CSS in settings pane
Obsidian API → Plugin Entry → SettingsTab UI
SettingsTab UI ↔ Annotation Manager ↔ Storage
Annotation Manager → Legacy Settings (migration)
SettingsTab UI → Grammar Parser (on display/render)
Architectural Patterns & Technologies
• Modular MVC-style separation:
• View: settings_tab.ts, annotation_control.ts
• Controller: manageAnnotations.ts
• Model: storage JSON, types.ts
• Build & Bundling: esbuild (esbuild.config.mjs)
• Parsing: Peggy (grammar.pegjs + peggy.mjs)
• Styling: plain CSS (styles/styles.css)
Essential Elements
• Component names (Main, SettingsTab, AnnotationControl, ManageAnnotations, PeggyParser, Storage)
• Data stores (plugin JSON folder, legacy_settings)
• Obsidian API boundaries
• Build pipeline (esbuild.config → main.js + styles.css)