Carrel

A novel way to view, sort, and study any set of notes — as a column-balancing board of typed reference cards. Carrel turns a folder (or several) of vault notes into a browsable wall of cards you can pin, filter, search, and expand to read in place, without leaving the board.

Carrel works as a full workspace pane, as an inline embed you can drop into any note, and as a custom view for Obsidian Bases. It started as the References tab of the Wayfinder character sheet and now runs on its own — when both are installed, the two integrate.

Installation

From the Community Plugins browser

1. Open Settings → Community plugins.
2. Turn off Restricted mode if it is on.
3. Click Browse, search for Carrel, and click Install.
4. Click Enable.

From BRAT (beta releases)

BRAT (the Beta Reviewers Auto-update Tool) installs and updates pre-release builds ahead of the stable Community Plugins listing.

1. Install BRAT from the Community Plugins browser and enable it.
2. Open the command palette and run BRAT: Add a beta plugin for testing.
3. Enter the repository: alas-poor-ophelia/carrel
4. BRAT downloads the latest release and installs Carrel. Enable it under Settings → Community plugins.
5. To update later, run BRAT: Check for updates to all beta plugins.

Manual

Download main.js, styles.css, and manifest.json from the latest release, and copy them into <your-vault>/.obsidian/plugins/carrel/. Reload Obsidian and enable Carrel.

Quick start

1. Enable Carrel. A book icon appears in the left ribbon — click it (or run Carrel: Open Carrel pane) to open the board.
2. Run Carrel: Create nook from folders and pick one or more folders. A nook is a named board built from those folders' notes.
3. Open the board. Every note becomes a card. Click a card to expand and read it in place; click the star to pin it to the rail at the top.
4. (Optional) Tag a note with category: <name> in its front matter, then create that category under Settings → Carrel to give it a color and icon.

That's the whole loop: point a nook at some folders, then browse, pin, filter, and read.

How it works

Nooks — named boards over folders

A nook is a saved board that reads from one or more vault folders. You can keep several — "Combat rules", "Lore", "Project specs" — each with its own source folders, theme, and display settings. Switching nooks (or setting one active) changes what the pane shows. Your notes are never moved or modified; a nook is just a lens over them.

Cards and the column-balancing board

Each note is rendered as a card. Closed, a card shows its icon, type badge, title, and a short preview of the note's opening blocks — rendered by Obsidian itself, so inline marks, links, lists and callouts read exactly as they do in the note (clamped to four lines). The board lays cards out as a column-balancing masonry — it fits as many columns as your pane is wide (roughly one per 330px, down to a single column in a narrow sidebar pane; or pin the count in the nook's settings) and drops each card into the shortest column so the wall stays even instead of leaving ragged gaps.

Click a card to expand it in place. The full note renders inline (wikilinks, embeds, and markdown all work), and the card claims one to three columns depending on how much content it holds — a one-line note stays narrow; a multi-paragraph entry with a table widens out and flows into reading-width text columns. Opening a card slides its neighbors out of the way; you can have any number open at once and clear them all with Collapse. (Prefer your categories laid out as columns instead of a balanced wall? Switch the nook to the Kanban layout.)

A note that opens with something opaque — a code or plugin block, a note embed, a table, a roll block — shows a small typed badge in its preview instead of the block, plus the prose around it. To render those opening blocks as-is in the preview (a Meta Bind input, an embed, …), add carrel-preview: render to the note's front matter; the preview is still clamped to four lines, so keep such blocks small. A summary front-matter property always wins and is rendered as markdown.

Typed cards

Every card has a type that sets its badge, icon, and accent color. Most types are inferred from the note's structure — write normal Markdown and Carrel recognizes a table, a checklist, a flowchart, and so on. Type badges double as filter chips. See Card types below for the full list and how to structure each kind of content.

Categories

Where types are inferred, categories are yours to define. A note joins a category by declaring it in front matter:

---
category: Deed
---

