Metadata Precedence

How Strayfiles Resolves Metadata

When multiple metadata sources exist for a file, Strayfiles follows a clear priority order to determine which values to use.

Priority Order

Priority	Source	Description
1 (highest)	YAML Frontmatter	In-file strayfiles: block
2	HTML Comment	<!-- strayfiles: {...} -->
3	Project TOML	./strayfiles.toml auto-assignment
4 (lowest)	User TOML	~/.strayfiles/strayfiles.toml

How Each Field is Resolved

ID Extraction

The note’s unique identifier is extracted from the first source that provides one:

1. Frontmatter strayfiles.id field
2. HTML comment "id" field
3. Auto-generated if neither exists

Workspace Assignment

Workspaces can come from multiple sources and are resolved as follows:

• Explicit frontmatter workspaces: [...] overrides TOML auto-assignment
• If no frontmatter workspaces, TOML include patterns apply
• A file can belong to multiple workspaces from different sources

Enabled Status

• enabled: false in frontmatter excludes the file regardless of TOML settings
• explicit_only = true in TOML requires frontmatter enabled: true

TOML Config Precedence

When both project and user TOML configs exist:

• Project TOML (./strayfiles.toml) overrides User TOML
• Settings are not merged—project config wins entirely

Examples

Frontmatter overrides TOML workspace:

---
strayfiles:
  enabled: true
  workspaces: ["personal"]
---

Even if this file matches [workspaces.work].include = ["projects/**"], it will only belong to “personal” because frontmatter takes priority.

Frontmatter overrides HTML comment:

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

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

If both exist in the same file, “frontmatter-uuid” is used.

TOML auto-assignment (no frontmatter):

A file at projects/api/README.md with no explicit workspace assignment will be auto-assigned to any workspace whose include pattern matches, such as:

[workspaces.work]
include = ["projects/**"]

Summary

In-file metadata (frontmatter, HTML comments) always wins over configuration files. This ensures developers have full control over individual files while TOML provides convenient defaults and auto-assignment.

Setting	Resolved From
Note ID	Frontmatter → HTML comment → auto-generated
Workspaces	Frontmatter → TOML patterns
Enabled	Frontmatter → TOML explicit_only
Sync	Frontmatter only
Alias	Frontmatter or HTML comment