Obsidian

Obsidian

Overview

This skill provides comprehensive guidance for working with Obsidian, a powerful knowledge management and note-taking application. It covers vault structure, the Obsidian API for plugin development, URI scheme automation, markdown extensions, and integration with external tools via the Local REST API.

Quick Reference

Vault Structure

my-vault/
├── .obsidian/              # Configuration folder
│   ├── app.json            # App settings
│   ├── appearance.json     # Theme settings
│   ├── community-plugins.json  # Installed plugins list
│   ├── core-plugins.json   # Core plugin toggles
│   ├── hotkeys.json        # Custom keybindings
│   ├── plugins/            # Plugin data folders
│   │   └── <plugin-id>/
│   │       ├── main.js     # Compiled plugin code
│   │       ├── manifest.json
│   │       └── data.json   # Plugin settings
│   └── workspace.json      # Layout state
├── Notes/                  # User notes (any structure)
├── Attachments/            # Images, PDFs, etc.
└── Templates/              # Template files

Obsidian URI Scheme

Native Obsidian supports obsidian:// protocol for automation:

# Open a vault
obsidian://open?vault=MyVault

# Open a specific file
obsidian://open?vault=MyVault&file=Notes/MyNote

# Create a new note
obsidian://new?vault=MyVault&name=NewNote&content=Hello

# Search the vault
obsidian://search?vault=MyVault&query=keyword

# Open daily note
obsidian://daily?vault=MyVault

URI Parameters

Workflow Decision Tree

What do you need to do?
├── Automate Obsidian from external tools?
│   ├── Simple open/create operations?
│   │   └── Use: Native obsidian:// URI scheme
│   ├── Complex automation (append, prepend, commands)?
│   │   └── Use: Advanced URI plugin
│   └── Full programmatic access?
│       └── Use: Local REST API plugin
├── Build a plugin for Obsidian?
│   └── See: Plugin Development section
├── Work with vault files directly?
│   └── Use: obsidian-cli or direct file operations
├── Extend markdown syntax?
│   └── See: Markdown Extensions section
└── Query notes and metadata?
    └── Use: Local REST API or Dataview plugin

Plugin Development

Plugin Structure

my-plugin/
├── main.ts           # Plugin entry point
├── manifest.json     # Plugin metadata
├── package.json      # npm dependencies
├── styles.css        # Optional styles
├── tsconfig.json     # TypeScript config
└── esbuild.config.mjs # Build config

manifest.json

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "minAppVersion": "1.0.0",
  "description": "A sample plugin for Obsidian",
  "author": "Your Name",
  "authorUrl": "https://github.com/username",
  "isDesktopOnly": false
}

Basic Plugin Template

import { Plugin, Notice, MarkdownView } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    console.log('Loading plugin');

    // Register a command
    this.addCommand({
      id: 'my-command',
      name: 'My Command',
      callback: () => {
        new Notice('Hello from my plugin!');
      }
    });

    // Register editor command
    this.addCommand({
      id: 'my-editor-command',
      name: 'Insert Text',
      editorCallback: (editor, view: MarkdownView) => {
        editor.replaceSelection('Inserted text');
      }
    });

    // Register event listener
    this.registerEvent(
      this.app.workspace.on('file-open', (file) => {
        if (file) {
          console.log('Opened:', file.path);
        }
      })
    );
  }

  onunload() {
    console.log('Unloading plugin');
  }
}

Core API Classes

Plugin Lifecycle

// onload() - Called when plugin is enabled
async onload() {
  // Initialize UI components
  // Register event handlers
  // Set up commands
  // Load settings
}

// onunload() - Called when plugin is disabled
onunload() {
  // Cleanup is mostly automatic
  // Custom cleanup for external resources
}

Local REST API

The Local REST API plugin provides HTTP endpoints to interact with Obsidian programmatically.

Installation

1. Install "Local REST API" from Community Plugins 2. Enable the plugin 3. Configure API key in settings 4. Default endpoint: https://127.0.0.1:27124

Authentication

# Using API key header
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://127.0.0.1:27124/vault/

Common Endpoints

# List all files
GET /vault/

# Get file content
GET /vault/{path-to-file}

# Create/Update file
PUT /vault/{path-to-file}
Content-Type: text/markdown
Body: File content here

# Delete file
DELETE /vault/{path-to-file}

# Search vault
POST /search/simple/
Content-Type: application/json
Body: {"query": "search term"}

# Execute command
POST /commands/{command-id}

# Get active file
GET /active/

# Open file in Obsidian
POST /open/{path-to-file}

Python Example

import requests

class ObsidianAPI:
    def __init__(self, api_key, base_url="https://127.0.0.1:27124"):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
        self.session = requests.Session()
        self.session.verify = False  # Self-signed cert

    def list_files(self, path=""):
        response = self.session.get(
            f"{self.base_url}/vault/{path}",
            headers=self.headers
        )
        return response.json()

    def read_file(self, path):
        response = self.session.get(
            f"{self.base_url}/vault/{path}",
            headers=self.headers
        )
        return response.text

    def write_file(self, path, content):
        response = self.session.put(
            f"{self.base_url}/vault/{path}",
            headers={**self.headers, "Content-Type": "text/markdown"},
            data=content.encode('utf-8')
        )
        return response.status_code == 204

    def search(self, query):
        response = self.session.post(
            f"{self.base_url}/search/simple/",
            headers=self.headers,
            json={"query": query}
        )
        return response.json()

Markdown Extensions

Obsidian extends standard Markdown with special syntax:

Internal Links (Wikilinks)

