Tetromino Settings Reference

This document describes every setting available in Tetromino, including default values, allowed values, and examples. Use it alongside the [[USER_GUIDE]] for setup help and the [[FAQ]] for common questions.

Table of Contents

1. How Settings Are Stored
2. Authentication
3. Content Rendering
4. Notifications and Logging
5. Channel Management
6. Channel Mappings
7. Attachment Migration
8. Advanced: Custom Templates
9. Backup and Restoration
10. Settings Migration Between Versions

How Settings Are Stored

Tetromino stores all settings in Obsidian’s plugin data store (data.json inside <vault>/.obsidian/plugins/tetromino/). This file is managed by Obsidian’s Plugin.loadData() / Plugin.saveData() API and is not meant to be edited by hand for routine changes — except advanced template fields, which are not yet in the Settings UI.

Channel mappings, sync records, and your API token live in the same data blob. You can back up and restore channel mappings independently using the built-in backup buttons (see Backup and Restoration).

Security note: Your Are.na token is stored locally in Obsidian’s plugin data. It is never transmitted outside the Are.na API and is masked in the UI.

Authentication

Click Verify in settings to validate the token before running imports.

Content Rendering

These settings control how imported blocks are converted into Markdown notes.

Default Template String

When Template engine is enabled and no custom string is set, Tetromino uses this default:

---
title: "{{title}}"
arena_id: {{id}}
arena_class: {{class}}
arena_url: "{{arena_url}}"
{{#if description}}description: "{{description}}"{{/if}}
---

# {{title}}

{{content}}

{{#if description}}
## Description
{{description}}
{{/if}}

Notifications and Logging

Channel Management

Actions (Buttons in Settings)

Channel Mappings

Each mapping links one Are.na channel to one vault folder. Mappings are stored in the channelMappings array.

Mapping Fields

Example: Setting Up a Real Channel Mapping

Suppose you have an Are.na channel at https://www.are.na/channel/design-inspiration.

1. In Tetromino Settings, scroll to Channel mappings.
2. Click + Add mapping.
3. Enter the slug: design-inspiration.
4. Leave Local folder blank to use the default Are.na/design-inspiration.
5. Ensure the toggle is enabled.
6. (Optional) Set Attachment storage override to Global folder if you want all attachments in one place.

After saving, run “Import all channels now” from the Command Palette.

Per-Channel Attachment Override Example

If you want most channels to store attachments in Are.na/Attachments but one channel to keep its files locally:

• Global Attachment storage location: Global folder
• For the specific mapping, set Attachment storage override: With channel notes

Attachment Migration

When you change Attachment storage location or Global attachment folder, existing downloaded files may need to move. Tetromino detects these changes and offers migration.

Migration logs are written to Are.na/migration-history.md.

Advanced: Custom Templates

The template engine lets you control the exact Markdown output for every block using a Handlebars-like syntax.

Enabling Templates

Templates are configured via the plugin data store (data.json). Set templateEnabled: true and provide a templateString. The default template string is shown in Content Rendering.

UI note: Template settings are not exposed in the Settings tab UI yet. Enable them by editing <vault>/.obsidian/plugins/tetromino/data.json while Obsidian is closed: set templateEnabled: true and optionally templateString. The plugin id folder is lowercase tetromino.

Available Template Variables

Template Syntax

• Variables: {{variableName}}
• Conditionals: {{#if variable}}...{{/if}} or {{#if variable}}...{{else}}...{{/if}}
• Loops: {{#each arrayVar}}...{{/each}}

Template Example

---
title: "{{title}}"
arena_id: {{id}}
source: "{{source_url}}"
{{#if description}}description: "{{description}}"{{/if}}
---

# {{title}}

{{#if image}}![{{title}}]({{image}}){{/if}}

{{content}}

{{#if connected_channels}}
## Also appears in
{{#each connected_channels}}
- {{title}}
{{/each}}
{{/if}}

Tip: The rendered output is sanitized for security. Active code blocks (e.g., dataviewjs, templater) are neutralized to prevent accidental execution.

Backup and Restoration

Backing Up Settings

Tetromino does not back up the entire data.json automatically, but it does back up channel mappings:

1. Open Tetromino Settings.
2. Under Channel management, click Backup channel mappings.
3. A JSON file is created in Are.na/channel-mapping-backups/mappings-<timestamp>.json.

The backup file contains:

{
  "createdAt": "2026-06-26T10:00:00.000Z",
  "mappingCount": 3,
  "channelMappings": [ /* ... */ ]
}

Restoring Mappings

• Restore latest backup: Replaces current mappings with the most recent file in Are.na/channel-mapping-backups/.
• Restore from file: Choose a specific backup JSON file anywhere in your vault.

Full Settings Backup

To back up all settings (including templates, toggles, and tokens):

1. Close Obsidian.
2. Copy <vault>/.obsidian/plugins/tetromino/data.json to a safe location.
3. Restart Obsidian.

Caution: data.json contains your API token. Store backups securely.

Settings Migration Between Versions

Tetromino includes built-in normalization logic that runs every time settings are loaded. This ensures forward compatibility when new fields are added.

How Migration Works

• On load: loadSettings() merges saved data with DEFAULT_SETTINGS using Object.assign. Missing fields receive their default values automatically.
• Mapping normalization: normalizeMappings() ensures every mapping has attachmentStorageOverride, customAttachmentFolderOverride, and lastAttachmentBase fields, even if they were created by an older version.
• Attachment base snapshots: ensureAttachmentBaseSnapshots() computes and stores the current attachment base path for each mapping so that future storage changes can trigger a migration prompt.

What This Means for Users

• Upgrading is safe: Installing a new version of Tetromino will not corrupt existing settings.
• New fields appear with sensible defaults: You do not need to manually edit data.json after updating.
• Migration prompts appear automatically: If a new version changes how attachments are stored, Tetromino will prompt you to preview or run a migration.

Manual Migration (Rare)

If you need to migrate settings manually (e.g., moving to a new vault):

1. Back up data.json from the old vault.
2. Install Tetromino in the new vault.
3. Close Obsidian and copy the backup into <new-vault>/.obsidian/plugins/tetromino/data.json.
4. Restart Obsidian and verify settings in the UI.

Related Documentation

• [[USER_GUIDE]] — Step-by-step walkthroughs and feature overview.
• [[DEVELOPER_GUIDE]] — Architecture, module guide, and contribution workflow.
• [[API_DESIGN]] — Are.na API integration details.
• [[FAQ]] — Common questions.
• [[TROUBLESHOOTING]] — Error reference and debugging steps.