Obsidian - Create a Handlebar Template from JSON (JSON/CV Importer)

A practical workflow for turning large JSON spell datasets into one Obsidian note per item hinges on writing a correct Handlebars template that matches the JSON’s structure—especially when fields are nested or repeat. The payoff is speed and control: once the template is right, importing hundreds or even thousands of spells becomes largely “set and forget,” with Obsidian notes generated in the layout the user wants.

The process starts with installing the “Json CSV importer” plugin (by filing 42) and using its Handlebars integration. The template isn’t generic: it must reflect how the JSON is shaped. For a concrete example, the walkthrough uses 5eTools data from GitHub (specifically the “spells-php.json” file inside a downloaded zip). That file contains thousands of lines, with each spell represented as a nested object keyed by spell name (e.g., “acid-splash”). The goal is to extract key fields—like name, level, school, casting time, range, and descriptive text—into a single note per spell.

To learn Handlebars syntax safely, the walkthrough leans on handlebarsjs.com’s live demo. Simple fields work via direct lookups like {{name}} and {{level}}. But nested objects require precise paths. For instance, casting time may be stored as time.number and time.unit, so a naive {{time}} returns “object object.” The template must drill down to the right subfields, and it must handle capitalization using the plugin’s built-in helpers (not the demo site’s limited environment). The walkthrough also highlights a common gotcha: capitalization and other helpers available in the Obsidian plugin won’t necessarily behave the same in the Handlebars demo.

Repeating structures introduce another layer. When JSON contains arrays (or “unknown counts” of items), the template needs looping constructs. The walkthrough uses each to iterate over time entries (so multiple casting-time actions can be rendered) and over class lists (so every class that can cast a spell becomes a comma-separated list). Descriptions are also treated as collections: spell text often arrives in multiple entries, so rendering requires looping through entries rather than assuming a single blob of text.

After building a template, the workflow tests with a small JSON subset (a manually extracted few spells saved as testimport.json). In Obsidian, the importer is configured with the JSON file, the Handlebars template, the field to use as the note name (name), and options like overriding existing notes. The resulting notes are then checked in reading mode, including optional styling via the ITS theme.

Finally, the walkthrough addresses cleanup and maintainability. Some outputs may include ugly placeholders like “object object” when a field path is wrong or a helper isn’t applied correctly. The suggested fix is iterative refinement: import a small sample, adjust the template line-by-line, then re-import. For broader cleanup, it recommends using find/replace across the generated notes (e.g., removing repeated “object object” artifacts) while being careful not to break other content.

The overall message is that JSON-to-notes isn’t about memorizing Handlebars—it’s about mapping the template to the JSON’s nesting and repetition patterns, then iterating until the import output matches the desired Obsidian note structure.