Extension Design Reference
This reference catalog records the kinds of extensions users commonly expect from a Markdown-first note application. It is informed by established Obsidian community-plugin patterns, but it is not a commitment to reproduce those plugins or their APIs. It guides future platform boundaries, data contracts, permission design, and roadmap choices; Release 1 ships no operational extension or plugin runtime.
Design rule
Design extension points around declared capabilities, stable data contracts, and explicit user grants. Mobile extensions should be limited integrations rather than arbitrary executable code. A later desktop app may offer more powerful automation, but only with a separate trust model and clear per-capability permissions.
1. Sync destinations and backup
Ecosystem examples
- Remotely Save: connects a file-based vault to S3-compatible storage, WebDAV, Dropbox, OneDrive, Google Drive, Box, and other services; it also exposes scheduling, encryption, and conflict-handling choices.
- Obsidian Git: treats a Git repository as a versioned backup/sync workflow, primarily on desktop.
Expected extension capabilities
- Authorize/deauthorize access and securely store credentials.
- Discover remote changes; fetch, conditionally write, and delete items.
- Declare remote history, tombstone, conflict-signal, stable-ID, and background-sync support.
- Report destination status, retries, user action needed, and storage/scope disclosure.
- Optionally provide backup-only or one-way export semantics.
Product implications
The app’s local revision history remains authoritative. When later implemented, file-style destinations—including the Android local-folder extension—can exchange current Markdown state but must never claim that they preserve application-managed history. Cloud providers need an additional security, conflict, and data-retention review before launch.
2. Templates and fast capture
Ecosystem examples
- QuickAdd: provides a single action for templated note creation, appending a capture to a known note, forms, multi-step macros, and optional scripts/AI.
- Templater: creates dynamic templates using variables and functions; it can execute arbitrary code, which makes it powerful but unsuitable as a direct mobile-plugin model.
- Calendar: creates and navigates daily/weekly notes based on an existing template convention.
Expected extension capabilities
- Register a template and request user inputs through a controlled form schema.
- Create a note in a notebook or append content to a user-selected/declared target.
- Resolve a safe built-in variable set: date/time, selected text, note metadata, clipboard with permission, and app deep links.
- Register commands or share-sheet capture actions with a clear name, icon, destination, and preview of the resulting formatted note; the app serializes Markdown internally.
Product implications
Provide these as built-in automation primitives first: templates, daily-note conventions, form fields, capture actions, and command registration. Do not initially expose arbitrary JavaScript, shell access, or unrestricted file writes. The extension API should compose approved actions rather than execute unreviewed scripts.
3. Structured views over notes and metadata
Ecosystem examples
- Dataview: queries Markdown front matter and inline fields to generate lists, tables, grouped results, and reports.
- Tasks: indexes Markdown task items across notes, supports recurring/due/completed states, and renders filtered task views that update source text.
- Calendar and Kanban: provide calendar, daily-note, and board views over note/task data.
Expected extension capabilities
- Read an indexed, permission-scoped projection of note metadata, tags, links, dates, and parsed task items.
- Register a view with declarative filters, grouping, sorting, and display configuration.
- Provide a structured query language or an app-owned query builder before exposing raw database access.
- Request narrowly defined mutations—for example, updating a task checkbox or a
statusmetadata field—through domain use cases that create revisions and sync events.
Product implications
Do not let a view plugin maintain an unsynchronized parallel database. The app should own indexing, execute queries locally, enforce notebook/content permissions, and ensure every plugin mutation passes through normal revision/history and sync behavior. Start with built-in search, task parsing, and basic list/calendar views; consider a public query/view API only once those contracts are stable.
4. Research, import, and external-library integrations
Ecosystem examples
- Zotero Integration: imports citations, bibliographies, notes, and PDF annotations.
- Zotero Sync: incrementally mirrors a Zotero library as Markdown for linking and search while keeping the source library read-only.
- ZotFlow: supports a deeper research workflow including reading/annotating and generating source notes.
Expected extension capabilities
- Connect to an external account, local service, share sheet, or imported file using a scoped user grant.
- Map external objects to a stable external ID and an app note ID.
- Import Markdown/content and attached metadata with a preview, target-notebook choice, and duplicate policy.
- Support one-way import, read-only mirror, or explicit two-way sync; require the extension to declare which model it uses.
- Expose provenance: source service, import time, original URI/identifier, and refresh behavior.
Product implications
Treat imports as revisions with a distinct reason and origin, so users can see where content came from and recover an earlier state. Preserve external IDs in app metadata/front matter only when portability requires it. Never allow an integration to overwrite a user-edited note without a visible conflict path.
5. Automation and system integrations
Ecosystem examples
- QuickAdd supports multi-step macros, external triggers, and optional scripts.
- Shell Commands runs user-configured system commands from Obsidian on supported desktop operating systems.
- Obsidian Git illustrates a desktop workflow that depends on local system tooling and is not available in the same way on mobile.
Expected extension capabilities
- Register deep links, application commands, widgets/shortcuts where the OS permits, and share-sheet entry points.
- Receive a narrowly scoped trigger payload such as selected text, URL, or audio/transcript result after explicit user approval.
- Compose permitted app actions: create note, append capture, assign notebook, set metadata, invoke an approved sync, or open a view.
- On desktop only, potentially call a reviewed local automation bridge with granular consent, visible command preview, audit log, timeout, and revocation.
Product implications
Keep an automation manifest separate from the sync adapter contract. A mobile implementation should support intent/deep-link/share-sheet automations without code execution. Desktop scripting, if ever introduced, is a high-risk capability and requires a dedicated permission model—not merely an extension installation toggle.
6. AI providers and local models
Ecosystem examples
- QuickAdd can optionally route prompts to OpenAI, Anthropic, Gemini, OpenAI-compatible providers, and local models as part of a user-created workflow.
- Many note workflows use AI for summaries, suggested tags, rewriting, extraction, and semantic retrieval rather than as a replacement for note ownership.
Expected extension capabilities
- Declare provider type, model, data sent, storage/logging policy, cost model, and whether processing is local or remote.
- Request selected text, current note, an explicitly chosen notebook subset, or local search results—never the entire library by default.
- Return a proposed change, new note, tags, summary, or retrieval results for user review.
- Support bring-your-own key through platform secure storage and allow the user to revoke/delete provider credentials.
Product implications
AI must be opt-in, transparent, and reviewable. The default interaction is a previewable proposal that becomes a normal local revision only after the user accepts it. Keep AI provider contracts separate from core sync so that an AI service cannot inherit permission to read all notes or access sync credentials.
Prioritization
| Priority | Extension surface | Reason |
|---|---|---|
| Release 1 | Documentation/types only for future sync and extension boundaries; no runtime, destination, or plugin | Preserves a path forward while keeping the initial release entirely local. |
| Future post-beta | Sync destination contract and Android local-folder implementation | Validates destination lifecycle and capability disclosure after the local core is proven. |
| Later | Templates, capture actions, daily notes, import/export hooks | High user value with a manageable, safe API surface. |
| After core metadata/index contracts stabilize | Structured query and view API; task/calendar/board views | Avoids freezing a fragile data/query model too early. |
| After cloud and permission work mature | External research integrations and AI providers | Both require robust credential, provenance, privacy, and conflict design. |
| Desktop-only future | Advanced automation and system-tool bridges | Powerful but requires a substantially stronger security/trust model. |