Properties (frontmatter)

Orbit supports a YAML header at the beginning of a Markdown page. The block editor shows it as Properties, a list of names and values under the page title, edited the same way as a database row. To add properties to a page, point at the space above its title and choose + Add › Properties, or type /properties.

---
title: Network runbook
description: Steps for diagnosing network incidents
tags: [infrastructure, networking]
owner: Platform
---

# Network runbook

Start with the service status.

Edit properties

Properties start collapsed, and Orbit remembers whether you last expanded or collapsed them, across all your pages. A tags list is previewed beside the folded label. Click the Properties label or its chevron to expand or collapse the list. A page with no properties yet opens on Add property.

• Click a value to change it. Text and numbers are typed in place; press Enter to keep the change or Escape to put it back. A list is typed as comma-separated items. Click a Checkbox value to switch it between true and false.
• Click a property’s name to rename it, change its type (Text, Number, Checkbox or List), or Remove it. The property turns red while you point at Remove.
• Click Add property, type a name and pick its type, the same menu a page table uses. Enter picks Text. Orbit then puts you in the new property’s value; a Checkbox starts unticked. Escape closes the menu without adding anything.

Every change is saved to the page’s YAML straight away, and can be undone in the page. Values that cannot be edited on one line (text over several lines, list items containing commas, nested objects) open the properties dialog instead, with a key, type and value for each property. Removing every property removes the header.

If the YAML changed underneath you (another person edited it at the same moment), Orbit keeps their version and says so; try your change again.

Invalid or unsupported YAML stays intact. Use Raw markdown in the page’s … menu to repair the source or change the opening and closing --- delimiters.

What Orbit preserves

Untouched YAML keeps its comments, field order, quotes, indentation, custom fields, and multiline values. Orbit normalizes file line endings to LF, removes an initial BOM, uses plain --- fences, and places one blank line before the Markdown body. This is source preservation, not a promise of identical file bytes.

The header must be at the beginning of the file and have matching --- opening and closing lines. A page beginning with two such divider lines is treated as having a header even if the text between them is not valid YAML. Read mode omits Properties; Markdown exports retain it.

Metadata conventions

tags is an ordinary property. Orbit shows it in Properties like any other key but does not read it into Orbit’s own tag system: the tag bar, the sidebar tag filters and counts, Untagged, autocomplete and #tag search all use tags you assign in Orbit, which are stored as page metadata, not in the file. Editing a tag in Orbit never rewrites your YAML, and a tags: line in YAML never appears as an Orbit tag. #words in the body are ordinary content too.

title, description, status, and lastReviewed are conventions for you and your agents; they do not automatically rename files or trigger workflows. Templates reserve the orbitTemplate prefix: those fields are removed when applying a template, while other properties are retained.

If two collaborators add Properties simultaneously, both sources are saved in one header. You may briefly see two Properties cards; consolidate their fields using Raw Markdown. Their shared text remains intact so delayed edits are not lost. Conflicting keys show a YAML error so you can choose the intended value; Orbit does not silently choose for you.

Reading with agents

Use orbit_list_notes with includeFrontmatter: true to discover pages through a flat, paged list of paths and parsed properties, without their bodies. Existing calls without this option still return the folder tree. No property names or folder structure are required.

{"workspaceId": "YOUR_WORKSPACE_ID", "includeFrontmatter": true, "pageSize": 10}

Follow nextCursor until it is null, retaining the same workspace, folder, depth, and includeRaw setting. A response can hold fewer than pageSize results, or none with a continuation, because work, output, and time per request are bounded — a response never waits on slow pages. Headers come from the live editor when a page is open and from the saved file otherwise. The default depth is two folder levels below the starting folder; choose up to six or start from a specific folderPath or folderId. Page size defaults to 10 and accepts 1–25 entries, including folders. Concurrent moves or edits can change a listing: deduplicate by page ID, or restart if a cursor becomes invalid. This is live discovery, not a frozen snapshot.

To inspect just one header, use orbit_get_note with format: "frontmatter":

{"workspaceId": "YOUR_WORKSPACE_ID", "path": "Network runbook", "format": "frontmatter"}

Both modes return parsed frontmatter.data by default. Set includeRaw: true to also receive original YAML. Missing headers return frontmatter: null; invalid headers carry a parseError. Oversized headers return frontmatter_response_limit instead of partial data. Discovery entries that cannot be read carry readError; non-Markdown documents report frontmatterSupported: false. These states do not mean a page is irrelevant.

A header projection is limited to 8 KiB and a discovery page to 64 KiB of formatted JSON (before MCP transport wrapping). These are response limits, not limits on what pages may contain. Reads use the current collaborative document; Orbit may still read the full document internally. Token savings come from returning only metadata to the agent and then fetching the relevant content. Useful descriptions help an agent choose; frontmatter itself does not compress a document or generate summaries.

For selected pages, orbit_get_note with format=document-map returns the original YAML, body structure, previews, and comment locations. Use that outline to fetch specific sections or prepare edits. Index and log files remain ordinary pages that your agent maintains. Use targeted edits for metadata changes and preserve fields you do not own.