Under Settings → Carrel you give each category a name, a color (from a curated palette or a custom picker), and an icon (from Obsidian's built-in Lucide set, or RPG Awesome when Wayfinder is installed). Categories drive card tinting, the category section headers on the board, and the category filter chips. Drag the grip to reorder them. Deleting a category leaves your notes' front matter intact — it just stops styling them.

Pinning and the rail

Click the star on any card to pin it. Pinned cards collect in a horizontal rail at the top of the board. Grab a card's grip and drag to reorder the rail; the order is saved per nook. A pin filter chip (★) lets you show only pinned cards.

Search and filters

A fuzzy search box matches across title, category, summary, and body — type aoc and it finds "Aura of Courage", highlighting the matched letters. While searching, the board collapses into a single ranked results section.

Below the search box, filter chips narrow the wall: the pin filter, one chip per category, and one per content type. Selecting several categories (or several types) shows cards matching any of them. Chips only appear for categories and types that actually exist in the current nook.

Keyboard navigation

The board is fully keyboard-drivable:

Kanban layout

Every nook can switch from the masonry Board to a Kanban layout — choose it from the Layout dropdown on the toolbar (the choice is saved per nook). Instead of a balanced wall, your categories become columns (swimlanes) laid out left to right, with each card sitting under its category.

Curating the columns. The columns are yours to choose, with the ＋ Add column button. Its menu lists every category your notes already use and every category you've defined in Settings — plus a New category… entry to spin up a brand-new swimlane on the spot. Remove a column with the × on its header; the notes are untouched, they just stop showing until you add the column back.

Drag to recategorize. Drag a card from one column to another and Carrel writes the new category into the note's front matter — so the move sticks to the note, not just the board. Drop a card into a new, empty column and that category is written onto it. Drag within a column to reorder (saved per nook). Dragging toward a column that's scrolled off-screen auto-scrolls the board to bring it into reach.

Expanding across columns. Open a card and it expands sideways, spanning as many columns as its content needs and flowing the neighbouring swimlanes' cards down to make room — then snapping them back when you collapse it.

Scrolling. A wide board scrolls horizontally — spin the wheel over the column headers, drag the header row, or use the scrollbar — while the columns scroll vertically. Column width is adjustable through Style Settings (Carrel → Kanban column width).

Kanban reads and writes the same category property as the rest of Carrel, so a card's column always reflects its note. In a Bases view, cards can be reordered but not moved between columns — a category write could drop them from the Base's filter.

Card types

Most card types are inferred from a note's structure — you write ordinary Markdown and Carrel recognizes it. A few are declared explicitly in front matter.

A type is a label, not a renderer. It sets the card's badge, icon, accent color, and filter chip, and its section when you group by type. It does not change how the note's content is drawn: a table renders as a table and a callout as a callout whatever the card is called, so two cards that differ only in type show the same preview and the same body. The one exception is image, which shows a cover thumbnail when collapsed.

Declaring a type (optional)

Set type: in front matter to force a card's type, regardless of its content:

---
type: process
---

The built-in types are flowchart, table, formula, lookup (shown as Roll Table), process, quote, image, and reference. They are usually left to inference (or, for image, to a cover property — see Image cards).

For a name of your own — ability, npc, clue — add a custom type in Settings → Carrel → Types, with its own color and icon, then declare it the same way (type: npc). A type: value that is neither a built-in nor one of your custom types is ignored, and the note falls back to inference.

How a type is inferred

When you don't declare one, Carrel chooses a type from the note's blocks, in this order:

Image cards

A note that's mostly a picture — an image embed or two with little other text — renders as an image card: a cover thumbnail when collapsed. Expanded, the body renders through Obsidian exactly as reading view does, so image alt-arguments — theme positioning like |right, size hints like |300 — all apply. Handy for maps, character art, reference shots, and mood boards.

You can also give any note a cover image with a front-matter property, which forces an image card and supplies the thumbnail even when the note has other content:

---
image: "[[ser-aldric.png]]"
---

The property defaults to image, and its name is configurable (Settings → Carrel). It accepts an embed (![[pic.png]]), a wikilink ([[pic.png]]), a bare path or filename, or an external URL — and it doubles as the cover mapping for Bases views, so a Base of notes with cover images renders as a wall of image cards. A cover that isn't also embedded in the body renders bounds-contained at the top of the expanded card.

Fitting the cover. By default (auto) a wide image is cropped to fill the cover box, and a square or tall one is shrunk to fit so nothing is cut off. To choose for one note, set imageScaleType in its front matter: contain (shrink to fit), cover (crop to fill), stretch, or auto. (fit and fill are accepted as older names for contain and cover.)

Sizing the covers on a board. Each board has three settings for the cover's fit and size — in a nook's settings, or in the view options of a Bases view:

• Image fit — Auto, Contain, or Cover, for every note that doesn't set imageScaleType itself.
• Image aspect ratio — the shape of the cover box as height ÷ width, from wide and short to tall. The default is 0.75 (4:3); 1 is square.
• Image max height — a cap on the cover's height, so covers stay small on a wide or single-column board.

Preview under the cover. When the cover comes from the image property (or a Bases formula) rather than from the note's body, the collapsed card shows the note's usual preview beneath it. A carrel-preview: render preview works there too, so a Meta Bind button can sit under a computed image. Turn this off per board with Preview under cover. A note that is itself a picture has no other text to show and stays cover-only.

From CSS. A snippet can change the defaults for every board by setting --cr-cover-aspect (for example 1 / 1) and --cr-cover-max-height (for example 140px) on body. A board whose own setting has been changed keeps its own value.

Typed blocks

Inside a note, certain Markdown shapes render as rich blocks when the card is expanded. Write them as ordinary Markdown.

Table — a standard Markdown table:

| Code | Meaning |
| --- | --- |
| 200 | OK |
| 404 | Not Found |

Checklist — task-list items. They render as checkboxes you can toggle, and their state is saved per nook:

- [ ] Scout the area
- [x] Set up camp

Steps — a numbered list, rendered as ordered steps:

1. Freeze the release branch.
2. Run the test suite.
3. Deploy behind a flag.

Bullets — a normal bullet list. Lead an item with **Term** — text to render a term/definition pair:

- **Correctness** — does it handle the edge cases?
- **Tests** — is the new behavior covered?

Callout — a blockquote. A trailing — attribution line becomes a citation:

> The mountain gives warmth, and takes its due.
> — The first oath

Obsidian callouts & infoboxes — an Obsidian callout (> [!type]), including the worldbuilding infobox pattern, renders through Obsidian's own pipeline, so the native callout chrome plus any embedded images, headings, and tables inside it all resolve:

> [!infobox|left]
> # Ser Aldric
> ![[aldric.png|cover]]
> | Trait | Value |
> | --- | --- |
> | Class | Paladin |
> | Level | 7 |

Flowchart — a fenced ref-flow block written in a small step language:

```ref-flow
start: An alert fires.
check: Can you confirm customer impact?
branch:
  success: Declare an incident and page the lead.
  fail: Log it, watch five minutes, and close if quiet.
note: Assign roles before debugging.
options: Incident lead | Communications | Operations
```

The keys are start, note, check, branch (followed by indented success: / fail: lines), and options (a |-separated list).

Dice — a one-line HTML comment that renders an interactive roll widget:

<!-- block: dice expr:"2d6" mod:"3" label:"Damage" -->

expr is the dice expression (default 1d20), mod an optional flat modifier, and label the caption.

Tip: any block can be forced to a specific type with a leading <!-- block: <type> … --> comment — for example <!-- block: table caption:"Reach by weapon" --> adds a caption to the table that follows.

Customizing types — disable and detect

The built-in types and their inference fit most vaults, but Settings → Carrel → Types adds two levers for the rest:

• Disable a built-in type. Toggle off any type you don't use. Carrel stops inferring it — those notes fall through to the next match — and its filter chip and type section disappear. Notes that declare the type in front matter keep it.
• Type detection rules. Auto-assign a type to notes that match a metadata rule, without parsing the note body. Each rule maps a condition to a target type, checked in order — the first enabled match wins:
  • Has frontmatter key — the note has a given property (any value).
  • Frontmatter key equals — a property equals a given value.
  • Has tag — the note carries a given tag.

So "notes tagged #spell are Formula" or "notes with a statblock property are Table." An explicit type: in front matter still wins over a rule; rules only fill in where you'd otherwise rely on inference.

Embedding Carrel in a note

Besides the full-width pane, Carrel can render a board inline inside any note — a more compact view meant to live alongside your writing. Add a carrel code block naming the nook:

```carrel
nook: Team Handbook
```

The fastest way is the Carrel: Insert Carrel block command, which lets you pick a nook (or create one on the spot) and writes the block for you.

An inline embed is deliberately different from the full pane:

• It shows the pinned rail and cards only — no toolbar, search box, or filter chips.
• It sits at the note's width and is capped at a height (set in Style Settings), scrolling within itself.
• It runs its own index, so it always shows the nook you named — independent of whichever nook is active in the pane.

It still updates live as the underlying notes change, and you can expand cards and follow links right inside the note.

Bases view

Obsidian Bases (Obsidian 1.10+) turns a set of notes into a filtered, queryable view. Carrel registers a "Carrel" view type for any .base file: switch a Base to the Carrel view and its filtered results render as the full Carrel board — real types, flowcharts, colors, and your type rules, all of it. Each note is parsed exactly as it is in a nook, so a flowchart note is a flowchart and a table is a table.

To use it, open a .base file, add or open a view, and choose Carrel as the view type. The board updates live as you change the Base's filters and formulas or edit the underlying notes.

Where the settings are. A Carrel view is configured the way any Bases view is:

• What appears, and in what order — the Base's own toolbar: filters, sort, group, and result limit.
• How the board looks — the view's options (click the view's name, then the arrow beside it), saved in the .base file with the view:
  • Display — theme, density, columns, pinned rail, type badges & meta, reflow animation. A new Carrel view starts in the Obsidian theme so it matches the rest of the Base; pick Ember here for the brand look.
  • Images — image and icon image properties, image fit, aspect ratio and max height, preview under cover.
  • Properties — type and category properties.
