obsidian

Obsidian

概要

このスキルでは、強力なナレッジ管理・ノート作成アプリケーションである Obsidian の使用方法を包括的に説明します。 Vault の構造、プラグイン開発向け Obsidian API、 URI スキームによる自動化、Markdown 拡張機能、Local REST API を介した 外部ツールとの連携を扱います。

クイックリファレンス

Vault の構造

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 スキーム

Obsidian は標準で、自動化用の obsidian:// プロトコルをサポートしています。

# 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 パラメーター

パラメーター	説明
vault	Vault 名（必須）
file	.md 拡張子を除いたファイルパス
path	フォルダーを含む完全なファイルパス
name	作成するノートの名前
content	挿入するコンテンツ
query	検索クエリ
heading	見出しに移動
block	ブロック参照に移動

ワークフローの判断ツリー

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

プラグイン開発

プラグインの構造

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
}

基本的なプラグインのテンプレート

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');
  }
}

コア API クラス

クラス	目的	アクセス方法
App	アプリケーションの中心となるインスタンス	this.app
Vault	ファイルシステム操作	this.app.vault
Workspace	ペインとレイアウトの管理	this.app.workspace
MetadataCache	ファイルメタデータのインデックス作成	this.app.metadataCache
FileManager	ユーザーに安全なファイル操作	this.app.fileManager

プラグインのライフサイクル

// 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

Local REST API プラグインは、Obsidian をプログラムから操作するための HTTP エンドポイントを提供します。

インストール

1. Community Plugins から「Local REST API」をインストールします
2. プラグインを有効にします
3. 設定で API キーを構成します
4. デフォルトのエンドポイント：https://127.0.0.1:27124

認証

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

一般的なエンドポイント

# 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 の例

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 拡張機能

Obsidian では、標準の Markdown に特殊な構文が追加されています。

内部リンク（ウィキリンク）

[[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

埋め込み（トランスクルージョン）

![[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

コールアウト

> [!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

ブロック参照

This is a paragraph. ^block-id

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

タグ

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

フロントマター（YAML）

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

# Note content starts here

コメント

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

%%
Multi-line
comment
%%

数式（LaTeX）

Inline: $E = mc^2$

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

Mermaid 図

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

CLI ツール

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

ベストプラクティス

1. 開発用 Vault を分ける：メインの Vault でプラグインを開発しないでください
2. プラグインをホットリロードする：開発の反復を速めるためにインストールします
3. registerEvent() を使用する：アンロード時に適切にクリーンアップされます
4. パスより UID を優先する：ファイルパスは変更されることがあるため、一意の識別子を使用します
5. 非同期処理を適切に扱う：Vault の操作では await を使用します
6. Obsidian のサンドボックスでテストする：ベータテストには BRAT プラグインを使用します
7. manifest の規約に従う：id をフォルダー名と一致させます
8. バージョンを慎重に管理する：互換性のために versions.json を更新します

トラブルシューティング

プラグインが読み込まれない

# 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 が動作しない

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

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

REST API への接続に失敗する

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

リソース

リファレンス

• references/uri-scheme.md - URI スキームの完全なドキュメント
• references/plugin-development.md - プラグイン開発ガイド
• references/vault-structure.md - Vault と設定の構造
• references/markdown-extensions.md - Obsidian の Markdown 構文
• references/api-reference.md - TypeScript API リファレンス

スクリプト

• scripts/obsidian-vault.sh - Vault 管理ユーティリティ
• scripts/obsidian-api.py - Local REST API の Python クライアント

外部ドキュメント

• Obsidian 開発者向けドキュメント
• Obsidian API Types
• サンプルプラグインのテンプレート
• Local REST API Plugin
• Advanced URI Plugin
• Obsidian ヘルプ

---

統合後に取り込まれたサブスキル

このスキルは、旧 obsidian-master スキル（「統合オーケストレーション」という包括的なスキル）を統合するようになりました。その内容は詳細なリファレンスとして保持されています。

主題	パス
オーケストレーションの元の SKILL.md（複数ステップの Vault ワークフロー）	References/master.md
Master スキルのリファレンスドキュメント	References/master-reference/
Master スキルのワークフロー	References/master-workflows/
Master スキルのツール	References/master-tools/

旧 obsidian-second-brain スキルは、実際の内容を反映して obsidian-claude-integration に名称変更されました。汎用的な「セカンドブレイン」の概念ではなく、Claude Code と Obsidian の統合パターンを扱います。

個別の関連スキルも引き続き利用できます。

• obsidian-markdown — 構文のみ（wikilinks、埋め込み、コールアウト、frontmatter、タグ、LaTeX、Mermaid）。
• obsidian-bases — Bases（.base YAML、テーブルビュー、フィルター、数式）のみ。
• obsidian-nvim — obsidian.nvim Neovim プラグインのみ。
• obsidian-vault-management — Vault の内容（ノート、テンプレート、Dataview）の CRUD。
• obsidian-claude-integration — Claude Code と Obsidian の統合パターン。

---

注意点

• Wikilink [[Note]] の解決では、重複がある場合、Vault 内でアルファベット順に最初に見つかった項目が選ばれます — 警告は表示されません。異なるフォルダーに「Index」という名前のノートが2つあると、気付かない曖昧さが生じます。
• obsidian:// URI スキームを使うには、デスクトップアプリで Vault を開いておく必要があります — ヘッドレス環境（CI、Obsidian を起動していない Claude Code）では何も起きませんが、エラーも表示されません。
• Local REST API プラグインは、API キーとは別に有効化する必要があります — デフォルトのポートは 27124 ですが、HTTP リクエストを受け付けるにはプラグインが起動している必要があります。
• Markdown の脚注（[^1]）では、定義の前に空行が必要です — 空行がないと、Obsidian はエラーを表示せず、脚注をプレーンテキストとして表示します。
• Vault のパスにスペースや特殊文字が含まれる場合、大半のプラグインは対応していますが、シェル統合プラグインの中には対応していないものもあります。 スクリプトからの呼び出しを明示的にテストしてください。