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

TL;DR

Install the JSON CSV Importer plugin, then use it to connect a CSV dataset to a Handlebars template and generate notes in bulk.

Briefing Cornell Notes

Briefing

Bulk-importing TTRPG data into an Obsidian vault becomes practical once a CSV source is paired with a Handlebars template that maps CSV columns into Obsidian note front matter and body fields. The core payoff: a user can take a dataset such as Pathfinder’s System Reference Document (SRD) magic items and generate hundreds of consistently formatted notes in minutes—fast enough to go from “zero notes” to “a large library” while waiting for something as mundane as a coffee.

The workflow starts by installing the “JSON CSV Importer” community plugin in Obsidian, then sourcing data from the web. A common path is searching for an SRD dataset in CSV form (for example, “Pathfinder SRD csv”), often hosted on GitHub. After downloading the relevant CSV folder (such as “raw/spells” or “raw/magic items”), the user opens the CSV in Excel to confirm the table structure and, when needed, trims the dataset for testing. Column names matter: the importer and Handlebars templates won’t handle spaces or special characters in column headers, so the CSV must be cleaned so headers are compatible.

Next comes template creation. The user creates a dedicated folder for Handlebars templates inside the vault, then writes a template note that mirrors the desired output format for each imported item. The template includes front matter variables (for example, name, aura, cl, slot, weight, group, source, base item, and description), while the visible note body uses Handlebars expressions like {{name}} and {{aura}} to place CSV values into the correct locations. To avoid duplicating logic and to keep the template flexible, the template can also use Obsidian’s DataView plugin with inline queries that pull values from front matter into the body—e.g., referencing fields as this.file.name or this.file.<field> to populate repeated sections.

Once the template is ready, the JSON CSV Importer is used to connect the CSV file to the template. The importer settings include selecting the CSV data source, choosing the template file, and specifying which CSV column becomes the note name (commonly the “name” column). Options like “override existing notes” are important during iteration: the creator runs the import multiple times, fixing template mistakes such as incorrect DataView syntax or mismatched field names (for instance, using “cl” vs “CL” or accidentally leaving a Handlebars field pointing to the wrong column). After a successful import, the resulting notes land in the chosen destination folders (e.g., mechanics and spells), with front matter populated and links working cleanly.

The process isn’t limited to magic items. The same approach can generate monster stat blocks and encounter cards by pairing CSV columns with the TTRPG stat block application’s expected fields, including images named after the monster (e.g., {{name}}.png). When imported notes contain messy characters or formatting artifacts, the creator recommends post-processing with tools like search-and-replace (including regex) in an editor such as Sublime Text. Overall, the method turns scattered web tables into a structured, linkable Obsidian knowledge base with minimal manual typing.

Cornell Notes

A reliable bulk-import method for Obsidian uses the JSON CSV Importer plus a Handlebars template that maps CSV columns into note front matter and body fields. After downloading an SRD dataset (often from GitHub) and cleaning CSV headers to remove spaces/special characters, the template is built to match the desired note layout—using Handlebars variables like {{name}} and {{aura}}. DataView inline queries can further pull front matter values into repeated sections without duplicating logic. Imports are then run from the plugin by selecting the CSV file, the template, and the column used as the note name; iteration is normal when syntax or field mappings are off. The same pattern can generate monsters, spells, and encounter cards, including image filenames derived from {{name}}.

Why do CSV column names need cleaning before building a Handlebars template in Obsidian?

The importer and Handlebars template system won’t support spaces or special characters in column names. That means headers must be edited so they’re simple identifiers (e.g., “full text” becomes “fulltext” or “full_text”-style, depending on what the template expects). If headers aren’t cleaned, Handlebars expressions won’t map correctly and imports will fail or produce blank fields.

How does the template ensure each imported note gets a unique name and correct metadata?

The JSON CSV Importer uses a chosen CSV column (commonly “name”) as the note name. Inside the template, front matter fields are populated using Handlebars variables such as {{name}} and {{aura}}. The result is that each row in the CSV produces a separate note whose front matter matches that row’s values, preserving capitalization and exact text so links and lookups work.

What role does DataView play in the template beyond basic Handlebars substitution?

DataView inline queries can reference values stored in front matter (e.g., this.file.name or this.file.<field>) and inject them into the note body. This is useful when the visible layout needs repeated or computed placement of metadata. It also helps keep the template maintainable, though it introduces another place where syntax errors can break rendering—so testing and iteration matter.

What kinds of mistakes commonly require re-importing and editing the template?

Common issues include mismatched field names (wrong casing like CL vs cl), using the wrong column for a field (e.g., accidentally mapping “cl” into “source”), and DataView syntax errors (like leaving an extra “file.” or using the wrong query structure). The workflow expects trial-and-error: re-run imports with “override existing notes” after fixing the template so the vault reflects the corrected mapping.

How can the same import approach generate monsters with images and encounter triggers?

If a monster CSV includes columns like monster name and image filename base, the template can reference {{name}} to generate fields such as an image path like {{name}}.png. Additional columns can populate encounter trigger text (e.g., “encounter” or “show to players” fields) so the imported notes work with the TTRPG stat block application and player-facing views.

What’s a practical way to clean up messy imported text after the fact?

When imported descriptions include odd symbols or broken line formatting, the creator recommends using a text editor with search-and-replace (often with regex) across the imported notes. For example, replacing a repeated character pattern with a newline or a simpler equivalent can make the notes readable without editing each note manually. Back up before bulk replacements to avoid accidental formatting damage.

Review Questions

What specific constraints on CSV headers affect whether Handlebars variables can map correctly during import?
How do note naming and front matter variables work together to ensure each imported row becomes a correctly linked Obsidian note?
Which two categories of errors most often require re-running the import after template edits (field mapping vs DataView syntax)?

Key Points

1
Install the JSON CSV Importer plugin, then use it to connect a CSV dataset to a Handlebars template and generate notes in bulk.
2
Clean CSV column headers to remove spaces and special characters; template field mapping depends on header names matching exactly.
3
Design a template note that matches the target output layout, using Handlebars variables (e.g., {{name}}, {{aura}}) for repeated fields.
4
Use DataView inline queries when you want body content to pull from front matter values without duplicating logic, but expect syntax debugging.
5
Choose a single CSV column (typically “name”) as the note name so each row becomes a unique, linkable note.
6
Iterate: re-import with “override existing notes” after fixing casing mismatches, wrong column mappings, or DataView query errors.
7
Post-process imported text with search-and-replace (optionally regex) to fix formatting artifacts and odd characters across many notes quickly.

Highlights

A clean Handlebars template turns a CSV table into hundreds of consistently formatted Obsidian notes—fast enough to treat as “bulk library building.”

CSV headers can’t include spaces or special characters; cleaning them is a prerequisite for reliable imports.

DataView inline queries let templates pull values from front matter into the note body, but a small syntax mistake can break rendering.

Using the CSV “name” column as the note name is central to correct linking and predictable vault structure.

Image filenames can be generated from {{name}} (e.g., {{name}}.png), enabling monster pages and player-facing encounters to assemble automatically.

Topics

Obsidian Importer
Handlebars Templates
CSV Data Cleaning
DataView Inline Queries
TTRPG SRD Imports

Mentioned

Josh Plunkett