obsidian-data-importer
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseObsidian Data Importer
Obsidian 数据导入器
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
当满足以下条件时，该技能将激活：
- 用户上传或提供CSV/JSON数据文件
- 用户请求Obsidian导入协助
- 用户提及"Handlebars"、"JSON/CSV Importer"、"批量导入"或"数据导入"
- 用户希望从结构化数据创建多个Obsidian笔记
Quick Start (3 Steps)
快速开始（3步）
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
立即使用指南：
- 提供数据 - 上传CSV/JSON文件或粘贴内容
- 确认映射 - 查看建议的字段分配
- 获取模板 - 获取完整的Handlebars模板+使用说明
→ 简单示例： 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)obsidian-data-importer/
├── core/ → 处理引擎（5个阶段 + 4个模块）
├── knowledge/ → 参考文档（语法、类型、错误）
├── templates/ → 模板库（8个模板 + 片段）
└── examples/ → 完整演示（12个工作流）Component Diagram
组件图
[Data Input]
↓
[DataParser] ──→ [FieldAnalyzer] ──→ [TemplateGenerator] ──→ [Validator]
↓ ↓ ↓ ↓
Parsed Field Inventory Template String Validation
Structure Report
↓
[InstructionComposer]
↓
Complete Package[Data Input]
↓
[DataParser] ──→ [FieldAnalyzer] ──→ [TemplateGenerator] ──→ [Validator]
↓ ↓ ↓ ↓
解析后结构 字段清单 模板字符串 验证报告
↓
[InstructionComposer]
↓
完整交付包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系统按以下5个连续阶段执行：
| 阶段 | 目标 | 文档 | 输出 |
|---|---|---|---|
| 1. 数据摄入 | 解析并分析数据结构 | Phase 1 | 字段清单 |
| 2. 策略制定 | 映射字段并选择模板模式 | Phase 2 | 映射决策 |
| 3. 模板构建 | 生成Handlebars模板 | Phase 3 | 模板字符串 |
| 4. 验证 | 验证语法并预览输出 | Phase 4 | 验证报告 |
| 5. 交付 | 打包模板与使用说明 | Phase 5 | 完整交付物 |
处理流程：
CSV/JSON → 解析 → 分析 → 映射 → 生成 → 验证 → 交付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() |
| 模块 | 职责 | 文档 | 核心功能 |
|---|---|---|---|
| DataParser | 处理输入格式 | data-parser.md | parseCSV(), parseJSON() |
| FieldAnalyzer | 类型推断与分析 | field-analyzer.md | inferType(), detectIssues() |
| TemplateGenerator | 构建Handlebars模板 | template-generator.md | buildTemplate(), escapeYAML() |
| Validator | 语法与正确性检查 | 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 |
| 主题 | 内容 | 文档 |
|---|---|---|
| YAML安全 | 字符转义、引用策略 | yaml-safety.md |
| Handlebars语法 | 变量、条件语句、迭代 | handlebars-syntax.md |
| 类型映射 | 检测算法、策略 | type-mapping.md |
| 错误解决 | 常见问题与解决方案 | error-resolution.md |
| 最佳实践 | 优化指南 | 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
- base-generic.hbs - 极简通用结构
- base-full.hbs - 包含所有功能的完整模板
- base-minimal.hbs - 仅保留核心要素
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.
- task-management.hbs - 任务、项目、状态跟踪
- reference-material.hbs - 书籍、文章、资料来源
- people-contacts.hbs - 人脉、关系管理
- events-timeline.hbs - 时间线数据
- inventory-catalog.hbs - 物品、产品、资产
模板构成： 所有模板都使用templates/partials/中的模块化片段，以实现最大程度的复用。
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 |
| 任务 | 复杂度 | 示例 | 耗时 |
|---|---|---|---|
| 导入简单CSV | ⭐ | 01-task-list-csv | 3分钟 |
| 处理特殊字符 | ⭐⭐ | 02-contacts-csv | 5分钟 |
| 处理嵌套JSON | ⭐⭐⭐ | 04-nested-json-projects | 10分钟 |
| 修复YAML错误 | ⭐⭐ | 10-special-chars-fix | 5分钟 |
| 关联实体 | ⭐⭐⭐ | 08-complex-relationships | 15分钟 |
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
- 01-task-list-csv - 包含5个字段的基础CSV
- 02-contacts-csv - 特殊字符处理
- 03-books-json - 简单JSON结构
Intermediate
中级示例
- 04-nested-json-projects - 2-level nesting
- 05-array-handling - Repeated elements
- 06-multi-source-merge - Data combination
- 04-nested-json-projects - 2级嵌套结构
- 05-array-handling - 重复元素处理
- 06-multi-source-merge - 数据合并
Advanced
高级示例
- 07-deep-nested-json - 3+ level hierarchy
- 08-complex-relationships - Entity linking
- 09-computed-fields - Derived values
- 07-deep-nested-json - 3级及以上层级结构
- 08-complex-relationships - 实体关联
- 09-computed-fields - 派生值处理
Troubleshooting
故障排除示例
- 10-special-chars-fix - YAML safety
- 11-empty-values - Conditional handling
- 12-type-mismatches - Type corrections
- 10-special-chars-fix - YAML安全问题
- 11-empty-values - 空值条件处理
- 12-type-mismatches - 类型修正
Integration & Extensions
集成与扩展
Complementary Obsidian Plugins
互补的Obsidian插件
- 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
- Templater - 导入后转换与计算字段
- Dataview - 查询与聚合导入的数据
- QuickAdd - 手动数据录入工作流
- Metadata Menu - 交互式前置元数据管理
- Tag Wrangler - 层级标签管理
Extending This Skill
扩展该技能
- Add custom templates - Place in with metadata
templates/ - 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
- 添加自定义模板 - 将模板放入目录并添加元数据
templates/ - 创建领域模式 - 针对特定行业或用例建模
- 构建预处理器 - 在导入前转换数据
- 开发验证器 - 添加自定义验证规则
- 分享示例 - 为示例库贡献内容
Graph Structure Optimization
图谱结构优化
- Use for entities that should become nodes
[[Wikilinks]] - 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
- 对需要成为节点的实体使用
[[维基链接]] - 为大型导入创建MOC（内容地图）
- 应用层级标签（例如：）
project/alpha/task-001 - 标准化日期格式（ISO 8601）
- 保留来源URL以确保可追溯性
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
- 解析CSV和JSON数据结构
- 通过类型推断分析字段
- 生成YAML安全的Handlebars模板
- 验证语法并预览输出
- 提供完整的使用说明
- 建议图谱优化策略
❌ 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
- 执行实际导入操作（需用户配合插件完成）
- 修改源数据文件
- 安装或配置插件
- 导入后处理笔记
- 修复现有笔记中损坏的YAML
- 实时数据同步
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
- 在Obsidian中安装JSON/CSV Importer插件
- 将生成的模板保存到库中
- 通过插件界面执行导入
- 检查导入笔记的准确性
- 执行导入后的清理工作
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
undefined当提供数据时，系统将自动执行以下操作：
- 检测格式（CSV或JSON）
- 解析结构并分析字段
- 生成字段清单及建议
- 根据数据特征推荐模板模式
- 请求确认字段映射
- 构建YAML安全的模板
- 验证语法并生成预览
- 交付包含说明的完整包
响应格式：
markdown
undefined📊 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]
[带文档的完整Handlebars模板]
👁️ Preview
👁️ 预览
[Sample output from first data row]
[第一行数据的示例输出]
📋 Instructions
📋 操作说明
[Step-by-step import procedure]
[分步导入流程]
🔧 Troubleshooting
🔧 故障排除
[Common issues and solutions]
undefined[常见问题与解决方案]
undefinedMetadata
元数据
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
版本： 2.0.0（模块化架构）
创建时间： 2025年10月
兼容性： Obsidian + JSON/CSV Importer插件
复杂度： 中级到高级
技能类型： 数据转换与模板生成
前置条件：
- Obsidian（任意最新版本）
- "filing 42"开发的JSON/CSV Importer插件
- 基本了解YAML前置元数据
- 熟悉Markdown语法
外部资源：
- JSON/CSV Importer Plugin - 官方仓库
- Handlebars.js Guide - 模板语法参考
- YAML Specification - 格式规范
- Obsidian Forum - 社区支持
Version History
版本历史
See CHANGELOG.md for detailed version history.
详细版本历史请查看CHANGELOG.md。
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
问题排查：
- 首先查看examples/troubleshooting/
- 查阅knowledge/error-resolution.md
- 参考knowledge/best-practices.md
贡献指南：
- 添加示例以展示新模式
- 提交针对特定领域的自定义模板
- 报告边缘情况或问题
- 提升文档清晰度
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.
技能激活： 只需提供您的CSV或JSON数据，系统将立即开始分析并生成模板。
无需显式调用 - 该技能可自动识别数据文件和结构化内容。
最佳实践： 提供完整的数据样本（而非片段），以便准确分析字段。
准备好将数据导入Obsidian了吗？请提供您的文件或粘贴数据以开始。