• What you're looking at right now — the board's own toolbar: search, the pinned / category / type filter chips, and the Layout, Group and Sort presets. Search and chips reset when the view reloads; pins, card order and the presets are kept per view.

The base drives the board. Carrel renders the query result exactly as the Bases engine delivers it: the view's sort (the Bases sort toolbar) is the card order, and its Group by is the section grouping — pick a property or a formula there and the board follows. That's the default for a Carrel Bases view (Sort: Base, Group: Base in the board toolbar); Carrel's own presets remain available if you want to override the base.

Carrel inputs from Bases properties and formulas. In the view's options (the Images and Properties groups), you can point each of Carrel's per-note inputs at any Bases property — a note property, a file property, or a formula:

• Image property — the card's cover / thumbnail
• Icon image property — the card's corner icon
• Type property — the card type
• Category property — the card category

The engine evaluates the property per note; Carrel reads the result. So a formula such as link("Admin/Clock Images/" + segments + "segment/" + ticked + ".png") picked as the image property gives every card a computed cover, and an image(...) formula works the same way. Unset options leave the note's own front matter in charge. (Formulas are evaluated by Bases inside a view, so this is available for Bases-backed nooks only.)

Carrel renders the notes' content here, not the Base's columns, so reach for it when you want to read a filtered slice of your vault as cards; use the built-in Table or Cards views when you want the property grid.

