Obsidian Data Importer
Activation Conditions
This skill activates when:
- •User uploads or provides CSV/JSON data files
- •User requests Obsidian import assistance
- •User mentions "Handlebars", "JSON/CSV Importer", "bulk import", or "data import"
- •User wants to create multiple Obsidian notes from structured data
Quick Start (3 Steps)
For immediate use:
- •Provide your data - Upload CSV/JSON file or paste content
- •Confirm mapping - Review proposed field assignments
- •Receive template - Get complete Handlebars template + instructions
→ Simple example: 01-task-list-csv
System Architecture
code
obsidian-data-importer/ ├── core/ → Processing engines (5 phases + 4 modules) ├── knowledge/ → Reference documentation (syntax, types, errors) ├── templates/ → Pattern library (8 templates + partials) └── examples/ → Complete demonstrations (12 workflows)
Component Diagram
code
[Data Input]
↓
[DataParser] ──→ [FieldAnalyzer] ──→ [TemplateGenerator] ──→ [Validator]
↓ ↓ ↓ ↓
Parsed Field Inventory Template String Validation
Structure Report
↓
[InstructionComposer]
↓
Complete Package
Workflow Overview
The system executes in 5 sequential phases:
| Phase | Purpose | Documentation | Output |
|---|---|---|---|
| 1. Ingestion | Parse & analyze data structure | Phase 1 | Field inventory |
| 2. Strategy | Map fields & select pattern | Phase 2 | Mapping decisions |
| 3. Construction | Generate Handlebars template | Phase 3 | Template string |
| 4. Validation | Verify syntax & preview output | Phase 4 | Validation report |
| 5. Delivery | Package with instructions | Phase 5 | Complete deliverable |
Process Flow:
code
CSV/JSON → Parse → Analyze → Map → Generate → Validate → Deliver
Module Reference
Core Processing Modules
| Module | Responsibility | Documentation | Key Functions |
|---|---|---|---|
| DataParser | Input format handling | data-parser.md | parseCSV(), parseJSON() |
| FieldAnalyzer | Type inference & analysis | field-analyzer.md | inferType(), detectIssues() |
| TemplateGenerator | Handlebars construction | template-generator.md | buildTemplate(), escapeYAML() |
| Validator | Syntax & correctness checking | validator.md | validateYAML(), testRender() |
Knowledge Base
| Topic | Content | Documentation |
|---|---|---|
| YAML Safety | Character escaping, quoting strategies | yaml-safety.md |
| Handlebars Syntax | Variables, conditionals, iteration | handlebars-syntax.md |
| Type Mapping | Detection algorithms, strategies | type-mapping.md |
| Error Resolution | Common problems & solutions | error-resolution.md |
| Best Practices | Optimization guidelines | best-practices.md |
Template Library
Base Templates
- •base-generic.hbs - Minimal universal structure
- •base-full.hbs - Comprehensive with all features
- •base-minimal.hbs - Bare essentials only
Domain-Specific Templates
- •task-management.hbs - Tasks, projects, status tracking
- •reference-material.hbs - Books, articles, sources
- •people-contacts.hbs - Networking, relationships
- •events-timeline.hbs - Chronological data
- •inventory-catalog.hbs - Items, products, assets
Template Composition: All templates use modular partials from templates/partials/ for maximum reusability.
Common Tasks (Quick Recipes)
| Task | Complexity | Example | Duration |
|---|---|---|---|
| Import simple CSV | ⭐ | 01-task-list-csv | 3 min |
| Handle special characters | ⭐⭐ | 02-contacts-csv | 5 min |
| Process nested JSON | ⭐⭐⭐ | 04-nested-json-projects | 10 min |
| Fix YAML errors | ⭐⭐ | 10-special-chars-fix | 5 min |
| Link entities | ⭐⭐⭐ | 08-complex-relationships | 15 min |
Examples by Complexity
Simple (Start Here)
- •01-task-list-csv - Basic CSV with 5 fields
- •02-contacts-csv - Special character handling
- •03-books-json - Simple JSON structure
Intermediate
- •04-nested-json-projects - 2-level nesting
- •05-array-handling - Repeated elements
- •06-multi-source-merge - Data combination
Advanced
- •07-deep-nested-json - 3+ level hierarchy
- •08-complex-relationships - Entity linking
- •09-computed-fields - Derived values
Troubleshooting
- •10-special-chars-fix - YAML safety
- •11-empty-values - Conditional handling
- •12-type-mismatches - Type corrections
Integration & Extensions
Complementary Obsidian Plugins
- •Templater - Post-import transformations and computed fields
- •Dataview - Query and aggregate imported data
- •QuickAdd - Manual data entry workflows
- •Metadata Menu - Interactive frontmatter management
- •Tag Wrangler - Hierarchical tag organization
Extending This Skill
- •Add custom templates - Place in
templates/with metadata - •Create domain patterns - Model specific industries or use cases
- •Build preprocessors - Transform data before import
- •Develop validators - Add custom validation rules
- •Share examples - Contribute to examples library
Graph Structure Optimization
- •Use
[[Wikilinks]]for entities that should become nodes - •Create MOCs (Maps of Content) for large imports
- •Apply hierarchical tags (e.g.,
project/alpha/task-001) - •Standardize date formats (ISO 8601)
- •Preserve source URLs for traceability
Capabilities & Boundaries
✅ What This Skill Does
- •Parse CSV and JSON data structures
- •Analyze fields with type inference
- •Generate YAML-safe Handlebars templates
- •Validate syntax and preview output
- •Provide complete usage instructions
- •Suggest graph optimization strategies
❌ What This Skill Does NOT Do
- •Perform the actual import (requires user + plugin)
- •Modify source data files
- •Install or configure the plugin
- •Post-process notes after import
- •Fix corrupted YAML in existing notes
- •Real-time data synchronization
User Responsibilities
- •Install JSON/CSV Importer plugin in Obsidian
- •Save generated template to vault
- •Execute import through plugin interface
- •Review imported notes for accuracy
- •Perform any post-import cleanup
Execution Mode
When data is provided, the system automatically:
- •Detects format (CSV vs JSON)
- •Parses structure and analyzes fields
- •Generates field inventory with recommendations
- •Proposes template pattern based on data characteristics
- •Requests confirmation of field mappings
- •Constructs template with YAML safety
- •Validates syntax and generates preview
- •Delivers package with instructions
Response Format:
markdown
## 📊 Data Analysis [Field inventory table with types and recommendations] ## 🎯 Recommended Approach Pattern: [Selected template] Note Names: [Field for filenames] Target Folder: [Suggested location] ## ⚠️ Warnings [Special character issues, data quality concerns] ## ✨ Template [Complete Handlebars template with documentation] ## 👁️ Preview [Sample output from first data row] ## 📋 Instructions [Step-by-step import procedure] ## 🔧 Troubleshooting [Common issues and solutions]
Metadata
Version: 2.0.0 (Modular Architecture) Created: October 2025 Compatibility: Obsidian + JSON/CSV Importer plugin Complexity Level: Intermediate to Advanced Skill Type: Data transformation & template generation
Prerequisites:
- •Obsidian (any recent version)
- •JSON/CSV Importer plugin by "filing 42"
- •Basic understanding of YAML frontmatter
- •Familiarity with Markdown
External Resources:
- •JSON/CSV Importer Plugin - Official repository
- •Handlebars.js Guide - Template syntax reference
- •YAML Specification - Format specification
- •Obsidian Forum - Community support
Version History
See CHANGELOG.md for detailed version history.
Support & Contribution
For Issues:
- •Check examples/troubleshooting/ first
- •Review knowledge/error-resolution.md
- •Consult knowledge/best-practices.md
To Contribute:
- •Add examples to demonstrate new patterns
- •Submit custom templates for specific domains
- •Report edge cases or issues
- •Improve documentation clarity
Reception & Usage
Skill Activation: Simply provide your CSV or JSON data, and the system will immediately begin analysis and template generation.
No explicit invocation required - the skill recognizes data files and structured content automatically.
For best results: Include complete data samples (not fragments) so field analysis can be accurate.
Ready to import your data into Obsidian? Provide your file or paste your data to begin.