obsidian-data-importer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian 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
```
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

添加自定义模板 - 将模板放入
```
templates/
```
目录并添加元数据
创建领域模式 - 针对特定行业或用例建模
构建预处理器 - 在导入前转换数据
开发验证器 - 添加自定义验证规则
分享示例 - 为示例库贡献内容

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

对需要成为节点的实体使用
```
[[维基链接]]
```
为大型导入创建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

[常见问题与解决方案]

undefined

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

版本： 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数据，系统将立即开始分析并生成模板。

无需显式调用 - 该技能可自动识别数据文件和结构化内容。

最佳实践： 提供完整的数据样本（而非片段），以便准确分析字段。