Theming

Each nook chooses one of two looks in its settings:

• Ember — a dark theme with red/gold accents and the Norwester / Taroca / Crimson Text type treatment. Accent colors and fonts are customizable through the Style Settings plugin.
• Obsidian — inherits your active Obsidian theme's colors and fonts, so the board blends into whatever you already run. (This is the theme shown in the screenshot at the top.)

The same board in the Ember theme:

If you have the Style Settings plugin, a Carrel section lets you set the primary (red) and secondary (gold) accents, the display / label / body fonts, and the maximum height of inline embeds.

Dice Roller integration

Dice Roller is the popular TTRPG dice plugin for Obsidian. When it's installed, Carrel hands rolls off to it — so its full grammar (keep/drop, exploding dice, Fate/Fudge, and more), its lookup tables, and nested tables all work inside your cards. When it isn't installed, plain dice still roll with Carrel's own built-in roller; the table features simply stay quiet.

Because Carrel renders note content through Obsidian's own Markdown pipeline, any inline `dice:` expression rolls in place — in any card, not just Formula cards. Drop a roll into a plain reference note and it just works:

Roll Table cards

A note whose body is a Dice Roller lookup table — a Markdown table whose first header cell is a dice: formula — becomes a dedicated Roll Table card. Carrel shows the table with a Roll button; rolling highlights the matched row and shows the result with the rolled number beside it. A cell that points at another table (a nested roll) renders as a tidy reference chip and resolves to a live sub-roll when rolled.

