Add Reflect JSON importer by rossbrg · Pull Request #509 · obsidianmd/obsidian-importer

rossbrg · 2026-02-27T19:08:16Z

Fixes #248.

This adds a native Reflect (.json) importer so people can move from Reflect to Obsidian without relying on HTML export.

The issue describes formatting loss when importing Reflect via HTML. This importer reads Reflect's JSON export directly and converts the ProseMirror document model to Markdown.

What is included

New ReflectImporter wired into the importer list (Reflect (.json)).
Conversion support for common Reflect content:
- headings, paragraphs, blockquotes, horizontal rules, code blocks, embeds
- bullet lists, task lists, and legacy list nodes
- backlinks (including aliases), tags, and inline formatting marks
- images as embeds (with optional local download)
Import options in the UI:
- download attachments (opt-in)
- add YAML tags
- add YAML created/updated timestamps
- add YAML title
Reflect notes are written with preserved note timestamps (ctime/mtime).

Hardening work from real export edge cases

Note filename collision handling is deterministic, while backlink targets stay stable.
Backlink labels with ], |, or \\ fall back to Markdown link form when wiki-link syntax would be unsafe.
Nested list handling preserves non-paragraph blocks inside list items (for example headings, code blocks, and blockquotes).
Attachment download handling avoids path collisions and deduplicates repeated image URLs across notes.
Reflect image proxy URLs (reflect.academy/_next/image) are unwrapped to download the original asset URL.
Import toggle values are initialized and snapshotted at import start to avoid state drift mid-run.

Files and fixtures

New importer and converter:
- src/formats/reflect-json.ts
- src/formats/reflect/convert.ts
- src/formats/reflect/models.ts
Registration and metadata updates:
- src/main.ts
- manifest.json
- README.md
Regression fixtures:
- tests/reflect/sample-reflect-export.json
- tests/reflect/hardening-edge-cases.json

Guideline alignment

Implemented in TypeScript with no new runtime dependencies.
Importer UI is added through the existing modal/settings pattern.
Follows the existing importer architecture (FormatImporter + registration in main.ts).
Kept import processing sequential to avoid concurrency-related memory risk.

Testing

npm run build

The downloadAttachments toggle is snapshotted at import start (here) with a comment about preventing mid-import drift, but tagsFrontmatter, dateFrontmatter, and titleFrontmatter are read directly from this throughout the loop (lines 265, 282, 285, 289).

Either all four settings should be snapshotted for consistency, or none of them need to be — the import modal presumably isn't interactive while the import is running.

Good catch, all four settings are snapshotted at import start now

avi-cenna · 2026-03-16T15:19:22Z

@rossbrg Thanks for your work on this; I'm currently in the process of importing Reflect Notes into Obsidian (just using a temporary Python script for the time being).

- Revert .gitignore to upstream state (remove personal dev entries) - Remove duplicate importer.init() call from main.ts - Move this.init() into FormatImporter base constructor - Use truncateText utility with 'Untitled' fallback for note titles - Wrap JSON parsing in try/catch with structural validation - Use FrontMatterCache type, include note.id unconditionally - Snapshot all four settings consistently at import start - Add retry/backoff for image downloads (max 4 attempts, exponential delay) - Pass human-readable error messages to reportFailed() - Remove unused depth field from ConvertContext - Fix ordered list numbering and nested list handling Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Extract sanitizeFileName into standalone src/sanitize-file-name.ts to break the transitive obsidian dependency, enabling Node.js test imports. Wire up node:test + esbuild bundling with a smoke test for convertDocument.

Change hardBreak output from bare '\n' to '<br>\n' in both convertNode (block-level) and convertInline paths so forced line breaks render correctly in Obsidian/CommonMark.

Add text.trim() guards and skippedContent flag to all three list serializers so tag-only items produce no bare bullets. Archived annotations are preserved since the guard checks after appending the  comment.

Add prefixFirstLine helper so headings as first children of bullet and legacy list items appear on the same line as the prefix (e.g. "- ### Heading") instead of on a separate indented line. Task list items are intentionally unchanged since heading semantics don't work with checkbox prefixes.

rossbrg · 2026-03-19T04:40:41Z

@tgrosinger Just pushed a follow-up pass for the review comments, appreciate the help.

