---
title: "Front matter reference"
description: "The YAML block at the top of a markdown file, and the keys Treehouse reads from it to label, title and schedule your files."
canonical_url: "https://trytree.house/docs/files/front-matter"
last_updated: "2026-09-29"
---

# Front matter reference

The YAML block at the top of a markdown file, and the keys Treehouse reads from it to label, title and schedule your files.

## Keys Treehouse understands

| Key | Where it goes | Value | What it does |
| --- | --- | --- | --- |
| `title` | A folder's `README.md` or `index.md` | Text | Replaces the folder's name as the heading of its **Files** and **Calendar** views. |
| `title` | Any markdown note in a calendar folder | Text | Labels the note on the calendar instead of its file name. |
| `view` | A folder's `README.md` or `index.md` | `calendar` | Opens the folder on its calendar, as long as it has dated notes. |
| `date` | Any markdown note | `YYYY-MM-DD` | Places the note on its folder's calendar. Dragging it to another day rewrites this value. |

[Turn a folder into a page or calendar](https://trytree.house/docs/files/folder-pages) shows these keys at work.

## What front matter is

Front matter is a block of YAML at the very top of a markdown file, between two lines of three dashes. It holds facts about the document, separate from the text itself:

**plans/q4-roadmap.md**

```markdown
---
title: Q4 roadmap
date: 2026-10-01
status: draft
tags: [planning, product]
---

The roadmap starts here.
```

The block must be the first thing in the file. Treehouse reads it only from markdown files.

## Other keys

You can add any other keys you like. Treehouse keeps them exactly as written and shows them in the file's **Metadata**, but gives them no special meaning. Nothing in the app filters, sorts or acts on `status`, `tags`, `owner` or anything else.

That still makes them useful. Agents read front matter well, so a small shared vocabulary is a good way to tell them things. A common pattern is `status: draft` on work that isn't ready and `status: ready` once it is, with a line in your `AGENTS.md` saying what each value means. It's a convention you and your agents agree on, not a Treehouse feature. The [routines playbook](https://trytree.house/docs/playbooks/routines) shows where conventions like this fit.

## Where you see it in the app

- **Reading a file:** a collapsed **Metadata** card above the document, showing a couple of values and the number of fields. Select it to see them all.
- **The Info tab:** the details panel lists every field under **Metadata**.
- **Editing:** a **Metadata** form above the document lets you change existing values. True or false values are checkboxes, and lists have an **Add…** box for new items. To add or remove a key, or change a nested value, switch the editor to **Source** and edit the YAML directly.

If the YAML can't be parsed, the editor says so and offers to open **Source** so you can fix it.

## How agents set it

There's no separate metadata API. Front matter is part of the file, so an agent sets it by writing the file with the block at the top, and changes it the same way. Everyone sees the change as a new version of the file, with the usual [history](https://trytree.house/docs/files/version-history).

> **For agents**
>
> When you change a markdown file, keep its front matter block intact and at the very top. Write dates as `YYYY-MM-DD`. Don't invent new meanings for `title`, `view` or `date`: the app acts on those three.

## Related

- [Turn a folder into a page or calendar](https://trytree.house/docs/files/folder-pages): Give a folder a front page with a README, or show a folder of dated notes as a calendar you can reschedule by dragging.
- [Create and edit files](https://trytree.house/docs/files/create-and-edit): Make new files and folders in the web app, edit markdown, code and HTML, and save your changes.
- [Set up routines](https://trytree.house/docs/playbooks/routines): Recurring agent work, like a morning inbox run or a weekly review, and where the schedule lives when Treehouse doesn't run agents itself.