name: obsidian-export description: A high-performance AI-ready skill to export Obsidian vaults into interactive D3.js HTML graphs. This tool follows Obsidian's dark aesthetic and resolves standard wikilinks for portable knowledge sharing.

Obsidian Export Skill (AI Specification)

This specification allows an AI Agent to autonomously operate the obsidian-export tool. The agent acts as a bridge between the user's local vault and a professional web-based visualization.

⚙️ Configuration & Safety

1. Vault Detection

The agent must identify the local Obsidian vault path (the directory containing the .obsidian configuration folder).

2. Safety Protocol

[!IMPORTANT] Before execution, the agent MUST advise the user to ensure they have a recent backup of their vault or are working on a secondary copy. While the script is read-only, environment safety is paramount.

🛠️ Execution Logic

Step 1: Data Gathering

Ask the user for:

• Root Entity: A specific note (.md) or folder to start the export from.
• Traversal Depth: How many levels of wikilinks to follow (Default: 2).
• Scope: If exporting a single project, recommend --isolate to avoid pulling in unrelated notes from shared links.
• Exclude: Ask if any hub notes (e.g. Index, Home) should be skipped to keep the graph focused.
• Offline Mode: Whether to embed all dependencies (Default: Yes — recommended for portability).

Step 2: Command Construction

Construct and execute the CLI command:

python src/obsidian_to_html.py \
  --root "<root_path>" \
  --vault "<vault_path>" \
  --depth 2 \
  --output obsidian_export.html \
  --title "Interactive Knowledge Map"

Step 3: Result Reporting

Report the number of exported notes, successful connections (links), and the final file location.

Error Handling

• Path not found: Verify --root exists and the path has no typos. On Windows, wrap paths with spaces in quotes.
• --vault not specified warning: The script will warn if vault is inferred automatically — wikilinks to notes outside the root folder will not resolve. Always pass --vault explicitly.
• Duplicate note name warnings: The vault contains multiple files with the same stem (e.g. several Index.md in different folders). The first one found wins. Inform the user if this affects their key notes.
• D3.js fetch fails: All CDN mirrors timed out. The HTML still generates but requires internet to render. Suggest retrying with --offline flag.

📝 Script Reference

| Argument | Description | |---|---| | --root | Starting .md file or directory | | --vault | Root of the Obsidian vault | | --depth | Max traversal depth (0 for unlimited) | | --output | Path for the generated .html file | | --title | Custom title shown in the HTML header | | --exclude | Comma-separated substrings to skip (e.g. Indice,Home) | | --offline | Embeds D3.js (no external internet required for viewing) | | --isolate | Prevents the graph from expanding outside the root path |

🗂️ Adapt to Your Vault

Before using this skill, fill in the following based on your own setup:

1. Vault path

vault_path = "/absolute/path/to/your/vault"

This is the folder containing the .obsidian directory.

2. Folder color mapping Edit FOLDER_COLORS in src/obsidian_to_html.py to match your top-level folders (lowercase):

FOLDER_COLORS = {
    'projects':  '#e879f9',
    'research':  '#fb923c',
    'knowledge': '#34d399',
    # add your own structure here
}

Only top-level folder names matter — subfolders are ignored for color assignment.

3. Common exclusions Notes that act as hubs or indexes (e.g. Home.md, Index.md, Indice.md) tend to connect to everything and inflate the graph. Add them to --exclude by default:

--exclude "Index,Home,Indice"

4. Default export folder Decide where generated HTML files should land (e.g. ~/Desktop/exports/ or the project root). Set this as your default --output path so exports don't scatter across the filesystem.

Once configured, the agent can resolve natural language requests like "export my Projects/AppName notes" directly against your vault structure without asking for paths every time.

📦 Requirements

• mistune (Markdown parsing)
• PyYAML (Frontmatter processing) Fallback to standard libraries is supported.

Obsidian Export 🚀

Tell your AI agent which notes to export. It handles the rest.

Obsidian Export turns your local Obsidian vault into a self-contained, interactive HTML knowledge map — driven by an AI agent that understands your intent, selects the right notes, and runs the export for you.

You don't touch the command line. You just say what you want.

