Properties (frontmatter)

Orbit supports a YAML header at the beginning of a Markdown note. The block editor shows it as Properties. Choose Edit properties from the note’s … menu, beside the comments action, to add or edit a header. You can also expand the Properties card and choose Edit properties.

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

# Network runbook

Start with the service status.

Edit properties

Headers longer than five lines start folded; a tags list is previewed beside the folded label. Click the Properties label or its chevron to expand or collapse compact property rows: text, numbers, dates, lists, and tags. Nested objects show a summary.

Choose Edit properties to open a dialog with a key, type, and value for each property. Use Add property to add a row, or Remove to remove one. Lists accept one item per line; structured values use JSON. Save applies your changes, while Cancel leaves the note unchanged. Removing every existing property and saving removes the header. Changes can be undone in the note.

If properties change while the dialog is open, reopen it to load the latest values before saving. Changes to the note body do not prevent saving properties.

Invalid or unsupported YAML stays intact. Use Raw markdown in the note’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 note 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 note 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 notes through a flat page 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. Pages can be shorter than pageSize, or empty with a continuation, because work, output, and time per request are bounded — a page never waits on slow notes. Headers come from the live editor when a note 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 note 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 note 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 notes 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 notes, 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 notes that your agent maintains. Use targeted edits for metadata changes and preserve fields you do not own.