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.