🤖 How It Works

This repo is built around two components:

| Component | Role | |---|---| | SKILL.md | Tells the AI agent what this tool does, how to use it, and what questions to ask | | src/obsidian_to_html.py | Deterministic Python script that does the actual export |

The AI is the interface. You describe what you want in natural language — a project, a topic, a set of notes — and the agent:

1. Reads SKILL.md to understand the tool
2. Asks you the right clarifying questions (scope, depth, exclusions)
3. Constructs and runs the export command
4. Reports back with the result: how many notes, how many connections, where the file is

The script is the engine. The agent is the driver.

🌟 Why This Approach?

Obsidian vaults are personal and messy. No two are structured the same way. A static CLI tool would require you to know the exact path, the right depth, which files to exclude — every time.

An AI agent handles that translation layer:

• "Export everything about the GUS project" → agent finds Projects/GUS/, sets --isolate, runs it
• "Share my research on AI frameworks" → agent locates the right folder, adjusts depth, excludes index notes
• "Make a portable version of these notes for a client" → agent adds --offline, sets a clean title

✨ Output Features

The generated HTML is self-contained and needs no server or hosting:

• 🕸️ D3.js Force Graph — interactive physics-based visualization of note connections
• 🌓 Obsidian Dark Aesthetic — polished UI matching the Obsidian dark theme
• 🔍 Global Search — find notes and highlight matches across the graph and reader panel
• 🔗 Wikilink Navigation — [[wikilinks]] are clickable and navigate within the file
• 🎨 Folder Color-Coding — nodes colored automatically by top-level folder
• 📦 Fully Offline — with --offline, no external dependencies at render time

🚀 Quick Start

1. Install the script dependencies

pip install -r requirements.txt

Both libraries (mistune, PyYAML) are optional — the script falls back to standard Python libraries if they're not available. Installing them gives better Markdown rendering.

2. Load the skill into your AI agent

Copy SKILL.md into your agent's context, or reference it directly if your agent supports file reading.

3. Ask for an export

"Export everything related to my X project."
"Share my Research/AI folder as a portable HTML."
"Generate a knowledge map of my Proyects/App notes, depth 3."

The agent will ask any clarifying questions it needs, then run the export and tell you where the file is.

🧪 Running Tests

pip install -r requirements-dev.txt
pytest tests/ -v

🛡️ Safety

[!CAUTION] This tool is read-only — it never modifies your .md files. Even so, always keep a backup of your vault before running external scripts.

🔧 CLI Reference

For debugging or direct use without an agent:

python src/obsidian_to_html.py \
  --root "/path/to/vault/ProjectA" \
  --vault "/path/to/vault" \
  --title "Project A" \
  --offline

| Argument | Description | Default | |---|---|---| | --root | Starting note or folder | (Required) | | --vault | Root of your vault to resolve links | Parent of --root | | --depth | Traversal depth (0=unlimited) | 2 | | --output | Destination HTML file | obsidian_export.html | | --title | Custom title shown in the HTML header | Filename/folder name | | --exclude | Comma-separated substrings to skip (e.g. Index,Home) | "" | | --offline | Embed D3.js for full offline support | False | | --isolate | Only export notes within the root path | False |

Tip: Use --isolate when exporting a single project to prevent shared notes from pulling in unrelated content. Use --exclude to drop index or hub notes that would otherwise dominate the graph.

🎨 Customization

Node colors are assigned by the top-level folder of each note relative to the vault root. Edit FOLDER_COLORS in src/obsidian_to_html.py to match your structure:

FOLDER_COLORS = {
    'work':      '#4f8ef7',
    'knowledge': '#34d399',
    'research':  '#fb923c',
    # Add your own top-level folder names here (lowercase)
}

A note at Research/AI/note.md gets the color for 'research'. Notes in unmapped folders fall back to the default purple (#a78bfa). Subfolders do not affect the color.

🌐 Community & Support

Share your exported graphs:

• Showcase: Post in the Obsidian Forum - Share & Showcase
• Tags: #obsidian #knowledge-graph #ai-agent

📄 License

Distributed under the MIT License. See LICENSE for more information.