obsidian-export

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.