Tetromino

Deterministic, one-way import from Are.na into your Obsidian vault.

Tetromino brings channels, blocks, metadata, and attachments into your vault as stable Markdown notes. It is designed for clarity and control: same input, same output, with no background jobs and no push-back to Are.na.

API compatibility targets the current Are.na REST API v3 documentation: https://www.are.na/developers/explore.

Quick Navigation

• For users: User Guide | Settings Reference | FAQ | Troubleshooting
• For developers: Developer Guide | API Design | ADRs
• Project docs: README | CHANGELOG | ROADMAP | PHILOSOPHY | SECURITY | CONTRIBUTING | FIRST_CONTRIBUTION | CODE OF CONDUCT | CONTRIBUTORS | MAINTAINERS | COMMUNITY HEALTH | COMMUNITY CELEBRATION | COMMUNITY SURVEY
• CI and releases: CI workflow | Release workflow | Release template
• Planning and reporting: Project board | Bug report template
• Community: GitHub Discussions

What This Plugin Is (and Is Not)

• It is a deterministic importer from Are.na to Obsidian.
• It is vault-first, manual, and transparent.
• It is not a two-way sync engine.
• It does not auto-delete local notes when remote blocks disappear.
• Background sync is optional and disabled by default (you can enable sync-on-startup and periodic intervals in settings).

Feature Highlights

Import Engine

• Imports mapped Are.na channels into mapped vault folders.
• Supports full pagination for large channels (not limited to the first 100 blocks).
• Retries transient upstream failures (429, 500, 502, 503, 504) with backoff.
• Shows status bar progress for channels and block pages.
• Learn more: User Guide — First Import | API Design — Retry Logic

Deterministic Writing

• Writes stable Markdown notes for blocks.
• Rewrites existing notes when remote block content changes.
• Writes channel index notes and a master overview note (Are.na/overview.md).
• Supports channel index naming mode for Folder Note compatibility (index.md or folder-name note).
• Sync summary modal with per-file diff viewer after every import or dry-run.
• Learn more: ADR-003 — Deterministic Output | User Guide — Dry-Run

Block Enrichment (Optional)

• Banner frontmatter field for Banners plugin compatibility (enabled, custom key, source priority).
• Block description in frontmatter (arena_description).
• Block comments in a dedicated Comments section.
• Connected channel list (This block appears in) with external links.
• Best-effort preview image for Channel blocks.
• Learn more: Settings Reference — Enrichments

Template Engine