This removes the local .gitignore changes, drops the extra importer.init() call, switches title truncation to truncateText, adds an Untitled fallback, validates the Reflect JSON before import, and makes the reportFailed() messages readable while still logging the full error.

I also changed the frontmatter object to FrontMatterCache, added id to frontmatter, snapshotted all four import settings the same way, and added retry/backoff handling for attachment downloads.

While testing this against my own Reflect export, I ran into a few small converter issues and fixed them here too: hard breaks now render as
, tag-only list items are skipped when inline tags are stripped, legacy ordered lists keep their numbering, and headings at the start of a list item stay on the same bullet instead of creating a blank one.

sigrunixia · 2026-03-26T19:36:59Z

@tgrosinger When this is merged, please merge obsidianmd/obsidian-help#1039 as well.

rossbrg added 7 commits February 26, 2026 23:43

feat: add Reflect Notes JSON importer

910f956

Fix Reflect attachment path collisions

1a720f3

Refine Reflect import conversion and fixtures

13173d2

Default Reflect attachment downloads to opt-in

1ef9689

Stabilize Reflect attachment toggle state at import time

f87c50e

Initialize importers after construction to fix toggle defaults

164ffed

This was referenced Feb 27, 2026

docs: add Reflect import help page obsidianmd/obsidian-help#1039

Open

docs: add Reflect import help page rossbrg/obsidian-help#1

Closed

tgrosinger reviewed Mar 13, 2026

View reviewed changes

rossbrg and others added 7 commits March 16, 2026 23:27

feat: extract sanitizeFileName and add node:test infrastructure

2df23f0

Extract sanitizeFileName into standalone src/sanitize-file-name.ts to break the transitive obsidian dependency, enabling Node.js test imports. Wire up node:test + esbuild bundling with a smoke test for convertDocument.

fix: emit <br> for hard breaks in Reflect converter

24ac0d8

Change hardBreak output from bare '\n' to '<br>\n' in both convertNode (block-level) and convertInline paths so forced line breaks render correctly in Obsidian/CommonMark.

fix: drop tag-only list items when stripInlineTags is enabled

36c2510

Add text.trim() guards and skippedContent flag to all three list serializers so tag-only items produce no bare bullets. Archived annotations are preserved since the guard checks after appending the  comment.

Trim Reflect test harness

10faf6d

Restore Reflect fixture files

a18e871

+              	idToSubject: Map<string, string>;
+              	tags: Set<string>;
+              	images: ImageInfo[];
+              	depth: number;

+              						note.subject,
+              						convertOptions,
+              					);
+              					const outputPath = idToOutputPath.get(note.id);

               # Exclude files specific to personal development process
               .hotreload
               .devtarget

               		if (selectedId && importers.hasOwnProperty(selectedId)) {
               			let importer = this.importer = new selectedImporter.importer(this.app, this);
+              			importer.init();

+              	titleFrontmatter: boolean;
+              	init() {
+              		// Initialize defaults in init() because FormatImporter calls init() from its constructor.


		const MAX_FILENAME_LENGTH = 200;

		function truncateTitle(title: string): string {

+              					// Build frontmatter
+              					let content = result.markdown;
+              					const frontMatter: Record<string, any> = {};

	const frontMatter: Record<string, any> = {};
	const frontMatter: FrontmatterCache = {};

+              		if (note.daily_at) {
+              			return moment(note.daily_at).format(userDNPFormat);
+              		}
+              		return truncateTitle(note.subject);

	return truncateTitle(note.subject);
	return truncateTitle(note.subject).trim() \|\| 'Untitled';

+              		};
+              	}
+              	private async downloadImage(

+              	async import(ctx: ImportContext) {
+              		// Snapshot option values for this run so they can't drift mid-import.
+              		const shouldDownloadAttachments = this.downloadAttachments === true;

Conversation

rossbrg commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is included

Hardening work from real export edge cases

Files and fixtures

Guideline alignment

Testing

Related

Uh oh!

tgrosinger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avi-cenna commented Mar 16, 2026

Uh oh!

rossbrg commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sigrunixia commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rossbrg commented Feb 27, 2026 •

edited

Loading

rossbrg commented Mar 19, 2026 •

edited

Loading