Frontmatter Basics - Getting Started

In-File Metadata

strayfiles uses YAML frontmatter to manage file metadata. This is the same format used by most static site generators, so your files stay compatible with other tools.

Basic Structure

Add a strayfiles block to any Markdown file’s frontmatter:

---
title: My Project Notes
date: 2025-01-15
strayfiles:
  enabled: true
  id: "550e8400-e29b-41d4-a716-446655440000"
  workspaces: ["work", "ideas"]
---

# My Project Notes

Your content here...

Available Fields

Field	Type	Description
`enabled`	boolean	Opt this file into strayfiles indexing
`id`	string	Stable UUID for the file (auto-generated if omitted)
`workspaces`	array	Virtual workspaces this note belongs to
`sync`	boolean	Set to `false` to keep this file local-only (Pro)

How It Works

enabled: true

Tells strayfiles this file should be indexed. If your project uses explicit_only = true in the config, only files with this flag will be indexed.

strayfiles:
  enabled: true

id (optional)

A stable identifier for the file. strayfiles auto-generates this on first index, but you can set it manually if needed. Useful for:

Maintaining references when files move
Syncing across devices
API integrations

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

workspaces

Assign notes to virtual workspaces without moving files:

strayfiles:
  workspaces: ["work", "personal", "blog-drafts"]

sync: false (Pro only)

Keep sensitive files local-only. Files with sync: false are indexed and searchable but never uploaded to the cloud, even with Pro cloud sync enabled.

strayfiles:
  enabled: true
  sync: false

Use this for files containing:

API keys or secrets
Environment variables
Database credentials
Private configuration
Anything sensitive

Even with end-to-end encryption, we recommend keeping secrets local. This gives you the best of both worlds: your sensitive files are searchable alongside everything else, but they never leave your device.

Compatibility

The strayfiles block is ignored by other tools. Your files work everywhere:

GitHub renders them normally
Static site generators ignore the block
Other Markdown editors see it as metadata

Quick Examples

Minimal opt-in:

---
strayfiles:
  enabled: true
---

Full metadata:

---
title: API Documentation
tags: [api, reference]
strayfiles:
  enabled: true
  id: "api-docs-main"
  workspaces: ["work", "documentation"]
---

Multiple workspaces:

---
strayfiles:
  enabled: true
  workspaces: ["claude-code", "cursor", "ai-tools"]
---

Sensitive file (local-only):

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