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
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
[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:
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:
## 📊 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.