Tetromino — Frequently Asked Questions

Quick answers to the most common questions about Tetromino’s behavior, security, and limitations.

Table of Contents

  1. Why is import manual and not automatic?
  2. Can Tetromino sync changes back to Are.na?
  3. What happens if I delete a note imported by Tetromino?
  4. How do I update settings without re-importing all channels?
  5. What Are.na content is supported (images, videos, links, etc.)?
  6. How do I troubleshoot import failures?
  7. Can I use Tetromino offline?
  8. Is my Are.na token secure?

Why is import manual and not automatic?

Tetromino is manual by default so you remain in full control of when your vault changes. Obsidian is a local-first, user-controlled environment, and unexpected background modifications can be disruptive while you are writing or reviewing notes.

Manual imports also:

If you do want automation, you can opt in:

Both are disabled by default. See [[ADR-002]] for the full architectural rationale.

Can Tetromino sync changes back to Are.na?

No. Tetromino is a one-way importer only: Are.na → Obsidian. Any edits you make to imported notes inside your vault are never pushed back to Are.na.

This is an intentional design choice. Are.na is the source of truth; Obsidian is the destination. Two-way sync would introduce complex conflict-resolution logic, risk overwriting Are.na content, and violate the principle of deterministic, predictable output.

If you need to preserve changes made in Obsidian, keep them in a separate note or use Obsidian’s note-linking features to reference the imported block without modifying it. See [[ADR-001]] for the detailed decision record.

What happens if I delete a note imported by Tetromino?

The note is removed from your vault, but Tetromino does not track local deletions. The next time you run an import, the note will be recreated if the block still exists on Are.na.

If you want to stop a block from being re-imported, you have two options:

  1. Remove the block from Are.na (if you no longer want it anywhere).
  2. Exclude the block class in Tetromino settings (e.g., add Image to Exclude block classes if you no longer want image blocks imported).

There is no “delete and remember” feature because Tetromino does not maintain a local deletion ledger. See [[ADR-001]] for why auto-deletion was also rejected.

How do I update settings without re-importing all channels?

Simply change the setting and run “Import all channels now” again. Tetromino compares the planned Markdown output against the existing file content using a content hash. Only files whose rendered output actually changes are rewritten; the rest are skipped.

This means:

You can verify this behavior by running “Preview import (dry-run)” first. The Sync Summary modal will show exactly which notes would be updated, created, or skipped.

What Are.na content is supported (images, videos, links, etc.)?

Tetromino supports all standard Are.na block classes:

Block Class Behavior
Text Rendered as Markdown (Are.na’s text is converted to Markdown where possible).
Image Rendered according to the Image handling setting: download to vault, embed via URL, or external link.
Link Rendered as a Markdown link. The source URL is preserved and also stored in frontmatter.
Media Treated similarly to attachments; rendered based on Attachment handling settings.
Attachment Downloaded or linked based on Attachment handling (e.g., PDFs, audio files).
Channel Rendered as a channel block with a link to the Are.na channel. Optional preview image can be inserted.

All block types receive metadata in YAML frontmatter (ID, class, URL, etc.) unless Add frontmatter is disabled.

You can optionally skip specific block classes using the Exclude block classes setting (comma-separated list, e.g., Image, Media).

How do I troubleshoot import failures?

Follow this checklist:

  1. Enable Debug logging in Tetromino settings.
  2. Open the Obsidian Developer Console (Cmd/Ctrl + Shift + I).
  3. Run the import again and watch for [arena-sync] log lines.
  4. Check the Sync Summary modal for per-channel or per-block errors.
  5. Review Are.na/import-history.md in your vault for a timestamped log of past imports.

Common failure patterns:

Symptom Likely Cause Fix
401 Unauthorized Invalid or expired Are.na token Re-generate your token and click Verify in settings.
404 Not Found Channel does not exist or is private Check the slug and ensure your token has access.
429 Too Many Requests Are.na rate limiting Wait a moment and retry; Tetromino backs off automatically.
Network timeout Poor connection or large channel Try again later or start with a smaller channel.
Vault permission denied Path is outside vault or folder is read-only Ensure the target folder is inside your vault and writable.
Template render error Invalid custom template syntax Set templateEnabled: false in data.json temporarily to confirm, then fix syntax.

For a deeper guide, see [[TROUBLESHOOTING]].

Can I use Tetromino offline?

No. Tetromino requires an active internet connection to fetch channel metadata, block contents, and attachments from the Are.na API. There is no local cache of Are.na data that persists across sessions.

Once files are imported, the resulting Markdown notes and downloaded attachments live entirely in your vault and are available offline. However, you cannot run new imports or updates without connectivity.

Is my Are.na token secure?

Yes, within the constraints of Obsidian’s plugin architecture:

Best practices:

For full security practices, see SECURITY.md.

Still Have Questions?

If your question is not answered here:

Popular discussion topics are periodically summarized and added to this FAQ. If you find a question being asked repeatedly, feel free to open a PR adding it to this document.