guanghu/src-tauri/resources/agent-docs/pages/guides/use-spreadsheets.md

Use Spreadsheets

Source: guides/use-spreadsheets.md URL: /guides/use-spreadsheets

Use Spreadsheets

Tolaria spreadsheets are sheet notes: Markdown files with frontmatter and a CSV-like body that open in a spreadsheet editor when their Display as value is Sheet.

Use a sheet note when a model needs rows, columns, calculations, or repeated numeric editing. Use a normal note when the main artifact is prose.

Create A Sheet

Use the command palette action New Sheet, or create/open a note and set its Display as to Sheet from the Properties panel. Type remains separate and can still be Note, Project, Responsibility, or any other Tolaria type.

When a note is a sheet:

• the YAML frontmatter remains available for type, status, relationships, wikilinks, and custom properties
• _display: sheet tells Tolaria to display the note with the spreadsheet editor
• the body is the sheet itself
• there is no rich-text body around the table
• the editor switches from the text editor to the spreadsheet editor

Enter Values

Click a cell and type a value. Non-formula values can be text, numbers, dates, or wikilinks.

Press Enter on a selected cell to edit the cell. Press Escape while editing to leave cell editing and keep focus in the sheet.

Use Delete or Backspace to clear the selected cell or range.

Enter Formulas

Formulas start with =.

=B2+B3-B4
=SUM(B2:D2)
=ROUND(E6, 2)
=IF(E6>0, "Up", "Down")

Tolaria shows inline formula autocomplete while you type. The autocomplete list is built from the implemented function catalog in the bundled IronCalc engine; formula evaluation is still handled by IronCalc.

See Spreadsheet Formulas for syntax, supported examples, and links to the full IronCalc formula reference.

Select And Edit Ranges

The sheet editor follows spreadsheet conventions:

• arrow keys move the active cell
• Shift plus arrow keys extends the selection
• drag to select a range
• copy and paste preserves formulas where possible
• cut and paste moves formulas and shifts relative references
• right-click a selected cell or range to apply formatting

Right-click actions apply to the current selection. Keep a multi-cell selection active before opening the context menu when you want to format several cells together.

Format Cells

Use the context menu for common formatting:

• number formats such as plain numbers, currency, and percentages
• decimal precision
• bold and italic text
• alignment and clearing formatting when available

Formatting is stored as plain YAML under _sheet, not in an opaque workbook blob. For example, percentage formatting for E6 is stored as:

_sheet:
  cells:
    E6:
      num_fmt: "0.00%"

See Spreadsheet File Format for the full storage model.

Add Wikilinks

Type [[ in a cell to open note autocomplete.

Project,Owner,Status
[[website-redesign]],[[person/alice]],Active
[[sponsorship-pipeline]],[[person/matteo]],Review

When the cell is not being edited, Tolaria renders the wikilink like other note links. When you edit the cell, the raw [[wikilink]] syntax is shown again.

Command-click a wikilink in a sheet cell to open the linked note.

Reference Another Note

Formulas can read a cell from another sheet note with Tolaria's wikilink cell syntax:

=[[newsletter-revenue]].B5
=SUM(B2:D2)+[[sponsorship-pipeline]].E12
=ROUND([[business-plan]].$E$12, 2)

The part inside [[...]] resolves like a normal Tolaria wikilink. The part after the dot is an A1-style cell reference.

Use absolute markers when copying formulas:

Reference	Copy behavior
[[revenue]].B5	row and column can shift
[[revenue]].$B$5	row and column stay fixed
[[revenue]].B$5	row fixed, column can shift
[[revenue]].$B5	column fixed, row can shift

Cross-sheet references currently resolve single cells. Keep range formulas inside one sheet note.

Formulas can read scalar frontmatter properties from a note with dot notation:

=[[device]].power.watts
=[[project-alpha]].status
=[[book-notes/the-design-of-everyday-things.md]].rating

Numbers, booleans, and text properties can be used in formulas. Missing or ambiguous note targets, missing properties, and non-scalar values such as lists or nested objects show as spreadsheet errors.

Work With The Raw File

A sheet file remains readable text:

---
type: Project
_display: sheet
status: Draft
belongs_to:
  - "[[business-plan]]"
_sheet:
  frozen_rows: 1
  columns:
    A:
      width: 180
---
Metric,January,February,March,Q1 Total
Subscriptions,1200,1350,1500,=SUM(B2:D2)
Services,800,900,750,=SUM(B3:D3)
Expenses,650,700,760,=SUM(B4:D4)
Net,=B2+B3-B4,=C2+C3-C4,=D2+D3-D4,=SUM(B5:D5)

When editing this file with scripts or AI agents, parse the body as CSV and preserve formulas as formulas. Do not replace formulas with displayed values.