[[Note Name]]                    # Link to note
[[Note Name|Display Text]]       # Link with alias
[[Note Name#Heading]]            # Link to heading
[[Note Name#^block-id]]          # Link to block
[[Note Name#^block-id|alias]]    # Block link with alias

Embeds (Transclusion)

![[Note Name]]                   # Embed entire note
![[Note Name#Heading]]           # Embed section
![[Note Name#^block-id]]         # Embed block
![[image.png]]                   # Embed image
![[image.png|300]]               # Embed with width
![[image.png|300x200]]           # Embed with dimensions
![[audio.mp3]]                   # Embed audio
![[video.mp4]]                   # Embed video
![[document.pdf]]                # Embed PDF

Callouts

> [!note] Title
> Content here

> [!warning] Caution
> Important warning message

> [!tip]+ Expandable (default open)
> Click to collapse

> [!info]- Collapsed (default closed)
> Click to expand

# Available types:
# note, abstract, summary, tldr, info, todo, tip, hint,
# important, success, check, done, question, help, faq,
# warning, caution, attention, failure, fail, missing,
# danger, error, bug, example, quote, cite

Block References

This is a paragraph. ^block-id

# Reference this block from another note:
[[Note#^block-id]]

Tags

#tag
#nested/tag
#tag-with-dashes

Frontmatter (YAML)

---
title: My Note
date: 2024-01-15
tags:
  - tag1
  - tag2
aliases:
  - alternate name
cssclass: custom-class
---

# Note content starts here

Comments

%%This is a comment that won't render%%

%%
Multi-line
comment
%%

Math (LaTeX)

Inline: $E = mc^2$

Block:
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Mermaid Diagrams

````markdown

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

````

CLI Tools

obsidian-cli (Yakitrak)

# Install
go install github.com/Yakitrak/obsidian-cli@latest

# Commands
obsidian-cli open "Note Name"         # Open note
obsidian-cli search "query"           # Fuzzy search
obsidian-cli create "New Note"        # Create note
obsidian-cli daily                    # Open daily note
obsidian-cli list                     # List notes

obsidian-cli (Python)

# Install
pip install obsidian-cli

# Commands
obs vault list                        # List vaults
obs vault create <name>               # Create vault
obs note search <query>               # Search notes
obs settings export                   # Export settings

Best Practices

1. Use separate dev vault: Never develop plugins in your main vault 2. Hot reload plugin: Install for faster development iteration 3. Use registerEvent(): Ensures proper cleanup on unload 4. Prefer UIDs over paths: File paths can change; use unique identifiers 5. Handle async properly: Use await for vault operations 6. Test with Obsidian sandbox: Use BRAT plugin for beta testing 7. Follow manifest conventions: Keep id matching folder name 8. Version carefully: Update versions.json for compatibility

Troubleshooting

Plugin Not Loading

# Check console for errors
Ctrl+Shift+I (or Cmd+Option+I on Mac)

# Verify manifest.json is valid JSON
jq . manifest.json

# Check minAppVersion compatibility
# Ensure main.js exists in plugin folder

URI Not Working

# URL encode special characters
# Spaces: %20
# Slashes: %2F
# Ampersands: %26

# Test with simple vault name first
obsidian://open?vault=test

REST API Connection Failed

# Verify plugin is enabled
# Check API key is correct
# Confirm HTTPS and self-signed cert handling
# Default port: 27124

Resources

References

• references/uri-scheme.md - Complete URI scheme documentation
• references/plugin-development.md - Plugin development guide
• references/vault-structure.md - Vault and config structure
• references/markdown-extensions.md - Obsidian markdown syntax
• references/api-reference.md - TypeScript API reference

Scripts

• scripts/obsidian-vault.sh - Vault management utilities
• scripts/obsidian-api.py - Local REST API Python client

External Documentation

• Obsidian Developer Documentation
• Obsidian API Types
• Sample Plugin Template
• Local REST API Plugin
• Advanced URI Plugin
• Obsidian Help

---

Absorbed sub-skill (post-consolidation)

This skill now subsumes the former obsidian-master skill (the "unified orchestration" umbrella). Its content is preserved as deep reference:

The former obsidian-second-brain skill has been renamed to `obsidian-claude-integration` to reflect what it actually is: integration patterns for Claude Code + Obsidian, not a generic "second brain" concept.

Narrow siblings still apply:

• `obsidian-markdown` — syntax only (wikilinks, embeds, callouts, frontmatter, tags, LaTeX, Mermaid).
• `obsidian-bases` — Bases (.base YAML, table views, filters, formulas) only.
• `obsidian-nvim` — the obsidian.nvim Neovim plugin only.
• `obsidian-vault-management` — CRUD on vault contents (notes, templates, Dataview).
• `obsidian-claude-integration` — Claude Code ↔ Obsidian integration patterns.

---

Gotchas

• Wikilink `[[Note]]` resolution picks the first alphabetical match in the vault when duplicates exist — silently. Two notes named "Index" in different folders create an invisible ambiguity.
• `obsidian://` URI scheme requires the vault to be open in the desktop app — headless contexts (CI, Claude Code without Obsidian running) silently no-op.
• Local REST API plugin must be enabled separately from the API key — default port 27124, but the plugin must be running for any HTTP request to land.
• Markdown footnotes (`[^1]`) require a blank line before the definition — without the blank line, Obsidian renders them as plain text, no error.
• Vault path with spaces/special chars: most plugins handle it; some shell-integration plugins don't. Test scripted invocations explicitly.

Obsidian TypeScript API Reference

Complete reference for the Obsidian plugin API classes and interfaces.

Core Classes

App

Central application instance providing access to all subsystems.

interface App {
  // Core subsystems
  keymap: Keymap;
  scope: Scope;
  workspace: Workspace;
  vault: Vault;
  metadataCache: MetadataCache;
  fileManager: FileManager;

  // UI managers
  commands: Commands;

  // Methods
  loadLocalStorage(key: string): string | null;
  saveLocalStorage(key: string, value: string | undefined): void;
}

// Access in plugin
const app = this.app;
const vault = this.app.vault;
const workspace = this.app.workspace;

Vault

File system operations and event handling.

interface Vault extends Events {
  // Properties
  configDir: string;              // Usually ".obsidian"
  adapter: DataAdapter;           // Low-level file access

  // File retrieval
  getAbstractFileByPath(path: string): TAbstractFile | null;
  getMarkdownFiles(): TFile[];
  getAllLoadedFiles(): TAbstractFile[];
  getFiles(): TFile[];

  // File operations
  create(path: string, data: string): Promise<TFile>;
  createBinary(path: string, data: ArrayBuffer): Promise<TFile>;
  createFolder(path: string): Promise<void>;
  read(file: TFile): Promise<string>;
  readBinary(file: TFile): Promise<ArrayBuffer>;
  cachedRead(file: TFile): Promise<string>;
  modify(file: TFile, data: string): Promise<void>;
  modifyBinary(file: TFile, data: ArrayBuffer): Promise<void>;
  delete(file: TAbstractFile, force?: boolean): Promise<void>;
  trash(file: TAbstractFile, system: boolean): Promise<void>;
  rename(file: TAbstractFile, newPath: string): Promise<void>;
  copy(file: TFile, newPath: string): Promise<TFile>;

  // Events
  on(name: 'create', callback: (file: TAbstractFile) => any): EventRef;
  on(name: 'modify', callback: (file: TAbstractFile) => any): EventRef;
  on(name: 'delete', callback: (file: TAbstractFile) => any): EventRef;
  on(name: 'rename', callback: (file: TAbstractFile, oldPath: string) => any): EventRef;
}

Workspace

Layout and pane management.

interface Workspace extends Events {
  // Properties
  leftSplit: WorkspaceSidedock;
  rightSplit: WorkspaceSidedock;
  leftRibbon: WorkspaceRibbon;
  rightRibbon: WorkspaceRibbon;
  activeLeaf: WorkspaceLeaf | null;

  // Leaf operations
  getLeaf(newLeaf?: boolean | PaneType): WorkspaceLeaf;
  getActiveViewOfType<T extends View>(type: Constructor<T>): T | null;
  getLeavesOfType(viewType: string): WorkspaceLeaf[];
  getLeftLeaf(split: boolean): WorkspaceLeaf;
  getRightLeaf(split: boolean): WorkspaceLeaf;
  splitActiveLeaf(direction?: SplitDirection): WorkspaceLeaf;
  createLeafInParent(parent: WorkspaceSplit, index: number): WorkspaceLeaf;

  // File operations
  openLinkText(linktext: string, sourcePath: string, newLeaf?: boolean): Promise<void>;
  getActiveFile(): TFile | null;
  activeEditor: MarkdownEditView | null;

  // Layout
  changeLayout(workspace: any): Promise<void>;
  getLayout(): any;
  requestSaveLayout(): void;

  // Events
  on(name: 'file-open',
     callback: (file: TFile | null) => any): EventRef;
  on(name: 'active-leaf-change',
     callback: (leaf: WorkspaceLeaf | null) => any): EventRef;
  on(name: 'layout-change', callback: () => any): EventRef;
  on(name: 'editor-change',
     callback: (editor: Editor, info: MarkdownView) => any): EventRef;
  on(name: 'resize', callback: () => any): EventRef;
  on(name: 'quit', callback: (tasks: Tasks) => any): EventRef;
}

MetadataCache

Parsed file metadata and link resolution.

interface MetadataCache extends Events {
  // Get metadata
  getFileCache(file: TFile): CachedMetadata | null;
  getCache(path: string): CachedMetadata | null;
  getFirstLinkpathDest(linkpath: string, sourcePath: string): TFile | null;

  // Link resolution
  resolvedLinks: Record<string, Record<string, number>>;
  unresolvedLinks: Record<string, Record<string, number>>;

  // Events
  on(name: 'changed',
     callback: (file: TFile, data: string, cache: CachedMetadata) => any
  ): EventRef;
  on(name: 'deleted',
     callback: (file: TFile, prevCache: CachedMetadata | null) => any
  ): EventRef;
  on(name: 'resolved', callback: () => any): EventRef;
}

interface CachedMetadata {
  links?: LinkCache[];
  embeds?: EmbedCache[];
  tags?: TagCache[];
  headings?: HeadingCache[];
  sections?: SectionCache[];
  listItems?: ListItemCache[];
  frontmatter?: FrontMatterCache;
  frontmatterPosition?: Pos;
  frontmatterLinks?: FrontmatterLinkCache[];
  blocks?: Record<string, BlockCache>;
}

interface LinkCache extends ReferenceCache {
  link: string;
  original: string;
}

interface HeadingCache extends CacheItem {
  heading: string;
  level: number;
}

interface TagCache extends CacheItem {
  tag: string;
}

FileManager

User-safe file operations with prompts.

interface FileManager {
  // File operations
  createNewMarkdownFile(
    folder: TFolder,
    name: string,
    content?: string
  ): Promise<TFile>;

  renameFile(file: TAbstractFile, newPath: string): Promise<void>;

  // Frontmatter
  processFrontMatter(
    file: TFile,
    fn: (frontmatter: any) => void
  ): Promise<void>;

  // Links
  generateMarkdownLink(
    file: TFile,
    sourcePath: string,
    subpath?: string,
    alias?: string
  ): string;
}

File Abstractions

TAbstractFile

Base class for files and folders.

abstract class TAbstractFile {
  vault: Vault;
  path: string;
  name: string;
  parent: TFolder | null;
}

TFile

Represents a file.

class TFile extends TAbstractFile {
  stat: FileStats;
  basename: string;              // Name without extension
  extension: string;             // File extension
}

interface FileStats {
  ctime: number;                 // Created time
  mtime: number;                 // Modified time
  size: number;                  // Size in bytes
}

TFolder

Represents a folder.

class TFolder extends TAbstractFile {
  children: TAbstractFile[];

  isRoot(): boolean;
}

Editor

Editor Interface

Abstract editor operations (CodeMirror-agnostic).

interface Editor {
  // Content
  getValue(): string;
  setValue(content: string): void;
  getLine(line: number): string;
  setLine(line: number, text: string): void;
  lineCount(): number;

  // Selection
  getSelection(): string;
  setSelection(anchor: EditorPosition, head?: EditorPosition): void;
  somethingSelected(): boolean;
  replaceSelection(replacement: string, origin?: string): void;
  replaceRange(
    replacement: string,
    from: EditorPosition,
    to?: EditorPosition,
    origin?: string
  ): void;

  // Cursor
  getCursor(string?: 'from' | 'to' | 'head' | 'anchor'): EditorPosition;
  setCursor(pos: EditorPosition | number, ch?: number): void;
  offsetToPos(offset: number): EditorPosition;
  posToOffset(pos: EditorPosition): number;

  // Scroll
  scrollTo(x?: number | null, y?: number | null): void;
  scrollIntoView(range: EditorRange, center?: boolean): void;

  // Transactions
  transaction(tx: EditorTransaction): void;

  // Focus
  focus(): void;
  blur(): void;
  hasFocus(): boolean;

  // Undo
  undo(): void;
  redo(): void;

  // Word at position
  wordAt(pos: EditorPosition): EditorRange | null;

  // Exec command
  exec(command: EditorCommandName): void;
}

interface EditorPosition {
  line: number;
  ch: number;
}

interface EditorRange {
  from: EditorPosition;
  to: EditorPosition;
}

Views

View

Base class for all views.

abstract class View extends Component {
  app: App;
  icon: IconName;
  navigation: boolean;
  leaf: WorkspaceLeaf;
  containerEl: HTMLElement;

  abstract getViewType(): string;
  abstract getDisplayText(): string;
  abstract getIcon(): IconName;

  onOpen(): Promise<void>;
  onClose(): Promise<void>;

  getState(): any;
  setState(state: any, result: ViewStateResult): Promise<void>;
}

ItemView

Base for custom views.

abstract class ItemView extends View {
  contentEl: HTMLElement;

  addAction(
    icon: IconName,
    title: string,
    callback: (evt: MouseEvent) => any
  ): HTMLElement;

  onHeaderMenu(menu: Menu): void;
}

MarkdownView

Markdown file view.

class MarkdownView extends TextFileView {
  editor: Editor;
  previewMode: MarkdownPreviewView;

  getMode(): 'source' | 'preview' | 'live';
  getViewType(): 'markdown';

  showSearch(replace?: boolean): void;
}

WorkspaceLeaf

Container for views.

class WorkspaceLeaf extends Component {
  view: View;
  parent: WorkspaceSplit;

  // Navigation
  openFile(file: TFile, openState?: OpenViewState): Promise<void>;
  open(view: View): Promise<View>;

  // State
  getViewState(): ViewState;
  setViewState(viewState: ViewState, eState?: any): Promise<void>;

  // Layout
  detach(): void;
  setGroupMember(other: WorkspaceLeaf): void;
  setGroup(group: string): void;

  // Tab
  getDisplayText(): string;
  getIcon(): IconName;

  // History
  getHistoryState(): any;
  setHistoryState(state: any): void;

  // Pin
  setPinned(pinned: boolean): void;
  togglePinned(): void;
}

UI Components

Modal

Dialog base class.

abstract class Modal {
  app: App;
  scope: Scope;
  containerEl: HTMLElement;
  modalEl: HTMLElement;
  titleEl: HTMLElement;
  contentEl: HTMLElement;

  open(): void;
  close(): void;

  onOpen(): void;
  onClose(): void;
}

SuggestModal

Modal with search suggestions.

abstract class SuggestModal<T> extends Modal {
  inputEl: HTMLInputElement;
  resultContainerEl: HTMLElement;
  emptyStateText: string;
  limit: number;

  abstract getSuggestions(query: string): T[] | Promise<T[]>;
  abstract renderSuggestion(item: T, el: HTMLElement): void;
  abstract onChooseSuggestion(item: T, evt: MouseEvent | KeyboardEvent): void;

  selectSuggestion(value: T, evt: MouseEvent | KeyboardEvent): void;
}

FuzzySuggestModal

Modal with fuzzy search.

abstract class FuzzySuggestModal<T> extends SuggestModal<FuzzyMatch<T>> {
  abstract getItems(): T[];
  abstract getItemText(item: T): string;
  abstract onChooseItem(item: T, evt: MouseEvent | KeyboardEvent): void;
}

Setting

Settings UI builder.

class Setting {
  settingEl: HTMLElement;
  infoEl: HTMLElement;
  nameEl: HTMLElement;
  descEl: HTMLElement;
  controlEl: HTMLElement;

  constructor(containerEl: HTMLElement);

  setName(name: string | DocumentFragment): this;
  setDesc(desc: string | DocumentFragment): this;
  setClass(cls: string): this;
  setTooltip(tooltip: string, options?: TooltipOptions): this;
  setHeading(): this;
  setDisabled(disabled: boolean): this;

  // Controls
  addButton(cb: (component: ButtonComponent) => any): this;
  addExtraButton(cb: (component: ExtraButtonComponent) => any): this;
  addToggle(cb: (component: ToggleComponent) => any): this;
  addText(cb: (component: TextComponent) => any): this;
  addTextArea(cb: (component: TextAreaComponent) => any): this;
  addMomentFormat(cb: (component: MomentFormatComponent) => any): this;
  addDropdown(cb: (component: DropdownComponent) => any): this;
  addSlider(cb: (component: SliderComponent) => any): this;
  addSearch(cb: (component: SearchComponent) => any): this;
  addColorPicker(cb: (component: ColorComponent) => any): this;
}

Menu

Context menu builder.

class Menu extends Component {
  addItem(cb: (item: MenuItem) => any): this;
  addSeparator(): this;
  showAtMouseEvent(event: MouseEvent): this;
  showAtPosition(position: MenuPositionDef, doc?: Document): this;
  hide(): this;
  onHide(callback: () => any): void;
}

class MenuItem {
  setTitle(title: string | DocumentFragment): this;
  setIcon(icon: IconName | null): this;
  setChecked(checked: boolean | null): this;
  setDisabled(disabled: boolean): this;
  setSection(section: string): this;
  setIsLabel(isLabel: boolean): this;
  onClick(callback: (evt: MouseEvent | KeyboardEvent) => any): this;
  setSubmenu(): Menu;
}

Component Lifecycle

Component

Base class with lifecycle management.

class Component {
  load(): void;
  onload(): void;

  unload(): void;
  onunload(): void;

  // Child components
  addChild<T extends Component>(component: T): T;
  removeChild<T extends Component>(component: T): T;

  // Event registration
  registerEvent(eventRef: EventRef): void;

  // Interval/timeout
  registerInterval(id: number): number;

  // DOM events
  registerDomEvent<K extends keyof WindowEventMap>(
    el: Window,
    type: K,
    callback: (this: HTMLElement, ev: WindowEventMap[K]) => any,
    options?: boolean | AddEventListenerOptions
  ): void;

  registerDomEvent<K extends keyof DocumentEventMap>(
    el: Document,
    type: K,
    callback: (this: HTMLElement, ev: DocumentEventMap[K]) => any,
    options?: boolean | AddEventListenerOptions
  ): void;

  registerDomEvent<K extends keyof HTMLElementEventMap>(
    el: HTMLElement,
    type: K,
    callback: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any,
    options?: boolean | AddEventListenerOptions
  ): void;

  // Cleanup callback
  register(cb: () => any): void;
}

Plugin

Plugin base class.

abstract class Plugin extends Component {
  app: App;
  manifest: PluginManifest;

  // Data persistence
  loadData(): Promise<any>;
  saveData(data: any): Promise<void>;

  // Commands
  addCommand(command: Command): Command;

  // Ribbon
  addRibbonIcon(
    icon: IconName, title: string,
    callback: (evt: MouseEvent) => any
  ): HTMLElement;

  // Status bar
  addStatusBarItem(): HTMLElement;

  // Settings tab
  addSettingTab(settingTab: PluginSettingTab): void;

  // Views
  registerView(type: string, viewCreator: ViewCreator): void;

  // Extensions
  registerExtensions(extensions: string[], viewType: string): void;

  // Markdown processors
  registerMarkdownPostProcessor(
    postProcessor: MarkdownPostProcessor,
    sortOrder?: number
  ): MarkdownPostProcessor;

  registerMarkdownCodeBlockProcessor(
    language: string,
    handler: (
      source: string, el: HTMLElement,
      ctx: MarkdownPostProcessorContext
    ) => Promise<any> | void,
    sortOrder?: number
  ): MarkdownPostProcessor;

  // Events
  registerObsidianProtocolHandler(
    action: string,
    handler: ObsidianProtocolHandler
  ): void;

  registerEditorExtension(extension: Extension): void;

  registerEditorSuggest(editorSuggest: EditorSuggest<any>): void;

  registerHoverLinkSource(id: string, info: HoverLinkSource): void;
}

Command Interface

interface Command {
  id: string;
  name: string;
  icon?: IconName;

  // Callbacks (use one)
  callback?: () => any;
  checkCallback?: (checking: boolean) => boolean | void;
  editorCallback?: (
    editor: Editor, ctx: MarkdownView | MarkdownFileInfo
  ) => any;
  editorCheckCallback?: (
    checking: boolean, editor: Editor,
    ctx: MarkdownView | MarkdownFileInfo
  ) => boolean | void;

  // Hotkeys
  hotkeys?: Hotkey[];

  // Flags
  mobileOnly?: boolean;
  repeatable?: boolean;
}

interface Hotkey {
  modifiers: Modifier[];  // 'Mod' | 'Ctrl' | 'Meta' | 'Shift' | 'Alt'
  key: string;
}

Utility Functions

Notice

Display notifications.

class Notice {
  constructor(message: string | DocumentFragment, timeout?: number);
  setMessage(message: string | DocumentFragment): this;
  hide(): void;
}

// Usage
new Notice('Operation complete!');
new Notice('Error occurred', 5000);  // 5 second timeout

requestUrl

HTTP requests.

function requestUrl(request: RequestUrlParam | string): Promise<RequestUrlResponse>;

interface RequestUrlParam {
  url: string;
  method?: string;
  contentType?: string;
  body?: string | ArrayBuffer;
  headers?: Record<string, string>;
}

interface RequestUrlResponse {
  status: number;
  headers: Record<string, string>;
  arrayBuffer: ArrayBuffer;
  json: any;
  text: string;
}

debounce

Debounce function calls.

function debounce<T extends unknown[]>(
  cb: (...args: T) => any,
  timeout?: number,
  resetTimer?: boolean
): (...args: T) => void;

// Usage
const debouncedSave = debounce(saveData, 300);

normalizePath

Normalize file paths.

function normalizePath(path: string): string;

// Usage
const path = normalizePath('folder//file.md');
// Returns: 'folder/file.md'

moment

Date/time handling (bundled with Obsidian).

// Access global moment
declare const moment: typeof import('moment');

// Usage
const now = moment();
const formatted = moment().format('YYYY-MM-DD');

Type Definitions

Icons

type IconName =
  | 'lucide-file'
  | 'lucide-folder'
  | 'lucide-search'
  | 'lucide-settings'
  | 'lucide-star'
  // ... many more Lucide icons
  ;

Events

interface Events {
  on(name: string, callback: (...data: any) => any, ctx?: any): EventRef;
  off(name: string, callback: (...data: any) => any): void;
  offref(ref: EventRef): void;
  trigger(name: string, ...data: any[]): void;
  tryTrigger(evt: EventRef, args: any[]): void;
}

Common Patterns

Getting Active File

const activeFile = this.app.workspace.getActiveFile();
if (activeFile) {
  const content = await this.app.vault.read(activeFile);
}

Getting Active Editor

const view = this.app.workspace.getActiveViewOfType(MarkdownView);
if (view) {
  const editor = view.editor;
  const selection = editor.getSelection();
}

Processing All Files

for (const file of this.app.vault.getMarkdownFiles()) {
  const cache = this.app.metadataCache.getFileCache(file);
  if (cache?.frontmatter?.status === 'active') {
    // Process file
  }
}

Registering Events Safely

// Always use registerEvent for automatic cleanup
this.registerEvent(
  this.app.workspace.on('file-open', (file) => {
    // Handler
  })
);

Creating Modals

const modal = new MyModal(this.app, (result) => {
  console.log('User submitted:', result);
});
modal.open();

Obsidian Markdown Extensions Reference

Complete reference for Obsidian's markdown syntax beyond standard CommonMark.

Internal Links (Wikilinks)

Basic Links

[[Note Name]]                       # Link to note
[[Note Name|Display Text]]          # Link with alias
[[Folder/Note Name]]                # Link to note in folder
[[Note Name.md]]                    # Explicit extension

Heading Links

[[Note Name#Heading]]               # Link to heading
[[Note Name#Heading|text]]          # Heading link with alias
[[#Heading]]                        # Link to heading in current note

Block Links

[[Note Name#^block-id]]             # Link to specific block
[[Note Name#^block-id|text]]        # Block link with alias
[[#^block-id]]                      # Block in current note

Creating Block IDs

This is a paragraph that I want to reference. ^my-block-id

- List item ^list-block

> Quote block ^quote-block

Embeds (Transclusion)

Note Embeds

![[Note Name]]                      # Embed entire note
![[Note Name#Heading]]              # Embed section under heading
![[Note Name#^block-id]]            # Embed specific block

Image Embeds

![[image.png]]                      # Basic embed
![[image.png|100]]                  # Width in pixels
![[image.png|100x200]]              # Width x Height
![[image.png|alt text]]             # Alt text (with pipe)
![[Attachments/photo.jpg]]          # From subfolder

Other File Embeds

![[document.pdf]]                   # Embed PDF
![[document.pdf#page=5]]            # Embed PDF at page
![[audio.mp3]]                      # Embed audio player
![[video.mp4]]                      # Embed video player
![[file.csv]]                       # Embed CSV as table

External Embeds

![](https://example.com/image.png)  # External image
![|300](https://example.com/i.png)  # External with width

# YouTube (auto-detected)
![](https://www.youtube.com/watch?v=VIDEO_ID)
![](https://youtu.be/VIDEO_ID)

# Twitter/X
![](https://twitter.com/user/status/ID)

Callouts

Basic Syntax

> [!note]
> This is a note callout.

> [!info] Title Here
> Content with **formatting**.

> [!warning]
> Warning message.

Foldable Callouts

> [!tip]+ Expanded by Default
> This content is visible initially.

> [!example]- Collapsed by Default
> Click to expand this content.

Callout Types

Custom Callout Icons

Via CSS snippet:

.callout[data-callout="custom-type"] {
  --callout-color: 100, 150, 200;
  --callout-icon: lucide-sparkles;
}

Nested Callouts

> [!note] Outer
> Outer content
> > [!warning] Inner
> > Nested callout

Tags

Basic Tags

#tag                                # Simple tag
#nested/tag                         # Nested/hierarchical tag
#tag-with-dashes                    # Dashes allowed
#tag_with_underscores               # Underscores allowed
#123                                # Numeric tags allowed

Tag Restrictions

• Cannot contain spaces
• Cannot start with a number
• Case-insensitive matching
• Must follow word boundary

Inline vs Frontmatter Tags

---
tags:
  - tag1
  - tag2
  - nested/tag
---

This note has #inline-tag too.

Frontmatter (YAML)

Basic Frontmatter

---
title: My Note Title
date: 2024-01-15
author: Your Name
---

# Content starts here

Common Properties

---
# Standard properties
title: Note Title
date: 2024-01-15
created: 2024-01-01
modified: 2024-01-15

# Tags and categories
tags:
  - tag1
  - tag2
category: Category Name

# Aliases for linking
aliases:
  - Alternate Name
  - Another Alias

# Custom CSS class
cssclass: my-custom-class
cssclasses:
  - class1
  - class2

# Publishing
publish: true
permalink: custom-url

# Custom properties
status: draft
priority: high
rating: 5
---

Property Types

---
# String
title: "String Value"

# Number
count: 42
rating: 4.5

# Boolean
published: true
draft: false

# Date
date: 2024-01-15
datetime: 2024-01-15T10:30:00

# List
tags:
  - item1
  - item2

# Inline list
tags: [item1, item2, item3]

# Object/Map
metadata:
  key1: value1
  key2: value2

# Multi-line string
description: |
  This is a multi-line
  string value.
---

Comments

Inline Comments

This is visible. %%This is hidden.%%

More visible text.

Block Comments

%%
This entire block
is hidden from
the rendered view.
%%

Math (LaTeX)

Inline Math

The equation $E = mc^2$ is famous.

Inline: $\sum_{i=1}^{n} x_i$

Block Math

$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

$$
\begin{aligned}
a &= b + c \\
d &= e + f
\end{aligned}
$$

Common LaTeX Symbols

Greek: $\alpha, \beta, \gamma, \delta$
Operators: $\sum, \prod, \int$
Relations: $\leq, \geq, \neq, \approx$
Arrows: $\to, \leftarrow, \Rightarrow$
Sets: $\in, \notin, \subset, \cup, \cap$

Code Blocks

Fenced Code

````markdown

const hello = "world";
console.log(hello);

````

Syntax Highlighting

Supported languages include:

• javascript, js
• typescript, ts
• python, py
• bash, shell, sh
• json, yaml
• css, html
• sql
• markdown, md
• And many more...

Line Numbers (Plugin)

Some themes/plugins support:

```markdown ``javascript {1,3-5} // Highlighted lines const a = 1; const b = 2; const c = 3;

Diagrams (Mermaid)

Flowchart

````markdown

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

````

Sequence Diagram

````markdown

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B-->>A: Hi Alice!

````

Class Diagram

````markdown

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()

````

Gantt Chart

````markdown

gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Phase 1
    Task 1: 2024-01-01, 7d
    Task 2: 2024-01-08, 5d

````

State Diagram

````markdown

stateDiagram-v2
    [*] --> Draft
    Draft --> Review
    Review --> Published
    Review --> Draft
    Published --> [*]

````

Tables

Basic Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Alignment

| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| Left     | Center   | Right    |

Extended Features

| With Links | With Formatting |
|------------|-----------------|
| [[Link]]   | **bold** text   |
| `code`     | *italic* text   |

Task Lists

Basic Tasks

- [ ] Uncompleted task
- [x] Completed task
- [ ] Another task

Nested Tasks

- [ ] Parent task
  - [ ] Subtask 1
  - [x] Subtask 2 (done)
  - [ ] Subtask 3

Custom Status (Plugins)

Some plugins support extended status:

- [ ] Todo
- [x] Done
- [/] In Progress
- [-] Cancelled
- [>] Forwarded
- [<] Scheduled
- [?] Question
- [!] Important

Footnotes

Inline Footnotes

Here is a statement[^1] with a footnote.

[^1]: This is the footnote content.

Multi-line Footnotes

Complex footnote[^note].

[^note]: This footnote has multiple paragraphs.

    Second paragraph of the footnote.

    Even code blocks work:

code here

Highlights

==Highlighted text== using double equals.

Strikethrough

~~Strikethrough text~~

Horizontal Rules

---
***
___

External Links

Basic

[Link Text](https://example.com)
[Link with Title](https://example.com "Title")

Auto-linking

https://example.com          # Auto-linked
<https://example.com>        # Explicit auto-link
<email@example.com>          # Email link

Dataview (Plugin)

Inline Queries

`= this.file.name`
`= date(today)`
`= this.tags`

List Query

````markdown

LIST
FROM #tag
WHERE file.mtime > date(today) - dur(7 days)
SORT file.mtime DESC

````

Table Query

````markdown

TABLE file.ctime AS "Created", status
FROM "Projects"
WHERE status != "archived"
SORT file.ctime DESC

````

Task Query

````markdown

TASK
FROM "Daily Notes"
WHERE !completed
GROUP BY file.link

````

Templater (Plugin)

Basic Template

<%*
const title = await tp.system.prompt("Title?");
-%>
# <% title %>

Created: <% tp.date.now("YYYY-MM-DD") %>

Common Functions

<% tp.date.now("YYYY-MM-DD") %>
<% tp.file.title %>
<% tp.file.path() %>
<% tp.file.cursor() %>
<% tp.system.clipboard() %>

Query Blocks (Core)

Embed Search Results

````markdown

tag:#important

path:Projects

````

Best Practices

Link Formatting

1. Use relative paths - Works across devices 2. Use aliases - Cleaner in preview 3. Avoid deep nesting - Hard to maintain

Frontmatter

1. Consistent property names - Case-sensitive 2. Quote strings with colons - YAML parsing 3. Use lists for multiple values - Better for queries

Organization

1. One topic per note - Atomic notes 2. Link liberally - Build knowledge graph 3. Use tags sparingly - Avoid over-categorization

Obsidian Bases Reference

Bases are YAML-based .base files that define dynamic views of vault notes.

Complete Schema

filters:          # Global filters (all views)
  and: []
  or: []
  not: []

formulas:         # Computed properties
  name: 'expression'

properties:       # Display config
  property_name:
    displayName: "Display Name"
  formula.name:
    displayName: "Formula Name"

summaries:        # Custom summary formulas
  name: 'values.mean().round(3)'

views:            # One or more views
  - type: table | cards | list | map
    name: "View Name"
    limit: 10
    groupBy:
      property: property_name
      direction: ASC | DESC
    filters:      # View-specific filters
      and: []
    order:        # Properties to display
      - file.name
      - property_name
      - formula.name
    summaries:    # Property -> summary mapping
      property_name: Average

Filter Syntax

Operators

Examples

# Single
filters: 'status == "done"'

# AND
filters:
  and:
    - 'status == "done"'
    - 'priority > 3'

# OR
filters:
  or:
    - file.hasTag("book")
    - file.hasTag("article")

# NOT
filters:
  not:
    - file.hasTag("archived")

# Nested
filters:
  or:
    - file.hasTag("tag")
    - and:
        - file.hasTag("book")
        - file.hasLink("Textbook")
    - not:
        - file.hasTag("book")
        - file.inFolder("Required Reading")

Properties

Three Types

1. Note properties - From frontmatter: author or note.author 2. File properties - File metadata: file.name, file.mtime, etc. 3. Formula properties - Computed: formula.my_formula

File Properties

The this Keyword

• In main content: refers to base file itself
• When embedded: refers to embedding file
• In sidebar: refers to active file

Formula Syntax

formulas:
  total: "price * quantity"
  status_icon: 'if(done, "done", "pending")'
  formatted: 'if(price, price.toFixed(2) + " dollars")'
  created: 'file.ctime.format("YYYY-MM-DD")'
  days_old: '((now() - file.ctime) / 86400000).round(0)'

Functions Reference

Global Functions

Date Functions

Fields: .year, .month, .day, .hour, .minute, .second, .millisecond

Date Arithmetic

"date + \"1M\""         # Add 1 month
"date - \"2h\""         # Subtract 2 hours
"now() + \"1 day\""     # Tomorrow
"today() + \"7d\""      # Week from today
"now() - file.ctime"    # Milliseconds since creation

Duration units: y/year/years, M/month/months, d/day/days, w/week/weeks, h/hour/hours, m/minute/minutes, s/second/seconds

String Functions

Field: .length

contains(), containsAll(), containsAny(), startsWith(), endsWith(), isEmpty(), lower(), title(), trim(), replace(), repeat(), reverse(), slice(), split()

Number Functions

abs(), ceil(), floor(), round(digits?), toFixed(precision), isEmpty()

List Functions

Field: .length

contains(), containsAll(), containsAny(), filter(expr), map(expr), reduce(expr, init), flat(), join(sep), reverse(), slice(), sort(), unique(), isEmpty()

Filter/map/reduce use: value, index, acc (reduce only)

File Functions

asLink(display?), hasLink(file), hasTag(...tags), hasProperty(name), inFolder(folder)

Link Functions

asFile(), linksTo(file)

View Types

Table

views:
  - type: table
    name: "Tasks"
    order: [file.name, status, due_date]
    summaries:
      price: Sum

Cards

views:
  - type: cards
    name: "Gallery"
    order: [cover, file.name, description]

List

views:
  - type: list
    name: "Simple"
    order: [file.name, status]

Map

Requires lat/lng properties and Maps plugin.

Default Summary Formulas

Number: Average, Min, Max, Sum, Range, Median, Stddev Date: Earliest, Latest, Range Boolean: Checked, Unchecked Any: Empty, Filled, Unique

Common Patterns

# By tag
filters:
  and: [file.hasTag("project")]

# By folder
filters:
  and: [file.inFolder("Notes")]

# By date range
filters:
  and: ['file.mtime > now() - "7d"']

# By property
filters:
  and: ['status == "active"', 'priority >= 3']

Embedding

![[MyBase.base]]
![[MyBase.base#View Name]]

YAML Quoting

• Single quotes for formulas with double quotes: 'if(done, "Yes", "No")'
• Double quotes for simple strings: "My View"

References

• Bases Syntax
• Functions
• Views
• Formulas

Integration Patterns Reference

Overview

An Obsidian vault is a codebase of markdown files. Claude Code navigates file structures and makes surgical edits natively.

Pattern Decision Tree

What integration level?
├── Minimal (just works)?       -> Pattern A: Direct Access
├── Enhanced discovery?         -> Pattern B: Manifest-Based (CLAUDE.md)
├── Real-time bidirectional?    -> Pattern C: MCP Plugin
├── Self-evolving PKM?          -> Pattern D: COG Pattern
└── Pre-configured structure?   -> Pattern E: Claudesidian

Pattern A: Direct Access (Zero Setup)

Claude Code reads/edits vault files directly. No configuration needed.

cd /path/to/vault && claude
# "Read my daily note from today"
# "Find all notes mentioning project X"
# "Add backlinks to people mentioned in this note"

Pattern B: Manifest-Based (CLAUDE.md)

Add CLAUDE.md at vault root to describe structure, conventions, and rules.

Key sections: Vault Overview, Folder Structure, Conventions (frontmatter, links, tags, dates), Important Files, When Creating/Editing Notes.

Pattern C: MCP Plugin

Real-time bidirectional via Model Context Protocol.

{
  "mcpServers": {
    "obsidian": {
      "transport": "websocket",
      "url": "ws://localhost:22360"
    }
  }
}

Capabilities: read_note, write_note, search, list_notes, get_backlinks, get_outlinks, get_tags

Plugin: obsidian-claude-code-mcp (Community Plugins)

Pattern D: COG Self-Evolving

Git-based with auto-organization and self-healing.

vault/
├── .git/
├── CLAUDE.md
├── _meta/
│   ├── patterns.md          # Learned patterns
│   ├── conventions.md       # Auto-discovered rules
│   └── maintenance-log.md   # Self-healing log
├── notes/
└── daily/

Self-Healing Features

1. Auto cross-references: Updates links on note moves 2. Pattern learning: Discovers and applies conventions 3. Orphan detection: Identifies unlinked notes 4. Consistency checks: Validates frontmatter, tags

Git Hooks

# .git/hooks/post-commit
#!/bin/bash
claude --print "Check for broken links and orphan notes.
Fix issues and update _meta/maintenance-log.md."

Pattern E: Claudesidian

Pre-configured vault structure optimized for AI interaction.

vault/
├── CLAUDE.md
├── Inbox/
├── Projects/
├── Knowledge/
├── Journal/
├── Templates/
└── _meta/
    ├── prompts/
    ├── contexts/
    └── exports/

Comparison

Common Workflows

Auto-Linking Entities

1. Read note content 2. Extract entity mentions (people, places, books) 3. Search vault for existing notes 4. Create new notes if needed 5. Insert [[wikilinks]] throughout

Knowledge Graph Maintenance

1. Identify orphan notes (no in/out links) 2. Analyze content for potential connections 3. Suggest or create links 4. Update MOCs

Research Synthesis

1. Search for relevant notes by topic 2. Extract key insights 3. Create structured summary note 4. Link back to source notes

Daily Note Enhancement

1. Read raw daily capture 2. Add proper frontmatter 3. Identify tasks -> add checkboxes 4. Identify mentions -> add wikilinks 5. Suggest tags based on content

Neovim Integration (obsidian.nvim)

For Neovim users, obsidian.nvim provides vault management inside the editor.

Minimal Setup (lazy.nvim)

return {
  "obsidian-nvim/obsidian.nvim",
  version = "*",
  ft = "markdown",
  opts = {
    workspaces = {
      { name = "personal", path = "~/vaults/personal" },
    },
  },
}

Key Commands

Completion Triggers

• [[ - Wiki link completion
• [ - Markdown link completion
• # - Tag completion

Template Variables

Requires: Neovim >= 0.10.0, ripgrep

Best Practices

1. Keep vault in version control (git rollback + change tracking) 2. Use consistent frontmatter across note types 3. Maintain CLAUDE.md manifest with conventions 4. Regular maintenance (orphan detection, broken link scan) 5. Review AI changes via git diff before committing 6. Document exceptions in manifest

References

• obsidian-claude-code-mcp
• COG-second-brain
• Claudesidian
• obsidian.nvim

Knowledge Capture Patterns

Templates and workflows for extracting knowledge from conversations into vault notes.

Capture Types

ADR Template (Architecture Decision Record)

---
created: YYYY-MM-DDTHH:mm
updated: YYYY-MM-DDTHH:mm
type: adr
status: accepted | proposed | deprecated | superseded
tags:
  - decision
  - topic/subtopic
---

# ADR: [Decision Title]

## Status
Accepted

## Context
What is the issue we're deciding on? What forces are at play?

## Decision
What is the change that we're proposing and/or doing?

## Consequences
What becomes easier or harder as a result of this decision?

### Positive
- Benefit 1
- Benefit 2

### Negative
- Tradeoff 1
- Tradeoff 2

## Related
- [[Previous ADR]]
- [[Related Project]]

Concept Template

---
created: YYYY-MM-DDTHH:mm
updated: YYYY-MM-DDTHH:mm
type: zettelkasten
tags:
  - permanent
  - concept
  - topic
---

# [Concept Name]

## Definition
One-paragraph explanation in your own words.

## Key Insight
**Core idea**: [Single sentence capturing the essence]

## How It Works
Explain the mechanism or model.

## Examples
- Example 1
- Example 2

## Connections
- [[Related Concept 1]] - how it relates
- [[Related Concept 2]] - how it relates

## Sources
- Where you learned this

How-To Template

---
created: YYYY-MM-DDTHH:mm
updated: YYYY-MM-DDTHH:mm
type: howto
tags:
  - howto
  - tool/technology
---

# How To: [Task Description]

## Prerequisites
- Requirement 1
- Requirement 2

## Steps

### 1. [First Step]
Details and commands.

### 2. [Second Step]
Details and commands.

### 3. [Third Step]
Details and commands.

## Verification
How to confirm it worked.

## Troubleshooting
Common issues and fixes.

## Related
- [[Related How-To]]
- [[Tool Documentation]]

Meeting Note Template

---
created: YYYY-MM-DDTHH:mm
updated: YYYY-MM-DDTHH:mm
type: meeting
attendees:
  - "[[Person 1]]"
  - "[[Person 2]]"
tags:
  - meeting
  - project/name
---

# Meeting: [Topic] - YYYY-MM-DD

## Attendees
- [[Person 1]]
- [[Person 2]]

## Agenda
1. Topic 1
2. Topic 2

## Notes
Key discussion points.

## Decisions
- Decision 1
- Decision 2

## Action Items
- [ ] @[[Person 1]] - Action by YYYY-MM-DD
- [ ] @[[Person 2]] - Action by YYYY-MM-DD

## Follow-up
Next meeting: [[YYYYMMDD]]

MOC (Map of Content) Template

---
created: YYYY-MM-DDTHH:mm
updated: YYYY-MM-DDTHH:mm
type: moc
tags:
  - moc
  - topic
---

# [Topic] MOC

## Overview
Brief description of this knowledge area.

## Core Concepts
- [[Concept 1]] - brief description
- [[Concept 2]] - brief description

## How-Tos
- [[How To: Task 1]]
- [[How To: Task 2]]

## Decisions
- [[ADR: Decision 1]]
- [[ADR: Decision 2]]

## Projects
- [[Project using this topic]]

## Resources
- [[External reference]]
- [[Book notes]]

Capture Workflow

From Conversation to Note

1. Identify capture type - What kind of knowledge is this? (ADR, concept, howto, etc.) 2. Select template - Use appropriate template above 3. Extract key content - Pull relevant information from conversation 4. Add metadata - Frontmatter with timestamps, tags, type 5. Create wikilinks - Link to existing related notes in vault 6. Place in PARA folder - Put in correct location 7. Update MOCs - Add link to relevant Maps of Content if they exist

Auto-Detection Signals

Linking Strategy

When creating a captured note: 1. Search vault for existing notes on the same topic 2. Add [[wikilinks]] to those notes 3. Check if a relevant MOC exists and add entry 4. Add backlinks from related notes to new note 5. Tag with hierarchical tags matching vault conventions

Obsidian Flavored Markdown Reference

Obsidian uses CommonMark + GitHub Flavored Markdown + LaTeX + Obsidian extensions.

Basic Formatting

Escape with backslash: \*, \_, \#, ` \ `, \|, \~`

Internal Links (Wikilinks)

[[Note Name]]                    # Link to note
[[Note Name|Display Text]]       # Link with alias
[[Note Name#Heading]]            # Link to heading
[[Note Name#^block-id]]          # Link to block
[[#Heading in same note]]        # Same-file heading link
[[##heading]]                    # Search headings in vault
[[^^block]]                      # Search blocks in vault

Markdown-Style Links

[Display Text](Note%20Name.md)           # Spaces must be URL-encoded
[Display Text](Note%20Name.md#Heading)
[Display Text](https://example.com)
[Note](obsidian://open?vault=VaultName&file=Note.md)

Embeds (Transclusion)

![[Note Name]]                   # Embed entire note
![[Note Name#Heading]]           # Embed section
![[Note Name#^block-id]]         # Embed block
![[image.png]]                   # Embed image
![[image.png|300]]               # Width only
![[image.png|300x200]]           # Width x Height
![[audio.mp3]]                   # Embed audio
![[video.mp4]]                   # Embed video
![[document.pdf]]                # Embed PDF
![[document.pdf#page=3]]         # Embed PDF page

External Images

![Alt text](https://example.com/image.png)
![Alt text|300](https://example.com/image.png)

Embed Search Results

````markdown

tag:#project status:done

````

Block References

This is a paragraph. ^block-id

# Reference from another note:
[[Note#^block-id]]
![[Note#^block-id]]

For lists/quotes, add block ID on separate line after the block:

- Item 1
- Item 2

^list-id

Callouts

> [!note] Title
> Content

> [!tip]+ Expandable (default open)
> Click to collapse

> [!info]- Collapsed (default closed)
> Click to expand

Nested Callouts

> [!question] Outer
> > [!note] Inner
> > Nested content

Callout Types

Custom Callouts (CSS)

.callout[data-callout="custom-type"] {
  --callout-color: 255, 0, 0;
  --callout-icon: lucide-alert-circle;
}

Properties (Frontmatter)

---
title: My Note Title
date: 2024-01-15
tags:
  - project
  - important
aliases:
  - "Alternate Name"
cssclasses:
  - custom-class
status: in-progress
rating: 4.5
completed: false
due: 2024-02-01T14:30:00
---

Property Types

Default properties: tags, aliases, cssclasses

Tags

#tag
#nested/tag
#tag-with-dashes
#tag_with_underscores

Tags can contain: letters (any language), numbers (not first), underscores, hyphens, forward slashes (nesting).

Lists

- [ ] Incomplete task
- [x] Completed task
- Unordered item
  - Nested item

1. Ordered item
2. Second item
   1. Nested ordered

Tables

| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| Cell     | Cell     | Cell     |

Escape pipes in tables: [[Link\|Display]]

Math (LaTeX)

Inline: $E = mc^2$

Block:
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Common: $x^2$, $x_i$, $\frac{a}{b}$, $\sqrt{x}$, $\sum_{i=1}^{n}$, $\int_a^b$, $\alpha, \beta$

Mermaid Diagrams

````markdown

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

````

Sequence Diagrams

````markdown

sequenceDiagram
    Alice->>Bob: Hello
    Bob-->>Alice: Hi

````

Code Blocks

````markdown

code here

````

Nest by using more backticks for the outer block.

Footnotes

Text with footnote[^1].
[^1]: Footnote content.

Named footnote[^note].
[^note]: Named footnote content.

Inline footnote.^[This is inline.]

Comments

%%This is hidden%%

%%
Multi-line
hidden comment
%%

Horizontal Rules

---
***
___

HTML Support

<details>
  <summary>Click to expand</summary>
  Hidden content here.
</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd>

References

• Basic formatting
• Advanced formatting
• Obsidian Flavored Markdown
• Internal links
• Embed files
• Callouts
• Properties

Obsidian REST API & URI Scheme Reference

Local REST API Plugin

The Local REST API plugin provides HTTP endpoints for programmatic vault access.

Setup

1. Install "Local REST API" from Community Plugins 2. Enable the plugin 3. Configure API key in plugin settings 4. Default endpoint: https://127.0.0.1:27124

Authentication

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://127.0.0.1:27124/vault/

Environment variables: OBSIDIAN_API_KEY, OBSIDIAN_BASE_URL

Endpoints

# File Operations
GET    /vault/                    # List all files
GET    /vault/{path}              # Get file content
PUT    /vault/{path}              # Create/update file (Content-Type: text/markdown)
DELETE /vault/{path}              # Delete file
PATCH  /vault/{path}              # Append/prepend to file

# Search
POST   /search/simple/           # Simple text search
POST   /search/                   # Dataview query (DQL)
POST   /search/jsonlogic/        # JsonLogic search

# Active File
GET    /active/                   # Get active file info
PUT    /active/                   # Set active file content

# Commands
POST   /commands/{command-id}     # Execute Obsidian command
GET    /commands/                  # List available commands

# Open
POST   /open/{path}               # Open file in Obsidian

Search Examples

# Simple text search
curl -X POST https://127.0.0.1:27124/search/simple/ \
  -H "Authorization: Bearer $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "search term"}'

# Dataview query (DQL)
curl -X POST https://127.0.0.1:27124/search/ \
  -H "Authorization: Bearer $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/vnd.olrapi.dataview.dql+txt" \
  -d 'TABLE status, tags FROM "01 - Projects" WHERE status != "completed"'

# JsonLogic query
curl -X POST https://127.0.0.1:27124/search/jsonlogic/ \
  -H "Authorization: Bearer $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/vnd.olrapi.jsonlogic+json" \
  -d '{"and": [{"glob": ["01 - Projects/**", {"var": "path"}]}, {"!==": [{"var": "frontmatter.status"}, "completed"]}]}'

Python Client (httpx)

import httpx
import os

class ObsidianAPI:
    def __init__(self):
        self.base_url = os.getenv("OBSIDIAN_BASE_URL", "https://127.0.0.1:27124")
        self.api_key = os.getenv("OBSIDIAN_API_KEY", "")
        self.client = httpx.Client(
            base_url=self.base_url,
            headers={"Authorization": f"Bearer {self.api_key}"},
            verify=False,  # Self-signed cert
            timeout=30.0,
        )

    def list_files(self, path: str = "") -> list:
        r = self.client.get(f"/vault/{path}")
        r.raise_for_status()
        return r.json()["files"]

    def read_file(self, path: str) -> str:
        r = self.client.get(f"/vault/{path}", headers={"Accept": "text/markdown"})
        r.raise_for_status()
        return r.text

    def write_file(self, path: str, content: str) -> bool:
        r = self.client.put(
            f"/vault/{path}",
            content=content.encode("utf-8"),
            headers={"Content-Type": "text/markdown"},
        )
        return r.status_code == 204

    def search_simple(self, query: str) -> list:
        r = self.client.post("/search/simple/", json={"query": query})
        r.raise_for_status()
        return r.json()

    def search_dataview(self, dql: str) -> list:
        r = self.client.post(
            "/search/",
            content=dql.encode("utf-8"),
            headers={"Content-Type": "application/vnd.olrapi.dataview.dql+txt"},
        )
        r.raise_for_status()
        return r.json()

    def search_jsonlogic(self, logic: dict) -> list:
        r = self.client.post(
            "/search/jsonlogic/",
            json=logic,
            headers={"Content-Type": "application/vnd.olrapi.jsonlogic+json"},
        )
        r.raise_for_status()
        return r.json()

    def open_file(self, path: str) -> bool:
        r = self.client.post(f"/open/{path}")
        return r.status_code == 200

URI Scheme

Native obsidian:// protocol for automation:

obsidian://open?vault=MyVault                    # Open vault
obsidian://open?vault=MyVault&file=Notes/MyNote  # Open file
obsidian://new?vault=MyVault&name=NewNote&content=Hello  # Create note
obsidian://search?vault=MyVault&query=keyword    # Search
obsidian://daily?vault=MyVault                   # Open daily note

URI Parameters

Note: URL-encode spaces as %20, slashes as %2F, ampersands as %26.

Plugin Development API

Core API Classes

Plugin Template

import { Plugin, Notice, MarkdownView } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    this.addCommand({
      id: 'my-command',
      name: 'My Command',
      callback: () => new Notice('Hello!'),
    });

    this.addCommand({
      id: 'my-editor-command',
      name: 'Insert Text',
      editorCallback: (editor, view: MarkdownView) => {
        editor.replaceSelection('Inserted text');
      },
    });

    this.registerEvent(
      this.app.workspace.on('file-open', (file) => {
        if (file) console.log('Opened:', file.path);
      })
    );
  }

  onunload() {}
}

Plugin Structure

my-plugin/
├── main.ts           # Entry point
├── manifest.json     # Metadata (id, name, version, minAppVersion)
├── package.json
├── styles.css
├── tsconfig.json
└── esbuild.config.mjs

CLI Tools

# Go CLI (Yakitrak)
obsidian-cli open "Note Name"
obsidian-cli search "query"
obsidian-cli create "New Note"
obsidian-cli daily
obsidian-cli list

# Python CLI
obs vault list
obs vault create <name>
obs note search <query>

References

• Local REST API Plugin
• Advanced URI Plugin
• Obsidian Developer Docs
• Obsidian API Types

Vault Organization Reference

PARA Folder Structure

System Folders

Frontmatter Schemas

Standard Note

---
created: YYYY-MM-DDTHH:mm
updated: YYYY-MM-DDTHH:mm
tags:
  - category/subcategory
---

Daily Note

---
created: YYYY-MM-DDTHH:mm
updated: YYYY-MM-DDTHH:mm
title: "YYYYMMDD"
type: daily-note
status: true
tags:
  - daily
  - YYYY
  - YYYY-MM
date_formatted: YYYY-MM-DD
---

Project Note

---
created: YYYY-MM-DDTHH:mm
updated: YYYY-MM-DDTHH:mm
type: project
status: active | paused | complete
priority: high | medium | low
tags:
  - project/name
---

Zettelkasten Note

---
created: YYYY-MM-DDTHH:mm
updated: YYYY-MM-DDTHH:mm
type: zettelkasten
tags:
  - permanent
  - topic
---

Naming Conventions

• Regular notes: Descriptive titles (spaces allowed)
• Daily notes: YYYYMMDD.md in 06 - Daily/YYYY/MM/
• Templates: Located in 99 - Meta/00 - Templates/
• BMAD files: kebab-case

Link Conventions

• Use [[wikilinks]] for all internal links
• Link to headings: [[Note#Heading]]
• Block references: [[Note#^block-id]]
• Embed notes: ![[Note]]
• Embed images: ![[image.png]]

Dataview Queries

Quick Examples

LIST FROM "06 - Daily" WHERE file.cday = date(today) SORT file.ctime DESC

TABLE status, tags FROM "01 - Projects" WHERE status != "completed"

TABLE WITHOUT ID file.link AS "Note", file.mtime AS "Modified"
FROM "03 - Resources"
SORT file.mtime DESC
LIMIT 20

TASK FROM "01 - Projects" WHERE !completed

Common Patterns

# Notes by tag
LIST FROM #project AND -#archived

# Recent notes in folder
TABLE file.mtime AS "Modified" FROM "02 - Areas" SORT file.mtime DESC LIMIT 10

# Notes linking to current file
LIST FROM [[]] SORT file.name ASC

# Orphan detection
LIST FROM "" WHERE length(file.inlinks) = 0 AND length(file.outlinks) = 0

Templater Variables

<% tp.file.title %>              # Current file name
<% tp.date.now("YYYY-MM-DD") %>  # Current date
<% tp.file.cursor(1) %>          # Cursor position
<% tp.system.prompt("Question") %> # User input prompt

Installed Plugins

Lifecycle States

Notes can move through lifecycle states for processing:

inbox -> active -> processed -> archived

• inbox: Raw capture, needs triage
• active: Being worked on
• processed: Reviewed, properly tagged and linked
• archived: No longer active, preserved for reference

Best Practices

1. Always include created and updated timestamps in frontmatter 2. Tag notes for discoverability 3. Link to related notes bidirectionally 4. Use callouts for important information 5. Include navigation links in daily notes (<< prev | today | next >>) 6. Place notes in correct PARA folder based on type 7. Use descriptive filenames (avoid special characters except hyphens)