How aidenlx/marginnote-companion works
Project Type and Purpose
• This is an Obsidian plugin (“MarginNote Companion”) whose job is to bridge data between MarginNote 3 and Obsidian. It listens for user actions (paste, commands, gestures) inside Obsidian, fetches the selected note/selection/tree from MarginNote (via the obsidian-bridge add-on), transforms it (images, backlinks, metadata), applies user-configurable templates, and inserts the resulting Markdown into Obsidian.
Main Components
a. Host Environment
• Obsidian App (v0.12.17+) with Plugin API
• MarginNote 3 + obsidian-bridge add-on
b. Plugin Package
• manifest.json – plugin metadata & permissions
• main.js (built) – entry point that registers commands, UI, event listeners
• styles.css – default styling
c. Source Modules (src/)
1. Receivers – listen for Obsidian events
• autopaste.ts, input-handler.ts, insert.ts, rec-indicator.less
2. Handlers – coordinate data fetch & processing
• -new-video.ts, frontmatter.ts, mn-data-handler.ts
3. Controls – UI components & context-menu items
• heading-alias.ts/.less, heading-src.ts/.less, util.ts/.less
4. Settings UI
• setting-tab.ts/.less, settings.ts
5. Template Engine
• template.ts, note-template.ts, sel-template.ts, toc-template.ts, basic/…
6. Macros & Utilities
• macro-handler.ts, autodef.ts, misc.ts, cm-tools.ts
7. Language Support
• lang/en.ts, zh.ts, helper.ts
8. “ToSource” Helpers
• src-button.ts, src-cmd.ts, src-menu.ts, to-src.ts
9. Typings & Config
• svg.d.ts, tpl-cfg.d.ts, types.d.ts
Relationships & Data Flow
• User triggers an action in Obsidian (context menu, hotkey, paste) →
Receivers capture the event →
Handlers call into mn-data-handler to request JSON/XML from MarginNote via obsidian-bridge →
Data passes through macros & utilities →
Template engine renders Markdown according to user templates →
Frontmatter handler injects metadata (aliases, backlink) →
Controls/UI modules decide where and how to insert →
The plugin uses Obsidian API to insert or replace content in the editor →
Settings UI allows live configuration of commands, templates, and languages.
Architectural Patterns & Key Technologies
• Event-driven architecture: Receivers → Handlers → Template → Output
• Modular separation: each concern (UI, data fetch, templating, macros) lives in its own folder
• Plugin build pipeline: esbuild.js + rollup.config.js compile & bundle TS into main.js for Obsidian
• Styling with Less (.less files)
• Jest for unit tests (jest.config.ts)
• Language files for i18n support