Obsidian plugin development: Tự xây second brain extensions

Obsidian đã trở thành standard de-facto cho personal knowledge management (PKM) với 25+ triệu downloads. Sức mạnh thực sự không chỉ ở Markdown files, mà ở plugin ecosystem: 1.500+ community plugins, từ simple formatter đến complex spaced repetition. Bạn có thể tự build plugin riêng với TypeScript, đóng góp cho cộng đồng, hoặc tạo tool nội bộ cho team.

Kiến trúc plugin Obsidian

Obsidian chạy trên Electron, dùng Node.js APIs trong main process và browser APIs trong renderer. Plugin chạy trong renderer sandbox — có thể access Obsidian API, đọc/ghi vault files, register commands, ribbon icons, status bar items. Nhưng không có DOM access trực tiếp: bạn dùng Obsidian’s view component system.

Prerequisites: Node.js 18+, TypeScript 5+, Obsidian v1.0+ (API stable). Không cần build tool phức tạp — Obsidian template sẵn Vite config.

Obsidian plugin architecture được thiết kế với security và isolation như ưu tiên hàng đầu. Mỗi plugin chạy trong renderer process riêng biệt, chỉ có quyền truy cập thông qua Obsidian API được expose. Điều này ngăn chặn các plugin độc hại truy cập file system trực tiếp hoặc thực hiện các hành động nguy hiểm. Plugin API cung cấp các interface an toàn để tương tác với vault, workspace, và UI components.

Obsidian plugin architecture showing vault, API layer, plugin sandbox, and UI components

Tạo project từ template

git clone https://github.com/obsidianmd/obsidian-sample-plugin.git my-plugin
cd my-plugin
npm install
npm run dev

Template bao gồm: main.ts (entry point), manifest.json (metadata), tsconfig.json, và sample event handlers.

Plugin API chính

Plugin: Base class — onload(), onunload(), loadSettings(), saveSettings().
Vault: vault.create(), vault.read(), vault.modify(), vault.delete() — đọc/ghi Markdown files.
Workspace: Register leaf views, panels, modals. Ví dụ: workspace.dockLeft.add() để thêm sidebar.
MetadataCache: Đọc frontmatter, tags, links đã index — nhanh hơn đọc raw file.
SuggestModal: Class kế thừa để tìm kiếm modal. Ví dụ: tìm note theo tag, tìm internal link.

Vault API là trái tim của plugin development, cho phép bạn thao tác với Markdown files như một database. Bạn có thể tạo, đọc, sửa, xóa files, lắng nghe các event như file create/modify/delete. MetadataCache cung cấp khả năng query mạnh mẽ: tìm tất cả notes có tag cụ thể, tìm backlinks, đọc frontmatter mà không cần parse file thủ công.

Obsidian API class diagram showing Plugin, Vault, Workspace, and MetadataCache relationships

Ví dụ: Auto-tagging plugin

Plugin tự động gắn tag #daily cho note được tạo trong ngày:

import { Plugin, TFile } from 'obsidian';

export default class AutoTagPlugin extends Plugin {
  async onload() {
    this.registerEvent(
      this.app.vault.on('create', (file: TFile) => {
        if (file.extension === 'md') {
          const date = window.moment().format('YYYY-MM-DD');
          const content = `#daily/${date}nn`;
          this.app.vault.modify(file, content + await this.app.vault.read(file));
        }
      })
    );
  }
}

Ví dụ nâng cao: Plugin tìm kiếm và replace

Một plugin thực tế hơn có thể thêm command palette entry để tìm và replace text trong toàn bộ vault:

import { Plugin, TFile, Menu, Notice } from 'obsidian';

export default class FindReplacePlugin extends Plugin {
  async onload() {
    this.addCommand({
      id: 'find-replace',
      name: 'Find and Replace in Vault',
      callback: async () => {
        const files = this.app.vault.getMarkdownFiles();
        // Implementation details...
        new Notice('Find and replace completed');
      }
    });
  }
}

Điều này cho thấy sức mạnh của Obsidian API: bạn có thể build các tool phức tạp như full-text search, batch editing, hoặc tự động hóa workflow chỉ với vài trăm dòng code TypeScript.

Tích hợp với công cụ bên ngoài

Obsidian plugin cũng có thể tích hợp với các công cụ bên ngoài thông qua API calls. Ví dụ:

Kết nối với GitHub để lưu trữ vault dưới dạng repository
Tích hợp với Google Calendar để đồng bộ lịch và reminder
Kết nối với REST API để đồng bộ dữ liệu với ứng dụng bên thứ ba
Tích hợp với máy chủ local để thực hiện các tác vụ xử lý dữ liệu phức tạp

Ví dụ cụ thể: Plugin có thể tự động tạo note mỗi khi bạn có commit mới trên GitHub, hoặc đồng bộ task từ Todoist vào Obsidian dưới dạng danh sách công việc cần làm.

Cải thiện hiệu suất plugin

Khi phát triển plugin, bạn cần lưu ý đến hiệu suất để tránh làm chậm Obsidian:

Throttle các event listener thường xuyên như editor-change
Sử dụng requestIdleCallback để lên lịch tác vụ không quan trọng
Tránh thực hiện DOM operations trực tiếp trong main thread
Sử dụng Web Workers để xử lý các tác vụ CPU-intensive

Ví dụ: Thay vì xử lý ngay lập tức khi user gõ ký tự, bạn có thể delay 300ms để giảm tần suất cập nhật và cải thiện trải nghiệm gõ phím.

Test và debug plugin

Obsidian cung cấp một số công cụ để test và debug plugin:

Console logging như bình thường trong browser
Plugin debug mode trong cài đặt Obsidian
Unit testing framework với Jest hoặc Vitest
End-to-end testing với công cụ như Playwright

Bạn cũng có thể sử dụng Obsidian’s built-in developer tools để kiểm tra API calls và event emissions.

Publish lên community plugin list

Khi plugin sẵn sàng, publish lên community plugins repo:

Fork repo, copy manifest.json + main.js vào thư mục community-plugins/your-plugin.
PR với description, screenshots, compatibility info.
Obsidian team review và merge.

Hoặc distribute riêng: zip file, GitHub release, hoặc BRAT (Beta Reviewers Auto-update Tester) — tool cho early access trước khi publish chính thức.

Monetization

Obsidian community plugins phải MIT license, không bán trực tiếp. Nhưng developer có thể:

SaaS wrapper: Build desktop app dùng Obsidian core + plugin riêng + cloud sync, bán subscription (ví dụ: Reflect).
Consulting: Tạo custom plugin cho enterprise vaults — insurance, legal firms cần PKM compliance.
Template + Course: Dạy build plugin, chia sẻ template qua Gumroad, Patreon.

Kết luận

Obsidian plugin development là entry point dễ nhất để build knowledge tools với cộng đồng lớn sẵn. TypeScript + Obsidian API cho bạn access trực tiếp vào vault, metadata cache, và UI system. Với 25 triệu users, plugin được adopt nhanh hơn bất kỳ standalone Electron app nào.

Nếu bạn đang tìm project để học desktop app development, Obsidian plugin là lựa chọn tối ưu: có real users, có feedback loop, có monetization path, và không cần lo về hosting, payments, scaling.

Nguồn tham khảo: Obsidian Plugin Developer Docs, Obsidian API reference, Sample Plugin template, Obsidian community forum.