Pins

Pins are toolbar buttons that activate a layout — they appear as icon buttons in the left side of the app toolbar. Clicking a pin rebuilds the singleton frameset from that pin's saved template, switching the entire window layout at once.

Default Pins

Two built-in pins are configured by default — both activate the same Note Tray provider, pointed at a different directory:

There is no separate Search pin — searching is handled by Pile View, opened from either tray.

These correspond to defaultHeaderLeftPins in the settings schema (headerLeftPins: HeaderLeftPin[]).

Managing Pins (Header Pins Dialog)

Pins are managed through the Header Pins dialog, not through Settings. Open it from the command palette (Mod+K → "Manage header pins").

Adding a Pin

1. Open the Header Pins dialog.

2. Click Add pin at the bottom of the list.

3. Follow the three-step flow: choose a provider (Note Tray, External File Editor, etc.), configure its layout, then set the label and icon. A new Note Tray pin created this way defaults to the inbox/ directory — the two built-in pins are currently the only way to get an archives/ Note Tray pin.

4. The new pin appears at the end of the list and is visible in the toolbar immediately.

Removing a Pin

Click the remove button on a pin row, then confirm in the inline confirmation view. Built-in pins (Inbox, Archives) can be removed from the toolbar — their underlying views remain accessible — and can be re-added later.

Reordering Pins

Drag a pin row to a new position. The toolbar updates instantly to reflect the new order. Keyboard reordering is also supported.

Showing and Hiding Pins

Each pin row has a visibility toggle. Hidden pins stay in the list but do not appear in the toolbar.

Editing a Pin

Click the edit button on a pin row to change the label, icon, or provider-specific configuration (for example, the root and open files on an External File Editor pin).

Pin Data Shape

Each pin is a HeaderLeftPin record with:

• id — stable kebab-case identifier

• label — display label and tooltip text

• iconId — Lucide icon name

• template — a PinTemplate containing the FramesetTree to install on activation

• visible — whether the pin appears in the toolbar

• routeSlug — short random string for the /p/:slug route; null for built-in pins

Pins are stored in headerLeftPins in .zudotext.settings.json. There is no separate pins[] array — the v2 frameset architecture embeds the layout template directly in each pin record.