• Optional custom template system for full control over generated Markdown.
• Handlebars-like syntax: {{title}}, {{#if image}}...{{/if}}, {{#each comments}}...{{/each}}.
• Template variables include: title, id, class, content, description, image, arena_url, source_url, channel_title, channel_slug, comments, connected_channels.
• Toggle between default output and custom template in settings.
• Learn more: Settings Reference — Templates

Attachments and Media

• Image handling modes: download, embed, link.
• Non-image attachment handling modes: download, link.
• Downloaded attachment rendering: link or embed.
• Storage modes: channel-local, global folder, custom folder.
• Per-channel storage overrides.
• Migration tools with preview, diff, execution, and history logging.
• Learn more: Settings Reference — Attachments | User Guide — Attachment Handling

Channel Management

• Import my channels to bulk-create mappings from your Are.na account.
• Auto-enable imported channels toggle for granular control.
• Backup, restore, and reset tools for channel mappings.
• Restore from file... to pick a specific historical backup instead of only the latest.
• Default mapping target folder: Are.na/<channel-slug> unless overridden.
• Learn more: User Guide — Channel Management

Commands

Available from the Obsidian Command Palette (Ctrl/Cmd + P):

• Import all channels now
• Preview import (dry-run)
• Import current channel
• Preview current channel import (dry-run)
• Open channel on Are.na
• Preview attachment migration
• Run attachment migration

Settings Overview

• API token with verify action.
• Block file naming (title, id, title-id).
• Banner frontmatter options (enabled, field name, image source priority).
• Optional enrichments (description, comments, connected channels, channel preview image).
• Image and attachment rendering controls.
• Attachment storage controls (global defaults and per-channel overrides).
• Template engine toggle and custom template string.
• Frontmatter, notifications, and debug logging toggles.
• Channel mapping management and migration actions.
• Full reference: Settings Reference

How Import Works

1. Create mappings manually or use Import my channels in settings.
2. Run Import all channels now or a dry-run preview command.
3. The plugin fetches channel metadata and all paginated blocks from Are.na.
4. It normalizes each block into deterministic Markdown output.
5. It compares planned output against existing vault files.
6. It writes updated notes, indexes, and overview files.
7. It shows a sync summary with diffs for changed files.
8. It records import state and timestamps in plugin data.

Detailed walkthrough: User Guide — First Import

Documentation

For Users

New to Tetromino? Start here:

• User Guide — Overview, installation, first import walkthrough, dry-run explanation, settings reference, troubleshooting, and FAQ.
• Settings Reference — Every setting explained with defaults, examples, and advanced template syntax.
• Troubleshooting — Common errors, solutions, and how to collect logs for bug reports.
• FAQ — Answers to the most common questions about sync behavior, security, and offline usage.

For Developers

Want to contribute or understand the internals?

• Developer Guide — Architecture overview, module guide, code style, and how to add features or tests.
• API Design — Are.na API integration details, pagination, rate limiting, retry logic, and response normalization.
• ADRs — Architecture Decision Records documenting key design choices (one-way import, manual triggers, deterministic output, Markdown-only format, dry-run previews).

Installation

From Obsidian Community Plugins (Recommended)

1. Open Settings → Community Plugins in Obsidian.
2. Search for "Tetromino" in the Community Plugins browser.
3. Click Install, then Enable.
4. Open Tetromino settings and add your Are.na API token.
5. Add at least one channel mapping, or run Import my channels.

Plugin directory: https://community.obsidian.md/plugins/tetromino

Manual Installation

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Place them into <your-vault>/.obsidian/plugins/Tetromino/.
3. Enable Tetromino in Obsidian Community Plugins.
4. Open settings and add your API token.
5. Add at least one channel mapping, or run Import my channels.

Development

npm install
npm run dev

Build:

npm run build

Build output:

• main.js in the repository root.
• dist/<plugin-id>-<version>.zip with main.js, manifest.json, and styles.css.

Quality checks:

npm run lint
npm test

Contributor resources: Developer Guide | CONTRIBUTING | First-Time Contributor Guide

Companion Tools

If you are looking for a similar tool that imports Raindrop.io bookmarks instead of Are.na blocks, check out Make It Rain, the sister-tool to this plugin built on the same core sync engine and template parsing logic.

Security

• API tokens are masked in the UI and stored in Obsidian plugin data.
• The plugin collects no telemetry.
• External requests are limited to Are.na API and direct file URLs required for configured downloads.

For details, see SECURITY.md.

Troubleshooting

Invalid API token

1. Generate a token at https://www.are.na/developers/personal-access-tokens.
2. Paste it into settings and click Verify.
3. Ensure the token includes read access.

Slow imports or timeouts

• Large channels can take several minutes due to API rate limits and pagination.
• Enable debug logging to monitor progress.
• Start with a smaller channel to verify configuration.

Notes are not updating

• Run Import all channels now from the Command Palette.
• Confirm the channel mapping is enabled in settings.

Assets are not downloading

• Set image or attachment handling to Download to vault.
• Confirm attachment folders are valid and writable.
• Verify disk space.

Fewer blocks than expected

• Verify the channel mapping is enabled in settings.
• Check that the channel is public (or your token has access to private channels).
• Enable debug logging to see pagination progress in the console.

Full troubleshooting guide: docs/TROUBLESHOOTING.md

Contributors

Tetromino is maintained by Jonathan J Wagner. We welcome contributions of all kinds — code, documentation, bug reports, and community support.

• Want to contribute? See FIRST_CONTRIBUTION.md for a step-by-step guide.
• Looking for a first issue? Browse good first issue labels.
• All contributors: See CONTRIBUTORS.md for the full list.

First-time contributors are thanked by name in release notes.

License

MIT

Release History

See CHANGELOG.md for a complete version history.

• v1.1.0 (2025-06-26) — Sync summary modal, overview note generation, attachment migration, channel management tools, banner frontmatter, block enrichment, channel index enhancements, background sync, and numerous security and performance fixes.
• v1.0.0 (2025-01-15) — Initial stable release with deterministic Are.na → Obsidian import, pagination, retries, stable Markdown output, and attachment support.