Write one as an ordinary table, with the dice formula in the first header cell and a block-id anchor on the line beneath it (the anchor lets other tables and cards reference it):

| dice: 1d6 | Loot |
| --- | --- |
| 1-3 | Copper pieces |
| 4-5 | Silver pieces |
| 6 | `dice: [[Rare Loot^rare]]` |

^loot

Rolling on a table from another card

To roll on a lookup table that lives in a different note, add a roll-table block pointing at it. The card gets its own Roll button and shows the result — and the rolled number — each time:

<!-- block: rolltable ref:"[[Loot Table^loot]]" label:"Roll for loot" -->

Wayfinder integration

Carrel grew out of Wayfinder, a character-sheet plugin. The two work independently, but when Wayfinder is also installed you get a little more:

• The RPG Awesome icon set (1000+ themed glyphs) unlocks in the category icon picker, alongside the always-available Lucide set.
• A nook can pick up a linked character's accent colors, so its Ember theme matches the sheet.
• Wayfinder can render a Carrel board in place of its built-in References tab.

None of this is required — Carrel is fully standalone. The integration simply activates when both plugins are present.

Configuration reference

Categories (Settings → Carrel)

• Add, edit, reorder (drag), and delete categories.
• Per category: name, color (palette or custom), icon (Lucide / RPG Awesome).

Nooks (Settings → Carrel)

• Create a nook from selected folders; set the active nook; edit or delete.
• Per nook: name, theme (Ember / Obsidian), source folders, density (Compact / Regular / Comfortable), columns (Auto, or 1–4), pinned rail on/off, type badges & meta on/off, reflow animation on/off, and the cover settings — image fit, image aspect ratio, image max height, preview under cover.
• A Bases view has the same display settings in its own view options instead (see Bases view).

Style Settings (if the Style Settings plugin is installed)

• Primary accent (red), secondary accent (gold).
• Display, label, and body fonts.
• Inline embed maximum height (200–1200px).
• Kanban column width (150–460px).

Per-note front matter

• image (configurable name) — cover image; forces an image card.
• icon-image (configurable name) — replaces the card's corner glyph.
• imageScaleType — how the cover / thumbnail fits: auto, contain, cover, or stretch.
• summary — the preview text (markdown), instead of the note's opening blocks.
• carrel-preview: render — render the opening blocks in the preview even when they are opaque (plugin block, embed, table).

Commands

• Carrel: Open Carrel pane
• Carrel: Create nook from folders
• Carrel: Insert Carrel block

Known limitations

• Card type is inferred from structure by default. You can disable individual types and add metadata-based detection rules (Settings → Carrel → Types), but the inference itself is heuristic and falls back to a plain Reference card when nothing else matches.
• Open cards, keyboard focus, the search query, and active filters are transient — they reset when the pane reloads. Pins, pin order, and checklist state persist per nook.

Support

Found a bug or have a request? Open an issue at github.com/alas-poor-ophelia/carrel/issues.

License

MIT