Skip to content

Developer Obsidian Plugin

Vivek Sarin edited this page Nov 18, 2026 · 4 revisions

Obsidian plugin

The plugin is the layer between Obsidian and the core. It finds diagrams in notes, runs them, opens the editors, and adds the commands and menus. The core code has no Obsidian dependency, so the plugin is the only place that imports obsidian.

Entry point and lifecycle

src/obsidian/main.ts defines the plugin class. The onload method registers everything. The onunload method releases it.

On load, the plugin registers:

  • Code block processor for ```flowmotion. It creates one runtime per block. Each runtime is owned by a small class, and Obsidian calls its onunload when the note view is destroyed. The class removes itself from the registry and destroys the player.
  • Vault listener on modify. A saved diagram file is redrawn in the notes that embed it.
  • View for .flow files (FlowView), and the .flow extension.
  • Commands, listed in Editing and help.
  • Editor extension, flowLanguageExtension, and an editor suggestion provider, FlowSuggest. Both work on the note source.
  • Context menu entries, for notes, folders, and files.
  • Settings tab, FlowMotionSettings.

On unload, the plugin clears its cache, disposes the Monaco loader, and stops its local add-on servers.

Settings

The settings are stored with loadData and saveData. The defaults are:

Key Default Meaning
autoplay true Starts diagrams on display. A diagram can opt out with animation.autoplay
speed 1 Used when the diagram's speed is 1. Only 0.5, 1, and 2 are offered in the settings tab
paperLight light The draw.io sheet in a light theme
paperDark dark The draw.io sheet in a dark theme
drawioEnabled false Enables the draw.io add-on. Turning it on downloads it
codeEditor false Uses the optional Monaco add-on on desktop

A diagram's own animation.speed is used when it is not 1. Otherwise the setting applies. The backdrop of a draw.io drawing is merged with the setting for the current theme, unless the diagram sets paper itself.

FlowMotionSettings.getSettingDefinitions() supplies declarative settings for Obsidian 1.13 and later, including settings search. Older Obsidian versions use display() and drawLegacy() to render the same definitions through the Setting API. Speed is read as text for the dropdown and converted back to a number before saving.

The Playback controls row is explanatory text, not a vault-wide toggle. Controls are hidden by default; the diagram's gear button or controls: true shows them.

The draw.io add-on

addons.ts describes the draw.io add-on. To resolve a download it reads https://raw.githubusercontent.com/jgraph/drawio/dev/VERSION, then takes draw.war from the matching release on GitHub. It also fetches LICENSE from the same tag. addon-installer.ts downloads over https only, follows up to five redirects, and reads the war with zip.ts. It keeps only the files the embedded editor loads (the DRAWIO_FILES pattern, about 42 MB), writes them to drawio.installing, and renames that folder to drawio after the check for index.html passes. The download is not checksum-verified.

Turning the toggle on installs the add-on when its files are missing. Turning it off stops the server and deletes the folder. If the download fails, the toggle returns to off and a notice shows the reason. Settings show installed, not installed, or unknown status.

Async status updates write to setting.descEl.textContent. Do not replace these with setting.setDesc(): that update triggers repeated declarative re-rendering and can hang the settings window.

Files and their views

File Module What it does
editor-pane.ts Editor pane CodeMirror and a live preview by default; uses Monaco when enabled and installed
flowview.ts FlowView The .flow view. It wraps the editor pane and adds the Format and Toggle preview actions. A .drawio.flow file opens the draw.io editor instead
edit-modal.ts Edit window The ✎ Edit window. Format, Save, and Close or Discard. Its editor is disposed when the window closes
file-dialog.ts Add-file dialog The dialog that adds a diagram file to a note. It has the tabs Use existing and Create new, and it rejects the characters \ / : * ? " < > | # ^ [ ]
language.ts Note support Diagnostics, hover help, quick fixes, and formatting for the flowmotion blocks in a note
drawio-pane.ts draw.io pane Hosts the draw.io editor. Creates a new file from an empty draw.io SVG
static-server.ts StaticServer Serves the installed draw.io add-on folder on loopback
monaco-loader.ts Loader Loads the installed Monaco AMD runtime on first use and tracks open editors
addons.ts Add-on spec Where draw.io comes from and which files to keep, plus the installed-file check
addon-installer.ts Installer Downloads and unpacks an add-on into the plugin folder, or deletes it
zip.ts Zip reader Reads the draw.war archive

The draw.io server

StaticServer listens on 127.0.0.1, on a random port. It answers GET requests only, and it never serves a file outside the installed draw.io folder. The plugin stops it on unload.

The plugin is desktop-only: the manifest sets isDesktopOnly to true. The draw.io server and the downloader use Node modules.

If draw.io is disabled, opening a drawing explains how to turn it on. If its files are missing, the pane says to turn the add-on off and on again to download it. Creating a new draw.io file also requires the toggle to be on.

Code-editor loading and fallback

The optional Monaco runtime is downloaded from npm and served locally over a loopback connection. The build appends Monaco's CSS to styles.css. The loader uses the same window throughout AMD initialization. On cleanup, FlowMotion disposes its own Monaco editors and models without touching other plugins' editors.

Without Rich Code Editor (Monaco), EditorPane uses CodeMirror with YAML highlighting, formatting, and the same live preview. Language support inside a note's flowmotion block is independent.

Note support

language.ts works on the source of a note. It uses findBlocks from src/schema/blocks.ts to find the flowmotion fences. Then it calls lintSource for diagnostics, docsAt for hover help, and completeAt for suggestions. The Format command uses formatSource. If there is nothing to change, it shows nothing to format.

Quick fixes come from the suggested replacement in each issue. See Schema and validation.

Building the plugin

The plugin is built by scripts/build.mjs into dist/plugin/main.js. The Obsidian API, Electron, and the Node modules are external, so they are not bundled. See Setup and build for the full list of outputs.

Testing in a vault

Unit tests cover plugin lifecycle and settings with a stub Obsidian API. Desktop E2E tests cover plugin loading, SVG rendering, settings controls, add-on notices, and persistence across restarts. See Testing and examples.

The E2E helper handles both inline Settings and newer separate Settings windows. Obsidian API calls run in the main window; UI queries run in the settings window. Continue checking untested editor and drawing workflows in a test vault.

Related pages

Clone this wiki locally