Frontmatter & Metadata

Make your knowledge easier to find, compare, and reuse by giving pages a few structured facts. Frontmatter lets the same note become a project record, source entry, decision, or reference that both you and your agents can interpret.

Frontmatter is an optional YAML block at the beginning of a Markdown file. Its fields are called properties. They describe the page without replacing the writing beneath it.

Start with a small useful example

---
title: Website Launch
area: projects
type: project
status: in-progress
tags: [website, launch]
---

# Website Launch

Our goal is to make the product's main benefit clear to new visitors.

The opening and closing --- lines delimit the metadata. The body after the second delimiter is ordinary Markdown.

You can omit frontmatter completely, or begin with only a title and tags.

What metadata makes possible

Find a specific kind of knowledge. Identify decision pages, research sources, or active projects without relying on a phrase appearing in the body.

Compare and sort pages. The web Table view shows title, area, and updated date. The Mac Table view and property controls offer further ways to review structured pages. Custom fields remain in the file even when a particular view does not display them.

Give agents clearer context. An agent can distinguish a speculative idea from a decision, inspect a source URL, or identify a page's project and status.

Properties describe what you recorded. A confidence: high label is your assessment, not independent verification of a claim.

Common fields

Add only the fields you expect to search, filter, review, or use in a workflow.

Add your own properties

---
title: Launch Planning Meeting
type: meeting
status: reviewed
attendees: [Alex, Sam]
project: "[[Website Launch]]"
deadline: 2026-11-15
budget: 2500
approved: false
source: https://example.com/research
---

These values can become text, dates, numbers, checkboxes, lists, URLs, or page links in the Mac Properties panel.

Quote wikilinks in raw YAML, as shown above. Without quotes, brackets can be interpreted as YAML collection syntax instead of the string you intended.

Use consistent values

Choose one spelling for fields you reuse. status: in-progress and status: working may mean the same thing to you, but they are different stored values.

A practical starting set is:

• Projects: type, status, priority.
• Sources: type, source, author, published.
• Decisions: type, decided, confidence.

A property is useful when it helps you ask a better question or see the collection more clearly. You do not need to fill every possible field.

Write valid YAML

• Place the frontmatter block at the very top of the page.
• Use name: value with a space after the colon.
• Use true and false for booleans, and unquoted numeric values for numbers.
• Use YYYY-MM-DD for dates.
• Write lists as [website, launch] or valid indented YAML lists.
• Quote strings containing meaningful YAML punctuation or values that should remain text.
• Avoid duplicate property names within one page.

For example:

title: "Launch Plan: First Release"
project: "[[Website Launch]]"
reference_code: "00123"
tags: [website, launch]

Edit properties on your preferred surface

On Mac, use the Properties panel for typed controls. On the web, edit the YAML directly. Both refer to the page's underlying metadata.

Values such as updated, deadline, and status carry the meaning you assign them. A date field alone does not create a reminder or scheduled action. Follow your workflow's conventions for maintaining dates rather than assuming every field updates automatically.

Metadata and wikilinks are portable text conventions. Other applications may display them differently, but the values remain in the file.

Next: Properties, Search & Views, and Vault Structure.