by DGApex
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.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
# Add to your Claude Code skills
git clone https://github.com/DGApex/Obsidian-Export-Skill.mdGuides for using ai agents skills like Obsidian-Export-Skill.md.
No comments yet. Be the first to share your thoughts!
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.
The agent must identify the local Obsidian vault path (the directory containing the .obsidian configuration folder).
[!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.
Ask the user for:
.md) or folder to start the export from.--isolate to avoid pulling in unrelated notes from shared links.Index, Home) should be skipped to keep the graph focused.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"
Report the number of exported notes, successful connections (links), and the final file location.
--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.Index.md in different folders). The first one found wins. Inform the user if this affects their key notes.--offline flag.| 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 |
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.
mistune (Markdown parsing)PyYAML (Frontmatter processing)
Fallback to standard libraries is supported.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.

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:
SKILL.md to understand the toolThe script is the engine. The agent is the driver.
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:
Projects/GUS/, sets --isolate, runs it--offline, sets a clean titleThe generated HTML is self-contained and needs no server or hosting:
[[wikilinks]] are clickable and navigate within the file--offline, no external dependencies at render timepip 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.
Copy SKILL.md into your agent's context, or reference it directly if your agent supports file reading.
"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.
pip install -r requirements-dev.txt
pytest tests/ -v
[!CAUTION] This tool is read-only — it never modifies your
.mdfiles. Even so, always keep a backup of your vault before running external scripts.
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.
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.
Share your exported graphs:
#obsidian #knowledge-graph #ai-agentDistributed under the MIT License. See LICENSE for more information.