Frontmatter Reference

Complete Frontmatter Reference

Strayfiles uses YAML frontmatter for metadata. This reference covers all supported fields.

Basic Structure

---
title: Note Title
strayfiles:
  enabled: true
  id: "uuid-here"
  workspaces: ["workspace1", "workspace2"]
  tags: [tag1, tag2]
  alias: "Display Name"
  sync: true
custom_field: any value
---

Your markdown content here.

Standard Fields

These are common Markdown frontmatter fields:

Field	Type	Description
title	string	Note title (shown in UI)
date	string	Creation/publication date
author	string	Note author
description	string	Brief description

Strayfiles Fields

All Strayfiles-specific fields live under the strayfiles key:

strayfiles.enabled

strayfiles:
  enabled: true

Value	Behavior
true	File is indexed
false	File is skipped
(omitted)	Depends on explicit_only config

When explicit_only = true in config, only files with enabled: true are indexed.

strayfiles.id

strayfiles:
  id: "550e8400-e29b-41d4-a716-446655440000"

Stable UUID identifier for the note. If omitted, Strayfiles generates one automatically.

Properties:

• UUID v7 format (time-ordered)
• Survives file renames and moves
• Enables cross-device sync
• Links version history to note

strayfiles.workspaces

strayfiles:
  workspaces: ["work", "documentation", "api"]

Explicit workspace assignments. Combined with config-based auto-assignment (union merge).

strayfiles.sync

strayfiles:
  sync: false

Value	Behavior
true (default)	Note syncs to cloud (Pro)
false	Note stays local only

Use sync: false for sensitive files like API keys or credentials.

strayfiles.alias

strayfiles:
  alias: "Backend CLAUDE"

Display name shown instead of the filename. Useful when you have multiple files with the same name (like CLAUDE.md in different projects).

When set, Strayfiles displays: Backend CLAUDE (CLAUDE.md) with the original filename dimmed.

strayfiles.tags

strayfiles:
  tags: [api, reference, v2]

User-defined tags for organizing notes. Combined with config-based auto-assignment (union merge).

Smart Display

Strayfiles intelligently hides frontmatter in the UI:

Hidden (tracking-only):

---
strayfiles:
  enabled: true
  id: "uuid"
---

When frontmatter contains only Strayfiles tracking fields, it’s hidden from the editor. You see just the content.

Shown (has user content):

---
title: My Note
tags: [important]
strayfiles:
  enabled: true
---

When frontmatter contains user fields (title, tags, custom), the full frontmatter is shown.

Custom Fields

Any field not recognized by Strayfiles is preserved:

---
title: Project Plan
status: draft
priority: high
due_date: 2025-12-15
strayfiles:
  enabled: true
---

Custom fields:

• Passed through unchanged
• Searchable in Strayfiles
• Visible when frontmatter is shown
• Preserved on save

Examples

Minimal (hidden in UI):

---
strayfiles:
  enabled: true
---

Standard note:

---
title: Meeting Notes
strayfiles:
  enabled: true
  workspaces: ["work"]
  tags: [meetings, project-x]
---

Full metadata:

---
title: API Documentation
author: Team
date: 2025-12-10
strayfiles:
  enabled: true
  id: "550e8400-e29b-41d4-a716-446655440000"
  workspaces: ["documentation", "api"]
  tags: [api, reference, v2]
---

Local-only sensitive file:

---
title: API Keys
strayfiles:
  enabled: true
  sync: false
---

With alias (for files with common names):

---
strayfiles:
  enabled: true
  alias: "Backend CLAUDE"
---

With custom fields:

---
title: Sprint Planning
status: active
sprint: 42
points: 13
strayfiles:
  enabled: true
  workspaces: ["work", "agile"]
  tags: [planning]
---

Parsing Rules

1. Frontmatter must be at the very start of the file
2. Delimited by --- on its own line
3. Content is YAML format
4. Invalid YAML causes parse error (file still readable)

Valid:

---
title: Valid
---
Content here

Invalid (not at start):

Some content

---
title: Invalid
---

Field Types

Field	Type	Example
title	string	"My Note"
tags	array of strings	[tag1, tag2] or ["tag1", "tag2"]
strayfiles.enabled	boolean	true or false
strayfiles.id	string (UUID)	"550e8400-..."
strayfiles.workspaces	array of strings	["work", "personal"]
strayfiles.alias	string	"Display Name"
strayfiles.sync	boolean	true or false

Alternative: HTML Comment Format

For files where YAML frontmatter would be visible (like README files rendered on GitHub), use HTML comment tracking instead:

<!-- strayfiles: {"enabled": true, "id": "uuid-here", "workspaces": ["work"]} -->

# README

This renders cleanly - no visible metadata.

When to use HTML comments:

• README files on GitHub/GitLab
• Documentation rendered in browsers
• Any file where frontmatter would be distracting

Supported fields (same as frontmatter):

• enabled - boolean
• id - UUID string
• workspaces - array of strings
• sync - boolean
• alias - display name string

See HTML Comment Reference for complete details.

Best Practices

Always include enabled: true: Even if explicit_only = false, explicit opt-in is clearer.

Let Strayfiles generate IDs: Don’t manually create UUIDs. Strayfiles handles this.

Use workspaces for organization: Combine with config patterns for powerful organization.

Keep frontmatter minimal: Only add fields you actually need.