Frontmatter Basics

In-File Metadata

Note: This guide covers adding strayfiles tracking to existing Markdown files. To create a new note from scratch, use “Add Note” in the app — strayfiles will create the file and add frontmatter automatically. See Installation.

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-12-05
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)
alias	string	Display name shown instead of the filename

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"]

alias (optional)

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

strayfiles:
  enabled: true
  alias: "Backend API Docs"

When an alias is set, Strayfiles displays Backend API Docs (CLAUDE.md) with the original filename dimmed.

sync: false (Pro only)

Keep sensitive files local-only. Files with sync: false are indexed and searchable but never uploaded to Stray Cloud, even with Stray Cloud 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

Precedence

Frontmatter metadata takes priority over all other sources:

1. Frontmatter values override HTML comment metadata
2. Frontmatter values override TOML auto-assignment

See Metadata Precedence for details.

Alternative: HTML Comments

For files where you don’t want visible frontmatter (like README files), Strayfiles supports HTML comment metadata:

<!-- strayfiles: {"enabled": true, "id": "uuid-here"} -->

# My README

Content renders cleanly on GitHub.

HTML comments are invisible when rendered. See HTML Comment Reference for details.

Quick Examples

Minimal opt-in:

---
strayfiles:
  enabled: true
---

Full metadata:

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

With alias (for files with common names):

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

Multiple workspaces:

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

Sensitive file (local-only):

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